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