918 lines
20 KiB
Text
918 lines
20 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.
|
|
|
|
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. :-)
|