romdev-mcp 0.1.1

package/src/platforms/genesis/lib/sgdk/include/ext/flash-save/flash.h

@@ -0,0 +1,164 @@
+/**
+ * \file flash.h
+ * \brief Low level NOR flash read/erase/write interface.
+ * \author Jesus Alonso (doragasu)
+ * \date 08/2022
+ *
+ * This module allows reading, erasing and writing data from/to the
+ * cartridge flash chip. It should work with any flash chip compatible with
+ * the AMD format, and implementing a CFI interface. It has been tested
+ * successfully with S29GL032 and W29GL032C chips. Also it is required that
+ * the cart has the #WE line connected to the flash chip (that should be the
+ * case on most flash carts, but is not guaranteed).
+ *
+ * \note The module has some limitations: addresses must be even, data pointers
+ * must be word aligned, and some functions (flash_init(), flash_sector_erase()
+ * and flash_program()) must be run with interrupts disabled and Z80 stopped.
+ * Please also take into account that flash suffers from wear, so if you use
+ * this e.g. for saving data, avoid saving very frequently and/or implement
+ * a wear leveling algorithm to avoid damaging the chip.
+ *
+ * \note Although it is not a requirement for this module to work, it is
+ * strongly recommended that the cart you use also has the #RESET pin connected
+ * to the console #RESET signal. Otherwise, if the user pushes the RESET
+ * button while the flash chip is being erased/programmed, the machine will
+ * most likely freeze, requiring another press of the RESET button or a power
+ * cycle.
+ */
+
+#ifndef __FLASH_H__
+#define __FLASH_H__
+
+// I usually include stdint.h, but SGDK defines some stdint types here:
+#include "types.h"
+
+// Maximum number of flash regions. CFI standard allows up to 4
+#define FLASH_REGION_MAX 4
+
+/**
+ * \brief Metadata of a flash region, consisting of several sectors.
+ * \{/
+ */
+struct flash_region {
+	uint32_t start_addr;    //< Sector start address
+	uint16_t num_sectors;   //< Number of sectors
+	uint16_t sector_len;	//< Sector length in 256 byte units
+};
+/** \} */
+
+/**
+ * \brief Metadata of a flash chip, describing memory layout.
+ * \{
+ */
+struct flash_chip {
+	uint32_t len;                  //< Length of chip in bytes
+	uint16_t num_regions;          //< Number of regions in chip
+	struct flash_region region[FLASH_REGION_MAX]; //< Region data array
+};
+/** \} */
+
+/**
+ * \brief Initialise flash chip. Call this function only once, before any
+ * other function in the module.
+ *
+ * \warning This function must be called with interrupts disabled and
+ * Z80 stopped.
+ */
+int16_t flash_init(void);
+
+/**
+ * \brief Deinitialise flash chip.
+ */
+void flash_deinit(void);
+
+/**
+ * \brief Get chip metadata.
+ *
+ * \return An immutable reference to the chip metadata.
+ */
+const struct flash_chip *flash_metadata_get(void);
+
+/**
+ * \brief Erases a flash sector. Erased sectors will be read as 0xFF.
+ *
+ * \param[in] addr Any even address contained in the sector to erase.
+ *
+ * \note This function erases a complete sector. Use flash_sector_limits()
+ * function to obtain the sector limits that will be erased.
+ * \warning If addr is not even, this function can lock the machine.
+ * \warning This function must be called with interrupts disabled and
+ * Z80 stopped.
+ *
+ * \return The address of the next sector to the one erased on success,
+ * 0 on error.
+ */
+uint32_t flash_sector_erase(uint32_t addr);
+
+/**
+ * \brief Programs (writes) a data buffer to the specified flash address.
+ *
+ * \param[in] addr Address to which data will be programmed.
+ * \param[in] data Buffer containing the data to program.
+ * \param[in] len  Length of the data buffer to write.
+ *
+ * \return The number of written bytes on success, 0 on error.
+ *
+ * \warning Before using this function, make sure the address range to program
+ * is erased. Otherwise this function can lock the machine.
+ * \warning If addr is not even, this function can lock the machine.
+ * \warning If data is not word aligned, this function can lock the machine.
+ * \warning If data is not in work RAM, this function can lock the machine.
+ * \warning If len is odd, the last byte will not be written.
+ * \warning This function must be called with interrupts disabled and
+ * Z80 stopped.
+ */
+uint16_t flash_program(uint32_t addr, const uint8_t *data, uint16_t len);
+
+/**
+ * \brief Reads data from the specified flash address.
+ *
+ * \param[in]  addr Address to read data from.
+ * \param[out] data Buffer used to copy readed data.
+ * \param[in]  len  Length of the data block to read.
+ *
+ * \return The number of read bytes.
+ *
+ * \warning addr must be even.
+ * \warning data must be word aligned.
+ * \warning If len is odd, the last byte will not be read.
+ */
+int16_t flash_read(uint32_t addr, uint8_t *data, uint16_t len);
+
+/**
+ * \brief Copy data from a flash region to other region also in flash.
+ *
+ * \param[in] dst Destination address to copy data to.
+ * \param[in] src Source address to copy data from
+ * \param[in] len Length of the data block to copy.
+ *
+ * \return The number of copied bytes.
+ *
+ * \warning dst and src must be even.
+ * \warning If len is odd, the last byte will not be copied.
+ * \warning Before using this function, make sure the dst region is erased.
+ * Otherwise this function can lock the machine.
+ * \warning This function must be called with interrupts disabled and
+ * Z80 stopped.
+ */
+int16_t flash_copy(uint32_t dst, uint32_t src, uint16_t len);
+
+/**
+ * \brief Obtains the sector limits (start of sector, start of next sector)
+ * corresponding to the specified address.
+ *
+ * \return 0 on success, -1 if input address does not fit in the chip.
+ *
+ * \param[in]  addr  Address corresponding to the sector to get info from.
+ * \param[out] start Start address of the sector. Can be NULL if this
+ *             parameter is not needed.
+ * \param[out] next  Start address of the sector next to the current one.
+ *                   Can be NULL if this parameter is not needed.
+ */
+int16_t flash_sector_limits(uint32_t addr, uint32_t *start, uint32_t *next);
+
+#endif

