More docs!
This commit is contained in:
Scott Duensing
parent
cf3bceda58
commit
455af00e64
1 changed files with 466 additions and 38 deletions
504
f256lib.adoc
504
f256lib.adoc
|
|
@ -108,6 +108,13 @@ project files, makefiles, or other build configuration systems. The included
|
|||
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?
|
||||
|
|
@ -119,6 +126,7 @@ We *highly* recommend using the amalgamated build unless you are interested in w
|
|||
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.
|
||||
|
|
@ -203,121 +211,541 @@ 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:
|
||||
|
||||
* Constants
|
||||
* Helpers
|
||||
* Kernel
|
||||
* DMA
|
||||
* Math Co-Processor
|
||||
* Random Numbers
|
||||
* Text
|
||||
* Graphics
|
||||
* Bitmaps
|
||||
* Sprites
|
||||
* Tiles
|
||||
* File I/O
|
||||
* Platform
|
||||
[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
|
||||
|
||||
true
|
||||
false
|
||||
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
|
||||
|
||||
bool
|
||||
byte
|
||||
colorT
|
||||
kernelArgsT
|
||||
kernelEventT
|
||||
*_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.
|
||||
|
||||
=== Enums
|
||||
|
||||
textColorsT
|
||||
|
||||
=== 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
|
||||
|
||||
void kernelNextEvent(void);
|
||||
char kernelCall(function);
|
||||
byte kernelGetPending(void);
|
||||
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
|
||||
|
||||
void dmaFill(uint32_t start, uint32_t length, byte value);
|
||||
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);
|
||||
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);
|
||||
----
|
||||
|
||||
[,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);
|
||||
----
|
||||
|
||||
colorT textColors[16];
|
||||
|
||||
=== Graphics
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue