More docs!

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
+[cols="1,3",grid=rows,frame=none]
-* Helpers
+|===
-* Kernel
+| <<Constants>>
-* DMA
+| Provides friendly names for often used hardware addresses, kernel functions, and more.
-* Math Co-Processor
+
-* Random Numbers
+| <<Types>>
-* Text
+| Helpful data types to keep you code ambiguity-free.
-* Graphics
+
-* Bitmaps
+| <<Helpers>>
-* Sprites
+| Functions for safely dealing with memory and bits.
-* Tiles
+
-* File I/O
+| <<Kernel>>
-* Platform
+| 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
+A _lot_ of constants are provided by *_F256lib_*.  Hardware registers, kernel
-false
+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
+*_F256lib_* provides clear, helpful, data types.  It's highly recommended
-byte
+that you use `stdint.h`-style types for integer data to avoid size confusion. In
-colorT
+addition, we recommend using `char` only when you really mean character data,
-kernelArgsT
+`byte` for unsigned bytes, and `bool` for boolean values.  `true` and `false`
-kernelEventT
+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);
+Kernel functions provide simplified access to the features provided by
-char kernelCall(function);
+https://github.com/ghackwrench/F256_MicroKernel[Gadget's TinyCore MicroKernel].
-byte kernelGetPending(void);
+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);
+[,c]
-void textGetXY(byte *x, byte *y);
+----
-void textGotoXY(byte x, byte y);
+void textDefineBackgroundColor(byte slot, byte r, byte g, byte b);
-void textPrint(char *message);
+----
-void textPrintInt(int32_t value);
+
-void textPrintUInt(uint32_t value);
+[,c]
-void textSetColor(byte f, byte b);
+----
-void textSetCursor(byte c);
+void textDefineForegroundColor(byte slot, byte r, byte g, byte b);
-void textSetDouble(bool x, bool y);
+----
+
+[,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