How to use devkitSMS/SMSlib to code your own Master System/Game Gear program:

• include SMSlib.h in your sources
• compile your program:

  sdcc -c -mz80 --peep-file peep-rules.txt your_program.c

• link your program with crt0_sms.rel and the SMSlib library:

  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 crt0_sms.rel your_program.rel SMSlib.lib

note that you should put crt0_sms.rel first, and you should put the library after your code.

How to use devkitSMS/SGlib to code your own SG-1000/SC-3000 program:

• include SGlib.h in your sources
• compile your program:

  sdcc -c -mz80 your_program.c

• link your program with crt0_sg.rel and SGlib.lib (a.k.a. "the SG library"):

  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 crt0_sg.rel your_program.rel SGlib.lib

note that you should put crt0_sg.rel first, and you should put SGlib.lib after your code.

How to load your devkitSMS/SGlib code onto a BASIC IIIa/IIIb cartridge:

Software written with SGlib can be loaded to a BASIC cartridge on the SC-3000. The BASIC LOAD command loads the program over the cassette interface to address 0x9800. Once loaded, the program can be run with the CALL &H9800 command.

• Link with crt0_BASIC.rel instead of crt0_sg.rel, and used --code-loc 0x90a0 to place the code after the interrupt handler.

  sdcc -o your_program.ihx -mz80 --no-std-crt0 --code-loc 0x98a0 --data-loc 0xC000 crt0_BASIC.rel your_program.rel SGlib.lib

• Convert the compiler's hex output to binary

  objcopy -Iihex -Obinary your_program.ihx your_program.bin

• Convert the binary into an SC-3000 formatted audio file using a tool such as SC-TapeWave
• Note that the program size is limited. BASIC IIIa has 12 KiB of RAM following the load address. BASIC IIIb has 26 KiB.

How to use devkitSMS/SGlib to code your own ColecoVision program:

• include SGlib.h in your sources
• compile your program using the TARGET_CV define:

  sdcc -c -mz80 -D TARGET_CV your_program.c

• link your program with crt0_cv.rel and SGlib_CV.lib (a.k.a. "the SG library for ColecoVision"):

  sdcc -o your_program.ihx -mz80 --no-std-crt0 --code-loc 0x8080 --data-loc 0x6000 crt0_cv.rel your_program.rel SGlib_CV.lib

note that you should put crt0_cv.rel first, and you should put SGlib_CV.lib after your code.

How to use devkitSMS/PSGlib to use PSG audio/SFX in your SMS/GG/SG/SC program:

• include PSGlib.h in your sources
• compile your program

  sdcc -c -mz80 your_program.c

• link your program with proper crt0 and libraries, adding PSGlib.lib too after the proper library:

  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 crt0_sms.rel your_program.rel SMSlib.lib PSGlib.lib

How to use devkitSMS/PSGlib to use PSG audio/SFX in your ColecoVision program:

• include PSGlib.h in your sources
• compile your program using the TARGET_CV define:

  sdcc -c -mz80 -D TARGET_CV your_program.c

• link your program with with crt0_cv.rel and SGlib_CV.lib and adding the PSGlib_CV.lib library too:

  sdcc -o your_program.ihx -mz80 --no-std-crt0 --code-loc 0x8080 --data-loc 0x6000 crt0_cv.rel your_program.rel SGlib_CV.lib PSGlib_CV.lib

How to add external data into your ROM:

• use the assets2banks utility included, for example. This is the suggested way. Read its documentation
• alternatively, you use the folder2c utility included It creates a .c source file (with its .h header file) containing one constant data array for each single file found in the specified dir:

  folder2c assets data [<ROM bank #>]

this creates data.c and data.h from the files found inside assets subfolder.

Each array will be named from the original filename, replacing spaces, periods and brackets with an underscore (it doesn't convert any other char so please use only alphanumeric chars). For each array there will be a #define into the .h file specifying the size in bytes, and it'll be called [arrayname]_size. If a numerical third parameter is specified (it's optional), its value will be used in the .h file for an additional #define called [arrayname]_bank for each asset.

How to use more than 48 KiB in your SMS/GG/SG/SC ROM ('SEGA ROM paging'):

• in your program, use the SMSlib provided macro SMS_mapROMBank(n) (or the SGlib provided macro SG_mapROMBank(n)) to map the bank you need. Note that your code should be restrained to the first 32 KiB as the last 16 KiB will be paged out and any code there won't be accessible unless the bank is manually mapped in the address space. If you need more than 32 KiB of code, read the section titled "How to use more than 32 KiB of code in your SMS/GG/SG/SC ROM" at the end of this document.

• put your data into a separate .c file for each 16 KiB ROM bank starting from bank2, for example bank2.c, bank3.c etc... (you can use the assets2banks and/or folder2c tools described above) compiling each one with a different CONST segment name, I suggest using BANK# for descriptiveness:

  sdcc -c -mz80 --constseg BANK2 bank2.c
  sdcc -c -mz80 --constseg BANK3 bank3.c

• compile your program:

  sdcc -c -mz80 --peep-file peep-rules.txt your_program.c

• link all the objects together adding a parameter for the linker for each bank (_BANK#) and adding each .rel file to be linked (proper crt0 file goes always first) then all the bank#.rel files last, in ascending order:

  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 -Wl-b_BANK2=0x28000 -Wl-b_BANK3=0x38000 crt0_sms.rel your_program.rel SMSlib.lib bank2.rel bank3.rel

How to build the final .sms/.gg/.sg file:

• use the makesms utility included. Input file is the ihx generated by SDCC linker, the output file is the generated ROM:

  makesms your_program.ihx your_program.sms

The size of the ROM will be a multiple of 16 KiB. The utility also calculates the ROM checksum for the output file if the SEGA header has been included in your program.

How to use more than 32 KiB in your ColecoVision ROM ('MegaCart ROM paging'):

• in your program, use the SGlib provided SG_mapROMBank(n) macro to map the bank you need (your code should be restrained to 16 KiB as the second half of address space will be paged out)

• put your data into a separate .c file for each 16 KiB ROM bank starting from bank1, for example bank1.c, bank2.c etc... (you can use the assets2banks and folder2c tools described above) compiling each one with a different CONST segment name, I suggest using BANK# for descriptiveness. Note that only 16,320 bytes (16 KiB - 64 bytes) are available in each ROM bank.

  sdcc -c -mz80 --constseg BANK1 bank1.c
  sdcc -c -mz80 --constseg BANK2 bank2.c

• compile your program:

  sdcc -c -mz80 -D TARGET_CV your_program.c

• link all the objects together adding a custom parameter for the linker for each bank (_BANK#) and adding each .rel file to be linked (proper crt0 file goes always first) then all the bank#.rel files last, in ascending order:

  sdcc -o your_program.ihx -mz80 --no-std-crt0 --code-loc 0x8080 --data-loc 0x6000 -Wl-b_BANK1=0x1C000 -Wl-b_BANK2=0x2C000 crt0_cv.rel your_program.rel SGlib_CV.lib bank1.rel bank2.rel

How to build the final ColecoVision .col/.rom file:

• if you're not using MegaCart ROM paging, you program and data have to fit in 32 KiB. In this case you can use SDCC's sdobjcopy for the final step. Your input file is the ihx generated by the SDCC linker and the output file is the generated .col ROM file:

sdobjcopy --input-target=ihex --output-target=binary --pad-to 0x10000 your_program.ihx your_program.col

• you may wanto to use --pad-to 0xC000 if your program and data can fit in 16 KiB, or you could use --pad-to 0xA000 if your program and data can fit in 8 KiB.

• if you're using ROM paging instead, use the included makecvmc converter utility to create a ColecoVision MegaCart ROM. The input file is the ihx generated by SDCC linker, the output file is the generated ROM:

  makecvmc your_program.ihx your_program.rom

The size of the final ROM file will be either 128, 256, 512 or 1024 KiB, as these are the only supported sizes for a ColecoVision MegaCart ROM.

ADVANCED: How to use more than 32 KiB of code in your SMS/GG/SG/SC ROM ('banked code'):

SDCC 4.x supports banked code and this means that it's now possible to page in and out code in a transparent manner. To achieve this, banked code should be written in separate source files that have to get allocated in separate code banks. Upon calling a banked function the code will trigger a slot-1 bank change (using trampolines that are 'hidden' in bank 0 code) and will restore the previous bank upon returning from called function. This means that only code in bank 0 won't ever be paged out, but that means that total code won't be restricted to the 32 KiB maximum size.

You need to:

• put banked code in