Public_Skunkworks/f256
Public_Skunkworks/f256
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

Started asciidoc documentation.

Browse source
This commit is contained in:
Scott Duensing 2024-06-03 20:28:33 -05:00
parent a7c1bdc4cd
commit cf3bceda58
13 changed files with 713 additions and 396 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -46,6 +46,7 @@ overlay
overlayhelper
f256lib.h
/distro/f256dev.7z
/distro/f256dev.tar.xz
# These aren't for public use or aren't ready.
build-foenix-ide.sh

3
build-distro.sh
View file

@ -102,7 +102,8 @@ pushd distro
if [[ -f ../f256dev.tar.xz ]]; then
rm ../f256dev.tar.xz
fi
tar cjf ../f256dev.tar.xz .
tar cf ../f256dev.tar .
xz -z9e ../f256dev.tar
popd
popd

42
distro/README
View file

@ -1,8 +1,8 @@
_____ ____ ____ __ _ _
| ___|___ \| ___| / /_ | | |_ ___ __ ___ _ __ ___ ___ ___
| |_ __) |___ \| '_ \ | | \ \ / / '_ ` _ \ _____| '_ ` _ \ / _ \/ __|
| _| / __/ ___) | (_) | | | |\ V /| | | | | |_____| | | | | | (_) \__ \
|_| |_____|____/ \___/ |_|_| \_/ |_| |_| |_| |_| |_| |_|\___/|___/
_____ ____ ____ __ ____
| ___|___ \| ___| / /_ | _ \ _____ __
| |_ __) |___ \| '_ \ | | | |/ _ \ \ / /
| _| / __/ ___) | (_) | | |_| | __/\ V /
|_| |_____|____/ \___/ |____/ \___| \_/
Welcome to LLVM-MOS for the Foenix F256 family of computers!
@ -47,6 +47,12 @@ only thing that should need updated is the COM port used to communicate with
your F256. See: https://github.com/pweingar/FoenixMgr
UPGRADING
=========
Just re-run f256-install!
ASSUMPTIONS
===========
@ -78,13 +84,6 @@ USAGE
As shown above, f256build is used to build projects using the default linker
settings.
***FIX*** If you do not have linker settings in your project already, the
defaults will be added (in a file named f256.ld in your project directory).
Unless you need to use embedded binary data in your project, the defaults are
all you need. Embedded data examples are included. See SPRITES and TILEMAP in
the EXAMPLES folder. More details can be found in the f256lib documentation.
When building your project f256build will create a ".builddir" folder in your
project directory. In here you will find copies of your source code that have
been modified by the overlay tool (for creating programs larger than 64k),
@ -102,6 +101,23 @@ If you do not have a debug cable, you can copy the PGZ for your program from
its project directory to the SD card used in your F256.
TIPS
====
* Do NOT edit anything in the f256dev directory! It gets replaced on updates!
* Do NOT add anything under the f256dev directory! It gets nuked on updates!
* Create a "code" directory in the folder you copied f256-install into. Put
your F256 projects in directories under "code" for easy bulding!
* EMBED(); arguments must be literals. You cannot use #defines or variables.
* EMBED(); names (first argument) must begin with unique prefixes. For example,
"TILES" and "TILES_PALETTE" will cause an error due to "TILES" being a
complete substring of "TILES_PALETTE".
SUPPORT
=======
@ -118,7 +134,7 @@ and I'll probably ask you to join the Discord. :-)
HISTORY
=======
* xx-MAY-2024 - Everything now installs into a single folder for safe updating.
* 25-MAY-2024 - Everything now installs into a single folder for safe updating.
Linker scripts not added to projects by default any longer.
* 09-MAY-2024 - Updated MacOS and Linux installation script to also search for

20
distro/f256-install.bat
View file

@ -27,6 +27,13 @@ goto top
:top
echo.
for /f "useback delims=" %%_ in (%0) do (
if "%%_"=="___OGOL___" set $=
if defined $ echo(%%_
if "%%_"=="___LOGO___" set $=1
)
echo.
set REMOTE1=https://github.com/llvm-mos/llvm-mos-sdk/releases/latest/download/llvm-mos-windows.7z
set LOCAL1=llvm-mos-windows.7z
@ -136,3 +143,16 @@ echo FoenixMgr for your machine. Edit the foenixmgr.ini file in this directory.
echo -----------------------------------------------------------------------------
echo.
pause
goto :eof
___LOGO___
_____ ____ ____ __ ____
| ___|___ \| ___| / /_ | _ \ _____ __
| |_ __) |___ \| '_ \ | | | |/ _ \ \ / /
| _| / __/ ___) | (_) | | |_| | __/\ V /
|_| |_____|____/ \___/ |____/ \___| \_/
___OGOL___

13
distro/f256-install.sh
View file

@ -26,6 +26,13 @@
# This script is intended for use on Linux and MacOS.
#
echo
echo " _____ ____ ____ __ ____"
echo "| ___|___ \\| ___| / /_ | _ \\ _____ __"
echo "| |_ __) |___ \\| '_ \\ | | | |/ _ \\ \\ / /"
echo "| _| / __/ ___) | (_) | | |_| | __/\\ V /"
echo "|_| |_____|____/ \\___/ |____/ \\___| \\_/"
echo
MACTEST=$(uname -a | grep Darwin)
if [[ $? == 0 ]]; then
@ -91,7 +98,7 @@ else
fi
fi
if [[ -z ${MAC} ]]; then
if [[ ! -z ${MAC} ]]; then
xattr -d com.apple.quarantine ${LOCAL1}
xattr -d com.apple.quarantine ${LOCAL2}
xattr -d com.apple.quarantine ${LOCAL3}
@ -102,8 +109,8 @@ if [[ -d f256dev ]]; then
fi
mkdir -p f256dev
pushd f256dev
tar xf ${LOCAL1}
unzip -o ${LOCAL3}
tar xf ../${LOCAL1}
unzip -o ../${LOCAL3}
popd
tar xf ${LOCAL2}

2
distro/f256build.bat
View file

@ -58,7 +58,7 @@ pushd "%PROJECT%"
if not exist f256.ld copy /y "%ROOT%\llvm-mos\mos-platform\f256\lib\link.ld" f256.ld > NUL
set OLDPATH=%PATH%
set PATH=%~dp0llvm-mos\bin;%PATH%
call mos-f256-clang.bat -v *.c -o %NAME% -I"%ROOT%" -Tf256.ld -Wl,-Map=%NAME%.map -Os -Wall -lm
call mos-f256-clang.bat *.c -o %NAME% -I"%ROOT%" -Tf256.ld -Wl,-Map=%NAME%.map -Os -Wall -lm
if errorlevel 1 goto failed
ren %NAME% %NAME%.pgz
llvm-nm.exe %NAME%.elf > %NAME%.sym

111
examples/sprites/f256.ld
View file

@ -1,111 +0,0 @@
/* fake C Stack */
PROVIDE(__stack = 0xA000);
/* entry point to my program - 0x200 to 0x2ff are command line arguments */
PROVIDE(__f256_start = 0x300);
/* page size of a block of memory */
PROVIDE(__BLOCK_SIZE = 0x2000);
/* swappable block address */
PROVIDE(__SLOT_ADDR = 0xA000);
/* f256k uses first 16 bytes of ZP for mmu control? */
__rc0 = 0x10;
INCLUDE imag-regs.ld
ASSERT(__rc0 == 0x10, "Inconsistent zero page map.")
ASSERT(__rc31 == 0x2f, "Inconsistent zero page map.")
MEMORY {
/* kernel uses 0xf0-0xff for parameter passing */
zp : ORIGIN = __rc31 + 1, LENGTH = 0xF0 - (__rc31 + 1)
ram (rw) : ORIGIN = __f256_start, LENGTH = __stack-__f256_start
}
/* LMAs */
__block8_lma = ( 8<<24)|__SLOT_ADDR;
__block9_lma = ( 9<<24)|__SLOT_ADDR;
__block10_lma = (10<<24)|__SLOT_ADDR;
__block11_lma = (11<<24)|__SLOT_ADDR;
__block12_lma = (12<<24)|__SLOT_ADDR;
__block13_lma = (13<<24)|__SLOT_ADDR;
__block14_lma = (14<<24)|__SLOT_ADDR;
__block15_lma = (15<<24)|__SLOT_ADDR;
__block16_lma = (16<<24)|__SLOT_ADDR;
__block17_lma = (17<<24)|__SLOT_ADDR;
__block18_lma = (18<<24)|__SLOT_ADDR;
__block19_lma = (19<<24)|__SLOT_ADDR;
__block20_lma = (20<<24)|__SLOT_ADDR;
__block21_lma = (21<<24)|__SLOT_ADDR;
__block22_lma = (22<<24)|__SLOT_ADDR;
__block23_lma = (23<<24)|__SLOT_ADDR;
/* Stash preloaded binary data */
__binarydata_lma = 0x10000;
__BINARYDATA_SIZE = 0xA081; /* Size of sprites.bin + 1 */
MEMORY {
block8 : ORIGIN = __block8_lma, LENGTH = __BLOCK_SIZE
block9 : ORIGIN = __block9_lma, LENGTH = __BLOCK_SIZE
block10 : ORIGIN = __block10_lma, LENGTH = __BLOCK_SIZE
block11 : ORIGIN = __block11_lma, LENGTH = __BLOCK_SIZE
block12 : ORIGIN = __block12_lma, LENGTH = __BLOCK_SIZE
block13 : ORIGIN = __block13_lma, LENGTH = __BLOCK_SIZE
block14 : ORIGIN = __block14_lma, LENGTH = __BLOCK_SIZE
block15 : ORIGIN = __block15_lma, LENGTH = __BLOCK_SIZE
block16 : ORIGIN = __block16_lma, LENGTH = __BLOCK_SIZE
block17 : ORIGIN = __block17_lma, LENGTH = __BLOCK_SIZE
block18 : ORIGIN = __block18_lma, LENGTH = __BLOCK_SIZE
block19 : ORIGIN = __block19_lma, LENGTH = __BLOCK_SIZE
block20 : ORIGIN = __block20_lma, LENGTH = __BLOCK_SIZE
block21 : ORIGIN = __block21_lma, LENGTH = __BLOCK_SIZE
block22 : ORIGIN = __block22_lma, LENGTH = __BLOCK_SIZE
block23 : ORIGIN = __block23_lma, LENGTH = __BLOCK_SIZE
binarydata : ORIGIN = __binarydata_lma, LENGTH = __BINARYDATA_SIZE
}
REGION_ALIAS("c_writeable", ram)
REGION_ALIAS("c_readonly", ram)
SECTIONS {
INCLUDE c.ld
.block8 : { *(.block8 .block8.*) } >block8 end_block8 = .;
.block9 : { *(.block9 .block9.*) } >block9 end_block9 = .;
.block10 : { *(.block10 .block10.*) } >block10 end_block10 = .;
.block11 : { *(.block11 .block11.*) } >block11 end_block11 = .;
.block12 : { *(.block12 .block12.*) } >block12 end_block12 = .;
.block13 : { *(.block13 .block13.*) } >block13 end_block13 = .;
.block14 : { *(.block14 .block14.*) } >block14 end_block14 = .;
.block15 : { *(.block15 .block15.*) } >block15 end_block15 = .;
.block16 : { *(.block16 .block16.*) } >block16 end_block16 = .;
.block17 : { *(.block17 .block17.*) } >block17 end_block17 = .;
.block18 : { *(.block18 .block18.*) } >block18 end_block18 = .;
.block19 : { *(.block19 .block19.*) } >block19 end_block19 = .;
.block20 : { *(.block20 .block20.*) } >block20 end_block20 = .;
.block21 : { *(.block21 .block21.*) } >block21 end_block21 = .;
.block22 : { *(.block22 .block22.*) } >block22 end_block22 = .;
.block23 : { *(.block23 .block23.*) } >block23 end_block23 = .;
.binarydata : { *(.binarydata .binarydata.*) } >binarydata end_binarydata = .;
}
OUTPUT_FORMAT {
BYTE(0x5A) /* pgZ */
/* RAM Segment */
SHORT(ORIGIN(ram)) /* where to load it, 24 bits */
BYTE(0x00)
SHORT(__bss_start-ORIGIN(ram)) /* size to load */
BYTE(0x00)
TRIM(ram)
/* Overlay Segments */
INCLUDE output.ld
/* Binary Data */
SHORT(ORIGIN(binarydata))
BYTE(ORIGIN(binarydata)>>16)
SHORT(end_binarydata - __binarydata_lma)
BYTE((end_binarydata - __binarydata_lma)>>16)
TRIM(binarydata)
/* Launch the program, at _start */
SHORT(_start)
LONG(0)
}

2
examples/sprites/src/sprites.c
View file

@ -48,7 +48,7 @@
#define TURN_SPEED 25
EMBED(".binarydata.embedded", embedded, "../generated/sprites.bin");
EMBED(embedded, "../generated/sprites.bin", 0x10000);
static uint32_t spriteStartAddrs[SPRITE_COUNT] = { SPR_LEFT_ADDR, SPR_LEFT_FRONT_ADDR, SPR_RIGHT_FRONT_ADDR, SPR_RIGHT_ADDR };

111
examples/tilemap/f256.ld
View file

@ -1,111 +0,0 @@
/* fake C Stack */
PROVIDE(__stack = 0xA000);
/* entry point to my program - 0x200 to 0x2ff are command line arguments */
PROVIDE(__f256_start = 0x300);
/* page size of a block of memory */
PROVIDE(__BLOCK_SIZE = 0x2000);
/* swappable block address */
PROVIDE(__SLOT_ADDR = 0xA000);
/* f256k uses first 16 bytes of ZP for mmu control? */
__rc0 = 0x10;
INCLUDE imag-regs.ld
ASSERT(__rc0 == 0x10, "Inconsistent zero page map.")
ASSERT(__rc31 == 0x2f, "Inconsistent zero page map.")
MEMORY {
/* kernel uses 0xf0-0xff for parameter passing */
zp : ORIGIN = __rc31 + 1, LENGTH = 0xF0 - (__rc31 + 1)
ram (rw) : ORIGIN = __f256_start, LENGTH = __stack-__f256_start
}
/* LMAs */
__block8_lma = ( 8<<24)|__SLOT_ADDR;
__block9_lma = ( 9<<24)|__SLOT_ADDR;
__block10_lma = (10<<24)|__SLOT_ADDR;
__block11_lma = (11<<24)|__SLOT_ADDR;
__block12_lma = (12<<24)|__SLOT_ADDR;
__block13_lma = (13<<24)|__SLOT_ADDR;
__block14_lma = (14<<24)|__SLOT_ADDR;
__block15_lma = (15<<24)|__SLOT_ADDR;
__block16_lma = (16<<24)|__SLOT_ADDR;
__block17_lma = (17<<24)|__SLOT_ADDR;
__block18_lma = (18<<24)|__SLOT_ADDR;
__block19_lma = (19<<24)|__SLOT_ADDR;
__block20_lma = (20<<24)|__SLOT_ADDR;
__block21_lma = (21<<24)|__SLOT_ADDR;
__block22_lma = (22<<24)|__SLOT_ADDR;
__block23_lma = (23<<24)|__SLOT_ADDR;
/* Stash preloaded binary data */
__binarydata_lma = 0x10000;
__BINARYDATA_SIZE = 0x5f845; /* Size of tiles.bin + 1 */
MEMORY {
block8 : ORIGIN = __block8_lma, LENGTH = __BLOCK_SIZE
block9 : ORIGIN = __block9_lma, LENGTH = __BLOCK_SIZE
block10 : ORIGIN = __block10_lma, LENGTH = __BLOCK_SIZE
block11 : ORIGIN = __block11_lma, LENGTH = __BLOCK_SIZE
block12 : ORIGIN = __block12_lma, LENGTH = __BLOCK_SIZE
block13 : ORIGIN = __block13_lma, LENGTH = __BLOCK_SIZE
block14 : ORIGIN = __block14_lma, LENGTH = __BLOCK_SIZE
block15 : ORIGIN = __block15_lma, LENGTH = __BLOCK_SIZE
block16 : ORIGIN = __block16_lma, LENGTH = __BLOCK_SIZE
block17 : ORIGIN = __block17_lma, LENGTH = __BLOCK_SIZE
block18 : ORIGIN = __block18_lma, LENGTH = __BLOCK_SIZE
block19 : ORIGIN = __block19_lma, LENGTH = __BLOCK_SIZE
block20 : ORIGIN = __block20_lma, LENGTH = __BLOCK_SIZE
block21 : ORIGIN = __block21_lma, LENGTH = __BLOCK_SIZE
block22 : ORIGIN = __block22_lma, LENGTH = __BLOCK_SIZE
block23 : ORIGIN = __block23_lma, LENGTH = __BLOCK_SIZE
binarydata : ORIGIN = __binarydata_lma, LENGTH = __BINARYDATA_SIZE
}
REGION_ALIAS("c_writeable", ram)
REGION_ALIAS("c_readonly", ram)
SECTIONS {
INCLUDE c.ld
.block8 : { *(.block8 .block8.*) } >block8 end_block8 = .;
.block9 : { *(.block9 .block9.*) } >block9 end_block9 = .;
.block10 : { *(.block10 .block10.*) } >block10 end_block10 = .;
.block11 : { *(.block11 .block11.*) } >block11 end_block11 = .;
.block12 : { *(.block12 .block12.*) } >block12 end_block12 = .;
.block13 : { *(.block13 .block13.*) } >block13 end_block13 = .;
.block14 : { *(.block14 .block14.*) } >block14 end_block14 = .;
.block15 : { *(.block15 .block15.*) } >block15 end_block15 = .;
.block16 : { *(.block16 .block16.*) } >block16 end_block16 = .;
.block17 : { *(.block17 .block17.*) } >block17 end_block17 = .;
.block18 : { *(.block18 .block18.*) } >block18 end_block18 = .;
.block19 : { *(.block19 .block19.*) } >block19 end_block19 = .;
.block20 : { *(.block20 .block20.*) } >block20 end_block20 = .;
.block21 : { *(.block21 .block21.*) } >block21 end_block21 = .;
.block22 : { *(.block22 .block22.*) } >block22 end_block22 = .;
.block23 : { *(.block23 .block23.*) } >block23 end_block23 = .;
.binarydata : { *(.binarydata .binarydata.*) } >binarydata end_binarydata = .;
}
OUTPUT_FORMAT {
BYTE(0x5A) /* pgZ */
/* RAM Segment */
SHORT(ORIGIN(ram)) /* where to load it, 24 bits */
BYTE(0x00)
SHORT(__bss_start-ORIGIN(ram)) /* size to load */
BYTE(0x00)
TRIM(ram)
/* Overlay Segments */
INCLUDE output.ld
/* Binary Data */
SHORT(ORIGIN(binarydata))
BYTE(ORIGIN(binarydata)>>16)
SHORT(end_binarydata - __binarydata_lma)
BYTE((end_binarydata - __binarydata_lma)>>16)
TRIM(binarydata)
/* Launch the program, at _start */
SHORT(_start)
LONG(0)
}

2
examples/tilemap/src/tilemap.c
View file

@ -32,7 +32,7 @@
#define TILES_CLUT 0x6f804 // Len: 0x40
EMBED(".binarydata.embedded", embedded, "../tiles/tiles.bin");
EMBED(embedded, "../tiles/tiles.bin", 0x10000);
int main(int argc, char *argv[]) {

490
f256lib.adoc Normal file
View file

@ -0,0 +1,490 @@
= *_F256Dev_*: Compiler, Tools, and C Library for the Foenix F256 Family of Computers
:author: Scott Duensing
:email: scott@kangaroopunch.com
:homepage: https://kangaroopunch.com
:revnumber: 1.0
:revdate: 03-JUN-2024
:revremark: First Draft
:source-highlighter: coderay
:sectnums:
:toc: left
:toclevels: 5
:toc-title: Contents
== Introduction
*_F256Dev_* is a C development system for the https://c256foenix.com[Foenix F256]
family of "modern retro" computers.
It consists of the *_LLVM-MOS_* compiler toolchain, the *_F256lib_* programming library,
several helpful tools, build and run scripts, and more.
*_F256lib_* is a C library targeting the F256 family.
It provides easy access to the platform's various features (graphics, text, I/O, etc.) from
within a C program.
In addition, *_F256lib_* also unleashes the power of the F256 by automatically handling most of
the sometimes tricky memory management and paging required to truly harness the power of the system.
== Audience
This document is not an introduction to programming. It assumes you are comfortable with
your host OS and working from the command line.
== Requirements
* Foenix F256jr, F256K, (or emulator) with a 65c02 or 65816 CPU.
* Host PC running Linux (x64), Windows (x64), or MacOS (Apple Silicon).
On Windows, you will also need:
* https://www.rarlab.com/[WinRAR] or https://www.7zip.com/[7-Zip] installed.
* https://www.python.org/[Python 3.x] installed and in your PATH.
For MacOS and Linux:
* Ensure you have Python 3.x installed.
NOTE: Although the 65816 is supported, it is currently treated as a 65c02.
== Installation
Download the appropriate installation script:
|===
| Platform |Script
| 64 bit Intel Windows
| https://kangaroopunch.com/files/download/software/f256-install.bat[f256-install.bat]
| 64 bit Intel Linux
| https://kangaroopunch.com/files/download/software/f256-install.sh[f256-install.sh]
| 64 bit ARM MacOS
| https://kangaroopunch.com/files/download/software/f256-install.sh[f256-install.sh]
|===
Create a new, empty directory, with no spaces in the name (or in the names of
the parent directories) and place this file into it. Recommended locations:
* On Windows: `C:\F256`
* On Linux and MacOS: `~/f256`
From that folder, execute
the script. It will download additional dependencies and install them. Aside
from some Python modules needed by FoenixManager, everything will stay inside
this new folder. Uninstalling is just a matter of deleting it.
== Configuration
You will need to modify `foenixmgr.ini` in the main installation folder. The
only thing that should need updated is the COM port used to communicate with
your F256. See: https://github.com/pweingar/FoenixMgr
== Upgrading
Just re-run your `f256-install` script!
WARNING: This will *delete* the `f256dev` folder!
== Assumptions
This package was designed to be easy to use for new programmers. As such, some
liberties were taken that aren't entirely common practice. There are no
project files, makefiles, or other build configuration systems. The included
`f256build` and `f256run` scripts assume you have arranged your code in directories
like the example programs. If you are more advanced than this, feel free to go
crazy.
== Amalgamated or Not?
*_F256lib_* is distributed in two formats. _Amalgamated_ (everything in a single header file) or as individual source files for each
section of the API.
We *highly* recommend using the amalgamated build unless you are interested in working on the library
itself. The included build tools do not support using the non-amalgamated version out-of-the-box.
== Usage
Using *_F256lib_* is pretty painless for a low-level C library.
Simply include the header in each of your source files.
=== Setting Up Your Project
The main requirement is that each program have its
own parent directory named for that program and inside it, a "src" directory
where the actual code lives. Example:
[source]
C:\F256\CODE\MYPROGRAM\SRC
This would be a project named `MYPROGRAM` located in a `CODE` folder under the
folder you installed the toolkit in. (You do not have to locate your projects
under the toolkit folder.)
=== Creating Your Main Source File
In the file that contains your `main()` function, start with the following:
[,c]
----
#define F256LIB_IMPLEMENTATION
#include "f256lib.h"
int main(int argc, char *argv[]) {
printf("Hello from F256 Land!");
while(1)
;
return 0; // Reaching this will reset the F256.
}
----
=== Building Your Project
To build this, you would run `f256build` from the
`C:\F256` folder as follows:
[source]
f256build.bat code\myprogram
UNIX folks, flip your slashes!
[source]
----
./f256build.sh code/myprogram
----
When using `f256build` to build your projects, the include path will be set automatically.
=== Running Your Project
If you properly configured your `foenixmgr.ini` and have connected your F256
to your host PC, simply use `f256run` to start your program:
[source]
f256run.bat code\myprogram
UNIX folks, still flip your slashes!
[source]
----
./f256run.sh code/myprogram
----
=== Debugging
If your program fails to compile or isn't doing what you expect, a lot of
useful information can be found in the `.builddir` directory that is created
under your program's project directory.
== API Overview
The *_F256lib_* API is broken down into several general sections:
* Constants
* Helpers
* Kernel
* DMA
* Math Co-Processor
* Random Numbers
* Text
* Graphics
* Bitmaps
* Sprites
* Tiles
* File I/O
* Platform
== API Details
=== Constants
true
false
=== Types
bool
byte
colorT
kernelArgsT
kernelEventT
=== Enums
textColorsT
=== Helpers
byte value = PEEK(uint16_t address);
POKE(uint16_t address, byte value);
uint16_t value = PEEKW(uint16_t address);
POKEW(uint16_t address, uint16_t value);
POKEA(uint16_t address, uint32_t value);
uint32_t value = PEEKD(uint16_t address);
POKED(uint16_t address, uint32_t value);
byte value = FAR_PEEK(uint32_t address);
FAR_POKE(uint32_t address, byte value);
uint16_t value = FAR_PEEKW(uint32_t address);
FAR_POKEW(uint32_t address, uint16_t value);
byte result = LOW_BYTE(int16_t value);
byte result = HIGH_BYTE(int16_t value);
byte result = SWAP_NIBBLES(byte value);
uint16_t result = SWAP_UINT16(uint16_t value);
byte result = CHECK_BIT(byte value, byte position);
byte result = TOGGLE_BIT(byte value, byte position);
byte result = CLEAR_BIT(byte value, byte position);
byte result = SET_BIT(byte value, byte position);
=== Kernel
void kernelNextEvent(void);
char kernelCall(function);
byte kernelGetPending(void);
char kernelError;
kernelArgsT *kernelArgs;
=== DMA
void dmaFill(uint32_t start, uint32_t length, byte value);
void dma2dFill(uint32_t start, uint16_t width, uint16_t height, uint16_t stride, byte value);
=== Math Co-Processor
int16_t mathSignedDivision(int16_t a, int16_t b);
int16_t mathSignedDivisionRemainder(int16_t a, int16_t b, int16_t *remainder);
int32_t mathSignedMultiply(int16_t a, int16_t b);
uint32_t mathUnsignedAddition(uint32_t a, uint32_t b);
uint16_t mathUnsignedDivision(uint16_t a, uint16_t b);
uint16_t mathUnsignedDivisionRemainder(uint16_t a, uint16_t b, uint16_t *remainder);
uint32_t mathUnsignedMultiply(uint16_t a, uint16_t b);
=== Random Numbers
uint16_t randomRead(void);
void randomSeed(uint16_t seed);
=== Text
void textClear(void);
void textDefineBackgroundColor(byte slot, byte r, byte g, byte b);
void textDefineForegroundColor(byte slot, byte r, byte g, byte b);
void textEnableBackgroundColors(bool b);
void textGetXY(byte *x, byte *y);
void textGotoXY(byte x, byte y);
void textPrint(char *message);
void textPrintInt(int32_t value);
void textPrintUInt(uint32_t value);
void textSetColor(byte f, byte b);
void textSetCursor(byte c);
void textSetDouble(bool x, bool y);
colorT textColors[16];
=== Graphics
void graphicsDefineColor(byte clut, byte slot, byte r, byte g, byte b);
void graphicsSetLayerBitmap(byte layer, byte which);
void graphicsSetLayerTile(byte layer, byte which);
void graphicsWaitVerticalBlank(void);
=== Bitmaps
void bitmapClear(void);
void bitmapGetResolution(uint16_t *x, uint16_t *y);
void bitmapLine(uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2);
void bitmapPutPixel(uint16_t x, uint16_t y);
void bitmapSetActive(byte p);
void bitmapSetAddress(byte p, uint32_t a);
void bitmapSetCLUT(byte clut);
void bitmapSetColor(byte c);
void bitmapSetVisible(byte p, bool v);
=== Sprites
void spriteDefine(byte s, uint32_t address, byte size, byte CLUT, byte layer);
void spriteSetPosition(byte s, uint16_t x, uint16_t y);
void spriteSetVisible(byte s, bool v);
=== Tiles
void tileDefineTileMap(byte t, uint32_t address, byte tileSize, uint16_t mapSizeX, uint16_t mapSizeY);
void tileDefineTileSet(byte t, uint32_t address, bool square);
void tileSetScroll(byte t, byte xPixels, uint16_t xTiles, byte yPixels, uint16_t yTiles);
void tileSetVisible(byte t, bool v);
=== File I/O
fileDirEntT
int8_t fileClose(uint8_t *fd);
int8_t fileCloseDir(char *dir);
int8_t fileMakeDir(char *dir);
uint8_t *fileOpen(char *fname, char *mode);
char *fileOpenDir(char *name);
int16_t fileRead(void *buf, uint16_t nbytes, uint16_t nmemb, uint8_t *fd);
fileDirEntT *fileReadDir(char *dir);
int8_t fileRemoveDir(char *dir);
int8_t fileRename(char *name, char *to);
int8_t fileSeek(uint8_t *fd, uint32_t offset, uint8_t whence);
int8_t fileUnlink(char *name);
int16_t fileWrite(void *buf, uint16_t nbytes, uint16_t nmemb, uint8_t *fd);
#define _DE_ISREG(t) (t == 0)
#define _DE_ISDIR(t) (t == 1)
#define _DE_ISLBL(t) (t == 2)
#define _DE_ISLNK(t) (0)
#define closedir fileCloseDir
#define DIR char
#define dirent fileDirEntS
#define FILE uint8_t
#define fclose fileClose
#define fopen fileOpen
#define fread fileRead
#define fseek fileSeek
#define fwrite fileWrite
#define mkdir(d,m) fileMakeDir(d)
#define opendir fileOpenDir
#define readdir fileReadDir
#define rename fileRename
#define rewind(s) (void)fileSeek(s, 0, SEEK_SET)
#define rmdir fileRemoveDir
#define SEEK_SET 0
#define STDIN 0
#define STDOUT 1
#define unlink fileUnlink
=== Platform
void __putchar(char c);
int getchar(void);
== Using Code Overlays
== Embedding Binary Data
* EMBED(); arguments must be literals. You cannot use #defines or variables.
* EMBED(); names (first argument) must begin with unique prefixes. For example,
"TILES" and "TILES_PALETTE" will cause an error due to "TILES" being a
complete substring of "TILES_PALETTE".
== Optional Options
Before including *_F256lib_*, you may wish to define one or more of the following
to customize the library for your application:
|===
| `#DEFINE` |Description
| `SWAP_RESTORE`
| When using functions such as `FAR_PEEK` or bitmap features, return the swap slot back to it's original memory location before returning. By default, the swap slot is left in whatever state the last function that used it switched it to.
| `WITHOUT_GRAPHICS`
| Shortcut for `WITHOUT_BITMAP`, `WITHOUT_TILE`, and `WITHOUT_SPRITE`.
| `WITHOUT_BITMAP`
| Disables bitmap functions.
| `WITHOUT_TILE`
| Disables tilemap functions.
| `WITHOUT_SPRITE`
| Disables sprite functions.
| `WITHOUT_FILE`
| Disables file handling support.
| `WITHOUT_KERNEL`
| Disables microkernel support. Also disables `FILE`, `PLATFORM`, and `MAIN`.
| `WITHOUT_TEXT`
| Disables text functions. Also disables `PLATFORM`.
| `WITHOUT_MATH`
| Disables math co-processor support. Also disables `TEXT`, `PLATFORM` and `BITMAP`.
| `WITHOUT_MAIN`
| Removes support for the standardized `int main(int argc, char *argv[])` function and replaces it with `int main(void)`. You must also manually call `f256Init()` at the start of your program.
| `WITHOUT_PLATFORM`
| Removes basic C library I/O support for `getchar()` and `__putchar()`. This removes `printf()`.
| `WITHOUT_DMA`
| Removes DMA support. In the future, will also disable `BITMAP`.
|===
.Example:
[,c]
----
#define WITHOUT_FILE
#define WITHOUT_SPRITE
#define WITHOUT_TILE
#define F256LIB_IMPLEMENTATION
#include "f256lib.h"
int main(int argc, char *argv[]) {
return 0;
}
----
The compiler is really good at removing dead code so this isn't usually needed.
It's primarily helpful to purposefully diable features so you receive errors if
you attempt to use them.
== Support
Drop by the https://discord.gg/e32efF7FGy[Foenix Retro Systems Discord]!
I am almost always online as "sduensin".
Additional information on the F256 family of computers can be found on the
http://wiki.f256foenix.com/[F256 wiki].
As a last resort, you can email me, Scott Duensing, at scott@kangaroopunch.com
and I'll probably ask you to join the Discord. :-)

4
tools/overlay/overlay.c
View file

@ -283,6 +283,8 @@ void parseCFile(char *filename, char *targetFile, FILE *trampoline, char *trampo
} else { // Brackets
if (!inComment) {
// Is this a segment definition? "#define SEGMENT_<something>"
// ***TODO*** This doesn't allow the definition to be indented.
found = false;
@ -381,6 +383,8 @@ void parseCFile(char *filename, char *targetFile, FILE *trampoline, char *trampo
}
}
} // !inComment
// Write to output.
fprintf(out, "%s\n", buffer);