
 When you release a port, please include YOUR contact information for users
 to report bugs and other problems.

 I get a ton of e-mails about a color problem in the Nokia P900 port of SMS
 Plus because the author apparently included my e-mail address (please link
 to my webpage instead) and listed NO contact information for him/herself.

 Also, let me know when you release a port, so I can forward these types
 of e-mails appropriately.

 ----------------------------------------------------------------------------

 What's changed for SMS Plus v1.2

 I haven't finished up the porting notes so some things aren't covered yet;
 look at the DOS source for an example.

 After calling system_init(), use the following functions:

 system_poweron()  - Call once, can run game afterwards
 system_reset()    - Can call during gameplay if user wants a hard reset
 system_poweroff() - Call once when done with a game.

 When loading multiple ROMs in a single session, you'd call poweroff() when
 done with a game, then poweron() after the next one was loaded.

 SRAM is loaded when poweron() or reset() is called.
 SRAM is saved when poweroff() is called.

 The SRAM management function has changed:

 void system_manage_sram(uint8 *sram, int slot, int mode);

 'mode' is either SRAM_SAVE or SRAM_LOAD.
 The slot parameter is ignored for now.
 If there was SRAM to load, set sms.save = 1;
 Otherwise, clear SRAM to zero.
 See the DOS code for an implementation of this function.

 Sound emulation

 The following structure holds sound related information:

 struct {

     /* Input parameters */
     int sample_rate;
     int fps;
     uint32 psg_clock; 
     uint32 fm_clock;
     int fm_which;
     void (*mixer_callback)(int16 **stream, int16 **output, int length);

     /* Working data */
     int16 *stream[STREAM_MAX];
     int16 *output[2];

     /* Outputs */
     int enabled;
     int buffer_size;
     int sample_count;
 } snd;

 Normally you would set up this structure before calling system_init().
 You can change the input parameters and call sound_init() again to change
 them. Here are how the parameters should be used:

 snd.sample_rate    Set to the desired sample rate, e.g. 22050, 44100.
                    Set to 0 to disable sound emulation.

 snd.fps            Set to 50 (PAL) or 60 (NTSC) to specify the emulated
                    sound replay rate. PAL consoles are not completely
                    supported yet, I would advise leaving this at 60.

 snd.psg_clock      Set to the SN76489 clock speed.
                    Normally this is 3579545. (3.58 MHz)

 snd.fm_clock       Set to the YM2413 clock speed.
                    Normally this is 3579545. (3.58 MHz)

 snd.fm_which       Set to SND_EMU2413 or SND_YM2413 depending on the FM
                    sound chip emulator you want to use. You can change
                    this and call sound_init() again for realtime switching.

 snd.mixer_callback Set to NULL to use the default stream mixing routine,
                    or point it to your own.

 Calling sound_init() will return 0 if sound emulation was disabled or an
 error occured, or 1 if initialization was successful. The following
 variables will be valid for use afterwards:

 snd.enabled        Set to 1 if sound emulation is enabled, 0 if disabled.

 snd.buffer_size    Size of sample buffer in bytes.

 snd.sample_count   Length of sample buffer in samples.

 snd.stream         Sound streams for the built-in mixer function or a user
                    supplied one to use.

 snd.output         Mixed audio generated by the built-in mixer function
                    that can be output to a sound device. Updated after each
                    call to system_frame().

 An example of setup and use is as follows:

    // Init code
    snd.sample_rate    = 44100;
    snd.fps            = 60;
    snd.psg_clock      = 3579545;
    snd.fm_clock       = 3579545;
    snd.fm_which       = SND_EMU2413;
    snd.mixer_callback = NULL;
    system_init();

    // Change some parameter later on
    snd.fm_which       = SND_YM2413;
    sound_init();
    
    // Update code
    system_frame();
    osd_play_stream_stereo( snd.output, snd.buffer_size );

 Custom mixing

 You can provide your own mixing routine to combine audio streams. Some
 uses might include:

 - Per-stream volume adjustment, filtering, effects.
 - Stereo output of YM2413 sound.
 - Bass-boost on YM2413 rhythm output.
 - Can take advantage of in-hardware playback/mixing (console ports, etc.)

 There are four sound streams available:

 STREAM_PSG_L   SN76489 left channel output
 STREAM_PSG_R   SN76489 right channel output
 STREAM_FM_MO   YM2413 melody channel output
 STREAM_FM_RO   YM2413 rhythm channel output

 The two YM2413 outputs are mixed together, along with the PSG output, for
 a single monoaural channel in all versions of the SMS and related hardware
 that support FM sound.

 Synopsis of audio features by console:

                FM sound    Stereo PSG  Output
 Mark III       No          No          Mono
 Mark III+FM    Yes         No          Mono
 SMS 1          No          No          Mono
 SMS 2          No          No          Mono
 SMS 1 (J)      Yes         No          Mono
 Game Gear      No          Yes         Stereo (headphone jack) Mono (speaker)

 Audio from the YM2413 emulator has a lower volume than EMU2413 and will
 need to be adjusted.

 See the default mixer routine in 'sound.c' for an example.

 ----------------------------------------------------------------------------
 Porting notes for earlier 0.9.x versions
 ----------------------------------------------------------------------------

 You can check out the DOS specific code to get an idea of
 how to port SMS Plus.

 0.) Machine dependant issues
 ----------------------------

 Everything should compile fine for big-endian platforms, however
 I'm not sure the 8-bit pixel to 16-bit pixel conversion function
 in 'render.c' is endian safe.

 You need to either define or not define 'LSB_FIRST' in your makefile,
 depending on your needs.

 1.) Graphics
 ------------

 The emulated display can be shown in either 8-bit or 16-bit color.
 The following structure is used by the rendering routines to
 draw the display, and you need to set it up prior to running the
 emulation.

    typedef struct
    {
        uint8 *data;
        int width;
        int height;
        int pitch;
        int depth;
        struct
        {
            uint8 color[PALETTE_MAX][3];
            uint8 dirty[PALETTE_MAX];
            uint8 update;
        }pal;
    }t_bitmap;

 'data'     - Pointer to a linear chunk of memory. This should be at least
              256x192 pixels in size. You can modify this pointer between
              frames for double buffering (if it's pointed into memory mapped
              video RAM), or point it to system memory so further changes
              can be made. (like special effects, or for converting the
              graphics data to 24 or 32-bit format)
 'width'    - Width of the bitmap, in pixels.
 'height'   - Height of the bitmap, in pixels.
 'pitch'    - Width of the bitmap, in *bytes*.
 'depth'    - Color depth. Must be 8 or 16.
 'color'    - An array of 32 RGB values, each scaled up to eight bits.
 'dirty'    - Each entry is nonzero if the color has been modified.
 'update'   - Nonzero if one or more colors have been modified.

 If you are using 8-bit color, please note that each pixel drawn to
 the bitmap uses some extra unused bits during the rendering process.
 You can either mask out these bits using the PIXEL_MASK constant
 from 'system.h', or set palette ranges 20-3F, 40-5F to the same
 values as 00-1F.

 If you are using 16-bit color, you can ignore the members of the 'pal'
 structure. Remember to adjust the MAKE_PIXEL macro in 'render.h' to
 whatever format your display uses. By default it will make a 16-bit
 pixel in RGB 5:6:5 format.

 The macros BMP_X_OFFSET, BMP_Y_OFFSET, give the offset into the
 bitmap. This is because the SMS display takes up the entire bitmap,
 while the GG display is centered in the middle. These macros provide
 a convenient way to get the right offset.

 The PALETTE_MAX constant returns the size of the palette.
 This is currently set to 32 entries.

 2.) Sound
 ---------

 Sound emulation is handled through the following structure:

    typedef struct
    {
        int fps;             /* Set to 50 or 60 FPS for PAL or NTSC games */
        int sample_rate;     /* Set between 8000 and 48000 */
        int enabled;         /* 1= Init OK, 0= Sound disabled or error */
        int sample_count;    /* Length of buffer in samples */
        int buffer_size;     /* Size of buffer in bytes */
        int16 *output[2];    /* Left and right channels */
    } snd_t;

 You must call 'system_init()' and pass the desired sample rate as an
 parameter to enable sound emulation. You can set the sample rate to
 zero if you do not want sound emulation. Remember that 'snd.enabled'
 will be set afterwards to indicate if any errors occured.

 You also must call 'system_shutdown()' when you are done running
 the virtual console emulation, so some memory used by the sound
 emulation code can be freed.

 3.) Input
 ---------

 Input is handled through the following structure:

    typedef struct
    {
        int pad[2];
        int system;
    }t_input;

 'pad[]'    - Corresponds to joystick one and joystick two.
 'system'   - System buttons, specifically pause, start, and reset.

 During each frame, you should clear members of this structure to zero,
 then update each one using the INPUT_* constants in 'system.h'.

 4.) Game Images
 ---------------

 Game images are handled through the following structure:

    typedef struct
    {
        uint8 *rom;
        uint8 pages;
        uint8 type;
    }t_cart;

 'rom'      - Pointer to the ROM image.
 'pages'    - ROM size divided by 16k.
 'type'     - Set to either TYPE_SMS or TYPE_GG.

 Games can be identified by their extension, which is usually '.sms'
 or '.gg'. Some games have an optional 512-byte header which you must
 remove. Remember to adjust the file size accordingly.

 5.) Battery backed RAM
 ----------------------

 Some game cartridges can have up to 32k of battery backed RAM present.
 There are two variables relating to this:

    typedef struct
    {
        uint8 sram[0x8000];
        uint8 save;
    }t_sms;

 'sram'     - This is the data that should be saved and loaded.
 'save'     - This is nonzero if the contents of sram[] should be saved.

 It's impossible to know if a game will use battery backed RAM, so the
 emulation code waits until a game tries to read or write it, and then
 sets the 'save' flag meaning the data needs to be saved.

 The basic way to deal with this is:

 1. Load a game file
 2. If a file with the same name, and the extension .sav exists,
    then load that data into 'sram' and set the 'save' flag.
 3. When exiting, check if the 'save' flag is nonzero, and if so,
    write the contents of sram[] to a file with the extension .sav
    and the same filename as the game file loaded.

 Note that when system_reset() is called, the function 'system_load_sram'
 which has a prototype in 'system.h' will be called. You *must* implement
 this function. All it has to do is see if any saved battery backed RAM
 is present, and update the save/sram[] members accordingly.

 6.) Miscellaneous
 -----------------

 Before running the virtual console emulation, you can set up
 these two variables:

 sms.use_fm         :   0= No YM2413 sound, 1= YM2413 sound
 sms.country        :   Set to TYPE_DOMESTIC (Japan), TYPE_OVERSEAS

 Some games will display different text depending on the country
 setting. The default value is TYPE_OVERSEAS. This is suitable for every
 country but Japan.

 Some games have different music if the YM2413 sound chip is present.
 If the 'fm_enable' value is set to one, then games can detect it.

 If you want to use FM sound, you must ensure that 'use_fm' is nonzero
 before loading a game, since this variable controls if games can detect
 the YM2413 chip as well as actual YM2413 output.

 Some games will only enable YM2413 sound if the country type is
 also set to TYPE_DOMESTIC. One such example is Wonderboy 3.

 Both of these variables are preserved when system_reset() is called.

 You can call load_state/save_state to save and restore the current state
 of the virtual console emulation. You need to pass a file handle as
 a parameter to these functions. Therefore, you are responsible for ensuring
 the file exists, and the file name. The naming convention is that all
 state files are named '.st0' up to '.st9'.

 7.) Function reference
 ----------------------

    void system_init(int sound_rate);

 You must set up the 'bitmap' and 'cart' structures prior to calling this
 function. If you want sound emulation, pass the desired sample rate
 (8000..44100). Afterwards, check the members of the 'snd' structure to see
 if you can use sound emulation. You can now call system_frame() and the like.

    void system_shutdown(void);

 Call this when you're done with the emulation. Not terribly important
 as it only frees some memory allocated by the sound emulation routines...

    void system_reset(void)

 Reset the virtual console emulation. This is called internally when
 the INPUT_HARD_RESET flag for 'input.system' is set.

    void system_load_sram(void);

 Refresh the 'sms.sram[]' and 'sms.save' variables.
 You must impelement this function yourself.

    void system_frame(int skip);

 You need to call this function 60 times a second. Pass zero as the
 parameter to draw the current frame, otherwise pass one to omit
 the drawing process. (ideal for frame skipping) Afterwards,
 the 'bitmap' and 'snd' structures will be updated with the current
 graphics and sound data. You should set up the 'input' structure
 before calling this function.

 8.) Example
 -----------

 Here's a brief overview of how to use all this:

 - do machine dependant initialization (audio, video, init input, etc.)
 - set up bitmap structure
 - set up cart structure (load game)
 - call system_init()
 - if snd.enabled is set, we can use sound
 - load sram data if it exists for the game
 in a loop:
   - update input structure based on gamepad/keyboard
   - call system_frame()
   - play sound using 'snd.buffer'
   - copy 'bitmap.data' to the video display
   - quit if needed
 - save sram data if the game used it
 - call system_shutdown()

 9.) Other notes on porting
 --------------------------

 - Please read the license first. 

 - You must release the source code to your port in accordance with the GPL.

   If you have made *no* changes to the main source code, meaning everything
   in the root directory, and the cpu and dos directories, then you
   do not have to include those files. No point in wasting space.

   Otherwise, you must include those files with the changes clearly stated.
   If the changes are the kind that could benefit other ports (like a bug
   fix), then just let me know so I can update the main distribution, and
   don't bother releasing those files. But let me know before you release
   your port, however.

   If you are using some commercial libraries to take care of items like
   audio output, or if you have developed some routines which you do not want
   made public (i.e. an assembly optimized blitter, or some custom joypad
   polling functions), then you do not have to include those files.

   I prefer it where anybody can download a port of SMS Plus and compile it
   themselves, but I realize this isn't always possible.

   It would be nice, and is not required, that you could organize the
   source in the same way I have it set up. For instance, maintaining the
   same directory structure, but adding an '/myport' directory with your
   specific files, and an appropriate makefile.

 - You must clearly state in the executable that you are the porter,
   and that I wrote the program. Include YOUR contact information (e-mail
   address, website URL). This is so users will not ask me questions on how
   to use a specific port, which I know nothing about.

 - You need to provide documentation. Please remember to mention
   the licensing stuff pertaining to SMS Plus and the MAME code that's
   mentioned (for example) in the original 'readme' I wrote. Or just
   include my documentation and make some additions.

   Please link to my website in the documentation, so people will know
   where to get the original source code.
