= *_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.

While we've tried to simplify things, do not be afraid to dig into the source code
for *_F256lib_* and the included tools!


[quote,Some Code Monkey Jedi]
Use the Source, Luke!



== 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.


== Definitions

* `low memory`: the first 64k of memory (0x0000 to 0xffff).
* `far memory`: RAM not directly accessable by the CPU (from 0x10000 on).



== API Overview

The *_F256lib_* API is broken down into several general sections:

[cols="1,3",grid=rows,frame=none]
|===
| <<Constants>>
| Provides friendly names for often used hardware addresses, kernel functions, and more.

| <<Types>>
| Helpful data types to keep you code ambiguity-free.

| <<Helpers>>
| Functions for safely dealing with memory and bits.

| <<Kernel>>
| Access to the TinyCore MicroKernel.

| <<DMA>>
| Direct memory access for fast fills and copies.

| <<Math Co-Processor>>
| Highly performant common math functions.

| <<Random Numbers>>
| Easy hardware-assisted random numbers.

| <<Text>>
| Text display layer handling.

| <<Graphics>>
| Common graphic functions shared by the bitmap, sprite, and tile layers.

| <<Bitmaps>>
| Bitmap graphic features.

| <<Sprites>>
| Functions for defining and manipulating sprites.

| <<Tiles>>
| Tile-based graphics features.

| <<File I/O>>
| MicroKernel file I/O wrapped as standard C file functions.

| <<Platform>>
| Bare minimum features needed to support the compiler standard library.
|===



== API Details

The following section is a detailed description of the API provided by
*_F256lib_*.  Only the portions of the API that are considered "stable" are
documented.  You may discover other (potentially dangerous) goodies in the
source code.


=== Constants

A _lot_ of constants are provided by *_F256lib_*.  Hardware registers, kernel
functions, return values, and more.  If they were all listed here, this document
would be longer than anyone cares to read.  For the ugly details, please see
the following:

* `f256dev\f256lib\f_api.h` contains kernel information.
* `f256dev\include` is full of header files containing handy contants.


=== Types

*_F256lib_* provides clear, helpful, data types.  It's highly recommended
that you use `stdint.h`-style types for integer data to avoid size confusion. In
addition, we recommend using `char` only when you really mean character data,
`byte` for unsigned bytes, and `bool` for boolean values.  `true` and `false`
are also provided.



=== Helpers

These helper functions are convenience features for dealing directly
with memory.  Using them ensures the compiler will not optimize out
memory accesses that appear to "do nothing" but may be significant to the
hardware.

==== PEEK

[,c]
----
byte value = PEEK(uint16_t address);
----

Returns the 8 bit value of a given low memory address.

==== POKE

[,c]
----
POKE(uint16_t address, byte value);
----

Writes an 8 bit value to a given low memory address.

==== PEEKW

[,c]
----
uint16_t value = PEEKW(uint16_t address);
----

Returns the 16 bit value starting at a given low memory address.

==== POKEW

[,c]
----
POKEW(uint16_t address, uint16_t value);
----

Writes a 16 bit value starting at a given low memory address.

==== POKEA

[,c]
----
POKEA(uint16_t address, uint32_t value);
----

Writes a 24 bit value starting at a given low memory address.  The remaining
8 bits of the `value` argument are ignored.

==== PEEKD

[,c]
----
uint32_t value = PEEKD(uint16_t address);
----

Returns the 32 bit value starting at a given low memory address.

==== POKED

[,c]
----
POKED(uint16_t address, uint32_t value);
----

Writes a 32 bit value starting at a given low memory address.

==== FAR_PEEK

[,c]
----
byte value = FAR_PEEK(uint32_t address);
----

Returns the 8 bit value of a given far memory address.

==== FAR_POKE

[,c]
----
FAR_POKE(uint32_t address, byte value);
----

Writes an 8 bit value to a given far memory address.

==== FAR_PEEKW

[,c]
----
uint16_t value = FAR_PEEKW(uint32_t address);
----

Returns the 16 bit value starting at a given far memory address.

==== FAR_POKEW

[,c]
----
FAR_POKEW(uint32_t address, uint16_t value);
----

Writes a 16 bit value starting at a given far memory address.

==== LOW_BYTE

[,c]
----
byte result = LOW_BYTE(int16_t value);
----

Returns the lower byte of a 16 bit word.

==== HIGH_BYTE

[,c]
----
byte result = HIGH_BYTE(int16_t value);
----

Returns the upper byte of a 16 bit word.

==== SWAP_NIBBLES

[,c]
----
byte result = SWAP_NIBBLES(byte value);
----

Returns the byte with the nibbles swapped.

==== SWAP_UINT16

[,c]
----
uint16_t result = SWAP_UINT16(uint16_t value);
----

Returns the word with the upper and lower bytes swapped.

==== CHECK_BIT

[,c]
----
byte result = CHECK_BIT(byte value, byte position);
----

Returns non-zero if the bit at the indicated position is set.

==== TOGGLE_BIT

[,c]
----
byte result = TOGGLE_BIT(byte value, byte position);
----

Returns the byte with the bit at the indicated position flipped.

==== CLEAR_BIT

[,c]
----
byte result = CLEAR_BIT(byte value, byte position);
----

Returns the byte with the bit at the indicated position cleared.

==== SET_BIT

[,c]
----
byte result = SET_BIT(byte value, byte position);
----

Returns the byte with the bit at the indicated position set.



=== Kernel

