### Build All Examples (Linux/Windows/MSYS2)

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Commands to build all included examples using autoreconf, configure, and make. Assumes ngdevkit packages are installed and the examples repository is cloned.

```bash
cd examples
autoreconf -iv
./configure
make
```

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

### Run Emulator for an Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Commands to navigate to an example directory and build/run the GnGeo emulator for testing. Supports fullscreen mode.

```bash
cd examples/01-helloworld
make gngeo
# or run "make gngeo-fullscreen" for a more immersive test
```

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

### Install ngdevkit on Ubuntu/Debian

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Installs ngdevkit and example dependencies using apt. Ensure you have the ngdevkit PPA added.

```bash
add-apt-repository -y ppa:dciabrin/ngdevkit
apt update
apt install ngdevkit
# the remaining packages are only required for the examples
apt install pkg-config autoconf zip imagemagick sox libsox-fmt-mp3 ngdevkit-gngeo
```

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

### Build Example ROMs

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-msys2.md

Configures and builds the example ROMs after the ngdevkit has been compiled and the environment is set up. Ensure you are still in a UCRT64 shell.

```shell
cd examples
./configure
make
```

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

### Build All Examples (macOS)

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Commands to build all included examples on macOS, using brew's python3 and gmake. Requires setting the PATH environment variable.

```bash
cd examples
export PATH=$HOMEBREW_PREFIX/opt/python3/bin:$PATH
autoreconf -iv
./configure
gmake
```

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

### Usage Example: Allocate Backup Data Size

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/memory-and-storage.md

Example demonstrating how to use the `ROM_BACKUP_DATA_SIZE` macro to allocate a specific size for backup data.

```c
// Allocate 2 KiB for backup data
ROM_BACKUP_DATA_SIZE(0x800);
```

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

### Install ngdevkit on macOS with Homebrew

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Installs ngdevkit and example dependencies using brew. Ensure Xcode command-line tools are installed and Homebrew is initialized.

```bash
# If you haven't done it yet, make sure XCode is installed first
sudo xcode-select --install
# If needed, init brew and its environment variables
eval $(/opt/homebrew/bin/brew shellenv)
# install ngdevkit
brew tap dciabrin/ngdevkit
brew install ngdevkit
# the remaining packages are only required for the examples
brew install pkg-config autoconf automake zip imagemagick sox ngdevkit-gngeo
```

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

### Install ngdevkit on Windows with MSYS2

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Installs ngdevkit and example dependencies for the ucrt64 subsystem of MSYS2. Configures pacman repository and uses pacboy for installation.

```bash
MSYSTEM=UCRT64 /usr/bin/bash -l
echo -e "\n[ngdevkit]\nSigLevel = Optional TrustAll\nServer = https://dciabrin.net/msys2-ngdevkit/
$arch" >> /etc/pacman.conf
# install pacboy with `pacman -S pactoys` if necessary
pacboy -Sy
pacboy -S ngdevkit:u
# the remaining packages are only required for the examples
pacboy -S autoconf automake make zip imagemagick:u sox:u ngdevkit-gngeo:u
```

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

### Usage Example: Place Backup Data

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/memory-and-storage.md

Example demonstrating how to use the `ROM_BACKUP_DATA_ADDRESS` macro to place backup data at a specific memory address.

```c
// Place backup data at 0x102000
ROM_BACKUP_DATA_ADDRESS(0x102000);
```

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

### Install ngdevkit on Fedora

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Installs ngdevkit and example dependencies using dnf. Requires enabling the ngdevkit COPR repository.

```bash
dnf copr enable dciabrin/ngdevkit
dnf install ngdevkit
# the remaining packages are only requred for the examples
dnf install install pkg-config autoconf zip ImageMagick sox ngdevkit-gngeo
```

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

### tiletool.py Command Examples

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Shows how to use tiletool.py for graphics conversion. Examples include converting PNG images to tile data and extracting tile data from ROMs.

```bash
./tiletool.py --input graphics.png --output tiles.bin --width 8 --height 8
```

```bash
./tiletool.py --extract rom.bin output.png
```

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

### Install ngdevkit Dependencies

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-msys2.md

Installs all necessary dependencies for compiling the ngdevkit and example ROMs using pacboy.

```shell
pacboy -S msys2-w32api-runtime windows-default-manifest
pacboy -S msys2-runtime-devel msys2-w32api-headers
pacboy -S autoconf autoconf-archive automake pkgconf make tar zip unzip
pacboy -S git flex bison expat gettext ncurses-devel zlib-devel
pacboy -S gmp-devel isl-devel mpc-devel mpfr-devel texinfo
pacboy -S python:u python-ruamel-yaml:u python-pillow:u toolchain:u zlib:u
# dependencies for the example ROMs
pacboy -S rsync sox:u imagemagick:u SDL2:u glew:u boost:u
```

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

### Install msys2-w32api-runtime

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-msys2.md

Installs the msys2-w32api-runtime package, which may require a shell restart.

```shell
pacboy -S msys2-w32api-runtime
```

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

### Example: Switching P-ROM Bank

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/hardware-registers.md

Demonstrates how to include the bank-switch header and use the P_ROM_SWITCH_BANK macro to switch to a specific P-ROM bank.

```c
#include <ngdevkit/bank-switch.h>

// Switch to bank 1 of the second P-ROM
P_ROM_SWITCH_BANK(1);

// Code now executes from the new bank
```

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

### Makefile Integration Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Example Makefile snippet demonstrating how to integrate Python build tools like 'tiletool.py' and the C compiler into the ROM build process.

```makefile
rom.bin: graphics.png
	tiletool.py --input graphics.png --output graphics.bin

game.rom: rom.c p1.bin s1.bin
	m68k-neogeo-elf-gcc -c rom.c -o rom.o
	m68k-neogeo-elf-ld rom.o p1.bin s1.bin -o game.rom
```

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

### API Reference Format Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/INDEX.md

Illustrates the standard documentation format for API functions, including signature, parameters, return values, and usage examples.

```markdown
```markdown
### Function Name

Brief description.

    function_signature();

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| name | type | Yes/No | — | Description |

**Return:** Type and meaning

**Throws/Errors:** Error conditions (if applicable)

**Usage Example:**
    
    // Code example

**Source:** File location and line reference

**See Also:** Related functions/sections
```
```

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

### VRAM Write Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/hardware-registers.md

Demonstrates how to set the VRAM address, configure the increment mode, and write tile data to the VRAM using the defined registers.

```c
#include <ngdevkit/registers.h>

// Set VRAM address and write tile data
*REG_VRAMADDR = ADDR_FIXMAP + 0;  // Fix layer, first tile
*REG_VRAMMOD = 1;                 // Increment by 1 per write
*REG_VRAMRW = 0x1234;             // Write tile data
```

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

### romtool.py Create Command Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Example of using the romtool.py script to create a new cartridge package. Specify names, year, publisher, and paths for each ROM type.

```bash
./romtool.py create --name myrom --long-name "My Game" --year 2025 \
    --publisher "MyCompany" \
    --p-roms p1.bin --m-roms m1.bin \
    --v-roms v1.bin --s-roms s1.bin --c-roms c1.bin
```

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

### vromtool.py Command Examples

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Illustrates the usage of vromtool.py for managing ADPCM sample data. Examples cover building V-ROMs from sample lists and extracting samples.

```bash
./vromtool.py build --input samples.txt --output vrom.bin
```

```bash
./vromtool.py extract --input vrom.bin --output samples/
```

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

### BIOS System IO Initialization: bios_system_io

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Initializes input/output subsystems. Called during system setup.

```c
void bios_system_io(void);
```

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

### Menu System Implementation in C

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Build a menu system with navigation and selection handling. This example demonstrates clearing the screen, displaying text, and responding to player input for menu control.

```c
#include <ngdevkit/ng-fix.h>
#include <ngdevkit/registers.h>

u8 menu_selection = 0;

void show_menu(void) {
    ng_cls();
    ng_center_text(5, 0, "MAIN MENU");
    
    const char* items[] = {"START GAME", "CONTINUE", "OPTIONS", "EXIT"};
    for (int i = 0; i < 4; i++) {
        u8 color = (menu_selection == i) ? 1 : 0;
        ng_text(10, 10 + i * 2, color, items[i]);
    }
}

void handle_menu_input(void) {
    u8 input = *REG_P1CNT;
    
    if (input & CNT_UP && menu_selection > 0) {
        menu_selection--;
    } else if (input & CNT_DOWN && menu_selection < 3) {
        menu_selection++;
    } else if (input & CNT_A) {
        execute_menu_action(menu_selection);
    }
}
```

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

### Time DIP Usage Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/soft-dips.md

Demonstrates how to read and utilize the time DIP settings. Includes calculating total seconds from minutes and seconds.

```c
#include <ngdevkit/soft-dip.h>

dip_time_t round_time = DIP_TIME[0];
u16 total_seconds = round_time.min * 60 + round_time.sec;
```

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

### Build and Install ngdevkit

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-macos.md

Builds the ngdevkit using autotools and gmake, then installs it into a local directory. Uses gmake due to GNU Make version requirements.

```shell
autoreconf -iv
    ./configure --prefix=$PWD/local
    gmake
    gmake install
```

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

### Start GDB for Debugging

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Command to start the GDB debugger, targeting the original ELF file which contains debugging information.

```bash
cd examples/01-helloworld
m68k-neogeo-elf-gdb rom.elf
```

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

### paltool.py Command Examples

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Demonstrates common usage patterns for paltool.py, including converting palette files and extracting palettes from ROM images.

```bash
./paltool.py convert input.pal output.bin
```

```bash
./paltool.py extract rom.bin output.pal
```

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

### Start MSYS2 UCRT64 Shell from cmd.exe

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-msys2.md

This command starts the MSYS2 UCRT64 shell from cmd.exe or PowerShell, setting the necessary environment variable.

```shell
set MSYSTEM=UCRT64
C:\msys64\usr\bin\bash.exe -l
```

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

### Build ngdevkit using Autotools

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-linux.md

Builds the ngdevkit using autotools. It configures the build with a specified installation prefix and then installs the built components.

```bash
autoreconf -iv
./configure --prefix=$PWD/local
make
make install
```

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

### bios_system_int1

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/api-index.md

Performs BIOS initialization via INT1. This is a fundamental BIOS call for system setup.

```APIDOC
## bios_system_int1

### Description
BIOS initialization INT1

### Method
`void bios_system_int1(void)`

### Header
`bios-calls.h`
```

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