package/src/platforms/genesis/lib/sgdk/include/ext/flash-save/saveman.h

@@ -0,0 +1,177 @@
+/**
+ * \file saveman.h
+ * \brief Save manager for flash memory chips supported by the flash module.
+ * \author Jesus Alonso (doragasu)
+ * \date 10/2022
+ *
+ * This module allows saving data to non volatile flash chips. It supports as
+ * many save slots as required, and arbitrary data lengths can be written to
+ * each slot. This allows defining for example a 5 slot layout that uses slot
+ * 0 for the game configuration, slot 1 to keep high scores and slots 2 to 4 to
+ * save games. Each time data is written to a slot, it replaces whatever was
+ * written to the slot previously.
+ *
+ * The module uses two sectors from the flash chip in order to implement flash
+ * wear leveling and safe save: the save file is not lost even if there is a
+ * power cut during save operation. Note that typical flash chips used in carts
+ * such as Krikkzz Flash Kit Cart use 64 KiB sectors at the end of the flash, so
+ * if you want to use this module, it will use the top 128 KiB of the ROM
+ * address space by default. Keep this in mind because if code/data falls there,
+ * it will be erased by this module routines, breaking your game! There is also
+ * a way to use 8 KiB sectors from these carts, in order to waste 16 KiB instead
+ * of 128 KiB, but it is a bit tricky, so unless you are very tight on ROM
+ * space, better use the default layout. Using the default 128 KiB layout has two
+ * additional benefits: wear is reduced and bigger save lengths are possible.
+ *
+ * Note when you define the slot layout, you must make sure all of them fit in
+ * a single sector (plus a bit more room for internal headers). So e.g. if you
+ * use 64 KiB sectors and have 5 slots with 2 KiB each, that will fit without a
+ * problem, but if you use 8 KiB sectors, that config will not fit (5 x 2 KiB =
+ * 10 KiB, bigger than the 8 KiB available in the sector). Make sure your
+ * sector configuration is correct, because if it isn't, the module will work
+ * initially, but will fail when more slots are saved and they do not fit in
+ * one sector.
+ *
+ * Typical usage of the module is as follows:
+ *
+ * 1. Call sm_init() to initialize the module. Make sure it is always called
+ *    with the same parameters.
+ * 2. Call sm_load() to load data, sm_save() to save data and sm_delete() to
+ *    delete saved data.
+ * 3. In case you need to perform a factory reset, call sm_clear().
+ *
+ * The module has been carefully written, but some of its logic is a bit
+ * complex, so make sure you test it thoroughly just in case there is a bug
+ * lurking inside!
+ *
+ * \note Excepting sm_load(), all module functions stop Z80 and disable
+ * interrupts until they return. Thus you shall make sure no music or sound
+ * is playing when you call them.
+ * \warning Save/load buffers must be word aligned or you will get a
+ * SM_STAT_INVALID_PARAM_ERR error. Variables using types with a length equal
+ * or bigger than 2 bytes will be aligned (same as structs with at least one
+ * variable obeying this rule), but if variable has a type with length 1 (such
+ * as a char array), to make sure it is aligned, you can use the attribute:
+ * __attribute__((aligned(2))) in the declaration.
+ * \warning If any save write operation returns a SM_STAT_HW_ERR, something
+ * weird has occurred. Your best chance if this happens is to either restart
+ * the console or at least deinit and init this module to let the init routine
+ * try correcting the mess and avoid further data loss.
+ */
+
+#ifndef _SAVEMAN_H_
+#define _SAVEMAN_H_
+
+#include "types.h"
+
+/**
+ * \brief Status code for some of the function calls
+ * \{/
+ */
+enum {
+	SM_STAT_PARAM_ERR = -3,   ///< Invalid parameter in function call
+	SM_STAT_HW_ERR = -2,      ///< Flash chip hardware related error
+	SM_STAT_ERR = -1,         ///< Generic error
+	SM_STAT_OK = 0,           ///< Success
+	SM_STAT_WARN_NO_DATA = 1, ///< Success, chip has no data saved
+};
+/** \} */
+
+/**
+ * \brief Initialise save manager module. Must be called once before invoking
+ * any other function in the module.
+ *
+ * \param[in] num_slots Number of save slots to support.
+ *
+ * \return Status code:
+ * - SM_STAT_OK if initialisation was successful and flash has data to load.
+ * - SM_STAT_WARN_NO_DATA if initialisation was successful but there is no
+ *   save data to load.
+ * - SM_STAT_PARAM_ERR if function was called with invalid parameters.
+ * - SM_STAT_HW_ERR if the flash chip failed to perform any operation.
+ * - SM_ERR if other unrecoverable error was found.
+ *
+ * \note This function internally calls flash_init(), you must not call it
+ * by yourself.
+ * \note This function halts Z80 and disables interrupts until done.
+ * \note This module uses the two adjacent sectors in the memory range
+ * specified in the ROM header at offset 0x1B4. If the range does not exactly
+ * match two flash adjacents sectors, function will return SM_STAT_PARAM_ERR.
+ * Make sure you read and understand the save manager README.md file.
+ * \warning The two flash sectors used by this module must not have code. If
+ * there is code in there, it will be deleted. Don't make your game erase
+ * itself!
+ */
+int16_t sm_init(uint8_t num_slots);
+
+/**
+ * \brief Deinitialises save manager module. Usually you do not have to use
+ * this function.
+ */
+void sm_deinit(void);
+
+/**
+ * \brief Load previously saved data for the specified slot.
+ *
+ * \param[in]  slot Slot from which we want to load the data.
+ * \param[out] save_data Buffer in which loaded data will be copied.
+ * \param[in]  len Length of the data to load.
+ *
+ * \return A positive number with the loaded data length, or a negative
+ * error status code:
+ * - SM_STAT_PARAM_ERR: Invalid parameter in invocation.
+ * - SM_STAT_ERR: The requested slot has no data available.
+ *
+ * \note Readed bytes can be less than len if there is an error (e.g. 0 if the
+ * slot has no data, or less than len if less data than requested was saved).
+ */
+int16_t sm_load(uint8_t slot, void *save_data, uint16_t len);
+
+/**
+ * \brief Save data to the specified slot.
+ *
+ * \param[in] slot Slot to which we want to save the data.
+ * \param[in] save_data Data buffer to save in the slot.
+ * \param[in] len Length of the data to save.
+ *
+ * \return Status code:
+ * - SM_STAT_OK: Save operation successful.
+ * - SM_STAT_PARAM_ERR: Invalid parameter in invocation.
+ * - SM_STAT_HW_ERR: Save operation failed due to flash error.
+ * - SM_STAT_ERR: Other unrecoverable error.
+ *
+ * \note Readed bytes can be less than len if there is an error.
+ * \note This function halts Z80 and disables interrupts until it done.
+ */
+int16_t sm_save(uint8_t slot, const void *save_data, uint16_t len);
+
+/**
+ * \brief Delete data from specified slot
+ *
+ * \param[in] slot Slot to delete.
+ *
+ * \return Status code:
+ * - SM_STAT_OK: Delete operation successful.
+ * - SM_STAT_PARAM_ERR: Invalid parameter in invocation.
+ * - SM_STAT_HW_ERR: Delete operation failed due to flash error.
+ * - SM_STAT_ERR: Other unrecoverable error.
+ *
+ * \note This function halts Z80 and disables interrupts until it done.
+ */
+int16_t sm_delete(uint8_t slot);
+
+/**
+ * \brief Deletes all save data from all save slots, and reinitializes the
+ * module to support the requested number of save slots.
+ *
+ * \param[in] num_slots Number of slots to support after data clear.
+ *
+ * \return Status code:
+ * - SM_STAT_OK: Clear operation successful.
+ * - SM_STAT_HW_ERR: Flash chip failed to erase.
+ *
+ * \note This function halts Z80 and disables interrupts until it done.
+ */
+int16_t sm_clear(uint8_t num_slots);
+
+#endif

package/src/platforms/genesis/lib/sgdk/include/ext/link_cable.h

@@ -0,0 +1,316 @@
+/**
+ * Link Cable Protocol (LCP) - Protocol for data exchange via SEGA Link Cable
+ * between two Sega Mega Drive / Sega Genesis consoles connected through the second controller port
+ * for SGDK
+ *
+ * BlodTor 2025
+ *
+ * *************************************************************************************************
+ * *************************************************************************************************
+ * Master console function call sequence:
+ *
+ * 1) Initialize Link Cable Protocol.
+ * LCP_init();
+ *
+ * 2) Prepare data for transmission from master console via Link Cable Protocol.
+ * LCP_objectToPacketForSend(transferObject, objectType, objectTypeSizes);
+ * LCP_objectToPacketForSend(transferObject, objectType, objectTypeSizes);
+ * ...
+ * LCP_objectToPacketForSend(transferObject, objectType, objectTypeSizes);
+ *
+ * 3) Trigger external interrupt on slave console and send/receive data via Link Cable Protocol
+ * LCP_masterCycle();
+ *
+ * 4) Extract received objects from packet transmitted by slave console
+ * objectType = LCP_getNextObjectFromReceivePacket(transferObject, objectSizes);
+ * objectType = LCP_getNextObjectFromReceivePacket(transferObject, objectSizes);
+ * ...
+ * objectType = LCP_getNextObjectFromReceivePacket(transferObject, objectSizes);
+ * until objectType becomes 0
+ *
+ * 5) Close Link Cable Protocol if no further interaction with slave console is required.
+ * LCP_close();
+ *
+ * *************************************************************************************************
+ * *************************************************************************************************
+ * Slave console function call sequence:
+ *
+ * 1) Initialize Link Cable Protocol
+ * LCP_init();
+ *
+ * 2) Open port to enable slave console to handle external interrupts triggered by
+ *    master console. Master console can only call LCP_slaveCycle() - the external
+ *    interrupt handler on slave console - after this method is called.
+ * LCP_open();
+ *
+ * 3) Prepare data for transmission from slave console via Link Cable Protocol.
+ *    Transmission occurs in LCP_slaveCycle() after receiving data from master console
+ *    in this method. LCP_slaveCycle() is called asynchronously by suspending game code
+ *    execution on slave console when external interrupt from LCP_masterCycle() method
+ *    of master console occurs.
+ * LCP_objectToPacketForSend(transferObject, objectType, objectTypeSizes);
+ * LCP_objectToPacketForSend(transferObject, objectType, objectTypeSizes);
+ * ...
+ * LCP_objectToPacketForSend(transferObject, objectType, objectTypeSizes);
+ *
+ * 4) Extract received objects from packet transmitted by master console
+ * objectType = LCP_getNextObjectFromReceivePacket(transferObject, objectSizes);
+ * objectType = LCP_getNextObjectFromReceivePacket(transferObject, objectSizes);
+ * ...
+ * objectType = LCP_getNextObjectFromReceivePacket(transferObject, objectSizes);
+ * until objectType becomes 0
+ *
+ * 5) Close Link Cable Protocol if no further interaction with master console is required.
+ *    Slave console will stop responding to external interrupts from master console!
+ * LCP_close();
+ *
+ * *************************************************************************************************
+ * *************************************************************************************************
+ * IMPORTANT USAGE NOTES:
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ *
+ * Object types (objectType) must be defined in YOUR game's main code!
+ * See constant declaration examples in 'Super Turbo MEGA Pac-Man 2.1' game code
+ * starting with 'OBJECT_TYPE_' prefix
+ *
+ * Object sizes (objectSizes) in bytes must be defined in YOUR game's main code!
+ * The protocol transfers 2 bytes of information per cycle, so there's no point in setting
+ * object lengths not multiples of 2 bytes! See constant declaration examples in
+ * 'Super Turbo MEGA Pac-Man 2.1' game code ending with '_OBJECT_LENGTH' postfix,
+ * as well as the LINK_TYPES_LENGHT array definition example which is passed as objectSizes
+ * parameter to LCP_objectToPacketForSend() and LCP_getNextObjectFromReceivePacket() functions
+ *
+ * Master/Slave console determination implementation must be in YOUR game's code!
+ * See initControllerPort2() function example in 'Super Turbo MEGA Pac-Man 2.1' game code
+ * which determines which of the two consoles becomes master and which becomes slave
+ *
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ *
+ * For debugging, use the function that returns transmission errors via SEGA Link Cable:
+ * LCP_getError()
+ *
+ */
+#ifndef _LINK_CABLE_H_
+#define _LINK_CABLE_H_
+
+#include "config.h"
+
+#if (MODULE_LINK_CABLE != 0)
+
+#include "types.h"
+
+/**
+ * Constants
+ */
+
+// Input/output direction for SEGA MD console port 2 (set individually for each bit)
+// Determines the data line operation mode (input or output) and controls the interrupt request mask from external devices.
+// Essentially, this is memory address 0xA1000B for data transfer control
+// via SEGA Link Cable (CTRL port register CTRL 2 in SEGA documentation)
+// Bit 7 (INT) - Interrupt on SYN line signal. 0 = disabled; 1 = enabled.
+// Bit 6 (PC6) - Data line "SYN" mode. 0 = input; 1 = output.
+// Bits 0-5 (PC0-PC5) - Data line mode. 0 = input; 1 = output.
+#define LCP_Ctrl   				(*(vu8*) 0xa1000b)
+
+// State of port 2 on SEGA MD console
+// Essentially, this is memory address 0xA10005 for direct data transfer
+// via SEGA Link Cable (DATA register of CTRL port 2 in SEGA documentation)
+//
+// Lower 4 bits (0-3) are used for data transfer.
+//
+// Bit addressing features between consoles:
+// Bit 5 in the current console corresponds to bit 6 in the other console
+// for the same memory address 0xA10005. If we change bit 5 on our console,
+// bit 6 will change in the other console's LCP_Data variable, and vice versa -
+// if bit 5 is changed on the other console, bit 6 will change on our console.
+//
+// Bits 0-3 at address 0xA10005 will have the same value in both consoles,
+// i.e., if we change these bits on one console, they will also change on the other.
+// Which console is currently responsible for this is determined by the LCP_Ctrl state -
+// i.e., which data line is in output mode (sending data),
+// and which is in input mode (receiving data).
+#define LCP_Data   				(*(vu8*) 0xa10005)
+
+// Bit 5 is set to 1, others to 0. Primarily used to set bit 5 to 1
+// in LCP_Data and LCP_Ctrl to signal the other console that it can
+// read or send data via Link Cable.
+#define LCP_BIT5				0b00100000
+
+// Bit 6 is set to 1, others to 0. Mainly used to determine
+// whether bit 6 is set in LCP_Data, signaling that
+// data can be read from the other console or sent to the other console via Link Cable.
+#define LCP_BIT6				0b01000000
+
+// Bits 7 and 5 are set to 1, other bits are 0. Used to set these bits in LCP_Ctrl, which indicates
+// readiness for data exchange through console port 2 upon external interrupt EX-INT (External Interrupt
+// in SEGA documentation), i.e., reading data from the port (data reception) in the external interrupt handler LCP_slaveCycle().
+//
+// LCP_Ctrl bit values:
+// - Interrupt on SYN line signal enabled, bit 7 = 1
+// - Data line PC5 in output mode (transmission), bit 5 = 1
+// - Data lines PC6, PC4, PC3, PC2, PC1, PC0 in input mode (reception). Corresponding bits = 0
+//
+// At the "hardware" level for my code this means:
+// - Enable pins 0-3 of controller port 2 for data reception
+// - Pin 5 signals that data has been received by our console (on the other console this will be bit 6 in LCP_Data)
+// - Pin 6 signals that data has been sent by the other console (the other console should change bit 5 in its LCP_Data)
+#define	LCP_BIT7_AND_BIT5 		0b10100000;
+
+// Bits 5, 3, 2, 1, 0 are set to 1, others are 0. Used to set these bits in LCP_Ctrl, which means
+// starting the data write cycle to port 2 (data transmission) by triggering an external interrupt on the slave console.
+//
+// I.e., on the master console, the LCP_masterCycle() method should be called from the main game code, which will set
+// the bits in LCP_Ctrl to the state specified above, and on the slave console we will previously trigger an external
+// interrupt that will halt the main game code execution and call the LCP_slave() method. This will occur when on the
+// master console the 5th bit in LCP_Data is reset to 0 in the LCP_startSendCycle() method.
+//
+// LCP_Ctrl bit values:
+// - Interrupt on SYN line signal disabled, bit 7 = 0
+// - Data lines PC5, PC3, PC2, PC1, PC0 in output mode (transmission), bits 5, 3, 2, 1, 0 = 1
+// - Data lines PC6, PC4 in input mode (reception). Corresponding bits = 0
+//
+// At the "hardware" level for my code this means:
+// - Enable pins 0-3 of controller port 2 for data transmission
+// - Pin 5 signals that data can be read by the other console (on the other console this will be bit 6 in LCP_Data)
+// - Pin 6 signals that data has been read by the other console (the other console should change bit 5 in its LCP_Data)
+#define LCP_BIT_5_3_2_1_0 		0b00101111;
+
+// Mask 00001111. Mainly used to reset the high 4 bits in a byte to 0
+#define LCP_LO_BITS 			0b00001111
+
+// Mask 11110000. Mainly used to reset the low 4 bits in a byte to 0
+#define LCP_HI_BITS  			0b11110000
+
+// Timeout - used for waiting for data from the other console (waiting for reset or set of bit 6 in LCP_Data)
+#define LCP_TIME_OUT 			0x40
+
+// Maximum packet size for data transmission via Link Cable
+#define LCP_PACKET_SIZE			2048
+
+
+/**
+ * Library function declarations
+ */
+
+
+/**
+ * Opening port 2 of the console for data exchange via Link Cable
+ * upon external interrupt - External Interrupt (EX-INT)
+ * interrupt mask level 2 for Motorola 68000 processor
+ * setting up a callback function called when EX-INT interrupt occurs
+ */
+void LCP_open();
+
+
+/**
+ * Initialization of console port 2 for data exchange via Link Cable
+ * for direct data writing to the port and subsequent data reading from the port.
+ * EX-INT interrupts are disabled for this console.
+ * Reset of global variables.
+ */
+void LCP_init();
+
+
+/**
+ * Closing the console port for data exchange via Link Cable
+ * disabling the external interrupt handler - External Interrupt (EX-INT)
+ * interrupt mask level 2 for Motorola 68000 processor
+ */
+void LCP_close();
+
+
+/**
+ * Function for copying the transferObject as a byte array
+ * into the LCP_sendPacket for transmission via Link Cable.
+ *
+ * Packet structure:
+ * - First 2 bytes contain the type of transmitted object (cannot be 0)
+ * - Followed by object data (2 bytes each) according to objectTypeSizes table
+ *
+ * Multiple objects can be transmitted at once, as long as they fit in the buffer.
+ * It is assumed that the function can be called multiple times in sequence until
+ * the errors described below occur.
+ *
+ * Error codes (error code = LCP_error & 0x000F):
+ * 0xC - transmitted object size is negative or zero
+ * 0xD - transmitted object size exceeds remaining packet space
+ * 0xF - packet data start index is greater than data end index
+ *
+ * Parameters:
+ * transferObject - object to send as byte array via Link Cable
+ * objectType - type of object to send (number corresponding to index in object sizes array)
+ * objectTypeSizes - array of object sizes (defined in YOUR main game code)
+ */
+void LCP_objectToPacketForSend(u8 *transferObject, u16 objectType , u16 *objectTypeSizes);
+
+
+/**
+ * Function extracts the next object as a byte array transferObject from the received LCP_ReceivePacket
+ * via Link Cable and returns the type of this object or 0 if the object could not be extracted from LCP_ReceivePacket.
+ *
+ * Since multiple objects can be transmitted at once, it is assumed that this function can be called
+ * multiple times in sequence until 0 is returned, meaning - all objects have been extracted from the transmitted packet.
+ *
+ * Packet structure:
+ * - First 2 bytes of LCP_ReceivePacket contain the type of transmitted object (cannot be 0)
+ * - Followed by object data (2 bytes each) according to objectSizes table
+ * - Multiple objects can be transmitted at once, as long as they fit in the LCP_ReceivePacket array
+ *
+ * Error codes (error code = LCP_error & 0xF000):
+ * 0x1000 - no object in received packet, all objects already extracted or nothing was transmitted
+ * 0x2000 - size of object to extract from read packet buffer is negative or zero
+ * 0x3000 - size of object to extract exceeds remaining data in received packet
+ * 0x4000 - size of object to extract exceeds remaining size of LCP_ReceivePacket array
+ *
+ * Parameters:
+ * transferObject - next received object as byte array via Link Cable
+ * objectSizes - array of object sizes (defined in YOUR main game code)
+ *
+ * Returns:
+ * type of received object or 0 if object could not be extracted from received packet
+ */
+u16 LCP_getNextObjectFromReceivePacket(u8 *transferObject, u16 *objectSizes);
+
+
+/**
+ * Data transmission and reception cycle via Link Cable for SEGA master console
+ * At the very beginning, disable all interrupt processing and reset LCP_timeOut and LCP_error to 0.
+ * Both in case of error and successful function completion (i.e. always), call LCP_masterCycleEnd() at the end
+ * to set console port 2 to correct state and enable all interrupt processing.
+ *
+ * Error codes (error code = LCP_error & 0x00F0):
+ * 0x10 - error calling LCP_startSendCycle() - start of data transmission from master console
+ * 0x20 - error calling LCP_send(size) - transmission of 2 bytes (packet size) from master console
+ * 0x30 - error calling LCP_send(data) - transmission of 2 bytes (packet data) from master console
+ * 0x40 - error calling LCP_send(checksum) - transmission of 2 bytes (checksum) from master console
+ * 0x50 - error calling LCP_endSendCycle() - end of main packet transmission cycle from master to slave console
+ * 0x60 - error calling LCP_startReceiveCycle() - start of data reception cycle from slave to master console
+ * 0x70 - error calling checksum = LCP_Receive() - reception of 2 bytes (packet checksum) from slave console
+ * 0x80 - checksum calculated by master console != checksum received from slave console
+ * 0x90 - error calling size = LCP_Receive() - reception of 2 bytes (packet size) from slave console
+ * 0xA0 - error calling data = LCP_Receive() - reception of 2 bytes (packet data) from slave console
+ * 0xB0 - error calling checksum = LCP_Receive() - main reception cycle of 2 bytes (checksum) from slave console
+ * 0xC0 - checksum calculated by master console != checksum received from slave console
+ * 0xD0 - error calling LCP_endReceiveCycle() - end of data reception cycle from slave console
+ * 0xE0 - error calling LCP_startSendCycle() - start of checksum transmission from master to slave console
+ * 0xF0 - error calling LCP_send(checksum) - transmission of checksum from master to slave console
+ */
+void LCP_masterCycle();
+
+
+/**
+ * Error in data transmission via SEGA Link Cable
+ *
+ * If 0x0000, no errors occurred!                                        Value ranges     in binary format
+ * Lower 4 bits of low byte  - data reception errors via Link Cable    (0x0001 - 0x000F)  000000000000xxxx
+ * Upper 4 bits of low byte  - data transmission errors via Link Cable (0x0010 - 0x00F0)  00000000xxxx0000
+ * Lower 4 bits of high byte - packet reception or transmission errors (0x0100 - 0x0F00)  0000xxxx00000000
+ * Upper 4 bits of high byte - object extraction errors from packet    (0x1000 - 0xF000)  xxxx000000000000
+ *
+ * return LCP_error
+ */
+u16 LCP_getError();
+
+#endif // MODULE_LINK_CABLE
+
+#endif // _LINK_CABLE_H

package/src/platforms/genesis/lib/sgdk/include/ext/minimusic/minimus.h

@@ -0,0 +1,29 @@
+#ifndef MINIMUS_H_
+#define MINIMUS_H_
+
+// SGDK replacement for stdint.h
+#include "types.h"
+
+#define MINIMUSIC_MEMORY_BARRIER() asm volatile ("" : : : "memory")
+
+static inline void MINIMUSIC_Z80_GUARD_BEGIN() {
+   volatile uint16_t *port = (uint16_t*)(0xA11100);
+   MINIMUSIC_MEMORY_BARRIER();
+   *port = 0x100;
+   MINIMUSIC_MEMORY_BARRIER();
+}
+
+static inline void MINIMUSIC_Z80_GUARD_END() {
+   volatile uint16_t *port = (uint16_t*)(0xA11100);
+   MINIMUSIC_MEMORY_BARRIER();
+   *port = 0x000;
+   MINIMUSIC_MEMORY_BARRIER();
+}
+
+#define MINIMUSIC_STATUS_BGM        0x01
+
+void minimusic_init(const void *, uint16_t);
+void minimusic_sendcmd(uint8_t);
+uint8_t minimusic_get_status(void);
+
+#endif