### Basic Makefile for libSFX

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Docs/Make-txt.html

This is the minimal Makefile required to start a libSFX build. Ensure the 'libsfx_dir' variable correctly points to the libSFX root directory.

```makefile
# Include libSFX.make
libsfx_dir    := ../..
include $(libsfx_dir)/libSFX.make
```

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

### Initialize CPU to Known State (`CPU_init`)

Source: https://context7.com/optiroc/libsfx/llms.txt

Call `CPU_init` once at program start to set the 65816 to native mode, enable 3.58 MHz ROM access, set the stack pointer, and initialize the direct page. It also includes a two VBlank period wait for hardware stabilization. This is called by the libSFX runtime before `Main`.

```asm
Main:
        CPU_init                ; Sets MEMSEL, stack, D register; waits 2 frames
        REG_init                ; Zero all PPU/CPU MMIO registers via the runtime
        ; ... rest of initialization
```

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

### SMP_playspc

Source: https://context7.com/optiroc/libsfx/llms.txt

Transfers an SPC music file from ROM to WRAM and starts playback using the libSFX fast-transfer SMP boot routine.

```APIDOC
## `SMP_playspc` — Transfer and start an SPC music file

Copies all 64 kB of SPC RAM plus the DSP/CPU register state from ROM to WRAM, then executes the libSFX fast-transfer SMP boot routine. The source data is split into LoROM banks using the `SPC_incbin_state`, `SPC_incbin_lo`, and `SPC_incbin_hi` helper macros.

### Parameters

- `state_address` (address) - Address of the SPC state data.
- `lo_ram_address` (address) - Address of the lower half of the SPC RAM data.
- `hi_ram_address` (address) - Address of the upper half of the SPC RAM data.

### Example

```asm
        SMP_playspc SPC_State, SPC_Image_Lo, SPC_Image_Hi

;--- Data section ---
.define spc_file "Data/Music.spc"
.segment "RODATA"
SPC_State:      SPC_incbin_state spc_file   ; DSP regs + CPU regs ($87 bytes)
.segment "ROM2"
SPC_Image_Lo:   SPC_incbin_lo    spc_file   ; SPC RAM $0000-$7fff
.segment "ROM3"
SPC_Image_Hi:   SPC_incbin_hi    spc_file   ; SPC RAM $8000-$ffff
```
```

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

### Decompress LZ4 Frame Example

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Packages/LZ4/LZ4-i.html

This example demonstrates decompressing an LZ4 frame from a source address to a destination address, returning the decompressed length. It's useful for decompressing graphics and uploading them to VRAM.

```assembly
;Decompress graphics and upload to VRAM

LZ4_decompress    Tilemap, EXRAM, y           ;Returns decompressed length in y
VRAM_memcpy       $2000, EXRAM, y             ;Copy y bytes to VRAM
```

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

### Accessing Mouse Cursor Data

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Packages/Mouse/Mouse-i.html

Example of how to load the vertical cursor position from the SFX_mouse1 zero-page location using the MOUSE_data structure offset.

```assembly
;Load cursor vertical position
 lda     z:SFX_mouse1+MOUSE_data::cursor_y
```

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

### Configure Stack Size with 'stack_size'

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Docs/Make-txt.html

Adjust the space reserved for the 65816 stack, starting at memory location 00:2000. The default is 100 bytes.

```makefile
stack_size := 200
```

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

### memset / memcpy

Source: https://context7.com/optiroc/libsfx/llms.txt

Performs block fill and copy operations on the CPU bus using the 65816 `mvn`/`mvp` instructions. These are suitable for smaller data transfers where DMA setup overhead is not desired.

```APIDOC
## memset / memcpy — CPU-bus block fill and copy (65816 `mvn`/`mvp`)

Uses the 65816 block-move instructions. Slower than DMA for large regions but has no DMA setup cost. `memcpy` handles overlapping regions safely when both addresses are assemble-time constants.

```asm
        ; Fill $7f:6000–$7f:603f with $66
        ldy     #$40
        memset  $7f6000, y, $66

        ; Copy 512 bytes from ROM to HIRAM
        memcpy  $7e2000, SomeData, 512
```
```

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

### SMP_playspc

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Transfers and starts an SPC music file using a custom, fast transfer method. It handles different ROM mapping modes.

```APIDOC
## SMP_playspc

### Description
Transfer & start SPC music file using custom (fast!) transfer

If ROM_MAPMODE == 0 (“LoROM”) both ram and ram_hi parameters are required.

### Method
N/A (Macro/Function Call)

### Parameters
#### Path Parameters
- **state** (uint24) - Required - Address to the DSP/CPU state data.
- **ram** (uint24) - Required - Address to the full 64kB SPC RAM dump.
- **ram_hi** (uint24) - Optional - Address to the upper 32kB SPC RAM dump. Required for LoROM.

### Request Example
```assembly
;Transfer and execute SPC file
SMP_playspc       SPC_State, SPC_Image_Lo, SPC_Image_Hi

;Import music
.define spc_file  "Data/Music.spc"
.segment "RODATA"
SPC_State:        SPC_incbin_state spc_file
.segment "ROM2"
SPC_Image_Lo:     SPC_incbin_lo spc_file
.segment "ROM3"
SPC_Image_Hi:     SPC_incbin_hi spc_file
```
```

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

### CPU-bus Block Fill and Copy (65816 mvn/mvp)

Source: https://context7.com/optiroc/libsfx/llms.txt

Utilizes 65816 block-move instructions for memory operations. Suitable for smaller regions due to higher setup cost compared to DMA.

```asm
        ; Fill $7f:6000–$7f:603f with $66
        ldy     #$40
        memset  $7f6000, y, $66

        ; Copy 512 bytes from ROM to HIRAM
        memcpy  $7e2000, SomeData, 512
```

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

### Transfer and execute SPC file

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Use SMP_playspc to transfer and start an SPC music file using a custom, fast transfer method. Depending on ROM_MAPMODE, you may need to provide addresses for both the lower and upper 32kB of SPC RAM.

```Assembly
;Transfer and execute SPC file
SMP_playspc       SPC_State, SPC_Image_Lo, SPC_Image_Hi

;Import music
.define spc_file  "Data/Music.spc"
.segment "RODATA"
SPC_State:        SPC_incbin_state spc_file
.segment "ROM2"
SPC_Image_Lo:     SPC_incbin_lo spc_file
.segment "ROM3"
SPC_Image_Hi:     SPC_incbin_hi spc_file
```

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

### REG_init

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_Runtime-i.html

Initialize PPU & CPU MMIO registers.

```APIDOC
## REG_init

### Description
Initialize PPU & CPU MMIO registers.
```

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

### CPU_init

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_Runtime-i.html

Initialize CPU state.

```APIDOC
## CPU_init

### Description
Initialize CPU state.
```

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

### Initialize and Upload Sprite Table (OAM)

Source: https://context7.com/optiroc/libsfx/llms.txt

OAM_init fills a shadow OAM table with off-screen positions, and OAM_memcpy DMAs this table to PPU OAM during VBlank.

```asm
.segment "BSS"
OAM_Table: .res 544

        ; Hide all sprites off-screen (x=$f0, y=$f0, size=0)
        OAM_init    OAM_Table, $f0, $f0, 0

proc MyVBlank
        OAM_memcpy  OAM_Table   ; DMA shadow table to PPU
        rtl
endproc
```

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

### Turn on screen using SFX_inidisp

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_Runtime-i.html

Sets the INIDISP shadow variable to turn on the screen with maximum brightness. Ensure VBL_on is called to apply the change during the next vertical blanking interval.

```assembly
;Turn on screen
lda          #inidisp(ON, DISP_BRIGHTNESS_MAX)
sta          SFX_inidisp
VBL_on
```

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

### Initialize PPU and CPU MMIO Registers

Source: https://context7.com/optiroc/libsfx/llms.txt

Calls SFX_INIT_mmio to write safe default values to I/O registers. Must be called during VBlank or forced-blank to prevent graphical corruption.

```asm
Main:
        CPU_init
        REG_init                ; Clear VRAM, OAM, CGRAM address registers and display control
        lda     #DISP_BLANKING_ON
        sta     INIDISP         ; Keep display off during further setup
```

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

### Decompress LZ4 Block Example

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Packages/LZ4/LZ4-i.html

This macro decompresses an LZ4 block from a source address to a destination address, returning the decompressed length. It is suitable for decompressing individual LZ4 blocks.

```assembly
;Decompress LZ4 block

LZ4_decompress_block    SourceBlock, Destination, Length
```

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

### REG_init

Source: https://context7.com/optiroc/libsfx/llms.txt

Initializes all PPU and CPU MMIO registers to safe default values, primarily zero. This function must be called during VBlank or forced-blank to prevent graphical corruption.

```APIDOC
## REG_init — Zero all PPU and CPU MMIO registers

Calls the runtime subroutine `SFX_INIT_mmio`, which writes safe default values (mostly zero) to every writable PPU and CPU I/O register. Must be called during VBlank or forced-blank to avoid graphical corruption.

```asm
Main:
        CPU_init
        REG_init                ; Clear VRAM, OAM, CGRAM address registers and display control
        lda     #DISP_BLANKING_ON
        sta     INIDISP         ; Keep display off during further setup
```
```

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

### OAM_init

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_PPU-i.html

Initialize shadow OAM table in RAM.

```APIDOC
## OAM_init

### Description
Initialize shadow OAM table in RAM.

### Parameters
#### Path Parameters
- **table** (uint24 constant) - Table address
- **xpos** (9 bits constant) - X position
- **ypos** (8 bits constant) - Y position
- **size** (constant) - Size bit
```

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

### VBL_set / VBL_on / VBL_off

Source: https://context7.com/optiroc/libsfx/llms.txt

Manages software VBlank (NMI) interrupt handling. `VBL_set` installs a user-defined handler, while `VBL_on` and `VBL_off` enable or disable the NMI and joypad auto-read.

```APIDOC
## VBL_set / VBL_on / VBL_off — Software VBlank (NMI) interrupt management

`VBL_set` redirects the NMI trampoline to a user-supplied handler address. `VBL_on` enables the NMI and (when `SFX_AUTO_READOUT` is active) the joypad auto-read. `VBL_off` disables both. The shadow variable `SFX_inidisp` is copied to `INIDISP` each VBlank automatically.

```asm
proc MyVBlank
        ; Update OAM etc.
        OAM_memcpy OAM_Table
        rtl
endproc

Main:
        VBL_set MyVBlank        ; Install handler
        lda     #inidisp(OFF, DISP_BRIGHTNESS_MAX)
        sta     SFX_inidisp     ; Written to $2100 on next VBlank
        VBL_on                  ; Enable NMI + joypad auto-read
:       wai
        bra     :-
```
```

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

### bgmode() / bgsc() / bgnba() / tm()

Source: https://context7.com/optiroc/libsfx/llms.txt

Compile-time functions to pack PPU register bits for background mode, tile/screen base addresses, and layer priorities.

```APIDOC
## `bgmode()` / `bgsc()` / `bgnba()` / `tm()` — PPU register encoding macros

Compile-time functions that pack mode, tile base, screen base, and layer-enable bits into the byte values expected by PPU registers. Used directly as operands to `lda #`.

### `bgmode(mode, priority, size1, size2, size3, size4)`
Encodes background mode and layer properties.

### `bgsc(map_location, size)`
Encodes background screen base address and size.

### `bgnba(base1, base2, base3, base4)`
Encodes background name table base addresses.

### `tm(bg1, bg2, bg3, bg4, obj)`
Encodes background and object layer enable bits.

### Example

```asm
        ; Configure BG Mode 1, 8x8 tiles, all layers normal priority
        lda     #bgmode(BG_MODE_1, BG3_PRIO_NORMAL, BG_SIZE_8X8, BG_SIZE_8X8, BG_SIZE_8X8, BG_SIZE_8X8)
        sta     BGMODE

        ; BG1 screen at VRAM $0000, 32x32 tiles
        lda     #bgsc(VRAM_MAP_LOC, SC_SIZE_32X32)
        sta     BG1SC

        ; BG1 character data starts at VRAM $8000, BG2 at $0000
        ldx     #bgnba($8000, $0000, 0, 0)
        stx     BG12NBA

        ; Enable BG1 and OBJ on main screen only
        lda     #tm(ON, OFF, OFF, OFF, ON)
        sta     TM
```
```

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

### Set Expansion RAM Size

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Configurations/libSFX-cfg.html

Configures the expansion RAM size in Kbit. $00 indicates no expansion RAM.

```cfg
ROM_EXPRAMSIZE = $00
```

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

### Configure Zero Page Scratchpad Size with 'zpad_size'

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Docs/Make-txt.html

Set the size for the zero page scratchpad, accessible via the 'ZPAD' label. The default is 10 bytes.

```makefile
zpad_size := 20
```

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

### Set RAM Size

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Configurations/libSFX-cfg.html

Defines the RAM size in Kbit. $00 indicates no RAM.

```cfg
ROM_RAMSIZE = $00
```

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

### Transfer data to SMP

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Use SMP_ready to wait for the SMP to be ready, then use SMP_memcpy to copy bytes from CPU to SMP memory. The transfer returns control to the IPL.

```Assembly
;Transfer data to SMP
SMP_ready
SMP_memcpy        $2000, Sample1, sizeof_Sample1
```

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

### Transfer and execute SMP code

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Use SMP_ready to wait for the SMP to be ready, then use SMP_exec to transfer and execute SPC700 binary code. Ensure the __SMPCODE__ symbols are exported from Map.cfg.

```Assembly
;Transfer and execute SMP code
;The __SMPCODE__***__ symbols are exported from Map.cfg
SMP_ready
SMP_exec          __SMPCODE_RUN__, __SMPCODE_LOAD__, __SMPCODE_SIZE__, __SMPCODE_RUN__
```

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

### Configure libSFX project settings

Source: https://context7.com/optiroc/libsfx/llms.txt

Defines the ROM header and library settings. Unset values revert to framework defaults. Copy and edit from include/Configurations/libSFX.cfg.

```cfg
; libSFX.cfg – project-local overrides

define "ROM_TITLE",  "MY SNES GAME         "  ; 21 chars exactly
ROM_MAPMODE  = $1           ; Mode 21 "HiROM"
ROM_SPEED    = $1           ; Fast (120ns) ROM
ROM_CHIPSET  = $02          ; ROM + SRAM
ROM_ROMSIZE  = $09          ; 4 Mbit
ROM_RAMSIZE  = $03          ; 64 Kbit SRAM
ROM_COUNTRY  = $01          ; USA (NTSC)
ROM_VERSION  = $00

SFX_JOY              = JOY1 | JOY2
SFX_AUTO_READOUT     = ENABLE
SFX_AUTO_READOUT_FIRST = NO
```

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

### Setting Mouse Sensitivity

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Packages/Mouse/Mouse-i.html

Demonstrates how to set the mouse sensitivity using the MOUSE_sensitivity_normal value and storing it in the SFX_mouse1 zero-page location.

```assembly
;Set normal mouse sensitivty
 lda     #MOUSE_sensitivity_normal
 sta     SFX_mouse1+MOUSE_data::sensitivity
```

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

### VBL_on

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_Runtime-i.html

Enable vblank interrupt.

```APIDOC
## VBL_on

### Description
Enable vblank interrupt.
```

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

### Import 64KB SPC RAM image

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Use SPC_incbin to import a full 64KB SPC RAM image. Specify the SPC file path as the parameter.

```Assembly
### SPC_incbin

Import 64KB SPC RAM image

#### Parameters

> :in:    filename  SPC File                path
```

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

### SMP_ready

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Waits for the SMP ready signal, ensuring the Synchronous Multi-Processing unit is prepared for further operations.

```APIDOC
## SMP_ready

### Description
Wait for SMP ready signal

### Method
N/A (Macro/Function Call)

### Parameters
None

### Example
```assembly
SMP_ready
```
```

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

### OAM_memcpy

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_PPU-i.html

Copies shadow OAM table to the PPU.

```APIDOC
## OAM_memcpy

### Description
Copies shadow OAM table (512+32 bytes) to the PPU. Disables DMA and uses channel 7 for transfer.

### Parameters
#### Path Parameters
- **table** (uint24 constant) - Table address
```

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

### Configure LORAM Scratchpad Size with 'rpad_size'

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Docs/Make-txt.html

Set the size for the LORAM scratchpad, accessible via the 'RPAD' label. The default is 100 bytes.

```makefile
rpad_size := 20
```

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

### SFX_inidisp

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_Runtime-i.html

INIDISP shadow variable (byte). Writes to SFX_inidisp will be written to $2100 at the next vertical blanking interval.

```APIDOC
## SFX_inidisp

### Description
INIDISP shadow variable (byte). Writes to SFX_inidisp will be written to $2100 at the next vertical blanking interval.

### Example
```assembly
;Turn on screen
lda          #inidisp(ON, DISP_BRIGHTNESS_MAX)
sta          SFX_inidisp
VBL_on
```
```

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

### OAM_init / OAM_memcpy

Source: https://context7.com/optiroc/libsfx/llms.txt

Manages the Object Attribute Memory (OAM) for sprites. `OAM_init` initializes a shadow OAM table with off-screen positions, and `OAM_memcpy` performs a DMA transfer of this table to the PPU OAM during VBlank.

```APIDOC
## OAM_init / OAM_memcpy — Initialize and upload the sprite table

`OAM_init` fills a 544-byte shadow OAM table in RAM with a uniform off-screen position. `OAM_memcpy` DMAs the shadow table to the PPU OAM during VBlank.

```asm
.segment "BSS"
OAM_Table: .res 544

        ; Hide all sprites off-screen (x=$f0, y=$f0, size=0)
        OAM_init    OAM_Table, $f0, $f0, 0

proc MyVBlank
        OAM_memcpy  OAM_Table   ; DMA shadow table to PPU
        rtl
endproc
```
```

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

### CPU Meta Instructions

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU-i.html

Various meta-instructions for branching, subroutine calls, arithmetic, and debugging.

```APIDOC
## bgt

### Description
Branch if greater than.

### Parameters
#### Path Parameters
- **addr** (Address) - Required.

## bsr

### Description
Relative subroutine call.

### Parameters
#### Path Parameters
- **addr** (Address) - Required.

## bsl

### Description
Relative long subroutine call.

### Parameters
#### Path Parameters
- **addr** (Address) - Required.

## add

### Description
Add (without carry).

### Parameters
#### Path Parameters
- **op** (Operand) - Required.
- **ix** (Index) - Optional.

## sub

### Description
Subtract (without carry).

### Parameters
#### Path Parameters
- **op** (Operand) - Required.
- **ix** (Index) - Optional.

## asr

### Description
Arithmetic shift right.

## neg

### Description
Negate (signed integer).

## break

### Description
Break debugger. If assembled with debug=1 the break macro emits a “wdm $00” instruction, which can be set to trigger a break in the bsnes+ debugger.
```

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

### CPU State Management

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU-i.html

Macros for pushing and pulling the CPU state from the stack.

```APIDOC
## push

### Description
Push CPU state to stack.

## pull

### Description
Pull CPU state from stack.
```

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

### Set ROM Size

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Configurations/libSFX-cfg.html

Configures the ROM size in Mbit. Ensure Map.cfg corresponds to the selected ROM size.

```cfg
ROM_ROMSIZE = $07
```

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

### SMP_exit

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/SMP_Util-i.html

Returns control to the IPL (Initial Program Load), clearing timers and zeropage memory.

```APIDOC
## SMP_exit

### Description
Return to IPL (clears timers, zeropage)

### Parameters
This function does not take any parameters.
```

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

### libSFX.cfg — Project ROM header and runtime configuration

Source: https://context7.com/optiroc/libsfx/llms.txt

Configuration file for libSFX to define the ROM header and library runtime settings. Allows customization of ROM title, map mode, speed, chipset, country, and joypad/mouse configurations.

```APIDOC
## libSFX.cfg

### Description
Project ROM header and runtime configuration file for libSFX. Defines the ROM header (title, map mode, size, chipset, country) and library settings (joypad auto-readout ports, mouse configuration). Unset values fall back to framework defaults.

### Usage
Copy `include/Configurations/libSFX.cfg` to the project directory and edit.

### Configuration Options
```
; libSFX.cfg – project-local overrides

define "ROM_TITLE",  "MY SNES GAME         "  ; 21 chars exactly
ROM_MAPMODE  = $1           ; Mode 21 "HiROM"
ROM_SPEED    = $1           ; Fast (120ns) ROM
ROM_CHIPSET  = $02          ; ROM + SRAM
ROM_ROMSIZE  = $09          ; 4 Mbit
ROM_RAMSIZE  = $03          ; 64 Kbit SRAM
ROM_COUNTRY  = $01          ; USA (NTSC)
ROM_VERSION  = $00

SFX_JOY              = JOY1 | JOY2
SFX_AUTO_READOUT     = ENABLE
SFX_AUTO_READOUT_FIRST = NO
```
```

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

### HDMA_set_absolute

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_PPU-i.html

Set up absolute mode HDMA.

```APIDOC
## HDMA_set_absolute

### Description
Set up absolute mode HDMA.

### Parameters
#### Path Parameters
- **ch** (constant) - Channel (0-7)
- **mode** (constant) - Mode (0-7)
- **dest** (uint8 constant) - Destination register
- **table** (uint24 constant) - Table location
```

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

### SMP_exec

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Transfers an SPC700 binary via IPL transfer and executes it. This is useful for running custom code on the SMP.

```APIDOC
## SMP_exec

### Description
Transfer & execute SPC700 binary via IPL transfer

### Method
N/A (Macro/Function Call)

### Parameters
#### Path Parameters
- **dest** (uint16) - Required - Destination address for the binary.
- **source** (uint24) - Required - Source address of the binary in memory.
- **length** (uint16) - Required - Length of the binary to transfer.
- **exec** (uint16) - Required - Jump address to start execution after transfer.

### Request Example
```assembly
;Transfer and execute SMP code
;The __SMPCODE***___ symbols are exported from Map.cfg
SMP_ready
SMP_exec          __SMPCODE_RUN__, __SMPCODE_LOAD__, __SMPCODE_SIZE__, __SMPCODE_RUN__
```
```

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

### SPC_incbin_state

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Imports the SPC DSP/CPU state (#$87 bytes) from a specified file. This is a helper macro for initializing the SPC state.

```APIDOC
## SPC_incbin_state

