SGDK

https://github.com/stephane-d/sgdk
Admin
SGDK is a free development kit that allows software development in C language for the Sega Mega...
Tokens:261,505
Snippets:1,840
Trust Score:8.1
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Sjasm command-line examples

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Four example invocations demonstrating option grouping and placement, with explanations of the resulting files and behavior.

```text
sjasm -l prog.asm 
     assemble prog.asm to prog.out with prog.lst as listfile, include labels and code in listfile
```

```text
sjasm -ql prog.asm
     assemble prog.asm to prog.out with prog.lst as listfile, include only the label listing in listfile
```

```text
sjasm prog.asm -i/devel/inc
     assemble prog.asm to prog.out with prog.lst as listfile, include only code in listfile and search in /devel/inc for includefiles if not found in the current directory
```

```text
sjasm -lidevel -izooi prog.asm prog.com
     assemble prog.asm to prog.com with prog.lst as listfile, include code and label listing in listfile and search in zooi and devel for includefiles if not found in the current directory
```

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

### INCBIN directive examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Includes a binary file into the output, optionally skipping bytes or including a specific length. Note the space between filename and comma in the third example.

```sjasm
  INCBIN "gfx.scc",7        ; include gfx.scc, skip first 7 bytes
  INCBIN "rantab.com",3,256 ; include 256 bytes from offset 3
  INCBIN gfx.scc ,7         ; note the space between the filename and the ',7' here :)
```

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

### Module and local label scoping example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Demonstrates how labels are scoped within modules and how local labels (starting with '.') are relative to the previous non-local label. The comments show the fully qualified names.

```assembly
  module main
Main:                     ; main.Main
  CALL SetScreen          ; SetScreen
  CALL vdp.Cls            ; vdp.Cls
.loop:                    ; main.Main.loop
  LD A,(.event)           ; main.Main.event
  CALL ProcesEvent        ; label not found: main.ProcesEvent
  DJNZ .loop              ; main.Main.loop

  module vdp
@SetScreen:               ; SetScreen
.loop                     ; vdp.SetScreen.loop
  RET
Cls:                      ; vdp.Cls
.loop                     ; vdp.Cls.loop
  DJNZ .loop              ; vdp.Cls.loop
  RET

  endmodule
Main.event                ; main.Main.event
  byte 0
```

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

### OUTPUT directive examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Creates multiple output files from one source. Modes: truncate (default), rewind, append. The example creates loader.com and bigfile.dat.

```sjasm
OUTPUT "<filename>",t  ; truncate (default)
OUTPUT "<filename>",r  ; rewind
OUTPUT "<filename>",a  ; append
```

```sjasm
  OUTPUT loader.com
  ORG 100H
  INCLUDE loader.asm
  INCLUDE bios.asm

  OUTPUT bigfile.dat
  ORG 4000H
  INCLUDE main.asm
  ORG 8000H
  INCLUDE data.asm

  END
```

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

### ORG directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Sets the program counter to a specific address.

```sjasm
  ORG 100h
```

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

### SIZE directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Pads the output file with bytes if it is shorter than the given size.

```sjasm
  SIZE 32768       ; make sure file will be 32K
```

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

### OUTPUT file creation example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Shows the files created when assembling bigfile.asm with sjasm bigfile.asm. Bigfile.out is created even with zero bytes.

```sjasm
sjasm bigfile.asm
```

```text
Bigfile.out  ; file length is zero
Loader.com
Bigfile.dat
```

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

### DOT1 SDOT example

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Shows a structure declaration with initial values, with a comment showing alternative syntax.

```assembly
DOT1 SDOT 0,0, 0,0,0     ; or 0,0,0,0,0 or {0,0,{0,0,0}}
```

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

### DZ pseudo-op examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Same as BYTE but appends a zero byte.

```z80
DZ 1      ; same as BYTE 1,0
```

```z80
DZ "kip"  ; same as BYTE "kip",0
```

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

### Hello World with VDP_drawText

Source: https://github.com/stephane-d/sgdk/wiki/Tuto-Hello-World

Includes the genesis.h header to access SGDK functions and prints 'Hello World!' at tile coordinates (10, 13). This is the basic example but it returns immediately, which is not suitable for a game.

```c
#include <genesis.h>

int main(bool hard)
{
    VDP_drawText("Hello World!", 10, 13);

    return 0;
}
```

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

### txt format default options command

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Command-line example showing default options for the txt format: -inopt "/fmt='%s %X' /offsetFirst-".

```text
-inopt "/fmt='%s %X' /offsetFirst-"
```

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

### PUSH and POP register lists example

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Shows that PUSH and POP can take register lists, with the order of pushes and pops noted.

```z80
    PUSH AF,BC  ; push af / push bc
    POP  AF,BC  ; pop  bc / pop  af <- reversed order
```

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

### log format default options command

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Command-line example showing default options for the log format: -inopt "/separator=: /useDecimal-".

```text
-inopt "/separator=: /useDecimal-"
```

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

### SGDK 1.6 Hello World main loop