Kernel functions provide simplified access to the features provided by
https://github.com/ghackwrench/F256_MicroKernel[Gadget's TinyCore MicroKernel].
https://github.com/ghackwrench/F256_MicroKernel/tree/master/docs#readme[MicroKernel documentation]
is beyond the scope of this document.

Kernel interaction relies on two global variables:

[,c]
----
char kernelError;
kernelArgsT *kernelArgs;
----

* `kernelError` will be set to the error code, if any, returned by the kernel.
* `kernelArgs` provides structures to pass data to and receive data from the kernel.

.Keyboard Reading Example:
[,c]
----
do {
   kernelNextEvent();
   if (kernelEventData.type == kernelEvent(key.PRESSED)) {
      printf("Key %c pressed.\n", kernelEventData.key.ascii);
   }
} while(true);
----

TIP: Take a look at the `f256dev\examples\sprites` program and `f256dev\f256lib\f_file.c` from the *_F256lib_* source code for kernel usage examples.

==== kernelCall

[,c]
----
char kernelCall(function);
----

Calls one of the functions provided by the kernel.  You will need to fill in the
proper fields in the `kernelArgs` structure prior to calling.  `kernelArgs` will
be populated, as appropriate, if the call was successful.

==== kernelEvent

[,c]
----
size_t eventType = kernelEvent(size_t event);
----

Converts a named kernel `event` to the value expected by the `kernelEventData.type` structure.
See the above example for usage.

==== kernelGetPending

[,c]
----
byte kernelGetPending(void);
----

Returns the number of pending kernel events that need to be handled by your program.

==== kernelNextEvent

[,c]
----
void kernelNextEvent(void);
----

When using the kernel, you must call this function to "pump" the kernel's event queue.
Failing to call this often enough can starve the kernel of event objects.



=== DMA

At the moment, DMA access is... hit and miss.  Feel free to try it but don't expect
it to be stable.  More DMA features will be available in the future.

==== dma2dFill

[,c]
----
void dma2dFill(uint32_t start, uint16_t width, uint16_t height, uint16_t stride, byte value);
----

Fills a rectangular section of memory (near or far) with a value.

==== dmaFill

[,c]
----
void dmaFill(uint32_t start, uint32_t length, byte value);
----

Fills a linear section of memory (near or far) with a value.

=== Math Co-Processor

These functions provide vastly faster math operations than using the CPU alone.
Use them whenever possible!

==== mathSignedDivision

[,c]
----
int16_t  mathSignedDivision(int16_t a, int16_t b);
----

Performs signed division on two 16 bit signed integer values.
Any remainder is discarded.

==== mathSignedDivisionRemainder

[,c]
----
int16_t  mathSignedDivisionRemainder(int16_t a, int16_t b, int16_t *remainder);
----

Performs signed division on two 16 bit signed integer values.  The remainder is
returned in the pointer passed as the `remainder` argument.

==== mathSignedMultiply

[,c]
----
int32_t  mathSignedMultiply(int16_t a, int16_t b);
----

Performs signed multiplication of two signed 16 bit integer values.

NOTE: The return value is 32 bits.

==== mathUnsignedAddition

[,c]
----
uint32_t mathUnsignedAddition(uint32_t a, uint32_t b);
----

Performs unsigned multiplication of two unsigned 16 bit integer values.

NOTE: The return value is 32 bits.

==== mathUnsignedDivision

[,c]
----
uint16_t mathUnsignedDivision(uint16_t a, uint16_t b);
----

Performs unsigned division on two 16 bit unsigned integer values.
Any remainder is discarded.

==== mathUnsignedDivisionRemainder

[,c]
----
uint16_t mathUnsignedDivisionRemainder(uint16_t a, uint16_t b, uint16_t *remainder);
----

Performs unsigned division on two 16 bit unsigned integer values.  The remainder is
returned in the pointer passed as the `remainder` argument.

==== mathUnsignedMultiply

[,c]
----
uint32_t mathUnsignedMultiply(uint16_t a, uint16_t b);
----

Performs unsigned multiplication of two unsigned 16 bit integer values.

NOTE: The return value is 32 bits.



=== Random Numbers

Generating good psuedo-random numbers is a significant challenge.  Fortunately
the Foenix F256 has hardware-assisted random number generation.

==== randomRead

[,c]
----
uint16_t randomRead(void);
----

Returns the next psuedo-random unsigned 16 bit integer.

==== randomSeed

[,c]
----
void     randomSeed(uint16_t seed);
----

Specifies the starting value for the psuedo-random number generator.  Use this
to generate a reproducable sequence of "random" values.

On startup, the psuedo-random number generator is seeded from the real-time
clock, if available.



=== Text

[,c]
----
void textClear(void);
----

[,c]
----
void textDefineBackgroundColor(byte slot, byte r, byte g, byte b);
----

[,c]
----
void textDefineForegroundColor(byte slot, byte r, byte g, byte b);
----

[,c]
----
void textEnableBackgroundColors(bool b);
----

[,c]
----
void textGetXY(byte *x, byte *y);
----

[,c]
----
void textGotoXY(byte x, byte y);
----

[,c]
----
void textPrint(char *message);
----

[,c]
----
void textPrintInt(int32_t value);
----

[,c]
----
void textPrintUInt(uint32_t value);
----

[,c]
----
void textSetColor(byte f, byte b);
----

[,c]
----
void textSetCursor(byte c);
----

[,c]
----
void textSetDouble(bool x, bool y);
----


=== 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.  :-)
