490 lines
12 KiB
Text
490 lines
12 KiB
Text
= *_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. :-)
|