Source: https://github.com/stephane-d/sgdk/wiki/Tuto-Hello-World

Use this as the starting point for any SGDK 1.6+ project. It draws "Hello Genny World!" and then enters an infinite loop that calls SYS_doVBlankProcess() each frame to handle VBlank tasks. The main function takes a bool parameter named hard, which is standard for SGDK entry points.

```c
#include <genesis.h>

int main(bool hard)
{
    VDP_drawText("Hello Genny World!", 10, 13);

    while(TRUE)
    {
        // read input
        // move sprite
        // update score
        // draw current screen (logo, start screen, settings, game, gameover, credits...)

        // wait for screen refresh and do all SGDK VBlank tasks
        SYS_doVBlankProcess();
    }

    return 0;
}
```

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

### ABYTE pseudo-op examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines bytes with an offset added to each byte.

```z80
ABYTE 2 4,9    ; Same as BYTE 6,11
```

```z80
ABYTE 3 "ABC"  ; Same as BYTE "DEF"
```

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

### DEFINE pseudo-op example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines a text replacement identifier.

```z80
DEFINE str_honderd "Honderd"
  BYTE str_honderd,0             ; BYTE "Honderd",0
```

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

### ABYTEZ pseudo-op example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines bytes with offset and appends a zero byte.

```z80
ABYTEZ 0 "KIP"        ; Same as BYTE "KIP",0
```

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

### ALIGN pseudo-op examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Aligns the address to a power of two by filling with zeros.

```z80
ALIGN         ; => ALIGN 4
```

```z80
ALIGN 2       ; 
```

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

### Macro with angle brackets example

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Shows how angle brackets can be used in macro arguments to include commas. The example defines a UseLess macro and shows its expansion with angle brackets.

```assembly
  MACRO UseLess data
    DB data
  ENDM
```

```assembly
  UseLess <10,12,13,0>
```

```assembly
  DB 10,12,13,0
```

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

### BYTE pseudo-op examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines a byte or string of bytes.

```z80
BYTE 0x56
```

```z80
BYTE 1,-78,'@'
```

```z80
BYTE "Format C:? ",0h
```

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

### INCLUDE directive examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Includes another source file. Angle brackets search command-line directories first; quotes search current directory first.

```sjasm
  INCLUDE <VDP.I>
  INCLUDE MORE.I
  INCLUDE "MORE.I"
```

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

### Macro with escaped characters example

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Shows how to include '!' and '>' in macro arguments using '!'. The example shows two expansions.

```assembly
  UseLess <5, 6 !> 3>
```

```assembly
  DB 5, 6 > 3
```

```assembly
  UseLess <"Kip!!",3>
```

```assembly
  DB "Kip!",3
```

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

### BLOCK pseudo-op examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines a block of bytes with optional fill value.

```z80
BLOCK 500     ; define a block of 500 bytes of zero
```

```z80
BLOCK 500,0   ; define a block of 500 bytes of zero
```

```z80
BLOCK 400,-1  ; define a block of 400 bytes of 255
```

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

### Generic HTTP GET request (http_get)

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/mw/README.md

Performs a generic HTTP GET request without a data payload. It calls http_begin with MW_HTTP_METHOD_GET and then http_finish to receive the response. Returns the HTTP status code or -1 if the request was not completed.

```C
/****************************************************************************
 * \brief Generic HTTP GET request without data payload.
 *
 * \param[in]  url      URL for the request.
 * \param[out] recv_buf Buffer used for HTTP response data.
 * \param[out] len      Length of the response.
 *
 * \return HTTP status code, or -1 if request was not completed.
 ****************************************************************************/
int http_get(const char *url, char *recv_buf, unsigned int *len)
{
	enum mw_err err;

	err = http_begin(MW_HTTP_METHOD_GET, url, 0);
	if (!err) {
		err = http_finish(recv_buf, len);
	}

	return err;
}
```

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

### Compass-style macro syntax

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Example of a Compass-style macro definition with parameters and a local label.

```assembly
name: macro @param1,@param2
      ld hl,@param1
      ld b,@param2
loop@sym:
      djnz loop@sym
      endm
```

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

### ABYTEC pseudo-op examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines bytes with offset and sets bit 7 on the last byte of a string.

```z80
ABYTEC 0 "KIP"        ; Same as BYTE "KI",'P'|128
```

```z80
ABYTEC 1 "ABC",0,"DE" ; Same as BYTE "BC",'D'|128,1,'E','F'|128
```

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

### DC pseudo-op example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Same as BYTE but sets bit 7 on the last character of a string.

```z80
DC "kip" ; same as BYTE "ki",'p'|128
```

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

### ASSERT pseudo-op example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Issues an assertion error if the expression evaluates to zero.

```z80
STACKPOINTER=0D500H
  ASSERT END_OF_PROGRAM < STACKPOINTER
END_OF_PROGRAM
  END
```

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

### Compile SGDK library with make

Source: https://github.com/stephane-d/sgdk/wiki/SGDK-Installation

Run this command in a terminal (cmd) to compile the SGDK library. Replace <SGDK_PATH> with your actual installation path. Successful compilation produces <SGDK_PATH>\lib\libmd.a.

```console
<SGDK_PATH>\bin\make -f <SGDK_PATH>\makelib.gen
```

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

### TEXTAREA directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Sets the program counter to a specified address and restores it with ENDT. Useful for assembling code at a different address.

```sjasm
  MODULE Main
  LD HL,start
  LD DE,8000h
  LD BC,len
  LDIR
  CALL DoThings
  RET

start
  MODULE DoUsefulThings
  TEXTAREA 8000h
@DoThings
  CALL DoALot
  CALL DoEvenMore
  RET
  ENDT
  MODULE Main
Len:=$-start
```

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

### Local label usage example

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Demonstrates module-local labels and dot-local labels. The comment shows the resolved full names, including an error for a label not found in the module.

```assembly
  module main
Main:                     ; main.Main
  CALL SetScreen          ; SetScreen
  CALL vdp.Cls            ; vdp.Cls
.loop:                    ; main.Main.loop
  LD A,(.event)           ; main.Main.event
  CALL ProcesEvent        ; label not found: main.ProcesEvent
  DJNZ .loop              ; main.Main.loop
```

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

### Compile project with default release profile

Source: https://github.com/stephane-d/sgdk/wiki/SGDK-Usage

Use this command from the project root to compile with the default release profile. Replace <SGDK_PATH> with the full path to your SGDK installation, including drive letter (e.g., D:\SGDK).

```console
<SGDK_PATH>\bin\make -f <SGDK_PATH>\makefile.gen
```

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

### sjasm command-line examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Shows how to invoke sjasm with different options for listfile content and include paths. The output, list, and export filenames default to the input filename with .out, .lst, and .exp extensions respectively.

```shell
sjasm -l prog.asm
```

```shell
sjasm -ql prog.asm
```

```shell
sjasm prog.asm -i/devel/inc
```

```shell
sjasm -lidevel -izooi prog.asm prog.com
```

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

### Create and scroll a background map with MAP_create and MAP_scrollTo

Source: https://github.com/stephane-d/sgdk/wiki/Tuto-Background

Minimal SGDK example for the high-level MAP API. The .res file defines a palette, tileset, and map; main.c creates a Map object, loads tiles, fades in, scrolls to a position, and frees the map. Requires the MAP resource to be defined after its TILESET resource, and compression may need to be disabled if the unpacked map exceeds memory.

```res
PALETTE palette_all "gfx/S1_GHZ1_FG.png"
TILESET bga_tileset "gfx/S1_GHZ1_FG.png" BEST ALL
MAP bga_map "gfx/S1_GHZ1_FG.png" bga_tileset BEST 0
```

```c
#include <genesis.h>
#include "res_gfx.h"

Map *bga;

int main(bool hard)
{
    u16 palette[1];

    VDP_loadTileSet(&bga_tileset, TILE_USER_INDEX, DMA);

    // init backgrounds
    bga = MAP_create(&bga_map, BG_A, TILE_ATTR_FULL(PAL0, FALSE, FALSE, FALSE, TILE_USER_INDEX));

    SYS_doVBlankProcess();

    memcpy(&palette[0], palette_all.data, 64 * 2);

    // fade in
    PAL_fadeIn(0, (4 * 16) - 1, palette, 20, TRUE);

    MAP_scrollTo(bga, 9920, 1056);

    while(TRUE)
    {
        // sync frame and do vblank process
        SYS_doVBlankProcess();
    }

    // release maps
    MEM_free(bga);

    return 0;
}
```

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

### Module and label handling example

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Shows how labels are processed within a module, including the use of '@' to prevent label processing. The first block demonstrates a module with labels and a loop, while the second block shows the effect of '@' on label names and the duplicate label error.

```z80
  module vdp
@SetScreen:               ; SetScreen
.loop                     ; vdp.SetScreen.loop
  RET
Cls:                      ; vdp.Cls
.loop                     ; vdp.Cls.loop
  DJNZ .loop              ; vdp.Cls.loop
  RET

  endmodule
Main.event                ; main.Main.event
  byte 0
```

```z80
  MODULE xxx
Label      ; xxx.Label
.Local     ; xxx.Label.Local
@Label     ; Label
.Local     ; xxx.Label.Local => duplicate label error
@Label2    ; Label2
.Local     ; xxx.Label2.Local
@yyy.Local ; yyy.Local
yyy.Local  ; xxx.yyy.Local
```

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

### Compile SGDK library with make

Source: https://github.com/stephane-d/sgdk/wiki/Setup-SGDK-basic

Run this command from the command line to compile the SGDK library. It requires GDK_WIN to be set to the Windows path of the SGDK installation. The output is the library file %GDK%/lib/libmd.a.

```batch
%GDK_WIN%\bin\make -f %GDK_WIN%\makelib.gen
```

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

### log output format options

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Shows the /fmt option for the log output format, which specifies a printf-compatible format string for printing (offset, label) pairs. The default is "%X: %s". The example shows the default option expressed as a command-line argument.

```text
  /fmt='format-string'
    specifies format string to print (offset, label) pairs, default: "%X: %s"

```

```text
	-outopt "/fmt='%X: %s'"

```

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

### FPOS directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Sets the file position to anywhere in the output file. Useful for creating files with specific sizes or updating existing files when combined with OUTPUT.

```sjasm
  BYTE 0
  FPOS 0
  BYTE 1
  END
```

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

### ENDMODULE example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Shows how ENDMODULE ends a module and returns to the previous module's namespace. Labels in different modules can share names without conflict.

```sjasm
  MODULE M1
A                 ; M1.A
  MODULE M2
A                 ; M2.A
  ENDMODULE
B                 ; M1.B
```

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

### User task with mw_process()

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/mw/README.md

Example of a user task that calls update_game_logic() and mw_process() in a loop. This approach can lead to VDP timing bugs if not carefully synchronized.

```C
static void user_tsk(void)
{
	while (1) {
		update_game_logic();
		mw_process();
	}
}
```

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

### EQU directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Assigns a value to a label using EQU or '='. The label must not already exist.

```sjasm
Label EQU 3
Kip=3
```

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

### REPT directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Repeats the statements inside the macro a specified number of times. Cannot be used inside macros.

```sjasm
  REPT 3
  NOP
  ENDM
```

```sjasm
  NOP
  NOP
  NOP
```

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

### Macro with parameters (WAVEOUT)

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines a macro that takes two parameters and outputs them to ports 7EH and 7FH. The example shows the macro definition and its expansion when called with WAVEOUT 2,17.

```sjasm
  MACRO WAVEOUT reg, data
  LD A,reg
  OUT (7EH),A
  LD A,data
  OUT (7FH),A
  ENDM
```

```sjasm
  WAVEOUT 2,17
```

```sjasm
  LD A,2
  OUT (7EH),A
  LD A,17
  OUT (7FH),A
```

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

### asm output format options

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Shows the /fmt option for the asm output format, which specifies a printf-compatible format string for printing (label, offset) pairs. The default is "%s:\tequ\t$%X". The example shows the default option expressed as a command-line argument.

```text
  /fmt='format-string'
    specifies format string to print (label, offset) pairs, default: "%s:	equ	$%X"

```

```text
	-outopt "/fmt='%s:	equ	$%X'"

```

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

### Character and string constant usage examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Shows how to use character and string constants with BYTE and LD instructions. Note that single-quoted string constants cannot be used with BYTE.

```assembly
  BYTE "stringconstant"  ; single quote string constants can't be used with BYTE
  LD HL,'hl'
  LD HL,"hl" ; :(
  LD A,"7"   ; :(
  LD A,'8'   ; :)
  LD A,'\E'
  LD A,'"'
  LD A,"'"
```

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

### Temporary labels example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Shows how to use numeric labels for jumps. Use 'F' for forward and 'B' for backward references. Temporary labels should not be used within macros.

```assembly
  ADD A,E
  JR NC,1F
  INC D
1 LD E,A
2 LD B,4
  LD A,(DE)
  OUT (152),A
  DJNZ 2B
```

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

### deb2 output format options

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Shows the /favorLastLabels option for the deb2 format, which controls label selection when multiple labels share the same offset. Default is '-'. The example shows the default option expressed as a command-line argument.

```text
  /favorLastLabels[+|-]
    sets whether to prefer the last processed label when multiple labels share 
    the same offset (the first processed label is chosen otherwise); default: -

```

```text
	-outopt "/favorLastLabels-"

```

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

### @ label scoping example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Shows that labels starting with '@' are used as-is and are not affected by module or local label processing. The comments show the resulting names and a duplicate label error.

```assembly
  MODULE xxx
Label      ; xxx.Label
.Local     ; xxx.Label.Local
@Label     ; Label
.Local     ; xxx.Label.Local => duplicate label error
@Label2    ; Label2
.Local     ; xxx.Label2.Local
@yyy.Local ; yyy.Local
yyy.Local  ; xxx.yyy.Local
```

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

### Compile project with debug profile

Source: https://github.com/stephane-d/sgdk/wiki/SGDK-Usage

Use this command to compile with the debug profile, which includes symbols and displays errors in Gens KMod log. Replace <SGDK_PATH> with the full path to your SGDK installation.

```console
<SGDK_PATH>\bin\make -f <SGDK_PATH>\makefile.gen debug
```

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

### minimusic_init

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/minimusic/doc/api-c.md

Initializes the MiniMusic sound driver with sound data. Pass a pointer to the sound data and its size (up to 6KB).

```APIDOC
## minimusic_init

### Description
Initializes the MiniMusic sound driver with the provided sound data. The sound data must fit within 6144 bytes and includes all tracks and instruments.

### Function Signature
```c
void minimusic_init(const void *data, unsigned int size);
```

### Parameters
- **data** (const void*) - Required - Pointer to the sound data.
- **size** (unsigned int) - Required - Size of the sound data in bytes.

### Example
```c
minimusic_init(&sound_data, sizeof(sound_data));
```
```

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

### Initialize MiniMusic with sound data

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/minimusic/doc/api-c.md

Initializes the sound driver with sound data up to 6KB. The data must fit within 6144 bytes and follow the format in doc/format.md.

```c
minimusic_init(&sound_data, sizeof(sound_data));
```

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

### MINIMUSIC_Z80_GUARD_BEGIN / MINIMUSIC_Z80_GUARD_END

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/minimusic/doc/api-c.md

Inline functions to guard against Z80 bus interference during DMA or I/O port accesses. Request the Z80 bus before starting DMA or accessing I/O ports, and release it afterwards.

```APIDOC
## MINIMUSIC_Z80_GUARD_BEGIN / MINIMUSIC_Z80_GUARD_END

### Description
These inline functions are used to guard against hardware bugs when using DMA or I/O ports. They request and release the Z80 bus to prevent interference from MiniMusic.

### Usage
```c
MINIMUSIC_Z80_GUARD_BEGIN();
// start DMA or read pads here
MINIMUSIC_Z80_GUARD_END();
```

### Notes
- Only the command that triggers DMA needs to be guarded.
- You don't need to wait for the Z80 to release the bus.
```

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

### gj_init

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/mw/README.md

Initializes the GameJolt API module with required credentials and buffer settings.

```APIDOC
## gj_init

### Description
Initializes the GameJolt API with the endpoint, game credentials, user credentials, buffer, and timeout. It is recommended to retrieve credentials from gamertag slots using `mw_gamertag_get()` before calling this function.

### Function Signature
`int gj_init(const char *endpoint, const char *game_id, const char *private_key, const char *username, const char *user_token, char *buffer, int buffer_len, int timeout)`

### Parameters
- **endpoint** (string) - Required - The GameJolt API endpoint URL.
- **game_id** (string) - Required - The game ID.
- **private_key** (string) - Required - The game private key.
- **username** (string) - Required - The user's username.
- **user_token** (string) - Required - The user's token.
- **buffer** (char*) - Required - The buffer used for receiving data.
- **buffer_len** (int) - Required - The length of the buffer.
- **timeout** (int) - Required - The timeout in frames (e.g., `MW_MS_TO_FRAMES(30000)`).

### Return Value
Returns non-zero on error, zero on success.

### Example
```C
if (gj_init("https://api.gamejolt.com/api/game/v1_2/", GJ_GAME_ID,
            GJ_PRIV_KEY, username, user_token,
            cmd_buf, MW_BUFLEN, MW_MS_TO_FRAMES(30000))) {
    // Handle init error
}
```
```

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

### DWORD pseudo-op examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines a doubleword (32-bit) value.

```z80
DWORD 4000h,0d000h
```

```z80
DWORD 4
```

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

### MegaWiFi initialization and game loop

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/mw/README.md

Initializes MegaWiFi, detects the module and firmware version, and runs a game loop with a user task that calls mw_process() during idle time. Requires including mw/util.h, mw/tsk.h, and mw/megawifi.h. The buffer length and TCP port are defined as macros.

```C
#include "mw/util.h"
#include "mw/tsk.h"
#include "mw/megawifi.h"

// Length of the wflash buffer
#define MW_BUFLEN	1440

// TCP port to use (set to Megadrive release year ;-)
#define MW_CH_PORT 	1989

// Command buffer
static char cmd_buf[MW_BUFLEN];

// Runs mw_process() during idle time
static void user_tsk(void)
{
	while (1) {
		mw_process();
	}
}

// MegaWiFi initialization
static void megawifi_init(void)
{
	uint8_t ver_major = 0, ver_minor = 0;
	char *variant = NULL;
	enum mw_err err;

	// Initialize MegaWiFi
	mw_init(cmd_buf, MW_BUFLEN);

	// Try detecting the module
	err = mw_detect(&ver_major, &ver_minor, &variant);

	if (MW_ERR_NONE != err) {
		// Megawifi cart not found!
		// [...]
	} else {
		// MegaWiFi found!
		// [...]
	}
}

// Run the game loop once per frame
static void game_loop(void)
{
	// Make sure this yields spare CPU time to user task
	wait_vblank();
	read_input();
	draw_screen();
	play_sound();
	game_logic();
}

// Global initialization
static void init(void)
{
	// Initialize hardware and game
	// [...]
	// Configure user task
	TSK_userSet(user_tsk);
	// Initialize MegaWiFi
	megawifi_init();
}

/// Entry point
void main()
{
	// Initialization
	init();

	while (1) {
		game_loop();
	}
}
```

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

### Initialize GameJolt API with gj_init()

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/mw/README.md

Initializes the GameJolt API with the endpoint, game credentials, user credentials, command buffer, and timeout. The buffer is reused for all communication, so data must be copied before subsequent calls. Credentials should be stored securely.