### Install ngdevkit Dependencies with Homebrew

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-macos.md

Installs the necessary dependencies for ngdevkit using Homebrew, including build tools, Python, and libraries for examples.

```shell
brew update
    brew install gmake
    brew install python3 pillow
    # you need a package from pip, either in a virtual env or system-wide, e.g.:
    # $(brew --prefix python)/libexec/bin/pip install ruamel.yaml --break-system-packages
    brew deps gcc | xargs brew install
    brew deps sdcc | xargs brew install
    # dependencies for the example ROMs
    brew install autoconf-archive
    brew install glew sdl2 sdl2_image
    brew install zip imagemagick sox
```

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

### bios_system_int2

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/api-index.md

Performs BIOS initialization via INT2. Another essential BIOS call for system setup.

```APIDOC
## bios_system_int2

### Description
BIOS initialization INT2

### Method
`void bios_system_int2(void)`

### Header
`bios-calls.h`
```

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

### Debug with GDB

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Instructions for starting the emulator in debug mode and connecting GDB for debugging the ROM.

```bash
# Terminal 1: Start emulator in debug mode
ngdevkit-gngeo -i rom rom.elf -D

# Terminal 2: Connect GDB
m68k-neogeo-elf-gdb rom.elf
(gdb) target remote :2159
(gdb) b main
(gdb) c
```

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

### bios_system_io

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Initializes the input/output subsystems of the Neo-Geo system. This function is called during the system setup process.

```APIDOC
## bios_system_io

### Description
System IO initialization function. Initializes input/output subsystems. Called during system setup.

### Method
void

### Parameters
None

### Request Example
None

### Response
None
```

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

### Install ngdevkit Dependencies on Ubuntu

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-linux.md

Installs essential packages for building the ngdevkit and its toolchain on Ubuntu. Ensure source repositories are enabled for dependency resolution.

```bash
apt-get install autoconf autoconf-archive automake gcc curl zip unzip
apt-get install libsdl2-dev
apt-get install python3-pil python3-ruamel.yaml
apt-get install libreadline-dev
DISTRIB=$(. /etc/os-release; echo $VERSION_CODENAME)
echo "deb-src http://archive.ubuntu.com/ubuntu/ $DISTRIB main restricted" > /etc/apt/sources.list.d/ngdevkit.list
echo "deb-src http://archive.ubuntu.com/ubuntu/ $DISTRIB universe" >> /etc/apt/sources.list.d/ngdevkit.list
apt-get update
# install build-dependency packages
# make sure you have src packages enabled for dependency information
GCC_VERSION_PKG=$(apt-cache depends gcc | awk '/Depends.*gcc/ {print $2}')
apt-get build-dep $GCC_VERSION_PKG
apt-get build-dep --arch-only sdcc
# optional: install GLEW for OpenGL+GLSL shaders in GnGeo
apt-get install libglew-dev
# dependencies for the example ROMs
apt-get install imagemagick sox libsox-fmt-mp3
```

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

### Set Backup RAM Size

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Specifies the total size for Backup RAM at the top of the source file. This example allocates 2KB.

```c
#include <ngdevkit/backup-ram.h>

// At top of source file
ROM_BACKUP_DATA_SIZE(0x800);  // 2KB backup RAM
```

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

### Minimal Neo-Geo Game Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

A basic C program demonstrating the structure of a Neo-Geo game using the ngdevkit API. It includes VBlank callback, screen clearing, text display, and a main game loop for input handling.

```c
#include <ngdevkit/neogeo.h>

// VBlank callback called each frame
void rom_callback_VBlank(void) {
    // Update game logic each frame
}

int main(void) {
    // Clear screen
    ng_cls();
    
    // Display title
    ng_center_text(10, 0, "MY GAME");
    
    // Main game loop
    while (1) {
        ng_wait_vblank();
        
        // Read input
        u8 p1_input = *REG_P1CNT;
        
        // Update game state
        if (p1_input & CNT_UP) {
            // Handle up movement
        }
    }
    
    return 0;
}
```

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

### Note Slide FX Example: A-5 to B-5

Source: https://github.com/dciabrin/ngdevkit/blob/master/nullsound/doc/slide.md

Exhibits a note slide effect, functioning as a portamento with a relative target. This example slides from A-5 to B-5, setting the final note to B-5 after the portamento completes.

```text
A-50A......
...........
...........
.......E122
B-50A......
...........
```

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

### Integer DIP Usage Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/soft-dips.md

Shows how to read integer DIP values and interpret special values like 0 for unused and 100 for infinite.

```c
#include <ngdevkit/soft-dip.h>

u8 difficulty = DIP_INT[0];
u8 stamina = DIP_INT[1];

if (stamina == 0) {
    // Unused
} else if (stamina == 100) {
    // Infinite stamina
} else {
    // Use numeric value (1-99)
}
```

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

### Configure Debian Source Repository

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-linux.md

Sets up the source package repository for Debian-based systems like Trixie. This is necessary for installing build dependencies.

```bash
echo "deb-src http://deb.debian.org/debian $DISTRIB main" > /etc/apt/sources.list.d/ngdevkit.list
```

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

### m68k Cross-Compilation Flags

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/rom-configuration.md

Example compilation command using m68k-neogeo-elf-gcc for Neo-Geo development. Includes target CPU, no standard library, custom linker script, optimization, and object file creation.

```bash
# Compiler settings for Neo-Geo
m68k-neogeo-elf-gcc \
  -march=m68000           # Target m68000 CPU
  -nostdlib              # No standard library
  -T ngdevkit.ld         # Use custom linker script
  -Wl,--gc-sections      # Remove unused sections
  -O2                    # Optimization level
  -c main.c -o main.o
```

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

### Synchronize Game Logic with VBlank

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/video-and-graphics.md

Example demonstrating how to use ng_wait_vblank to synchronize game logic updates with the display refresh rate. This ensures graphics updates are performed during the safe VBlank period.

```c
#include <ngdevkit/ng-video.h>

void update_game_logic(void) {
    // Synchronize with display refresh
    ng_wait_vblank();
    
    // Safe to update graphics now
    update_sprites();
    update_palette();
}
```

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

### Complete Soft DIPs Definition and Access Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/soft-dips.md

Defines various types of DIPs (time, integer, enum) and demonstrates how to access them at runtime within a Neo-Geo game. Ensure DIP definitions precede the inclusion of 'soft-dip.h'.

```c
#include <ngdevkit/neogeo.h>

// Define game DIPs before including soft-dip.h
#define DIP_TIME_OPTS(opt) \
    opt(0, "ROUND TIME", 0x02, 0x00)

#define DIP_INT_OPTS(opt) \
    opt(0, "DIFFICULTY", 5) \
    opt(1, "STAMINA", 100)

#define DIP_ENUM_OPTS(opt) \
    opt(0, "BLOOD", ("OFF","ON"), 1) \
    opt(1, "LANGUAGE", ("EN","JP","FR"), 0)

#include <ngdevkit/soft-dip.h>

// Access DIPs at runtime
void check_settings(void) {
    dip_time_t *round_time = &DIP_TIME[0];
    u8 difficulty = DIP_INT[0];
    u8 stamina = DIP_INT[1];
    
    dip_enum_t blood_dip = DIP_ENUM[0];
    dip_enum_t lang_dip = DIP_ENUM[1];
    
    if (blood_dip.selected == 1) {
        enable_blood_effects();
    }
    
    set_game_difficulty(difficulty);
}
```

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

### Setup Player Count

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Configures the number of players (2 or 4) based on the system's 4-player mode support and whether controllers are plugged in.

```c
#include <ngdevkit/bios-ram.h>

void setup_players(void) {
    u8 player_count = 1;
    
    // Check for 4-player mode
    if (bios_4p_mode && bios_4p_plugged) {
        player_count = 4;
    } else {
        player_count = 2;
    }
    
    initialize_players(player_count);
}
```

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

### Pitch Slide FX Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/nullsound/doc/slide.md

Demonstrates a pitch slide effect that moves the current note up by a small increment. The slide stops when explicitly disabled or when another slide FX is configured.

```text
E-40A..0101
...........
...........
...........
...........
D-40A......
```

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

### Start Emulator in Debugger Mode

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Command to start the ngdevkit-gngeo emulator with the -D argument for remote debugging. The emulator will wait for a GDB client connection on port 2159.

```bash
cd examples/01-helloworld
# example ROM is named puzzledp
ngdevkit-gngeo -i rom puzzledp -D
```

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

### DIP_TIME_OPTS Macro with Multiple DIPs

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/soft-dips.md

Example showing how to define multiple time-based DIPs using the DIP_TIME_OPTS macro, each with its own index, label, and default values.

```c
#define DIP_TIME_OPTS(opt) \
    opt(0, "ROUND TIME", 0x02, 0x30) \
    opt(1, "PAUSE TIME", 0x00, 0x30)
```

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

### Example: Handling Memory Card Operation Errors

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/memory-and-storage.md

Demonstrates how to check the result of a memory card command and call bios_card_error() if an error occurred. Ensure ngdevkit/memory-card.h is included.

```c
#include <ngdevkit/memory-card.h>

bios_card_command = MC_CMD_LOAD_DATA;
bios_card();

if (bios_card_answer != MC_ERR_OK) {
    bios_card_error();  // Show error dialog
    return;  // Proceed after user acknowledges
}
```

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

### Portamento FX Example: Increasing Speed

Source: https://github.com/dciabrin/ngdevkit/blob/master/nullsound/doc/slide.md

Shows a portamento effect from C5 to G5, where the speed is increased mid-effect. This demonstrates how to modify the portamento speed while it is active.

```text
C-50A......
G-50A..0301
...........
...........
G-50A..0308
...........
```

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

### Persisting Game State with Backup RAM

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/memory-and-storage.md

Example of declaring variables with the `_backup_ram` attribute to ensure they are persisted across attract mode. This feature is specific to MVS hardware.

```c
#include <ngdevkit/backup-ram.h>

// This variable will be persisted across attract mode
u32 _backup_ram high_score;
u8 _backup_ram level_progress;
```

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

### bios_controller_setup

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Initializes the controller input system, preparing it for reading joystick and button states.

```APIDOC
## bios_controller_setup

### Description
Initialize controller input. Sets up the controller input system for reading joystick and button states.

### Method
void

### Parameters
None

### Request Example
None

### Response
None
```

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

### Update MSYS2 and Install Pactoys

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-msys2.md

Ensures your MSYS2 installation is up-to-date and installs the 'pactoys' package, which includes 'pacboy'.

```shell
pacman -Syuu
pacman -S pactoys
```

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

### Portamento FX Example: C5 to G-5

Source: https://github.com/dciabrin/ngdevkit/blob/master/nullsound/doc/slide.md

Illustrates a portamento effect moving from C5 towards G-5 with a speed of 1. The direction is determined by the current note, and the effect continues until the target is reached or another slide FX is applied.

```text
C-50A......
G-50A..0301
...........
...........
...........
...........
```

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

### bios_how_to_play

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Displays the game's 'How to Play' screen, typically shown during the attract mode.

```APIDOC
## bios_how_to_play

### Description
Display "How to Play" screen. Shows the game's how-to-play information screen, typically presented during attract mode.

### Method
void

### Parameters
None

### Request Example
None

### Response
None
```

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

### BIOS System Status: bios_controller_setup

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Sets up the controller input system for reading joystick and button states.

```c
void bios_controller_setup(void);
```

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

### Common Configuration Macros

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/rom-configuration.md

Sets up game-specific configurations using preprocessor macros, including ROM name, version, backup RAM size and address, and DIP switch settings.

```c
/* Set ROM name (displayed in BIOS) */
#define ROM_NAME "MY GAME"

/* Set ROM version */
#define ROM_VERSION 0x0100

/* Backup RAM configuration */
ROM_BACKUP_DATA_SIZE(0x1000);  // 4KB backup RAM
ROM_BACKUP_DATA_ADDRESS(0x102000);

/* DIP switch configuration */
#define DIP_TIME_OPTS(opt) \
    opt(0, "ROUND TIME", 0x02, 0x00)
#define DIP_INT_OPTS(opt) \
    opt(0, "DIFFICULTY", 3)
#define DIP_ENUM_OPTS(opt) \
    opt(0, "VARIANT", ("EASY","HARD"), 0)
```

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

### Build ROM

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Commands to clean the project and build the ROM binary.

```bash
make clean
make rom.bin
```

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

### Sound Driver and Instruments with soundtool.py

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/INDEX.md

Manages sound driver and instrument configurations using the `soundtool.py` script.

```python
soundtool.py — Sound driver and instruments
```

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

### Initialize Homebrew Environment

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-macos.md

If 'brew' is not found in your PATH, initialize it using the appropriate shellenv command for your Mac architecture.

```shell
eval $(/opt/homebrew/bin/brew shellenv)
    # Intel macs would use /usr/local/bin/brew shellenv
```

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

### Palette RAM Definition

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/hardware-registers.md

Defines a volatile pointer to the start of Palette RAM, used for storing color data for palettes.

```c
#define MMAP_PALBANK1 ((volatile u16*)0x400000)
```

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

### Common Build Tool Pattern: File Input/Output

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

A common command-line pattern for build tools, specifying input and output files with optional arguments.

```bash
tool.py --input file.ext --output file.bin [options]
```

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

### BIOS Information Display: bios_how_to_play

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Shows the game's how-to-play information screen, typically presented during attract mode.

```c
void bios_how_to_play(void);
```

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

### Controller Status Register Bit Definitions

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Defines bitmasks for special controller status bits like START and SELECT for players 1 and 2.

```c
#define CNT_START1  (1<<0)
#define CNT_SELECT1 (1<<1)
#define CNT_START2  (1<<2)
#define CNT_SELECT2 (1<<3)
```

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

### ng_center_text_args

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/video-and-graphics.md

Displays a horizontally centered string on the fix tilemap at a specified row and palette. It automatically calculates the starting column based on text length.

```APIDOC
## ng_center_text_args

### Description
Displays a horizontally centered string on the fix tilemap.

### Signature
```c
void ng_center_text_args(u8 y, u8 palette, u16 start_tile, const char *text);
```

### Parameters
#### Path Parameters
- **y** (u8) - Required - Row position (0-31)
- **palette** (u8) - Required - Palette bank index (0-7)
- **start_tile** (u16) - Required - Base tile index for text characters
- **text** (const char *) - Required - Null-terminated string to display

### Return
void

### Usage Example
```c
#include <ngdevkit/ng-fix.h>

ng_center_text_args(15, 1, SROM_TXT_TILE_OFFSET, "GAME OVER");
```
```

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

### Common Build Tool Pattern: Format Conversion

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Command-line pattern for build tools that support format conversion between different file types.

```bash
tool.py convert --from PNG --to TILE --input graphics.png --output tiles.bin
```

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

### Enum DIP Usage Example

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/soft-dips.md

Illustrates how to read the selected value and the number of options for an enum DIP. A switch statement is used to handle different selections.

```c
#include <ngdevkit/soft-dip.h>

dip_enum_t variant = DIP_ENUM[0];
u8 selected = variant.selected;   // Value 0-15
u8 max_options = variant.length;  // Number of options

switch (selected) {
    case 0: /* Option 1 */ break;
    case 1: /* Option 2 */ break;
    case 2: /* Option 3 */ break;
}
```

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

### Soundtool Command-Line Usage

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Command-line arguments for the soundtool.py script for managing Neo-Geo sound driver configurations and instrument definitions.

```bash
./soundtool.py --help
./soundtool.py build --instruments instr.txt --output driver.bin
./soundtool.py define --name bank1 --instruments instr.txt --output bank1.c
```

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

### Test with Emulator

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Command to run the compiled ROM binary using the ngdevkit-gngeo emulator.

```bash
ngdevkit-gngeo -i rom rom.bin
```

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

### Override Backup RAM Address

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/memory-and-storage.md

Defines a macro to override the starting address of the backup RAM region. Must be used at top-level scope after `.data` and `.bss` segments.

```c
#define ROM_BACKUP_DATA_ADDRESS(addr)
    __asm__(".global rom_backup_data_address\n.equ rom_backup_data_address," #addr)
```

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

### bios_system_io

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/api-index.md

Initializes BIOS I/O operations. This function sets up the necessary components for input and output handling.

```APIDOC
## bios_system_io

### Description
BIOS IO initialization

### Method
`void bios_system_io(void)`

### Header
`bios-calls.h`
```

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

### ngdevkit Build Tools

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/README.md

Utilize Python-based tools for ROM packaging, graphics conversion, music extraction, and audio encoding.

```bash
./tools/romtool.py      # ROM packaging
./tools/tiletool.py     # Graphics conversion
./tools/furtool.py      # Music extraction
./tools/adpcmtool.py    # Audio encoding
```

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

### Common Build Tool Pattern: Batch Processing

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Command-line pattern for build tools supporting batch processing of multiple files, potentially recursively.

```bash
tool.py --input dir/*.png --output roms/ --recursive
```

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

### Linker Symbol Definitions for Memory Sections

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/rom-configuration.md

These external symbols, defined by the linker script, mark the start and end of critical memory sections like .data, .bss, and backup RAM. CRT0 uses these for memory initialization.

```c
extern char __data_start;  // Start of .data section in ROM
extern char __data_end;    // End of .data section
extern char __bss_start;   // Start of .bss section
extern char __bss_end;     // End of .bss section
extern char __bram_start;  // Start of backup RAM section
extern char __bram_end;    // End of backup RAM section
```

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

### ADPCM Sample Management with vromtool.py

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/INDEX.md

Leverages the `vromtool.py` script for managing ADPCM sample data.

```python
vromtool.py — ADPCM sample management
```

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

### Compile and Link C Code

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/README.md

Compile a C source file into an object file and then link it with a linker script to create an ELF executable.

```bash
m68k-neogeo-elf-gcc -c main.c -o main.o
m68k-neogeo-elf-ld main.o -T ngdevkit.ld -o rom.elf
```

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

### Sound Synthesis with nsstool.py

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/INDEX.md

Handles sound synthesis operations with the `nsstool.py` script.

```python
nsstool.py — Sound synthesis
```

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

### MVS Calendar Functions: bios_setup_calendar

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Sets up or adjusts the RTC. MVS-specific function.

```c
void bios_setup_calendar(void);
```

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

### Write to VRAM for Tile Data

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/hardware-registers.md

Demonstrates writing tile data to VRAM by setting the VRAM address, autoincrement step, and then writing the data. Requires <ngdevkit/registers.h> and <ngdevkit/types.h>.

```c
#include <ngdevkit/registers.h>
#include <ngdevkit/types.h>

// Set VRAM address
*REG_VRAMADDR = ADDR_FIXMAP;

// Set autoincrement step
*REG_VRAMMOD = 32;

// Write tile data
*REG_VRAMRW = 0x0001;
```

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

### Reading Individual DIPs at Runtime

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/soft-dips.md

Demonstrates how to read individual DIP values for time, integer, and enum types using the provided macros and structures. Requires including necessary headers.

```c
#include <ngdevkit/bios-ram.h>
#include <ngdevkit/soft-dip.h>

void game_setup(void) {
    // Access time DIPs
    dip_time_t time1 = DIP_TIME[0];
    
    // Access integer DIPs
    u8 int_dip_0 = DIP_INT[0];
    u8 int_dip_1 = DIP_INT[1];
    
    // Access enum DIPs
    u8 enum_value = DIP_ENUM[0].selected;
    u8 enum_count = DIP_ENUM[0].length;
}
```

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

### Configure ROM Bank Switching

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/rom-configuration.md

Use the P_ROM_SWITCH_BANK macro to load and execute code from different ROM banks. Ensure to switch back to bank 0 when done.

```c
#include <ngdevkit/bank-switch.h>

// Load code from bank 1
P_ROM_SWITCH_BANK(1);

// Execute code now loads from bank 1
some_banked_function();

// Switch back to bank 0
P_ROM_SWITCH_BANK(0);
```

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

### Backup RAM Cabinet Settings

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Operator settings stored in backup RAM for coin requirements, credits per game, game selection, and demo sound preferences.

```c
extern u8 bram_settings_coins_for_p1_credit;
extern u8 bram_settings_credits_for_p1;
extern u8 bram_settings_coins_for_p2_credit;
extern u8 bram_settings_credits_for_p2;
extern u8 bram_settings_game_select;
extern u8 bram_settings_game_start_compulsion;
extern u8 bram_settings_compulsion_secs_bcd;
extern u8 bram_settings_demo_sound;
```

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

### Backup RAM Initialization Marker

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

A 16-character array used as an initialization marker for backup RAM validation.

```c
extern char bram_ok_check[16];
```

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

### Initialize ngdevkit Shell Environment

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-linux.md

Configures the current shell environment to include the ngdevkit binaries in the PATH. This command should be evaluated in the shell.

```bash
eval $(make shellinit)
```

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

### Include Main Header

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/api-index.md

Include the main header file to access all public APIs for complete Neo-Geo access.

```c
#include <ngdevkit/neogeo.h>
```

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

### Display Text with Convenience Macro

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/video-and-graphics.md

Convenience macro for displaying text on the fix layer. Simplifies the call by omitting the `start_tile` parameter, assuming a default offset.

```c
#include <ngdevkit/ng-fix.h>

// Display text at column 10, row 5, using palette 1
ng_text_args(10, 5, 1, SROM_TXT_TILE_OFFSET, "Hello Neo-Geo!");

// Or use the convenience macro
ng_text(10, 5, 1, "Hello Neo-Geo!");
```

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

### Read Software DIP Settings at Runtime

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Reads and applies settings from defined software DIP switches for round time, difficulty, and game variant.

```c
#include <ngdevkit/soft-dip.h>

void apply_dip_settings(void) {
    // Read time DIP
    dip_time_t round_time = DIP_TIME[0];
    u16 total_seconds = round_time.min * 60 + round_time.sec;
    game_duration = total_seconds;
    
    // Read integer DIP
    u8 difficulty = DIP_INT[0];
    apply_difficulty(difficulty);
    
    // Read enum DIP
    dip_enum_t variant_dip = DIP_ENUM[0];
    if (variant_dip.selected == 0) {
        setup_easy_mode();
    } else {
        setup_hard_mode();
    }
}
```

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

### Palette Conversion with paltool.py

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/INDEX.md

Uses the `paltool.py` script for palette conversion tasks.

```python
paltool.py — Palette conversion
```

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

### BIOS System Initialization: bios_system_int2

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Low-level BIOS initialization function. Not typically called directly by user code.

```c
void bios_system_int2(void);
```

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

### BIOS System Initialization: bios_system_int1

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Low-level BIOS initialization function. Not typically called directly by user code.

```c
void bios_system_int1(void);
```

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

### Backup RAM Configuration Macros

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/api-index.md

Macros for configuring backup RAM. These help in defining and accessing data stored in backup RAM.

```c
#define _backup_ram __attribute__((section(".bss.bram")))
#define ROM_BACKUP_DATA_ADDRESS(addr) ...
#define ROM_BACKUP_DATA_SIZE(size) ...
```

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

### Utility Macros for Text Rendering

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/api-index.md

Macros for simplifying text rendering operations. These macros abstract common text display patterns.

```c
#define SROM_TXT_TILE_OFFSET      0
#define SROM_TXT_TALL_TILE_OFFSET 256
#define SROM_EMPTY_TILE           255

#define ng_text(x,y,pal,text) 
    ng_text_args((x), (y), (pal), SROM_TXT_TILE_OFFSET, (text))

#define ng_text_tall(x,y,pal,text) 
    ng_text_tall_args((x), (y), (pal), SROM_TXT_TALL_TILE_OFFSET, (text))

#define ng_center_text(y,pal,text) 
    ng_center_text_args((y), (pal), SROM_TXT_TILE_OFFSET, (text))

#define ng_center_text_tall(y,pal,text) 
    ng_center_text_tall_args((y), (pal), SROM_TXT_TALL_TILE_OFFSET, (text))

#define ng_cls() ng_cls_args(0, SROM_EMPTY_TILE)
```

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

### String Types for DIP Configuration

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/types.md

Defines fixed-size padded string types for DIP configurations. `dip_str12_t` is for descriptions (12 chars) and `dip_str16_t` is for ROM names (16 chars).

```c
typedef struct { char s[12]; } dip_str12_t;
typedef struct { char s[16]; } dip_str16_t;
```

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

### Common Build Tool Pattern: Validation

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Command-line pattern for build tools that include validation capabilities, such as checksum checks.

```bash
tool.py validate --input file.bin --check-sum
```

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

### Furnace Module Extraction with furtool.py

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/INDEX.md

Uses the `furtool.py` script for extracting Furnace modules, referencing the `binstream` class.

```python
furtool.py — Furnace module extraction (`binstream` class)
```

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

### Software DIP Switch Configuration

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/INDEX.md

Defines options for time, integer, and enumeration-based DIP switches. Runtime access macros are also provided.

```c
#define DIP_TIME_OPTS() \
#define DIP_INT_OPTS() \
#define DIP_ENUM_OPTS() \
#define DIP_TIME \
#define DIP_INT \
#define DIP_ENUM
```

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

### Set Custom Backup RAM Size

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/rom-configuration.md

Use the BACKUP_RAM_SIZE environment variable to specify a custom size for the backup RAM during compilation.

```bash
export BACKUP_RAM_SIZE=0x1000
```

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

### Configure Build Flags for Brew Dependencies

Source: https://github.com/dciabrin/ngdevkit/blob/master/README-macos.md

Manually adds Homebrew's include and library paths to the compiler and linker flags to ensure dependencies are found during the build.

