optiroc/libsfx

Super Nintendo (SNES) development framework

libSFX

A Super Nintendo assembler development framework featuring:

• Basic system runtime for initialization and interrupt handling
• 65816 register size tracking macros to minimize rep/sep instructions (and mental overhead)
• Full set of memcpy/memset routines for efficiently transferring data to different parts of the system
• Some useful data structures with allocation and accessor macros (FIFO and FILO are currently implemented)
• S-SMP communication and SPC playing routines.
• LZ4 decompression
• Mouse driver
• Graphics conversion via SuperFamiconv
• BRR audio encoding using BRRtools
• ROM image validation via SuperFamicheck
• Sublime Text syntax definitions

Documentation available at optiroc.github.io/libSFX.

libSFX is developed by David Lindecrantz and distributed under the terms of the MIT license.

dependencies

A C/C++ toolchain, make, git and a decent command line interface.

Unix-like (Mac, Linux, etc.) systems should be ready to go out of the box. If you're running Windows the best option is to install Cygwin and make sure you include the git and mingw64 toolchain (mingw64-x86_64-binutils, mingw64-x86_64-gcc-core and mingw64-x86_64-gcc-g++) packages.

building

First you need to build the bundled tools, which are included as git submodules. Simply run make from the libSFX root path to initialize the submodules and build the tools.

Now the toolchain is in place and you should be able to run make from any of the example directories to assemble the source files and link a Super Nintendo ROM image (*.sfc).

setting up a project

For the most basic setup, copy examples/Template to a location of your liking. Then edit Makefile and make sure that libsfx_dir points to the libSFX root directory.

For project customization – for example extending the ROM size, adding SRAM or special code segments, or changing the default stack and scratchpad sizes – the build script looks for two files in the project directory; libSFX.cfg and Map.cfg. If these aren't found (like in the Template project), the defaults inside $(libsfx_dir)/include/Configurations are used.

To override the defaults, simply copy these two files into your project directory and edit them to your liking. In include/Configurations there's a few additional Map.cfg examples. You may also check out the example projects to see how a project can be customized.

acknowledgments

libSFX includes the following code and snippets:

• SPC-700 assembler for ca65 and S-SMP transfer routines by Blargg
• GSU assembler for ca65 by ARM9
• ca65 define/undefine macros by Movax12

resources

• fullsnes - comprehensive SNES reference
• ca65 users guide
• SNESdev forum

libsfx's Issues

data in ZP of SMP-Play example does not get included in main binary

In the SMP-Play example the data in the SMP zeropage doesn't seem to get included in the main binary, and never gets loaded into APURAM.

Is this intended behavior? What would the procedure be to include the zeropage in the SMP binary?

Here's a screenshot from BizHawk's Hex Editor, showing the first few bytes of APURAM. The string Zero! that's included in the source file is not loaded: Imgur Link

Sorry if i'm completely misinterpreting the example. Thanks for help in advance.

Calling VRAM_memcpy to the same location does not work for maps?

Hello, thank you for this excellent library, it helped me kickstart my dive into snes programming!

I load a background with

    LZ4_decompress Map, EXRAM, y
    VRAM_memcpy VRAM_MAP_LOC, EXRAM, y

    LZ4_decompress Tiles, EXRAM, y
    VRAM_memcpy VRAM_TILES_LOC, EXRAM, y

    CGRAM_memcpy 0, Palette, sizeof_Palette

and after the user presses the start button, another background will be loaded with

    LZ4_decompress Scr2Map, EXRAM, y
    VRAM_memcpy VRAM_MAP_LOC, EXRAM, y

    LZ4_decompress Scr2Tile, EXRAM, y
    VRAM_memcpy VRAM_TILES_LOC, EXRAM, y

    CGRAM_memcpy 0, Scr2Pal, sizeof_Scr2Pal

Unfortunately, this other background is garbled. The palette seems to load OK, but the map seems to be broken.

I have constructed a minimal example here (copy it into a subfolder of libsfx, e.g. into the examples folder):
https://github.com/josefcs/twopage-libsfx/

Forgive me, if I am missing something obvious here, but to me this seems like a bug.
Further pointers of what is going wrong would be very apreciated.

Thank you!

Compiler gets confused between CPU and SMP map files

When creating a program with a map file to use for the rom and a map file to use for the SMP, the compiler gets confused and tries to use them interchangably. This causes obvious errors when the SMP doesn't have the right mapping details.

With only one map file, the CPU doesn't seem to want to steal the SMP's, but the SMP will try and use the main CPU's. This makes it impossible to create a program with a larger than normal ROM and also SMP overlays.

WRAM_memset should transfer from ROM instead of VRAM

Recently, I've written a (somewhat CPU-heavy) effect that renders into a buffer and uses WRAM_memset to clear the buffer each time. Since almost all the normal vblank DMA bandwidth is used to get the buffer into VRAM, I end up clearing the buffer mid-frame instead, where WRAM_memset becomes problematic on a real console.

Rather than touching VRAM, a safer option might be to just have a table of all 256 possible fill values in ROM and use that as the transfer source instead. This way, it can be safely used during active display.

LZ4 decompressor crashes with specific file

I have a LZ4-compressed file that crashes the decoder in SFX_LZ4_decompress/DecodeBlock. The cpu goes haywire and the stack loops around. I have permission to send the file privately, looking up your email to do so.

Using RW_* macros inside a .proc seems to always fail

.include "libSFX.i"

;-------------------------------------------------------------------------------
.segment "CODE"

.proc test
	RW_push set:a16
	RW_pull
.endproc

test.s(7): Error: Constant expression expected
../../libSFX/include/CPU.i(234): Note: Macro was defined here
test.s(7): Error: Constant expression expected
../../libSFX/include/CPU.i(238): Note: Macro was defined here
test.s(7): Error: Constant expression expected
../../libSFX/include/CPU.i(241): Note: Macro was defined here
test.s(7): Error: Constant expression expected
../../libSFX/include/CPU.i(244): Note: Macro was defined here
test.s(7): Error: Constant expression expected
../../libSFX/include/CPU.i(270): Note: Macro was defined here
../../libSFX/include/CPU.i(69): Note: Macro was defined here
"make": *** [.build/test.o] Error 1

Is there something non-obvious I might be doing wrong here? It seems like using any of the register size macros inside of a .proc causes problems with how those macros actually keep track of register state. I'd like to be able to tidy up my code/labels a bit but unfortunately this makes it difficult to do that without breaking any libSFX macros that use the RW macros (which is pretty much all of them...)

examples build KO

Hi (again... sorry),

I got several build issues on the example you provided in libSFX.

1/ Hello-Mode7: make output : http://sprunge.us/RaQh
2/ Mode7-Transform : http://sprunge.us/fThY
3/ X-GSU : http://sprunge.us/PSVO

For 1/ and 2/, no sfc was produced.
For 3/ a SuperFX.sfc is generated, but is not functionnal (pink background, tested with higan, snes9x, nosns) ?

Have a good day,
Respectfully,
ekyo

GSU instructions bge and blt have the wrong opcodes

The opcodes for the SuperFX blt and bge are swapped. libSFX assembles them as bge = 06xx and blt as 07xx, but these values should be reversed.

dead link in readme

Following the "projects" link here gives a soft 404:

You may also check out the example projects to see how a project can be customized.

JOY_L and JOY_R are swapped in CPU_Def.i

The shoulder button defines are the wrong way around. Curious that it's not been noticed til now, maybe so few games use them.

Master:

JOY_L                   = $0010
JOY_R                   = $0020

nocash docs:

15          1st        Button B          (1=Low=Pressed)
  14          2nd        Button Y
  13          3rd        Select Button
  12          4th        Start Button
  11          5th        DPAD Up
  10          6th        DPAD Down
  9           7th        DPAD Left
  8           8th        DPAD Right
  7           9th        Button A
  6           10th       Button X
  5           11th       Button L
  4           12th       Button R
  3           13th       0 (High)
  2           14th       0 (High)
  1           15th       0 (High)
  0           16th       0 (High)