```C
	if (gj_init("https://api.gamejolt.com/api/game/v1_2/", GJ_GAME_ID,
				GJ_PRIV_KEY, username, user_token,
				cmd_buf, MW_BUFLEN, MW_MS_TO_FRAMES(30000))) {
		// Handle init error
	}
```

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

### Launch XGMRomBuilder from command line

Source: https://github.com/stephane-d/sgdk/blob/master/bin/xgmRomBuilder.txt

Use this command to launch XGMRomBuilder if it doesn't launch on double-click. Requires Java and XGMTool in the same folder.

```bash
java -jar XGMROMBuiler.jar
```

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

### ENDMAP example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Restores the map counter to the value before the last MAP directive.

```z80
MAP 100
  MAP 200
kop  # 2    ; kop=200
  ENDMAP
kip  # 2    ; kip=100
kip2 # 2    ; kip2=102
```

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

### WORD directive examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines a word (16-bit value). Values should be between -32787 and 65536.

```sjasm
  WORD 4000h,0d000h
  WORD 4,"HA"
```

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

### ConvSym supported options

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Lists all supported ConvSym options, including input/output formats, defaults, offset conversion, symbol table dump, and filtering options. Useful as a reference for constructing command lines.

```text
  -in [format]
  -input [format]
    Selects input file format. Supported formats: asm68k_sym, asm68k_lst,
    as_lst, as_lst_exp, log, txt
    Default: asm68k_sym

  -out [format]
  -output [format]
    Selects output file format. Supported formats: asm, deb1, deb2, log
    Default: deb2

  -inopt [options]
    Additional options specific for the input format.
    Default options (depending on -in [format]):
      -in asm68k_sym -inopt "/localSign=@ /localJoin=. /processLocals+"
      -in asm68k_lst -inopt "/localSign=@ /localJoin=. /ignoreMacroDefs+ /ignoreMacroExp- /addMacrosAsOpcodes+ /processLocals+"
      -in as_lst -inopt "/localJoin=. /processLocals+ /ignoreInternalSymbols+"
      -in log -inopt "/separator=: /useDecimal-"
      -in txt -inopt "/fmt='%s %X' /offsetFirst-"

  -outopt [options]
    Additional options specific for the output format.
    Default options (depending on -out [format]):
      -out deb2 -outopt "/favorLastLabels-"
      -out deb1 -outopt "/favorLastLabels-"
      -out asm -outopt "/fmt='%s:       equ     $%X'"
      -out log -outopt "/fmt='%X: %s'"

  -debug
    Enables verbose debug-level logging. Can be useful for troubleshooting.

Offsets conversion options:
  -base [offset]
    Sets the base offset for the input data: it is subtracted from every 
    symbol's offset found in [input_file] to form the final offset.
    Default: 0

  -mask [offset]
    Sets the mask for the offsets in the input data: it's applied to every 
    offset found in [input_file] after the base offset subtraction (if occurs).
    Default: FFFFFF

  -range [bottom] [upper]
    Determines the range for offsets allowed in a final symbol file (after 
    subtraction of the base offset).
    Default: 0 3FFFFF

  -a
    Enables "Append mode": symbol data is appended to the end of the 
    [output_file]. Data overwrites file contents by default.
    This is usually used to append symbols to ROMs.

  -noalign
    Don't align symbol data in "Append mode", which is aligned to nearest
    even offset by default. Using this option is not recommended, it's only 
    there to retain compatilibity with older ConvSym versions.

Symbol table dump options:
  -org [offset]
  -org @[symbolName]
    If set, symbol data will placed at the specified [offset] in the output 
    file. This option cannot be used in "append mode".
    You can specify @SomeSymbol instead of plain offset, in this case ConvSym 
    will resolve that symbol's offset.

  -ref [offset]
  -ref @[symbolName]
    If set, a 32-bit Big Endian offset pointing to the beginning of symbol
    data will be written at specified offset. This is can be used, 
    if symbol data pointer must be written somewhere in the ROM header.
    You can specify @SomeSymbol instead of plain offset, in this case ConvSym 
    will resolve that symbol's offset.

Symbols conversion and filtering options:
  -toupper
    Converts all symbol names to uppercase.

  -tolower
    Converts all symbol names to lowercase.

  -addprefix [string]
    Prepends a specified prefix string to every symbol in the resulting table.
    Done after all other transformations.

  -filter [regex]
    Enables filtering of the symbol list fetched from the [input_file]
    based on a regular expression.

  -exclude
    If set, filter works in "exclude mode": all labels that DO match
    the -filter regex are removed from the list, everything else stays.
```

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

### txt format options

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Lists the /fmt and /offsetFirst options for the txt format. /fmt specifies the scanf-like format string (default '%s %X'), /offsetFirst toggles whether offset comes first (default '-').

```text
  /fmt='format-string'
    specifies format string to parse input file lines, default: "%s %X"

  /offsetFirst[+|-]
    specifies whether offset comes first in the input string; default: -
```

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

### MAP directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Sets the map counter to a specified value. See FIELD for usage.

```sjasm
  MAP 5
```

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