```shell
HOMEBREW_PREFIX=$(brew --prefix)
    export CFLAGS="-I${HOMEBREW_PREFIX}/include${CFLAGS+ ${CFLAGS}}"
    export CXXFLAGS="-I${HOMEBREW_PREFIX}/include${CXXFLAGS+ ${CXXFLAGS}}"
    export CPPFLAGS="-I${HOMEBREW_PREFIX}/include${CPPFLAGS+ ${CPPFLAGS}}"
    export LDFLAGS="-L${HOMEBREW_PREFIX}/lib -Wl,-rpath,${HOMEBREW_PREFIX}/lib${LDFLAGS+ ${LDFLAGS}}"
```

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

### ROM Packaging with romtool.py

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/INDEX.md

Utilizes the `romtool.py` script for ROM packaging, specifically referencing the `Cartridge` and `ROM` classes and the `make_cartridge()` function.

```python
romtool.py — ROM packaging (`Cartridge`, `ROM` classes, `make_cartridge()`)
```

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

### Run Emulator on macOS with SIP

Source: https://github.com/dciabrin/ngdevkit/blob/master/README.md

Command to run GnGeo from gmake on recent macOS versions when System Integrity Protection might interfere. Uses eval to execute the command.

```bash
eval $(gmake -n gngeo)
```

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

### bios_setup_calendar

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/api-index.md

Sets the Real-Time Clock (RTC) date and time using the BIOS. This function allows for setting the system time.

```APIDOC
## bios_setup_calendar

### Description
Set RTC date/time (BIOS)

### Method
`void bios_setup_calendar(void)`

### Header
`bios-calls.h`
```

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

### bios_card

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/memory-and-storage.md

Executes a memory card command via the BIOS using global variables for configuration. Before calling, configure command and parameters using global variables like `bios_card_command`, `bios_card_fcb`, `bios_card_sub`, `bios_card_start`, and `bios_card_size`. For write commands, `ng_memory_card_unlock()` must be called first. The result is stored in `bios_card_answer`.

```APIDOC
## bios_card

### Description
Execute a memory card command via the BIOS.

### Method
void

### Parameters
None (reads from global variables)

### Return
void (result written to global `bios_card_answer`)

### Remarks
Low-level BIOS function that executes memory card commands. Before calling, configure the command and parameters using global variables:

- `bios_card_command`: Command to execute (see Memory Card Commands)
- `bios_card_fcb`: NGH number (BCD format) for the game
- `bios_card_sub`: Save slot selection (bitfield)
- `bios_card_start`: Address of save data in RAM
- `bios_card_size`: Size of data to transfer
- For write commands, call `ng_memory_card_unlock()` first

The result is stored in `bios_card_answer`.

**Macro Definition:**
```c
#define bios_card() do { __SAVE_REGS_AND_CALL("%%d2-%%d7/%%a2-%%a6", bios_card); } while(0)
```
The macro preserves caller-saved registers as required by the C calling convention.
```

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

### Furtool Command-Line Usage

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Command-line arguments for the furtool.py script to extract data from Furnace (.fur) music module files.

```bash
./furtool.py --help
./furtool.py --input song.fur --output instruments.json
./furtool.py extract --input song.fur --dir output/
```

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

### Nsstool Command-Line Usage

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/build-tools.md

Command-line arguments for the nsstool.py script for Neo-Geo sound synthesis and effect processing.

```bash
./nsstool.py --help
./nsstool.py synthesize --config effects.txt --output synth.bin
./nsstool.py compile --input music.txt --output music.bin
```

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

### bios_setup_calendar

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Configures or adjusts the Real-Time Clock (RTC) on the MVS system. This is a MVS-specific function.

```APIDOC
## bios_setup_calendar

### Description
Configure the system calendar/clock. Sets up or adjusts the RTC. MVS-specific function.

### Method
void

### Parameters
None

### Request Example
None

### Response
None
```

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

### VBlank Synchronization for Game Loop

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Ensures game logic updates occur only during the vertical blanking interval to prevent screen tearing. Requires ng-video.h.

```c
#include <ngdevkit/ng-video.h>

void game_loop(void) {
    while (1) {
        // Wait for vertical blank before updating
        ng_wait_vblank();
        
        // Update game logic
        update_game_state();
        
        // Update graphics (sprites, palette, etc.)
        update_display();
    }
}
```

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

### Memory Card Command: Load User Name

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/memory-and-storage.md

Retrieves the user name previously stored on the memory card and loads it into a specified RAM address. 

```c
#define MC_CMD_LOAD_USER_NAME 0x7
```

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

### bios_system_return

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/bios-and-system.md

Returns control to the BIOS, typically used to exit the game to the attract mode or menu.

```APIDOC
## bios_system_return

### Description
Returns control to the BIOS. Used to exit to attract mode or menu.

### Method
void

### Parameters
None

### Request Example
None

### Response
None
```

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

### Efficient Text Output using ng_text Macro

Source: https://github.com/dciabrin/ngdevkit/blob/master/_autodocs/getting-started.md

Demonstrates the efficient way to output text using the `ng_text` macro, which is more performant than the `ng_text_args` function.

```c
#include <ngdevkit/ng-fix.h>

void show_status(const char* text) {
    // Use macro version (more efficient)
    ng_text(10, 28, 0, text);
    
    // Instead of full version:
    // ng_text_args(10, 28, 0, SROM_TXT_TILE_OFFSET, text);
}
```