### Description
Import SPC DSP/CPU state (#$87 bytes)

### Method
N/A (Macro/Function Call)

### Parameters
#### Path Parameters
- **filename** (path) - Required - The path to the SPC file containing the state.

### Example
```assembly
; Example usage:
; SPC_incbin_state "path/to/your/music.spc"
```
```

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

### Import SPC DSP/CPU state

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Use SPC_incbin_state to import the SPC DSP/CPU state, which is #$87 bytes. Specify the SPC file path as the parameter.

```Assembly
### SPC_incbin_state

Import SPC DSP/CPU state (#$87 bytes)

#### Parameters

> :in:    filename  SPC File                path
```

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

### Unsigned Division (S-CPU MMIO)

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_Math-i.html

Performs unsigned division. If output parameters are omitted, the quotient is in RDDIVL (uint16) and the remainder in RDMPYL (uint16) after 13 cycles.

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

### Set ROM Map Mode

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Configurations/libSFX-cfg.html

Configures the ROM map mode. Ensure Map.cfg matches the selected mode. Mode 0 is LoROM, Mode 1 is HiROM.

```cfg
ROM_MAPMODE = $0
```

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

### Static Stack (FILO) Implementation

Source: https://context7.com/optiroc/libsfx/llms.txt

Allocates and manages a byte stack in LORAM. `FILO_alloc` reserves space, `FILO_push` adds a byte, and `FILO_pop` removes a byte, setting Z=0 on success and Z=1 if empty.

```asm
        FILO_alloc  CallStack, 16
```

```asm
        FILO_push   CallStack, $0b
        lda         #$0e
        FILO_push   CallStack, a
```

```asm
        FILO_pop    CallStack, a        ; a = $0e; z = 0
        FILO_pop    CallStack           ; y = $0b; z = 0
        FILO_pop    CallStack           ; z = 1 → empty
```

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

### Transfer and Play SPC Music File

Source: https://context7.com/optiroc/libsfx/llms.txt

Copies SPC RAM and register state from ROM to WRAM, then executes a libSFX fast-transfer boot routine for the S-SMP. Data is split into LoROM banks using helper macros.

```asm
        SMP_playspc SPC_State, SPC_Image_Lo, SPC_Image_Hi

;--- Data section ---
.define spc_file "Data/Music.spc"
.segment "RODATA"
SPC_State:      SPC_incbin_state spc_file   ; DSP regs + CPU regs ($87 bytes)
.segment "ROM2"
SPC_Image_Lo:   SPC_incbin_lo    spc_file   ; SPC RAM $0000-$7fff
.segment "ROM3"
SPC_Image_Hi:   SPC_incbin_hi    spc_file   ; SPC RAM $8000-$ffff
```

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

### Enable Mouse String Support in libSFX.cfg

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Packages/Mouse/Mouse-i.html

Optional configuration to enable special strings that some emulators might use for automatic mouse input detection. This is not required for real hardware.

```cfg
SFX_MOUSE_STRINGS = ENABLE
```

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

### Import lower 32KB of SPC RAM image

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Use SPC_incbin_lo to import the lower 32KB of an SPC RAM image. Specify the SPC file path as the parameter.

```Assembly
### SPC_incbin_lo

Import lower 32KB of SPC RAM image

#### Parameters

> :in:    filename  SPC File                path
```

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

### Import upper 32KB of SPC RAM image

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Use SPC_incbin_hi to import the upper 32KB of an SPC RAM image. Specify the SPC file path as the parameter.

```Assembly
### SPC_incbin_hi

Import upper 32KB of SPC RAM image

#### Parameters

> :in:    filename  SPC File                path
```

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

### Register Width Management

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU-i.html

Macros for assuming, forcing, asserting, pushing, pulling, and printing register widths.

```APIDOC
## RW_assume

### Description
Assume known accumulator/index register widths without emitting any instructions.

### Parameters
#### Path Parameters
- **widths** (a8/a16/i8/i16/a8i8/a16i16/a8i16/a16i8) - Required - Register widths

## RW_forced

### Description
Force set accumulator/index register widths (ie. always emit rep/sep instructions).

### Parameters
#### Path Parameters
- **widths** (a8/a16/i8/i16/a8i8/a16i16/a8i16/a16i8) - Required - Register widths

## RW_assert

### Description
Assert (at assemble time) that the specified register widths match with the state of the register tracking logic.

### Parameters
#### Path Parameters
- **widths** (a8/a16/i8/i16/a8i8/a16i16/a8i16/a16i8) - Required - Register widths
- **message** (string) - Required - Error message

## RW_push

### Description
Push current register widths state to the RW stack, and optionally set new state. No-op if current state == intended state.

### Parameters
#### Path Parameters
- **widths** (a8/a16/i8/i16/a8i8/a16i16/a8i16/a16i8) - Optional - Register widths

## RW_pull

### Description
Pull register widths state from the RW stack. No-op if current state == intended state.

## RW_pull_forced

### Description
Pull register widths state from the RW stack, always emitting rep/sep instructions. Might come in handy when calling a subroutine that returns with the register widths in an unknown state.

## RW_print

### Description
Print (at assemble time) the current register widths state.
```

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

### Map.cfg — Linker memory map and segment configuration

Source: https://context7.com/optiroc/libsfx/llms.txt

Configuration file for the ca65 linker, defining memory regions and mapping segments onto them. Provides templates for different ROM sizes and types (LoROM/HiROM).

```APIDOC
## Map.cfg

### Description
Linker memory map and segment configuration file for ca65. Defines `MEMORY` regions (ROM banks, WRAM, VRAM, SMP RAM) and maps ca65 `SEGMENTS` onto them. Several ready-made templates are provided for LoROM/HiROM at 1, 2, or 4 Mbit.

### Usage
Copy `include/Configurations/Map.cfg` (or a variant) to the project directory.

### Example Configuration (LoROM 4*32kB)
```
# Map.cfg – LoROM 4*32kB (default)

MEMORY {
    LORAM:  start = $000100, size = $1e00, define = yes;
    HIRAM:  start = $7e2000, size = $e000, define = yes;
    EXRAM:  start = $7f0000, size = $10000, define = yes;
    ROM0:   start = $808000, size = $8000, fill = yes, fillval = $ff;
    ROM1:   start = $818000, size = $8000, fill = yes, fillval = $ff;
    ROM2:   start = $828000, size = $8000, fill = yes, fillval = $ff;
    ROM3:   start = $838000, size = $8000, fill = yes, fillval = $ff;
    SMPRAM: start = $0200,   size = $fdc0;
}
SEGMENTS {
    CODE:    load = ROM0, type = ro;
    RODATA:  load = ROM0, type = ro;
    LORAM:   load = LORAM, type = bss, optional = yes;
    SMPCODE: load = ROM0, type = rw, run = SMPRAM, optional = yes, define = yes;
    VECTORS: load = ROM0, type = ro, start = $80ffe0;
}
```
```

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

### IRQ_on

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_Runtime-i.html

Enable vertical line interrupt.

```APIDOC
## IRQ_on

### Description
Enable vertical line interrupt.
```

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

### Immediate Load Macros (6502)

Source: https://github.com/optiroc/libsfx/blob/master/extras/Ideas.md

Macros for loading immediate values into registers. These are fundamental for initializing variables or setting up constants.

```assembly
;Immediate
move  #$ca, a         ;lda #$ca
move  #$c0d3, x       ;ldx #$c0d3
```

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

### Configure Interrupt Scratchpad Size with 'znmi_size'

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Docs/Make-txt.html

Define the space reserved for zero page scratchpad usage within interrupts, accessible via the 'ZNMI' label. The default is 10 bytes.

```makefile
znmi_size := 20
```

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

### SPC_incbin

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Imports a 64KB SPC RAM image from a specified file. This is a helper macro for loading SPC data.

```APIDOC
## SPC_incbin

### Description
Import 64KB SPC RAM image

### Method
N/A (Macro/Function Call)

### Parameters
#### Path Parameters
- **filename** (path) - Required - The path to the SPC file to import.

### Example
```assembly
; Example usage:
; SPC_incbin "path/to/your/music.spc"
```
```

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

### Set Accumulator/Index Register Widths (`RW`)

Source: https://context7.com/optiroc/libsfx/llms.txt

The `RW` macro tracks register widths and emits `rep`/`sep` instructions only when the state changes. Use width tokens like `a8`, `a16`, `i8`, `i16`, `a8i8`, `a16i16`, `a8i16`, `a16i8`.

```asm
proc Example
        RW a8i16                ; sep #$20 emitted (default i16 unchanged)
        lda     #$ff
        RW a8i16                ; no-op – already a8i16
        RW a16                  ; rep #$20 emitted
        lda     #$ffff
        RW a8i8                 ; sep #$30 emitted
        rtl
endproc
```

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

### Set ROM Speed

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Configurations/libSFX-cfg.html

Defines the ROM access speed. $0 for Slow (200ns) and $1 for Fast (120ns).

```cfg
ROM_SPEED = $1
```

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

### Configure Map.cfg linker memory map

Source: https://context7.com/optiroc/libsfx/llms.txt

Defines memory regions and maps ca65 segments onto them. Use pre-built templates for different ROM sizes. Copy from include/Configurations/Map.cfg.

```cfg
# Map.cfg – LoROM 4*32kB (default)

MEMORY {
    LORAM:  start = $000100, size = $1e00, define = yes;
    HIRAM:  start = $7e2000, size = $e000, define = yes;
    EXRAM:  start = $7f0000, size = $10000, define = yes;
    ROM0:   start = $808000, size = $8000, fill = yes, fillval = $ff;
    ROM1:   start = $818000, size = $8000, fill = yes, fillval = $ff;
    ROM2:   start = $828000, size = $8000, fill = yes, fillval = $ff;
    ROM3:   start = $838000, size = $8000, fill = yes, fillval = $ff;
    SMPRAM: start = $0200,   size = $fdc0;
}
SEGMENTS {
    CODE:    load = ROM0, type = ro;
    RODATA:  load = ROM0, type = ro;
    LORAM:   load = LORAM, type = bss, optional = yes;
    SMPCODE: load = ROM0, type = rw, run = SMPRAM, optional = yes, define = yes;
    VECTORS: load = ROM0, type = ro, start = $80ffe0;
}
```

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

### Set Country Code

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Configurations/libSFX-cfg.html

Defines the country code for the ROM. $00 for Japan, $01 for USA, $02 for Europe/PAL.

```cfg
ROM_COUNTRY = $00
```

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

### Enable Debug Information with 'debug'

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Docs/Make-txt.html

Set 'debug' to 1 to generate debug symbols and map files. In debug mode, the 'break' macro inserts a WDM instruction for emulator debuggers.

```makefile
debug := 1
```

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

### HDMA_set_indirect

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_PPU-i.html

Set up indirect mode HDMA.

```APIDOC
## HDMA_set_indirect

### Description
Set up indirect mode HDMA.

### Parameters
#### Path Parameters
- **ch** (constant) - Channel (0-7)
- **mode** (constant) - Mode (0-7)
- **dest** (uint8 constant) - Destination register
- **a1_table** (uint24 constant) - A1 Table location
- **a2_table** (uint24 constant) - A2 Table location
```

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

### SMP_memcpy

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_SMP-i.html

Copies bytes from the main CPU memory to the SMP memory and returns control to the IPL. Useful for transferring data to the SMP.

```APIDOC
## SMP_memcpy

### Description
Copy bytes from CPU to SMP memory and return to IPL

### Method
N/A (Macro/Function Call)

### Parameters
#### Path Parameters
- **dest** (uint16) - Required - Destination address in SMP memory.
- **source** (uint24) - Required - Source address in CPU memory.
- **length** (uint16) - Required - Number of bytes to copy.

### Request Example
```assembly
;Transfer data to SMP
SMP_ready
SMP_memcpy        $2000, Sample1, sizeof_Sample1
```
```

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

### Configure Mouse Port in libSFX.cfg

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/Packages/Mouse/Mouse-i.html

Specify the mouse port(s) to be used by the driver using the SFX_MOUSE variable in libSFX.cfg. Multiple ports can be OR-ed together.

```cfg
SFX_MOUSE = MOUSE1 | MOUSE2
```

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

### SFX_joy#cont

Source: https://github.com/optiroc/libsfx/blob/master/docs/files/CPU_Runtime-i.html

Joypad continuous read-out (word). If enabled, libSFX performs automatic joypad read-out and sets the 12 most significant bits to 1 as buttons are pushed.

```APIDOC
## SFX_joy#cont

### Description
Joypad continous read-out (word). If enabled with [SFX_JOY](Configurations/libSFX-cfg.html#SFX_JOY), libSFX performs automatic joypad read-out and sets the 12 most significant bits in these variables to 1 continously as the corresponding joypad button is pushed.

Depending on how many joypads are enabled for automatic read-out in libSFX.cfg, SFX_joy1cont to SFX_joy4cont are available.

#### Button Mapping

> Bit       Button
> 15        B
> 14        Y
> 13        Select
> 12        Start
> 11        Up
> 10        Down
> 09        Left
> 08        Right
> 07        A
> 06        X
> 05        L
> 04        R
```

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

### inidisp() / rgb()

Source: https://context7.com/optiroc/libsfx/llms.txt

Encodes display brightness and blanking status for INIDISP, and converts RGB color components into a 15-bit SNES color word.

```APIDOC
## `inidisp()` / `rgb()` — Display control and color encoding

`inidisp()` encodes a brightness + blanking byte for `INIDISP`. `rgb()` encodes a 15-bit SNES color word from three 5-bit channel values.

### `inidisp(blanking, brightness)`
Encodes the INIDISP register value.

### `rgb(red, green, blue)`
Encodes a 15-bit color value.

### Example

```asm
        ; Full brightness, screen on
        lda     #inidisp(OFF, DISP_BRIGHTNESS_MAX)
        sta     SFX_inidisp

        ; Build a color constant at assemble time
        CGRAM_setcolor  0, #rgb(31, 20, 0)   ; Orange
```
```