### Z80 mnemonic extensions examples

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Shows undocumented Z80 instructions and register list usage in SjASM.

```z80
SET 4,(IX+4),C (aka LD C,SET 4,(IX+4)) is LD C,(IX+4) / SET 4,C / LD (IX+4),C
```

```z80
RRC (IY),A     (aka LD A,RRC (IY+0))   is LD A,(IY)   / RRC A   / LD (IY),A
```

```z80
PUSH AF,BC  ; push af / push bc
POP  AF,BC  ; pop  bc / pop  af <- reversed order
```

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

### Compile SGDK project with make

Source: https://github.com/stephane-d/sgdk/wiki/Setup-SGDK-basic

Run this command from your project directory to compile your SGDK project. It requires the source tree to follow the specified structure (sources in root or src, includes in root or inc, resources in root or res). The output is a _out/rom.bin file.

```batch
%GDK_WIN%\bin\make -f %GDK_WIN%\makefile.gen
```

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

### EXPORT directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Exports a label to the export file in the form 'label: EQU value', allowing inclusion in other sources.

```sjasm
DRIE=3
  EXPORT DRIE
```

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

### Fully compliant demo with VDP_waitVSync

Source: https://github.com/stephane-d/sgdk/wiki/Tuto-Hello-World

Adds VDP_waitVSync() inside the loop to synchronize with the screen refresh (50/60 Hz). This is the recommended way to avoid running at full speed and to prevent VDP conflicts.

```c
#include <genesis.h>

int main(bool hard)
{
    VDP_drawText("Hello Genny World!", 10, 13);

    while(TRUE)
    {
        // read input
        // move sprite
        // update score
        // draw current screen (logo, start screen, settings, game, gameover, credits...)

        // wait for screen refresh
        VDP_waitVSync();
    }

    return 0;
}
```

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

### Get certificate hash with openssl

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/mw/README.md

Command to compute the hash of a PEM certificate file, which is used as the cert_hash parameter in http_cert_set.

```bash
$ openssl x509 -hash in <cert_file_name> -noout
```

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

### HTTP request helper functions (http_begin, sync_recv, http_finish)

Source: https://github.com/stephane-d/sgdk/blob/master/src/ext/mw/README.md

These functions implement the low-level steps of an HTTP request: setting the URL and method, opening the connection, synchronously receiving the response body, and finishing the request. Use them as building blocks for higher-level HTTP functions. The sync_recv function expects the first received byte to match the given channel character, otherwise it returns an error.

```C
// Performs initial steps of an HTTP request
static int http_begin(enum mw_http_method type, const char *url,
		unsigned int len) {
	enum mw_err err;

	err = mw_http_url_set(url);
	if (!err) {
		err = mw_http_method_set(type);
	}
	if (!err) {
		err = mw_http_open(len);
	}

	return err;
}

// Tries to synchronously receive exactly the indicated data length
static int sync_recv(uint8_t ch, char *buf, int len, uint16_t tout_frames)
{
	int recvd = 0;
	int err = 0;
	uint8_t get_ch = ch;
	int16_t get_len;

	while (err == 0 && recvd < len) {
		get_len = len - recvd;
		err = mw_recv_sync(&get_ch, buf + recvd, &get_len, tout_frames);
		if (!err) {
			if (get_ch != ch) {
				err = -1;
			} else {
				recvd += get_len;
			}
		}
	}

	return err;
}

// Performs final steps of an HTTP request
static int http_finish(char *recv_buf, unsigned int *len)
{
	enum mw_err err;
	uint32_t content_len = 0;

	err = mw_http_finish(&content_len, MW_MS_TO_FRAMES(60000));
	err = err >= 200 && err <= 300 ? 0 : err;
	if (content_len > b.msg_buf_len) {
		err = -1;
	}
	if (!err && content_len) {
		err = sync_recv(MW_HTTP_CH, recv_buf, content_len, 0);
	}
	if (!err && len) {
		*len = content_len;
	}

	return err;
}
```

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

### Structure definition SCOLOR

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines a structure with three BYTE members. The example shows the STRUCT definition and its equivalent offset/length definitions.

```sjasm
  STRUCT SCOLOR
RED   BYTE 4
GREEN BYTE 5
BLUE  BYTE 6
  ENDS
```

```sjasm
SCOLOR       EQU 3 ; lenght
SCOLOR.RED   EQU 0 ; offset
SCOLOR.GREEN EQU 1 ; offset
SCOLOR.BLUE  EQU 2 ; offset
```

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

### Draw bitmap image with VDP_drawImageEx

Source: https://github.com/stephane-d/sgdk/wiki/Tuto-Background

Loads a moon bitmap resource, sets its palette, and draws it on background A at (12,12) using CPU transfer. Requires including the generated moon.h and compiling the .res file.

```c
#include "moon.h"

int main( )
{
	// get the palette data of moon
	VDP_setPalette(PAL1, moon.palette->data);

	// load bitmap data of moon in VRAM and draw
	VDP_drawImageEx(BG_A, &moon, TILE_ATTR_FULL(PAL1, 0, 0, 0, 1), 12, 12, 0, CPU);

	while(1)
	{
		VDP_waitVSync();
	}

	return 0;
}
```

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

### Undocumented Z80 instructions examples

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Shows the use of undocumented Z80 instructions SET and RRC with index registers, and the equivalent standard instructions.

```z80
    SET 4,(IX+4),C (aka LD C,SET 4,(IX+4)) is LD C,(IX+4) / SET 4,C / LD (IX+4),C
    RRC (IY),A     (aka LD A,RRC (IY+0))   is LD A,(IY)   / RRC A   / LD (IY),A
```

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

### IFNDEF with JR and ENDIF

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Assembles the IFNDEF block when the symbol is not defined. The example uses IFNDEF DEBUG to conditionally assemble a JR instruction.

```sjasm
1 IN A,(0C4H)
  AND 2
  IFNDEF DEBUG
  JR NC,1B
  ENDIF
```

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

### MODULE directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Creates a new module for label scoping. '@' suppresses label processing, and labels are unique only within the current module.

```sjasm
  MODULE xxx
Kip                ; label xxx.Kip
  CALL Kip         ; call xxx.Kip
  CALL yyy.Kip     ; call yyy.Kip
  CALL Kop         ; call xxx.Kop
  CALL @Kop        ; call Kop
  Call @Kip        ; call Kip

  MODULE yyy
Kip                ; label yyy.Kip
@Kop               ; label Kop
@xxx.Kop           ; label xxx.Kop

  MODULE           ; no modulename
Kip                ; label Kip
```

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

### FIELD directive example

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Uses FIELD (#) to assign map counter values to labels, enabling structure-like data definitions. '##' aligns the map counter.

```sjasm
  MAP 8
Label # 2     ; Label=8
Kip   # 3     ; Kip=10
Kop   #       ; Kop=13
Kop2  # 1     ; Kop2=13
     ##       ; align map address (align 4 is default)
Kop3  # 6     ; Kop3=16
```

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

### Structure member initialization with DOT and SDOT

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Shows a structure member initialization using DOT and SDOT, and how to access structure members with labels.

```sjasm
DOT1 SDOT 0,0, 0,0,0     ; or 0,0,0,0,0 or {0,0,{0,0,0}}
```

```sjasm
  ld b,(ix+SCOLOR.RED)
  ld a,(COLOR.GREEN)
  ld de,COLOR
  ; etc.
```

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

### SjASM extended instruction: LD A,(+SDOT.X)

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Example of using an extended load instruction with a label offset. The comment 'why?' suggests this is a workaround for a specific situation.

```assembly
  LD A,(+SDOT.X)
```

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

### Structure definition SPOS with ALIGN

Source: https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.txt

Defines a structure with WORD, BYTE, ALIGN, and WORD members. The example shows the STRUCT definition and its equivalent offset/length definitions.

```sjasm
  STRUCT SPOS,4
X WORD
Y BYTE
  ALIGN 2
AD WORD
  ENDS
```

```sjasm
SPOS    EQU 10 ; length
SPOS.X  EQU  4 ; offset
SPOS.Y  EQU  6 ; offset
SPOS.AD EQU  8 ; offset
```

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

### asm68k_lst format options

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Options for the asm68k_lst format. /localSign and /localJoin set local label characters, /ignoreMacroDefs controls ignoring macro definitions, /ignoreMacroExp controls ignoring macro expansions, /addMacrosAsOpcodes controls recognition of macros with label parameters, and /processLocals controls local label processing. Defaults are shown in the command-line string.

```text
  /localSign=[x]
    determines character used to specify local labels; default: @

  /localJoin=[x]
    character used to join local label and its global "parent"; default: .

  /ignoreMacroDefs[+|-]
    specify whether macro definitions listings should be ignored (lines between
    "macro" and "endm"); default: +

  /ignoreMacroExp[+|-]
    specify if lines representing macro expansions should be ignored; default: -

  /addMacrosAsOpcodes[+|-]
    set if macros that process label as parameter (defined as "macro *") should 
    be recognized when used; default: +

  /processLocals[+|-]
    specify whether local labels will processed; default: +
```

```text
-inopt "/localSign=@ /localJoin=. /ignoreMacroDefs+ /ignoreMacroExp- /addMacrosAsOpcodes+ /processLocals+"
```

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

### Sjasm command-line usage

Source: https://github.com/stephane-d/sgdk/blob/master/tools/sjasm/README.txt

Shows the general command-line syntax for invoking Sjasm with optional output, list, and export files.

```text
sjasm [options] inputfile [outputfile [listfile [exportfile]]]
```

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

### ConvSym command-line format

Source: https://github.com/stephane-d/sgdk/blob/master/tools/convsym/README.md

Shows the command-line argument format for ConvSym. Input and output files are mandatory; using '-' redirects I/O to STDIN/STDOUT respectively.

```text
convsym [input_file|-] [output_file|-] <options>
```
Tokens:
Raw