C256 Foenix Wiki - User contributions [en]

Foenix Kernel Documentation

2023-07-19T18:27:40Z

PJW: /* Kernel Calls */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 || Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| SETSIZES || $00:112C || Recompute the size of the text screen given the current screen resolution and border size. This should be called whenever the screen size changes but text mode is being used so that the kernel's text routines work properly.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run an [[executable binary file]] from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|-
| IP_INIT || $00:1150 || [v0.5] Initialize network stack; B:Y->ip, mask, default_route. buffer_ptr below is 24 of 32 bits.
|-
| UDP_SEND || $00:1154|| [v0.5] Send a UDP packet: 0:X->local_port, remote_ip, remote_port, buffer_ptr, size, copied
|-
| UDP_RECV || $00:1158|| [v0.5] Receive a UDP packet: 0:X->local_port, remote_ip, remote_port, buffer_ptr, size, copied

|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

=== Network Calls ===

Networking support includes three functions and two structures below. All networking kernel calls are processor mode agnostic, return status in the condition codes, and leave all other registers unchanged. The calls are neither re-entrant nor thread-safe; don't attempt to call any of them concurrently. The stack will respond to pings (ICMP ECHO requests), but only so long as UDP_SEND and/or UDP_RECV is being called regularly. The stack does nothing in the background and does not use interrupts. The ARP timer works by polling the NIC's internal timer-expired flag.

<pre>
IP_INIT
IN: B:Y->ip_info (below)
OUT: Carry set on error (ethernet card not found or won't init)
NOTES: A default route in the 0.x.x.x range is formally unroutable.
</pre>

<pre>
UDP_SEND
IN: 0:X->udp_info (below)
OUT: Carry set on error (not initialized, no route to host, EOM)
NOTES: "No route to host" is usually temporary while the stack is
awaiting an ARP response from the target or the router;
callers are expected to retry the send. The stack rate-
limits ARP requests to approximately 2/s per address.
Sends to your IPv4 broadcast address will be sent to the
broadcast MAC (ff:ff:ff:ff:ff:ff). An EOM should only occur
if you aren't calling UDP_RECV often enough to drain the
incoming UDP packet queue.
</pre>

<pre>
UDP_RECV
IN: 0:X->udp_info (below)
OUT: Carry set on error (not initialized), Z set on queue empty.
NOTES: You MUST call UDP_RECV semi-regularly; if you don't, the
receive queue will eventually fill with garbage. The net
is a messy place, and random devices on your lan are always
spamming the local network. Broadcast UDP packets are
accepted and queued like any other UDP packets.
</pre>

==== Network Data Structures ====

<pre>
ip_info .struct
ip .fill 4 ; Local ipv4 address in network order
mask .fill 4 ; Local ipv4 netmask in network order
default .fill 4 ; Default ipv4 route in network order
size .ends

udp_info .struct
local_port .word ? ; local port #, little-endian
remote_ip .fill 4 ; ipv4 address of remote machine, network order
remote_port .word ? ; remote port #, little endian
buffer .dword ? ; 24-bit address of your data
buflen .word ? ; length of the above buffer in bytes
copied .word ? ; number of bytes copied in/out of the above buffer
size .ends
</pre>

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || 0 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Foenix Kernel Documentation

2023-07-19T18:22:48Z

PJW: /* Kernel Calls */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 || Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| SETSIZES || $00:112C || Recompute the size of the text screen given the current screen resolution and border size. This should be called whenever the screen size changes but text mode is being used so that the kernel's text routines work properly.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run an [[executable binary file]] from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|-
| IP_INIT || $00:1150 || [v0.5] Initialize network stack; B:Y->ip, mask, default_route. buffer_ptr below is 24 of 32 bits.
|-
| UDP_SEND || $00:1154|| [v0.5] Send a UDP packet: 0:X->local_port, remote_ip, remote_port, buffer_ptr, size, copied
|-
| UDP_RECV || $00:1158|| [v0.5] Receive a UDP packet: 0:X->local_port, remote_ip, remote_port, buffer_ptr, size, copied

|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || 0 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

F256 WiFi Setup

2023-07-05T02:49:42Z

PJW: /* Configuring the ESP8266 Router Using the F256 */

= Introduction =

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional Wi-Fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the [[F256K]] and [[F256JR]], both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP Wi-Fi router. This document will cover the process of configuring and installing such a Wi-Fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs.

= Supplies Needed =

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be Wi-Fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable --- A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

= Software Needed =

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/Wi-Fi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Linux : [Optional] Once installed, the Wi-Fi router firmware must be configured. This process requires connecting to the ESP8266's SLIP interface on a particular port and sending some commands. This can be done either through Linux or using the <code>Wi-Fi</code> command in the TinyCore DOS.

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the Wi-Fi router. The correct link will depend on your Linux distribution, but it may already be installed.

= Preparing the Feather ESP8266 =

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can be done on the F256 itself using the TinyCore DOS, or it can be done through Linux and using <code>telnet</code> to connect to the SLIP interface. Currently, Windows and MacOS X do not support SLIP networking, so they cannot be used to configure the router.

== Installation Prerequisites ==

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools (Linux-only: If Needed)

This will vary with each Linux distribution. Sometimes this package is installed by default.

== Installing the ESP_SLIP_ROUTER Firmware ==

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
python esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

== Configuring the ESP8266 Router Using the F256 ==

Once you have installed the ESP router software on the Wi-Fi module and socketed it into the F256 (see below),
you can use the TinyCore DOS <code>wifi</code> command to connect it to your network.
To use this command, you must have a recent version of TinyCore MicroKernel installed in flash (since 4 July, 2023).

<ol>
<li>Turn on the machine and wait for the SuperBASIC start screen.</li>
<li>Switch to the TinyCore DOS command line by entering the command:
<pre>/dos
</pre>
</li>
<li>Set the ssid and password for your network by entering the command:
<pre>
wifi {ssid} {password}
</pre>
where <code>{ssid}</code> is the name of your network, and <code>{password}</code> is its password.
</li>
<li>Wait the command to send the configuration data to your Wi-Fi module and reset it.</li>
<li>The status light on your Wi-Fi module should turn on briefly but go out after the module has connected to your Wi-Fi. If it remains on, it is not able to connect to your wireless network for some reason.</li>
</ol>

It is possible that something might go wrong with your configuration, locking up the <code>wifi</code> command.
The key combination CTRL-C will quit the command.
If a second attempt still does not work, you may need to completely turn off your system and leave it off for a few minutes to let the memory completely clear out to a random state before you try again.

== Configuring the ESP8266 Router for Your Network in Linux ==

To configure the router using Linux, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the Wi-Fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the Wi-Fi module should be ready to install in your F256.

= Installing the Wi-Fi Module in Your F256 =

The next step is to actually install the Wi-Fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the Wi-Fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 Wi-Fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with Wi-Fi module position highlighted|Figure 1: F256jr motherboard with Wi-Fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with Wi-Fi module position highlighted|Figure 2: F256k motherboard with Wi-Fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 Wi-Fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the Wi-Fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the Wi-Fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a Wi-Fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi Setup

2023-07-05T02:49:15Z

PJW: /* Configuring the ESP8266 Router Using the F256 */

= Introduction =

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional Wi-Fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the [[F256K]] and [[F256JR]], both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP Wi-Fi router. This document will cover the process of configuring and installing such a Wi-Fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs.

= Supplies Needed =

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be Wi-Fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable --- A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

= Software Needed =

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/Wi-Fi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Linux : [Optional] Once installed, the Wi-Fi router firmware must be configured. This process requires connecting to the ESP8266's SLIP interface on a particular port and sending some commands. This can be done either through Linux or using the <code>Wi-Fi</code> command in the TinyCore DOS.

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the Wi-Fi router. The correct link will depend on your Linux distribution, but it may already be installed.

= Preparing the Feather ESP8266 =

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can be done on the F256 itself using the TinyCore DOS, or it can be done through Linux and using <code>telnet</code> to connect to the SLIP interface. Currently, Windows and MacOS X do not support SLIP networking, so they cannot be used to configure the router.

== Installation Prerequisites ==

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools (Linux-only: If Needed)

This will vary with each Linux distribution. Sometimes this package is installed by default.

== Installing the ESP_SLIP_ROUTER Firmware ==

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
python esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

== Configuring the ESP8266 Router Using the F256 ==

Once you have installed the ESP router software on the Wi-Fi module and socketed it into the F256 (see below),
you can use the TinyCore DOS <code>wifi</code> command.
To use this command, you must have a recent version of TinyCore MicroKernel installed in flash (since 4 July, 2023).

<ol>
<li>Turn on the machine and wait for the SuperBASIC start screen.</li>
<li>Switch to the TinyCore DOS command line by entering the command:
<pre>/dos
</pre>
</li>
<li>Set the ssid and password for your network by entering the command:
<pre>
wifi {ssid} {password}
</pre>
where <code>{ssid}</code> is the name of your network, and <code>{password}</code> is its password.
</li>
<li>Wait the command to send the configuration data to your Wi-Fi module and reset it.</li>
<li>The status light on your Wi-Fi module should turn on briefly but go out after the module has connected to your Wi-Fi. If it remains on, it is not able to connect to your wireless network for some reason.</li>
</ol>

It is possible that something might go wrong with your configuration, locking up the <code>wifi</code> command.
The key combination CTRL-C will quit the command.
If a second attempt still does not work, you may need to completely turn off your system and leave it off for a few minutes to let the memory completely clear out to a random state before you try again.

== Configuring the ESP8266 Router for Your Network in Linux ==

To configure the router using Linux, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the Wi-Fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the Wi-Fi module should be ready to install in your F256.

= Installing the Wi-Fi Module in Your F256 =

The next step is to actually install the Wi-Fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the Wi-Fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 Wi-Fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with Wi-Fi module position highlighted|Figure 1: F256jr motherboard with Wi-Fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with Wi-Fi module position highlighted|Figure 2: F256k motherboard with Wi-Fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 Wi-Fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the Wi-Fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the Wi-Fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a Wi-Fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256K

2023-07-05T02:43:06Z

PJW:

The F256K is a 65xx-based system. It's an encased form factor with a built-in keyboard. It includes the following features:
* 512K of Shared System & Video RAM
* 256k of flash
* 256k of cartridge ram/rom
* [[TinyVICKY]] Graphic Chip (CFP9599)
* Port for connecting FNX4N4S, which can be used to connect Atari-Style Joysticks or NES/SNES gamepads
* 1x IEC Port to interface to Commodore Drives
* A few sound chips: SID, PSG/SN76489, OPL3
* 1x Simple 3-wire UART (RS-232 Port, [[F256_WiFi|Feather ESP8266 wifi]]

It shares many similarities to the [[F256JR]] and programs can in many cases run straightforwardly on both.

The 'K' in the name comes from the fact that it has an integrated keyboard, unrelated to the amount of memory available in the system. The base system has 512K of system memory; with expansion cartridge brings it up to 768K.

A common variety of the F256K uses the 6502 CPU. That said, the 65816 CPU can also be installed.

[[File:f256k_Secondpass.6-819x1024.png|400px]]

= Ports and connectors =

The back of the unit looks like this:

[[File:f256k_rear_connectors.PNG]]

* '''Power Switch''' is a toggle-style switch to turn the unit off and on.
* '''Reset Button''' reboots the system, with values in RAM persisting. If RAM has been modified using the debug interface, it stays modified.
* '''Power Jack''' is for plugging in A/C power. Use, for example, a +12V or +9V with 2.5mm barrel connector.
* '''USB Debug''' is for connection to a debug host computer, debugging F256K as a target, for example using a mini USB to USB A cable.
* '''PS/2''' can be used for connecting external keyboard and/or mouse.
* '''FNX4N4S Adapter''' provides connections to gamepads (e.g., SNES-style game controller) through the FNX4N4S adapter.
* '''IEC''' provides connectivity to Commodore-compatible devices that use serial interface
* '''DVI''' is for connecting a display.
* '''RS-232''' provides a standard RS-232 serial interface.
* '''Headphones''' is a standard 3.5mm headphone jack.
* '''Audio Line Out''' provides stereo audio output.

= Switches =
The bottom of the unit looks like this:

[[File:f256k_dip_switches.jpg|600px]]

There are eight DIP switches, with different interpretations depending on whether a kernel is present on the system.
If a kernel is present on the system, as the unit is shipped with, these switches are:
* [8] - On: Enable GAMMA correction
* [7] - Graphics resolution controls
* [6] - Not used
* [5] - Not used
* [4] - On: Feather Board installed (ESP8266)
* [3] - On: Enable SLIP Base Networking
* [2] - Reserved
* [1] - On: Enable Boot from RAM, off means it will boot from a pre-installed kernel in the first 48K of memory.

If a kernel is not present on the system, these switches can be used as desired:
* [8] - On: Enable GAMMA correction
* [7] - USER2
* [6] - USER1
* [5] - USER0
* [4] - BOOT Mode3
* [3] - BOOT Mode2
* [2] - BOOT Mode1
* [1] - BOOT Mode0

= Boot =
To start the machine, ensure A/C power is plugged in and flip the power switch. The exact boot behavior depends on the "Boot from RAM" DIP switch on the bottom.

* If the DIP1 "Boot from RAM" switch is '''off''' and a kernel is used, the kernel will search the 48K of memory for a pre-loaded kernel binary.

* If the DIP1 "Boot from RAM" switch is '''on''', then control is transferred to the reset vector entrypoint located at offset $FFFC.

Switching DIP1 to 'on' is useful for developer convenience and testing code. For those using the machine outside of a development-style environment, it's more likely the switch will be 'off'.

The ''Boot from RAM'' and ''Boot from flash'' options in uploader tools such as [https://github.com/pweingar/FoenixMgr FoenixMgr] or [https://github.com/clandrew/F256Uploader F256 Uploader] are unrelated to the "Boot from RAM" DIP switch:
* The DIP switch alters boot behavior by telling the kernel to search the first 48K of RAM for a pre-loaded kernel binary.
* Those tools, on the other hand, initiate a new boot using a soft reset signal, and the choice of ''Boot from RAM'' versus ''Boot from flash'' affects the initial memory look-up tables upon boot.

So those tools' options are also useful for developer convenience, they just affect a different part of the boot process, and are tightly integrated with the act of pushing data over the debug port onto F256K memory.

= Memory =
The F256K has a 16-bit address space, $0000 through $FFFF, visible to its CPU. In other words, the CPU address space is 64KB in size. While other units such as the TinyVicky graphics unit can access memory beyond that, the CPU itself has a 16-bit address space.

The address space is divided up into eight equal-sized ''banks''. The CPU-visible address space is divided into banks as follows:

{| class="wikitable"
|-
! scope="col"| Bank
! scope="col"| Address Range
|-
| scope="row"| 0
| $0000-$1FFF
|-
| scope="row"| 1
| $2000-$3FFF
|-
| scope="row"| 2
| $4000-$5FFF
|-
| scope="row"| 3
| $6000-$7FFF
|-
| scope="row"| 4
| $8000-$9FFF
|-
| scope="row"| 5
| $A000-$BFFF
|-
| scope="row"| 6
| $C000-$DFFF
|-
| scope="row"| 7
| $E000-$FFFF
|}

Note that each bank is $2000 in size; on other (e.g., non-Foenix) platforms, the term ''bank'' may be used differently. Here, each bank is 8KB, or $2000.

Since the F256K has a larger amount of total memory (up to 768KB) than this address space exposes, programs use and adjust the address space as a "window" to underlying memory needed by the CPU at any given time.

In other words, programs control what device memory this address space maps to. They do this through ''memory lookup tables'', or ''MLUT''s for short. Up to four MLUTs can be set up at a time, and programs choose which one is active at any given time.

To ensure that control of MLUTs is always possible, CPU address $0000 is special, and is a memory-mapped register to manipulate MLUTs:
<nowiki>
MMU_MEM_CTRL = $0000</nowiki>

For example, to enable editing of MLUT 0, set the MMU_EDIT_EN (the leftmost) bit:
<nowiki>
LDA MMU_MEM_CTRL
ORA #MMU_EDIT_EN
STA MMU_MEM_CTRL</nowiki>

As for where a bank of CPU address space can map to: programs can map a bank to any of RAM, flash or expansion memory.

An example of a straightforward mapping is to simply map the CPU address space linearly to the first 64KB of RAM.
<nowiki>
LDA #$00
STA MMU_MEM_BANK_0 ; map $000000 to bank 0
INA
STA MMU_MEM_BANK_1 ; map $002000 to bank 1
INA
STA MMU_MEM_BANK_2 ; map $004000 to bank 2
INA
STA MMU_MEM_BANK_3 ; map $006000 to bank 3
INA
STA MMU_MEM_BANK_4 ; map $008000 to bank 4
INA
STA MMU_MEM_BANK_5 ; map $00a000 to bank 5
INA
STA MMU_MEM_BANK_6 ; map $00c000 to bank 6
INA
STA MMU_MEM_BANK_7 ; map $00e000 to bank 7</nowiki>

where MMU_MEM_BANK_0, 1, 2, are specially mapped at addresses $0008, $0009, and so on. In this example code, the accumulator stores the bank number of device memory, and that value is written to the corresponding register. Write higher values to map later regions of device memory.

Finally, use
<nowiki>
LDA MMU_MEM_CTRL
AND #~(MMU_EDIT_EN)
STA MMU_MEM_CTRL ; disable mmu edit, use mmu lut 0</nowiki>
to commit the changes and enable use of the updated MLUT 0.

= Sound =
The F256K has a few different components capable of processing sound:
* Two PSG(SN76489) chips
* Two SID chips; SID, or Sound Interface Device, was used on C64 and others
* Yamaha OPL3 chip

The PSG chips are memory-mapped as follows:
<nowiki>
PSG_INT_L_PORT = $D600 ; Control register for the SN76489
PSG_INT_B_PORT = $D608 ; Control register for the SN76489, writes to both L and R ports
PSG_INT_R_PORT = $D610 ; Control register for the SN76489</nowiki>

= Keyboard =
The built-in keyboard does not operate by PS/2 controller, it's a matrix keyboard controlled by two WDC VIA (Versatile Interface Adapter) controllers and the CPU's NMI signal.

There are two ways for programs to interact with the keyboard:
* '''Using the kernel''', where the exact mechanism depends on the kernel involved; this can be through an environment like SuperBASIC that talks to the kernel
* '''Directly with the device''', using memory mappings.

For more information on interacting directly with the keyboard device, see [[F256K Keyboard]].

The F256K also supports plugging in an external keyboard. If this is done, it is through PS/2 interface.

= Manual =
For a technical reference, use this manual:
https://github.com/pweingar/F256Manual

Although the manual is F256Jr-centric, it's suitable for F256K development owing to the similarity of the two units. It describes common aspects between F256Jr and F256K, with some sections highlighting F256K functionality that differs.

= Kernels =
There are three kernels for the F256K.
* [[The TinyCore MicroKernel]] (ships with the unit)
* [[OpenKERNAL]] (for those wishing to run software written for the CBM KERNAL)
* [https://github.com/ghackwrench/FoenixKERNAL FoenixKERNAL], an open source, CBM-style layer also compatible with software written for Commodore 64 KERNAL

= Tools =
* [https://github.com/clandrew/F256Uploader F256 Uploader]
* https://github.com/pweingar/FoenixMgr

F256JR

2023-07-05T02:42:09Z

PJW:

The F256 Jr is a 65C02 based system which includes the following features:

* 512K of Shared System & Video RAM (256k on the Rev A)
* 256k of flash
* 256k of cartridge ram/rom
* TinyVICKY Graphic Chip (CFP9599)
* 1x Simple 3-wire UART (RS-232 Port, [[F256_WiFi|Feather ESP8266 wifi]], or Feather MIDI)
* 2x Atari Style Joystick Ports, 1x DB9 to interface to NES/SNES Adapter (For Rev B Only)
* 1x IEC Port to interface to Commodore Drives
* 2x Internal PSG Sound Chip
* 2x External SID Sockets

Aside from its sound chip, it's very similar to the [[F256K]].

= Hardware Setup =
[[File:Pinout_Jr_December_7th_Trans.png|200px]]

The PS2 mouse port may be wired to the keyboard port and then split out using a laptop PS2 splitter.
* [[Dual PS2 Port]]

If your Jr. is booting to a blank screen with a dark purple border, be sure that the RAM/FLASH jumper is set to FLASH.

= Kernels =
There are three kernels for the Jr.
* [[The TinyCore MicroKernel]] (ships with the unit)
* [[OpenKERNAL]] (for those wishing to run software written for the CBM KERNAL)
* [https://github.com/ghackwrench/FoenixKERNAL FoenixKERNAL], an open source, CBM-style layer also compatible with Commodore 64 KERNAL

= BASIC =
The F256 Jr. ships with SuperBASIC: https://github.com/paulscottrobson/superbasic

= DOS =
* There is a simple example DOS shell for the MicroKernel in the kernel/dos project: https://github.com/ghackwrench/F256_Jr_Kernel_DOS
* It may also be found in the SuperBASIC project under source/releases: https://github.com/paulscottrobson/superbasic
* SuperBASIC's install scripts install it by default. To access it, type "DOS" from BASIC.
* To return to SuperBASIC, type "basic <enter>" from DOS.
* To auto-boot into DOS instead of BASIC, install DOS in flash slot 1, and BASIC in slots 2,3,4.

= Assemblers =
* 64tass: https://sourceforge.net/projects/tass64/

= C compiler =
* [[cc65]]

= Tools =
* [https://github.com/clandrew/F256Uploader F256 Uploader]
* https://github.com/pweingar/FoenixMgr

F256 WiFi

2023-07-05T02:41:24Z

PJW: /* Introduction */

= Introduction =

The F256 computers (both the [[F256JR]] and [[F256K]]) optionally support connecting to your home wireless network.
Setting up your F256 to use wi-fi requires the installation and setup of a micro-controller board as a wi-fi router. The process is detailed in the [[F256_WiFi_Setup|F256 Wi-Fi Setup document]]

F256 WiFi Setup

2023-07-05T02:40:48Z

PJW: /* Configuring the ESP8266 Router Using the F256 */

= Introduction =

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional Wi-Fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the [[F256K]] and [[F256JR]], both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP Wi-Fi router. This document will cover the process of configuring and installing such a Wi-Fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs.

= Supplies Needed =

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be Wi-Fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable --- A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

= Software Needed =

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/Wi-Fi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Linux : [Optional] Once installed, the Wi-Fi router firmware must be configured. This process requires connecting to the ESP8266's SLIP interface on a particular port and sending some commands. This can be done either through Linux or using the <code>Wi-Fi</code> command in the TinyCore DOS.

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the Wi-Fi router. The correct link will depend on your Linux distribution, but it may already be installed.

= Preparing the Feather ESP8266 =

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can be done on the F256 itself using the TinyCore DOS, or it can be done through Linux and using <code>telnet</code> to connect to the SLIP interface. Currently, Windows and MacOS X do not support SLIP networking, so they cannot be used to configure the router.

== Installation Prerequisites ==

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools (Linux-only: If Needed)

This will vary with each Linux distribution. Sometimes this package is installed by default.

== Installing the ESP_SLIP_ROUTER Firmware ==

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
python esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

== Configuring the ESP8266 Router Using the F256 ==

Once you have installed the ESP router software on the Wi-Fi module and socketed it into the F256 (see below),
you can use the TinyCore DOS <code>wifi</code> command.
To use this command, you must have a recent version of TinyCore MicroKernel installed in flash (since 4 July, 2023).

# Turn on the machine and wait for the SuperBASIC start screen
# Enter the command "<code>/dos</code>" to switch to the TinyCore DOS command line
# Enter the command "<code>wifi {ssid} {password}</code>", where <code>{ssid}</code> is your network's name, and <code>{password}</code> is the password.
# Wait the command to send the configuration data to your Wi-Fi module and reset it.
# The status light on your Wi-Fi module should turn on briefly but go out after the module has connected to your Wi-Fi. If it remains on, it is not able to connect to your wireless network for some reason.

It is possible that something might go wrong with your configuration, locking up the <code>wifi</code> command.
The key combination CTRL-C will quit the command.
If a second attempt still does not work, you may need to completely turn off your system and leave it off for a few minutes to let the memory completely clear out to a random state before you try again.

== Configuring the ESP8266 Router for Your Network in Linux ==

To configure the router using Linux, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the Wi-Fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the Wi-Fi module should be ready to install in your F256.

= Installing the Wi-Fi Module in Your F256 =

The next step is to actually install the Wi-Fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the Wi-Fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 Wi-Fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with Wi-Fi module position highlighted|Figure 1: F256jr motherboard with Wi-Fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with Wi-Fi module position highlighted|Figure 2: F256k motherboard with Wi-Fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 Wi-Fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the Wi-Fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the Wi-Fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a Wi-Fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi Setup

2023-07-05T02:40:09Z

PJW: /* Introduction */

= Introduction =

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional Wi-Fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the [[F256K]] and [[F256JR]], both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP Wi-Fi router. This document will cover the process of configuring and installing such a Wi-Fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs.

= Supplies Needed =

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be Wi-Fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable --- A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

= Software Needed =

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/Wi-Fi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Linux : [Optional] Once installed, the Wi-Fi router firmware must be configured. This process requires connecting to the ESP8266's SLIP interface on a particular port and sending some commands. This can be done either through Linux or using the <code>Wi-Fi</code> command in the TinyCore DOS.

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the Wi-Fi router. The correct link will depend on your Linux distribution, but it may already be installed.

= Preparing the Feather ESP8266 =

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can be done on the F256 itself using the TinyCore DOS, or it can be done through Linux and using <code>telnet</code> to connect to the SLIP interface. Currently, Windows and MacOS X do not support SLIP networking, so they cannot be used to configure the router.

== Installation Prerequisites ==

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools (Linux-only: If Needed)

This will vary with each Linux distribution. Sometimes this package is installed by default.

== Installing the ESP_SLIP_ROUTER Firmware ==

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
python esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

== Configuring the ESP8266 Router Using the F256 ==

Once you have installed the ESP router software on the Wi-Fi module and socketed it into the F256 (see below),
you can use the TinyCore DOS <code>wifi</code> command.
To use this command, you must have a recent version of TinyCore MicroKernel installed in flash (since 4 July, 2023).

# Turn on the machine and wait for the SuperBASIC start screen
# Enter the command <code>/dos</code> to switch to the TinyCore DOS command line
# Enter the command <code>wifi {ssid} {password}</code>, where <code>{ssid}</code> is your network's name, and <code>{password}</code> is the password.
# Wait the command to send the configuration data to your Wi-Fi module and reset it.
# The status light on your Wi-Fi module should turn on briefly but go out after the module has connected to your Wi-Fi. If it remains on, it is not able to connect to your wireless network for some reason.

It is possible that something might go wrong with your configuration, locking up the <code>wifi</code> command.
The key combination CTRL-C will quit the command.
If a second attempt still does not work, you may need to completely turn off your system and leave it off for a few minutes to let the memory completely clear out to a random state before you try again.

== Configuring the ESP8266 Router for Your Network in Linux ==

To configure the router using Linux, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the Wi-Fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the Wi-Fi module should be ready to install in your F256.

= Installing the Wi-Fi Module in Your F256 =

The next step is to actually install the Wi-Fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the Wi-Fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 Wi-Fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with Wi-Fi module position highlighted|Figure 1: F256jr motherboard with Wi-Fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with Wi-Fi module position highlighted|Figure 2: F256k motherboard with Wi-Fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 Wi-Fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the Wi-Fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the Wi-Fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a Wi-Fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi Setup

2023-07-05T02:38:37Z

PJW:

= Introduction =

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional Wi-Fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the [[F256k]] and [[F256jr]], both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP Wi-Fi router. This document will cover the process of configuring and installing such a Wi-Fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs.

= Supplies Needed =

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be Wi-Fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable --- A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

= Software Needed =

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/Wi-Fi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Linux : [Optional] Once installed, the Wi-Fi router firmware must be configured. This process requires connecting to the ESP8266's SLIP interface on a particular port and sending some commands. This can be done either through Linux or using the <code>Wi-Fi</code> command in the TinyCore DOS.

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the Wi-Fi router. The correct link will depend on your Linux distribution, but it may already be installed.

= Preparing the Feather ESP8266 =

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can be done on the F256 itself using the TinyCore DOS, or it can be done through Linux and using <code>telnet</code> to connect to the SLIP interface. Currently, Windows and MacOS X do not support SLIP networking, so they cannot be used to configure the router.

== Installation Prerequisites ==

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools (Linux-only: If Needed)

This will vary with each Linux distribution. Sometimes this package is installed by default.

== Installing the ESP_SLIP_ROUTER Firmware ==

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
python esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

== Configuring the ESP8266 Router Using the F256 ==

Once you have installed the ESP router software on the Wi-Fi module and socketed it into the F256 (see below),
you can use the TinyCore DOS <code>wifi</code> command.
To use this command, you must have a recent version of TinyCore MicroKernel installed in flash (since 4 July, 2023).

# Turn on the machine and wait for the SuperBASIC start screen
# Enter the command <code>/dos</code> to switch to the TinyCore DOS command line
# Enter the command <code>wifi {ssid} {password}</code>, where <code>{ssid}</code> is your network's name, and <code>{password}</code> is the password.
# Wait the command to send the configuration data to your Wi-Fi module and reset it.
# The status light on your Wi-Fi module should turn on briefly but go out after the module has connected to your Wi-Fi. If it remains on, it is not able to connect to your wireless network for some reason.

It is possible that something might go wrong with your configuration, locking up the <code>wifi</code> command.
The key combination CTRL-C will quit the command.
If a second attempt still does not work, you may need to completely turn off your system and leave it off for a few minutes to let the memory completely clear out to a random state before you try again.

== Configuring the ESP8266 Router for Your Network in Linux ==

To configure the router using Linux, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the Wi-Fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the Wi-Fi module should be ready to install in your F256.

= Installing the Wi-Fi Module in Your F256 =

The next step is to actually install the Wi-Fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the Wi-Fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 Wi-Fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with Wi-Fi module position highlighted|Figure 1: F256jr motherboard with Wi-Fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with Wi-Fi module position highlighted|Figure 2: F256k motherboard with Wi-Fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 Wi-Fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the Wi-Fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the Wi-Fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a Wi-Fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi

2023-07-05T02:21:38Z

PJW: /* Introduction */

= Introduction =

The F256 computers (both the [[F256jr]] and [[F256k]]) optionally support connecting to your home wireless network.
Setting up your F256 to use wi-fi requires the installation and setup of a micro-controller board as a wi-fi router. The process is detailed in the [[F256_WiFi_Setup|F256 Wi-Fi Setup document]]

F256 WiFi

2023-07-05T02:20:53Z

PJW: /* Foenix F256 Wi-fi HOWTO */

F256 WiFi Setup

2023-07-05T02:17:34Z

PJW: /* Foenix F256 Wi-fi Setup */

= Introduction =

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

= Supplies Needed =

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable --- A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

= Software Needed =

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

= Preparing the Feather ESP8266 =

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

== Installation Prerequisites ==

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

== Installing the ESP_SLIP_ROUTER Firmware ==

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

== Configuring the ESP8266 Router for Your Network ==

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

= Installing the Wi-Fi Module in Your F256 =

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi Setup

2023-07-05T02:15:28Z

PJW: Created page with "= Foenix F256 Wi-fi Setup = == Introduction == The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi mo..."

= Foenix F256 Wi-fi Setup =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi

2023-07-05T02:15:07Z

PJW: /* Foenix F256 Wi-fi HOWTO */

= Foenix F256 Wi-fi HOWTO =

[[F256_WiFi_Setup]]

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi

2023-07-05T02:14:16Z

PJW:

= Foenix F256 Wi-fi HOWTO =

[[f256_wifi_howto]]

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi

2023-06-29T00:34:10Z

PJW: /* Installing the Wi-Fi Module in Your F256 */

= Foenix F256 Wi-fi HOWTO =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

# If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).
# Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).
# [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.
# Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).
# There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5
# Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi

2023-06-29T00:32:42Z

PJW: /* Preparing the Feather ESP8266 */

= Foenix F256 Wi-fi HOWTO =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE

2. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

1. If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).

2. Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).

3. [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.

4. Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).

5. There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5

6. Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi

2023-06-28T23:48:31Z

PJW: /* Supplies Needed */

= Foenix F256 Wi-fi HOWTO =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards are designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE
1. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

1. If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).

2. Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).

3. [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.

4. Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).

5. There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5

6. Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi

2023-06-28T23:48:01Z

PJW: /* Supplies Needed */

= Foenix F256 Wi-fi HOWTO =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather Huzzah with ESP8266 : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards is designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE
1. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

1. If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).

2. Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).

3. [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.

4. Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).

5. There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5

6. Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

F256 WiFi

2023-06-28T23:46:48Z

PJW: /* Installing the Wi-Fi Module in Your F256 */

= Foenix F256 Wi-fi HOWTO =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather ESP8266 Huzzah : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards is designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE
1. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

[[File:F256k_unpop_highlight.jpg|thumb|alt=F256k motherboard with wi-fi module position highlighted|Figure 2: F256k motherboard with wi-fi module position highlighted]]

1. If you did not buy the Feather with the pre-soldered pins, first solder the pins to the Feather board. The pins should be soldered so that the short side of the metal goes through the board of the Feather, and the long end (and the plastic separator) are on the underside of the board. The solder joint should be made on the top side of the board (see figure 3 but ignore some of the less than perfect solder joints).

2. Then it will be time to solder the socket header to the F256 motherboard. The socket header is inserted through the top side of the motherboard and soldered on the bottom side (see figure 4).

3. [Optional but recommended] Use a little isopropyl alcohol to clean any flux residue off the two boards.

4. Insert the Feather ESP 8266 wi-fi module into the socket header on the F256 (see figure 5).

5. There are two jumpers next to the wi-fi module. These route the transmit (Tx) and receive (Rx) pins to either the serial port or the wi-fi module. Make sure the jumpers are moved to the "SLIP" positions. You can see this in figure 5

6. Turn on DIP switches #3 and #4. These tell the kernel that SLIP support should be enabled and that a wi-fi module is installed.

[[File:Feather_soldered.jpg|thumb|alt=Feather ESP8266 with pins soldered|Figure 3: Feather ESP8266 with pins soldered]]

[[File:F256k_header.jpg|thumb|alt=F256k with headers soldered|Figure 4: F256k with headers soldered]]

[[File:Feather_installed.jpg|thumb|alt=F256k with Feather ESP8266 installed|Figure 5: F256k with Feather ESP8266 installed]]

File:Feather installed.jpg

2023-06-28T23:46:02Z

PJW: F256k with Feather ESP8266 installed

== Summary ==
F256k with Feather ESP8266 installed

File:F256k header.jpg

2023-06-28T23:45:08Z

PJW: F256k with headers soldered

== Summary ==
F256k with headers soldered

File:Feather soldered.jpg

2023-06-28T23:44:08Z

PJW: Feather ESP8266 with pins soldered

== Summary ==
Feather ESP8266 with pins soldered

File:F256k unpop highlight.jpg

2023-06-28T23:42:28Z

PJW: F256k motherboard with wi-fi module position highlighted

== Summary ==
F256k motherboard with wi-fi module position highlighted

F256 WiFi

2023-06-28T23:41:58Z

PJW: /* Installing the Wi-Fi Module in Your F256 */

= Foenix F256 Wi-fi HOWTO =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather ESP8266 Huzzah : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards is designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE
1. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

The next step is to actually install the wi-fi module onto the F256 motherboard, and this step will require some soldering. If you look at the motherboard, you will see two rows of unpopulated pads. These pads are for the wi-fi module. You will need to solder socket headers to those pads, and then insert the Feather ESP8266 wi-fi module board into the headers.

[[File:F256jr_unpop_highlight.jpg|thumb|alt=F256jr motherboard with wi-fi module position highlighted|Figure 1: F256jr motherboard with wi-fi module position highlighted]]

File:F256jr unpop highlight.jpg

2023-06-28T23:34:23Z

PJW: F256jr motherboard with wi-fi module position highlighted

== Summary ==
F256jr motherboard with wi-fi module position highlighted

F256 WiFi

2023-06-28T23:30:20Z

PJW: /* Software Needed */

= Foenix F256 Wi-fi HOWTO =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather ESP8266 Huzzah : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards is designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the <code>slattach</code> command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE
1. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

F256 WiFi

2023-06-28T23:29:50Z

PJW: /* Preparing the Feather ESP8266 */

= Foenix F256 Wi-fi HOWTO =

== Introduction ==

The Foenix F256 computers were designed to allow for networking either through the serial port or through an optional wi-fi module. The TinyCore MicroKernel installed by default includes support for networking using SLIP (Serial Line Internet Protocol). While it is possible to use SLIP through the RS-232 serial port on the F256k and F256jr, both computers include solder pads that can be used to install an ESP8266 board to serve as a SLIP wi-fi router. This document will cover the process of configuring and installing such a wi-fi module on your Foenix F256.

WARNING: The process described here requires some technical skills. It will be necessary to solder sockets to the F256 motherboard, which, if not done properly, could damage the board. Therefore, this process should only be attempted by someone comfortable soldering electronics onto PCBs. Similarly, some steps in setting up the wi-fi router can currently only be done on a Linux installation, so some experience with Linux and setting up software packages on Linux will be needed.

== Supplies Needed ==

; F256 Motherboard : Either the F256jr mini-itx motherboard or the F256k motherboard will work.

; Feather ESP8266 Huzzah : This board will be wi-fi module when the correct firmware is installed. It is available from Adafruit ([https://www.adafruit.com/product/2821 product link]), either with or without the pins pre-soldered. While the firmware will run on other ESP8266 boards, the solder pads on the F256 motherboards is designed for the Feather board from Adafruit. Be sure to order the Feather with the header pins (not with the "stacking headers"), although the correct header pins are readily available from several suppliers, as they are commonly used with Arduino projects (single row, 0.1 inch (2.5mm) spacing).

; Header Sockets : Single row, 0.1 inch (2.5 mm) spacing. These are commonly available from many suppliers, but Adafruit have a kit including the correct sized headers ([https://www.adafruit.com/product/2886 product link]).

; Soldering Supplies : Soldering iron suitable for through-hole soldering, decent solder, flux, and cleaning supplies to remove flux residue.

; USB Cable: A to B Micro : This cable will be used to connect your Feather ESP8266 to the computer you will use to install and configure the firmware.

== Software Needed ==

; ESP_SLIP_ROUTER : The firmware to install on the ESP8266 to turn it into a SLIP/WiFi router. [https://github.com/martin-ger/esp_slip_router GitHub Repository]

; Linux : While installation of the firmware on the ESP8266 can be done in Linux, Windows, or MacOS X, the configuration step seems to be possible only using a Linux install. Currently, configuration of the wi-fi router once the firmware is installed can only be done through a SLIP connection, but Windows and MacOS X do not support SLIP networking. An installation on a Raspberry Pi should be fine.

; Python 3 : Needed by the esptool.py for installing firmware on the ESP8266.

; PySerial : The Python package that provides serial port access for esptool.py.

; esptool.py : Tool used to install firmware on the ESP8266. [https://github.com/espressif/esptool GitHub Repository]

; Net Tools : A package for Linux that includes the `slattach` command, used to configure the wi-fi router. The correct link will depend on your Linux distribution, but it may already be installed.

== Preparing the Feather ESP8266 ==

This process is a bit involved on the software side. There are really just two main tasks that need to happen:

1. Installing the ESP_SLIP_FIRMWARE
1. Configure the ESP8266 for Your Network

However, both of these tasks require that the correct software and libraries are installed on your system. The first task can be done using Windows, Linux, or MacOS X. The second task can only be done using a Linux install at this time. The example commands below are shown for Linux, and in particular the Ubuntu distribution.

=== Installation Prerequisites ===

If you are currently using the FoenixMgr Python script to work with your F256's debug port, then you already have the prerequisites installed and can skip this section. Otherwise, you will need to make sure you have Python 3 installed, set as your default version of Python, PIP installed, PySerial installed, and the Net Tools package installed:

1. Install Python 3
<pre>
sudo apt install python3
sudo apt install python-is-python3
</pre>

2. Install PIP
<pre>
sudo apt install pip
</pre>

3. Install PySerial
<pre>
python pip install pyserial
</pre>

4. Install Net Tools

This will vary with each Linux distribution. Sometimes this package is installed by default.

=== Installing the ESP_SLIP_ROUTER Firmware ===

Use the USB cable to connect the Feather ESP8266 to your computer and make a note of the device or COM port the Feather will used. Now, the esptool.py script may be used to install the ESP_SLIP_ROUTER firmware. The ESP_SLIP_ROUTER repository includes two binary files in the firmware directory that need to be installed.

<pre>
esptool.py --port {device} write_flash -fs 8MB 0x00000 {path}/0x00000.bin 0x10000 {path}/0x10000.bin
</pre>

Substitute the path to the USB serial device for your ESP8266 (likely <code>/dev/ttyUSB0</code> or something similar on Linux, or some COM device on Windows) for <code>{device}</code> and the path to the ESP_SLIP_ROUTER's firmware directory for <code>{path}</code>.

The activity light on the Feather should flash for a bit. Once that is complete, the firmware should be installed.

'''NOTE:''' you may get an error message about access to your device on Linux. It is common for Linux distributions to lock USB device access to a special group. You can either add your account to that group, or for a quick and dirty solution add read and write access to all users—for example:

<pre>
sudo chmod a+rw /dev/ttyUSB0
</pre>

=== Configuring the ESP8266 Router for Your Network ===

To configure the router, you will need to make a SLIP connection over the USB cable and use the router's console to set the SSID and password of the wi-fi network it is to use. Unfortunately, there does not seem to be any SLIP support in Windows or MacOS X anymore. This is why a Linux install is needed.

To make this connection, you must first issue some commands in Linux to create a SLIP tunnel over the USB cable to the router and to assign it a local IP address so you can connect (assuming the Feather is on <code>/dev/ttyUSB0</code>. Substitute the correct device path, if it is different.):

<pre>
sudo slattach -L -p slip -s 115200 /dev/ttyUSB0 &
sudo ifconfig sl0 192.168.240.2 pointopoint 192.168.240.1 up mtu 1500
</pre>

Once that has been done, you can use telnet to connect to the router's console:

<pre>
telnet 192.168.240.1 7777
</pre>

At this point, you should see a prompt from the router's console. Enter the commends to set the SSID, set the password, and set the router to use an access point:

<pre>
CMD>set ssid {your_ssid}
CMD>set password {your_pw}
CMD>set use_ap 0
CMD>save
CMD>reset
</pre>

At this point, the wi-fi module should be ready to install in your F256.

== Installing the Wi-Fi Module in Your F256 ==

F256 WiFi

2023-06-28T23:18:10Z

PJW: A description of how to set up a Wi-Fi module on the F256 computers.

Foenix Kernel Documentation

2023-04-09T22:16:52Z

PJW: /* Kernel Calls */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 || Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| SETSIZES || $00:112C || Recompute the size of the text screen given the current screen resolution and border size. This should be called whenever the screen size changes but text mode is being used so that the kernel's text routines work properly.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run an [[executable binary file]] from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || 0 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Foenix Kernel Documentation

2022-09-09T02:24:16Z

PJW: /* Kernel Calls */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 || Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run an [[executable binary file]] from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || 0 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Using the Debug Interface

2021-12-12T01:35:07Z

PJW: /* Uploading with the Foenix IDE */

= Using the Debug interface =

Data and programs may be sent to the C256 Foenix over the USB debug port (right side of the FMX, left side of the U/U+).

== Installing Drivers ==

The debug interface is a USB serial port which requires a driver to be installed on the host system. The drivers for the serial USB device (XR21B1411) can be found at: https://www.maxlinear.com/support/design-tools/software-drivers.

== Uploading with the Foenix IDE ==

To setup the Foenix IDE, download and run the MSI installer from the repository from GitHub (https://github.com/Trinity-11/FoenixIDE/releases).

To upload a BIN or HEX file with the Foenix IDE's user interface:

# Select the Tools > Uploader menu option. An "Uploader Window" will open.
# Select the COM port associated with the C256 debug interface in the drop down selector.
# Click the "Connect" button to establish a connection to the C256.
# Click the button labeled with ellipsis (...) to select the file to upload. By default, the uploader will show BIN files, but you can choose to search for HEX files instead.
# If you are uploading a BIN file, enter the starting destination address in the field "C256 Dest Address". This step is not needed with HEX files, since they have the destination addresses for their data included.
# Click the "Send Binary" button to start the upload process.

[[File:Foenix IDE Uploader.png]]

== Uploading with C256Mgr ==

C256Mgr is a set of Python scripts allowing access to the C256's USB debug interface. The scripts allow you to use the command line to upload BIN and HEX files to the C256, reprogram the flash memory, or examine memory on the C256. If your code includes a 64Tass compatible LBL file, the C256Mgr scripts can use that LBL file to allow you to examine memory based on the labels in your code. C256Mgr was originally intended to provide a cross-platform option for those who cannot run .Net applications. The C256Mgr can be found at: https://github.com/pweingar/C256Mgr.

To install the C256Mgr, you will need to make sure you have Python 3.7 installed as well as the PySerial library. You will need to edit the c256.ini file to set the default COM port and LBL file for your project, although both settings can be overridden by the command line options.

Once the manager is installed and configured correctly, there are two batch files that can be used to upload a file to the C256:

; Binary
: To upload a binary file, you use the UPLOAD.BAT file, which takes a BIN file and destination address (in hex) as arguments:
<code>upload kernel.bin 380000</code>

; HEX File
: To upload an Intel HEX file, you use the RUN256.BAT file, which takes just the HEX file as an argument:
<code>run256 hello.hex</code>

Executable binary file

2021-08-09T15:52:06Z

PJW: /* PGZ */

The '''F_RUN''' and '''F_LOAD''' kernel calls supports multiple binary formats. If you try to load a file in one of these formats without specifying a starting address, it will be loaded into the locations specified in the file. If you try to run a file in one of these formats, the file will be loaded into memory and executed.

== PGX ==

PGX is a simple, single segment format akin to Commodore's PRG format. The file starts with an eight byte header, followed by the contents to be loaded into memory. The header consists of three parts:

* The first three bytes are the ASCII codes for "PGX", serving as a file type signature.
* The fourth byte is the CPU code, indicating the target CPU. Currently, only the value $01 is supported and designates that the 65816 is the target CPU.
* The final four bytes of the header are the starting destination address in little-endian format. This address will be the location to store the first byte of the data (which is the ninth byte of the file).

{| class="wikitable"
! Offset !! Count !! Example !! Purpose
|-
| 0 || 3 || "PGZ" || Signature
|-
| 3 || 1 || $01 || CPU
|-
| 4 || 4 || $010000 || Destination Address
|-
| 8 || - || $00 $01 $02 ... || The data to load
|}

== PGZ ==

PGZ is a multi-segment file format that can load data into multiple areas in memory. The format is derived from binary format used by Western Design Center's C compiler.

* The first byte of the PGZ format is the ASCII code for "Z". This serves as the file type signature.
* Next comes any number of segments, each following right after the previous segment with no separator. Each segment has the following format:
** Three bytes of address, in little endian format. This is the starting address for writing the data of the segment.
** Three bytes indicating the size of the segment, in little endian format.
** The bytes of data in the segment (same number of bytes as specified in the size).
* If final segment has a size of $000000 and no data bytes, then address specifies the starting address of the executable.

{| class="wikitable"
! Segment !! Offset !! Count !! Example !! Purpose
|-
| N/A || 0 || 1 || "Z" || Signature
|-
|rowspan="3"| 1 || 1 || 3 || $010000 || Address of segment #1
|-
| 4 || 3 || $000009 || Size of segment #1
|-
| 7 || ... || ... || Data of Segment #1
|-
|rowspan="3"| 2 || 16 || 3 || $020000 || Address of segment #2
|-
| 19 || 3 || $000008 || Size of segment #2
|-
| 22 || ... || ... || Data of Segment #2
|-
|rowspan="2"| START || 30 || 3 || $010000 || Starting address
|-
| 33 || 3 || $000000 || 0 to indicate start address
|}

Executable binary file

2021-08-09T15:43:39Z

PJW: /* PGX */

Executable binary file

2021-08-09T15:43:14Z

PJW: /* PGX */

The '''F_RUN''' and '''F_LOAD''' kernel calls supports multiple binary formats. If you try to load a file in one of these formats without specifying a starting address, it will be loaded into the locations specified in the file. If you try to run a file in one of these formats, the file will be loaded into memory and executed.

== PGX ==

PGX is a simple, single segment format akin to Commodore's PRG format. The file starts with an eight byte header, followed by the contents to be loaded into memory. The header consists of three parts:

* The first three bytes are the ASCII codes for "PGX", serving as a file type signature.
* The fourth byte is the CPU code, indicating the target CPU. Currently, only the value $01 is supported and designates that the 65816 is the target CPU.
* The final four bytes of the header are the starting destination address in little-endian format. This address will be the location to store the first byte of the data (which is the ninth byte of the file).

{| class="wikitable"
! Offset !! Count !! Example !! Purpose
|-
| 0 || 3 || "PGZ" || Signature
|-
| 4 || 1 || $01 || CPU
|-
| 5 || 3 || $010000 || Destination Address
|-
| 8 || - || $00 $01 $02 ... || The data to load
|}

== PGZ ==

PGZ is a multi-segment file format that can load data into multiple areas in memory. The format is derived from binary format used by Western Design Center's C compiler.

* The first byte of the PGZ format is the ASCII code for "Z". This serves as the file type signature.
* Next comes any number of segments, each following right after the previous segment with no separator. Each segment has the following format:
** Three bytes of address, in little endian format. This is the starting address for writing the data of the segment.
** Three bytes indicating the size of the segment, in little endian format.
** The bytes of data in the segment (same number of bytes as specified in the size).
* If final segment has a size of $000000 and no data bytes, then address specifies the starting address of the executable.

Executable binary file

2021-08-09T15:40:02Z

PJW: Created page with "The '''F_RUN''' and '''F_LOAD''' kernel calls supports multiple binary formats. If you try to load a file in one of these formats without specifying a starting address, it wil..."

The '''F_RUN''' and '''F_LOAD''' kernel calls supports multiple binary formats. If you try to load a file in one of these formats without specifying a starting address, it will be loaded into the locations specified in the file. If you try to run a file in one of these formats, the file will be loaded into memory and executed.

== PGX ==

PGX is a simple, single segment format akin to Commodore's PRG format. The file starts with an eight byte header, followed by the contents to be loaded into memory. The header consists of three parts:

* The first three bytes are the ASCII codes for "PGX", serving as a file type signature.
* The fourth byte is the CPU code, indicating the target CPU. Currently, only the value $01 is supported and designates that the 65816 is the target CPU.
* The final four bytes of the header are the starting destination address in little-endian format. This address will be the location to store the first byte of the data (which is the ninth byte of the file).

== PGZ ==

PGZ is a multi-segment file format that can load data into multiple areas in memory. The format is derived from binary format used by Western Design Center's C compiler.

* The first byte of the PGZ format is the ASCII code for "Z". This serves as the file type signature.
* Next comes any number of segments, each following right after the previous segment with no separator. Each segment has the following format:
** Three bytes of address, in little endian format. This is the starting address for writing the data of the segment.
** Three bytes indicating the size of the segment, in little endian format.
** The bytes of data in the segment (same number of bytes as specified in the size).
* If final segment has a size of $000000 and no data bytes, then address specifies the starting address of the executable.

Foenix Kernel Documentation

2021-08-09T15:26:04Z

PJW: /* Kernel Calls */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run an [[executable binary file]] from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || 0 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Foenix Kernel Documentation

2021-08-08T00:32:07Z

PJW: /* FDC_ST0 ($00:326) */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || 0 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Foenix Kernel Documentation

2021-08-08T00:31:59Z

PJW: /* DOS_STATUS ($00:32E) */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
|}

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || 0 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Foenix Kernel Documentation

2021-08-08T00:31:51Z

PJW: /* BIOS_STATUS ($00:320) */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
|}

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Foenix Kernel Documentation

2021-08-08T00:31:42Z

PJW: /* DOS_STATUS ($00:32E) */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| BIOS_OK || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
|}

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| N/A || $00 || The last DOS operation was successful
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Foenix Kernel Documentation

2021-08-08T00:31:21Z

PJW: /* BIOS_STATUS ($00:320) */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| BIOS_OK || $00 || The last BIOS operation was successful
|-
| BIOS_ERR_BADDEV || $80 || BIOS bad device # error
|-
| BIOS_ERR_MOUNT || $81 || BIOS failed to mount the device
|-
| BIOS_ERR_READ || $82 || BIOS failed to read from a device
|-
| BIOS_ERR_WRITE || $83 || BIOS failed to write to a device
|-
| BIOS_ERR_TRACK || $84 || BIOS failed to seek to the correct track
|-
| BIOS_ERR_CMD || $85 || A general block device command error
|-
| BIOS_ERR_WRITEPROT || $86 || The media was write-protected
|-
| BIOS_ERR_NOMEDIA || $87 || No media detected... unable to read/write in time
|-
| BIOS_ERR_RESULT || $88 || Couldn't get the result bytes for some reason
|-
| BIOS_ERR_OOS || $89 || FDC state is somehow out of sync with the driver.
|-
| BIOS_ERR_NOTATA || $8A || IDE drive is not ATA
|-
| BIOS_ERR_NOTINIT || $8B || Could not initilize the device
|-
| BIOS_ERR_TIMEOUT || $8C || Timeout error

|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
|}

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

Foenix Kernel Documentation

2021-08-08T00:28:43Z

PJW: /* Special Kernel Variables */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

=== BIOS_STATUS ($00:320) ===

This status variable records any error condition related to the low level block level BIOS routines.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
|}

=== FDC_ST0 ($00:326) ===

This status variable records hardware level status codes.
For FDC access, it represents the first status byte of the floppy drive controller.
For SDC and HDD access, it records the SDC and IDE level hardware status, respectively.
The meaning of the bits will vary depending on the hardware accessed, and you should refer
to the documentation on that specific device for details.

{| class="wikitable"
|-
! Name !! Code !! Description
|-
|}

=== DOS_STATUS ($00:32E) ===

This status variable records any error condition related to the DOS and FAT level code:

{| class="wikitable"
|-
! Name !! Code !! Description
|-
| DOS_ERR_READ || 1 || We could not read a sector, check BIOS_STATUS for details
|-
| DOS_ERR_NOTMBR || 2 || We could not find the MBR
|-
| DOS_ERR_NOFAT32 || 3 || We could not find a FAT32 parition using LBA
|-
| DOS_ERR_NOINIT || 4 || We could not INIT the block device
|-
| DOS_ERR_VOLID || 5 || Volume ID sector could not be loaded
|-
| DOS_ERR_FAT || 6 || Can't scan the FAT for some reason
|-
| DOS_ERR_BADPATH || 7 || The path was badly formatted
|-
| DOS_ERR_NODIR || 8 || Could not read the directory
|-
| DOS_ERR_NOTFOUND || 9 || File/directory requested was not found
|-
| DOS_ERR_NOCLUSTER || 10 || There are no more clusters
|-
| DOS_ERR_FILEEXISTS || 11 || There is already a file of that name
|-
| DOS_ERR_NOTOPEN || 12 || File has not been open
|-
| DOS_ERR_NOTREAD || 13 || File is not open for reading
|-
| DOS_ERR_NOTWRITE || 14 || File is not open for writing
|-
| DOS_ERR_OPEN || 15 || File is already open
|-
| DOS_ERR_PGXSIG || 16 || File does not have the PGX signature
|-
| DOS_ERR_NOEXEC || 17 || File does is not an executable format
|-
| DOS_ERR_MEDIAFULL || 18 || There are no more free clusters on the drive
|-
| DOS_ERR_WRITEPROT || 19 || The medium is write-protected
|-
| DOS_ERR_FATUPDATE || 20 || Can't update the FAT
|-
| DOS_ERR_DIRFULL || 21 || The directory is full
|-
| DOS_ERR_NOFD || 22 || No file descriptors are available for allocation
|-
| DOS_ERR_NOMEDIA || 23 || No media was present
|-
| DOS_ERR_EOF || 24 || At end of file
|-
| DOS_ERR_PGZSIG || 25 || File does not have the PGZ signature
|}

GABE

2021-08-02T15:16:51Z

PJW: /* GABE Random Number Generator Status and Control ($AF:E886) */

== GABE -- The System Control, I/O, and Sound Chip ==

"GABE" is the name of the system controller chip of the C256 Foenix RevC board, and performs several functions including system bus management, math coprocessing, I/O, and sound.
The RevB version of the C256 had two chips "Gavin" and "Beatrix" that were combined into a single master chip called "GABE".

GABE has several key functions:
* System start up
* Debug interface control and bus mastering
* I/O interfacing
* Math coprocessor
* Sound chip interfacing and emulation

=== GABE System Startup Process ===

When the C256 Foenix powers up, GABE takes control and coordinates the startup process.
It first copies the flash data out of flash and into system RAM, starting at bank $38 on the FMX ($18 on the RevB).
GABE also copies the first bank of flash data down to bank $00 of system RAM
before control is given to the CPU and the CPU's RESET is triggered.
This process ensures that the kernel, hardware vectors, and interrupt handlers are all in place prior to the CPU
taking control and resetting the first time on power up.

The mapping of flash memory locations to system RAM is thus:

{| class="wikitable"
|-
!Flash Range !! RAM Range
|-
|$F8:0000...$FF:FFFF || $38:0000...$3F:FFFF
|-
|$F8:0000...$F8:FFFF || $00:0000...$00:FFFF
|}

=== GABE Integer Math Coprocessor ($00:0100 – $00:012B) ===

GABE provides an easy to use integer math coprocessor in the form of two 16-multipliers (one signed, one unsigned),
two 16-bit dividers (one signed, one unsigned), and a single 32-bit adder. Using the coprocessor is straight-forward:
the operands are written to the correct registers, and the result is read from the output registers. The operations
are all performed within a single CPU clock cycle, so no waiting is required.

{| class="wikitable"
|-
!Start Address
!End Address
!Register Name
!Additional Info
|-
| $00:0100 || $00:0101 || UNSIGNED_MULT_A || A operand for unsigned multiplication (16-bit)
|-
| $00:0102 || $00:0103 || UNSIGNED_MULT_B || B operand for unsigned multiplication (16-bit)
|-
| $00:0104 || $00:0107 || UNSIGNED_MULT_RESULT || Result for unsigned multiplication (32-bit)
|-
| $00:0108 || $00:0109 || SIGNED_MULT_A || A operand for signed multiplication (16-bit)
|-
| $00:010A || $00:010B || SIGNED_MULT_B || B operand for signed multiplication (16-bit)
|-
| $00:010C || $00:010F || SIGNED_MULT_RESULT || Result for signed multiplication (32-bit)
|-
| $00:0110 || $00:0111 || UNSIGNED_DIV_DEM || Denominator for unsigned division (16-bit)
|-
| $00:0112 || $00:0113 || UNSIGNED_DIV_NUM || Numerator for unsigned division (16-bit)
|-
| $00:0114 || $00:0115 || UNSIGNED_DIV_QUO || Quotient for unsigned division (16-bit)
|-
| $00:0116 || $00:0117 || UNSIGNED_DIV_REM || Remainder for unsigned division (16-bit)
|-
| $00:0118 || $00:0119 || SIGNED_DIV_DEM || Denominator for signed division (16-bit)
|-
| $00:011A || $00:011B || SIGNED_DIV_NUM || Numerator for signed division (16-bit)
|-
| $00:011C || $00:011D || SIGNED_DIV_QUO || Quotient for signed division (16-bit)
|-
| $00:011E || $00:011F || SIGNED_DIV_REM || Remainder for signed division (16-bit)
|-
| $00:0120 || $00:0123 || ADDER32_A || A operand for 32-bit addition (32-bits)
|-
| $00:0124 || $00:0127 || ADDER32_B || B operand for 32-bit addition (32-bits)
|-
| $00:0128 || $00:012B || ADDER32_R || Result of 32-bit addition (32-bits)
|}

=== GABE Keyboard Ports ===

{| class="wikitable"
|-
! Address !! R/W !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:1060 || X || KBD_DATA || D7 || D6 || D5 || D4 || D3 || D2 || D1 || D0 || Keyboard data port
|-
| $AF:1061 || X || PORTB || D7 || D6 || D5 || D4 || D3 || D2 || D1 || D0
|-
| $AF:1064 || R || KBD_STATUS || PAR_E || RX_TO || TX_TO || KBD_INH || CMD || SYS || IN_F || OUT_F || Keyboard Status
|-
| $AF:1064 || W || KBD_CMD || CMD7 || CMD6 || CMD5 || CMD4 || CMD3 || CMD2 || CMD1 || CMD0 || Keyboard Command
|}

==== GABE Keyboard Status Flags ====

;PAR_E
:Parity error

;RX_TO
:Time out reading data

;TX_TO
:Time out transmitting data

;CMD
:If 0, then data written to input buffer is data for PS/2 device. If 1, then data written to input buffer is data for PS/2 controller command

;SYS
:Flag to the firmware that the keyboard has past POST

;IN_F
:Input buffer is full

;OUT_F
:Output buffer is full

=== GABE Floating Point Math Coprocessor ($AF:E200 – AFE20F) ===

GABE provides a floating point math coprocessor, providing addition, subtraction, multiplication, and division for 32-bit floating point numbers.
Additionally, the coprocessor allows for conversion between a fixed point format and 32-bit IEEE 754 floating point format.
The floating point coprocessor is a little more complex than the integer coprocessor, with each math unit having input multiplexers that control
where the inputs come from, and with the output registers having their own multiplexer. Finally, the output of the multiplier and divider units
can be used directly as inputs to the adder/subtracter.

[[File:FMX Floating Point.jpg|800px|FMX Floating Point Math Coprocessor]]

{| class="wikitable"
|-
! Start Address !! End Address !! Register Name !! Additional Information
|-
| $AF:E200 || || FP_MATH_CTRL0 || Controls input multiplexers, Adder function, and Adder multiplexers
|-
| $AF:E201 || || FP_MATH_CTRL1 || Controls output multiplexers
|-
| $AF:E202 || || FP_MATH_CTRL2 || Unused: reserved
|-
| $AF:E203 || || FP_MATH_CTRL3 || Unused: reserved
|-
| $AF:E204 || || FP_MATH_MULT_STAT || Status of the multiplier
|-
| $AF:E205 || || FP_MATH_DIV_STAT || Status of the divider
|-
| $AF:E206 || || FP_MATH_ADD_STAT || Status of the adder/subtracter
|-
| $AF:E207 || || FP_MATH_CONV_STAT || Status of the converters
|-
| $AF:E208 || $AF:E20B || FP_MATH_INPUT0 || Input 0 (write only)
|-
| $AF:E20C || $AF:E20F || FP_MATH_INPUT1 || Input 1 (write only)
|-
| $AF:E208 || $AF:E20B || FP_MATH_OUTPUT_FP || Result in IEEE 754 format (read only)
|-
| $AF:E20C || $AF:E20F || FP_MATH_OUTPUT_FIXED || Result in 20.12 fixed point format (read only)
|}

==== GABE Register FP_MATH_CTRL0 ($AF:E200) ====

{| class="wikitable"
|-
! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
|colspan="2"|FP_MATH_CTRL0_ADD_IN1_MUX ||colspan="2"|FP_MATH_CTRL0_ADD_IN0_MUX || FP_MATH_CTRL0_ADD_SUB || || FP_MATH_CTRL0_INPUT1_MUX || FP_MATH_CTRL0_INPUT0_MUX
|}

; FP_MATH_CTRL0_INPUT0_MUX
: If 0, Input0 is assumed to be in IEEE format. If 1, it is assumed to be in 20.12 fixed point format and will be converted to IEEE.

; FP_MATH_CTRL0_INPUT1_MUX
: If 0, Input1 is assumed to be in IEEE format. If 1, it is assumed to be in 20.12 fixed point format and will be converted to IEEE.

; FP_MATH_CTRL0_ADD_SUB
: If 0, the adder will perform a subtract operation. If 1, it will perform an addition.

; FP_MATH_CTRL0_ADD_IN0_MUX
: Selects the source for input 0 of the adder unit.

; FP_MATH_CTRL0_ADD_IN1_MUX
: Selects the source for input 1 of the adder unit.

{| class="wikitable"
|+ Adder Source Selector Codes
|-
! Control Bits !! Input
|-
| 00 || Input 0
|-
| 01 || Input 1
|-
| 10 || Output of the multiplier
|-
| 11 || Output of the divider
|}

==== GABE Register FP_MATH_CTRL1 ($AF:E201) ====

{| class="wikitable"
|-
! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
|colspan="6"| ||colspan="2"| FP_MATH_CTRL1_OUTPUT_MUX0
|}

; FP_MATH_CTRL1_OUTPUT_MUX0
: Selects which functional block provides the output result:

{| class="wikitable"
|+ Result Source Selector Codes
|-
! Control Bits !! Output Source
|-
| 00 || Result of multiplier is the routed to the output registers
|-
| 01 || Result of divider is the routed to the output registers
|-
| 10 || Result of adder is the routed to the output registers
|-
| 11 || 1.0 is routed to the output registers
|}

==== GABE Registers: FP Status Registers ($AF:E204 – $AF:E207) ====

These registers contain the status flags for the various functional units. The status flags are all roughly similar across the four units:

{| class="wikitable"
|+ Status Codes
|-
! Code !! Meaning
|-
| $01 || Result was not a number (NAN)
|-
| $02 || Overflow
|-
| $04 || Underflow
|-
| $08 || Result was 0.0
|-
| $10 || Division by 0.0 was attempted
|}

=== GABE Timer Registers ($00:0160 – $00:017F) ===

* Timer0 and Timer1 count system clock transitions (14318180Hz)
* Timer2 is clocked from VICKY's Start-of-Frame output (50hz).
* To create interrupts at a set interval for timer 0 and 1 divide the clock frequency by the desired interval. So if one wishes 4 interrupts every second use 14318180 divided by 4.

{| class="wikitable"
|-
!Start Address
!End Address
!Register Name
!Additional Info
|-
!colspan="4" style="text-align:left;" | Timer 0
|-
| $00:0160 || || TIMER0_CTRL_REG || Timer 0 control register
|-
| $00:0161 || || TIMER0_CHARGE_L || Timer 0 precharge register lower byte, loaded when counting down
|-
| $00:0162 || || TIMER0_CHARGE_M || Timer 0 precharge register middle byte, loaded when counting down
|-
| $00:0163 || || TIMER0_CHARGE_H || Timer 0 precharge register high byte, loaded when counting down
|-
| $00:0164 || || TIMER0_CMP_REG || Timer 0 compare register
|-
| $00:0165 || || TIMER0_CMP_L || Timer 0 compare register lower byte, loaded when counting up
|-
| $00:0166 || || TIMER0_CMP_M || Timer 0 compare register middle byte, loaded when counting up
|-
| $00:0167 || || TIMER0_CMP_H || Timer 0 compare register high byte, loaded when counting up
|-
!colspan="4" style="text-align:left;" | Timer 1
|-
| $00:0168 || || TIMER1_CTRL_REG || Timer 1 control register
|-
| $00:0169 || || TIMER1_CHARGE_L || Timer 1 precharge register lower byte, loaded when counting down
|-
| $00:016A || || TIMER1_CHARGE_M || Timer 1 precharge register middle byte, loaded when counting down
|-
| $00:016B || || TIMER1_CHARGE_H || Timer 1 precharge register high byte, loaded when counting down
|-
| $00:016C || || TIMER1_CMP_REG || Timer 1 compare register
|-
| $00:016D || || TIMER1_CMP_L || Timer 1 compare register lower byte, loaded when counting up
|-
| $00:016E || || TIMER1_CMP_M || Timer 1 compare register middle byte, loaded when counting up
|-
| $00:016F || || TIMER1_CMP_H || Timer 1 compare register high byte, loaded when counting up
|-
!colspan="4" style="text-align:left;" | Timer 2
|-
| $00:0170 || || TIMER2_CTRL_REG || Timer 2 control register
|-
| $00:0171 || || TIMER2_CHARGE_L || Timer 2 precharge register lower byte, loaded when counting down
|-
| $00:0172 || || TIMER2_CHARGE_M || Timer 2 precharge register middle byte, loaded when counting down
|-
| $00:0173 || || TIMER2_CHARGE_H || Timer 2 precharge register high byte, loaded when counting down
|-
| $00:0174 || || TIMER2_CMP_REG || Timer 2 compare register
|-
| $00:0175 || || TIMER2_CMP_L || Timer 2 compare register lower byte, loaded when counting up
|-
| $00:0176 || || TIMER2_CMP_M || Timer 2 compare register middle byte, loaded when counting up
|-
| $00:0177 || || TIMER2_CMP_H || Timer 2 compare register high byte, loaded when counting up
|-
|}

{| class="wikitable"
|-
!Register
!Value
!Name
!Additional Info
|-
| TIMER<X>_CTRL_REG || 0x01 || TMR_EN || Enabled the timer
|-
| TIMER<X>_CTRL_REG || 0x02 || TMR_SCLR || Set when counting up
|-
| TIMER<X>_CTRL_REG || 0x04 || TMR_SLOAD|| Set when counting down
|-
| TIMER<X>_CTRL_REG || 0x08 || TMR_UPDWN|| Set when counting up (1 = Up, 0 = Down)
|-
| TIMER<X>_CMP_REG || 0x01 || TMR_CMP_RECLR|| Set to one for it to cycle when Counting up
|-
| TIMER<X>_CMP_REG || 0x02 || TMR_CMP_RELOAD|| Set to one for it to reload when Counting Down
|-
|}

==== C pseudo code for counting up ====
TIMER1_CHARGE_L = 0x00; 
TIMER1_CHARGE_M = 0x00; 
TIMER1_CHARGE_H = 0x00; 
TIMER1_CMP_L = clockValue & 0xFF; 
TIMER1_CMP_M = (clockValue >> 8) & 0xFF; 
TIMER1_CMP_H = (clockValue >> 16) & 0xFF; 
 
TIMER1_CMP_REG = TMR_CMP_RECLR; 
TIMER1_CTRL_REG = TMR_EN | TMR_UPDWN | TMR_SCLR; 

==== C pseudo code for counting down ====
TIMER1_CHARGE_L = (clockValue >> 0) & 0xFF; 
TIMER1_CHARGE_M = (clockValue >> 8) & 0xFF; 
TIMER1_CHARGE_H = (clockValue >> 16) & 0xFF; 
TIMER1_CMP_L = 0x00; 
TIMER1_CMP_M = 0x00; 
TIMER1_CMP_H = 0x00; 
 
TIMER1_CMP_REG = TMR_CMP_RELOAD; 
TIMER1_CTRL_REG = TMR_EN | TMR_SLOAD; 
 

=== GABE Interrupt Control Registers ($00:0140 – $00:014B) ===

There are four types of interrupt control register that GABE provides: pending, polarity, edge detection, and mask.
Each interrupt that is supported has a bit position in each of the 24 or 32 bits provided by the register types.

; Pending
: The pending registers indicate if an interrupt of a particular type has been triggered and needs processing. An interrupt handler should also write to this register to clear the pending flag, once the interrupt has been processed.

; Polarity
: This register indicates if the interrupt is triggered by a high or low signal on the input to GABE.

; Edge
: This register indicates if the interrupt is triggered by an transition (edge) or by a high or low value.

; Mask
: This register indicates if the associated interrupt will trigger an IRQ to the processor. Interrupt signals with a mask bit of 0 will be ignored, while those with a mask bit of 1 will trigger an interrupt to the CPU.

{| class="wikitable"
|-
!Start
!Register Description
!Additional Info
|-
| $00:0140 || INT_PENDING_REG0 || Interrupt pending #0
|-
| $00:0141 || INT_PENDING_REG1 || Interrupt pending #1
|-
| $00:0142 || INT_PENDING_REG2 || Interrupt pending #2
|-
| $00:0143 || INT_PENDING_REG3 || Interrupt pending #3---FMX Model only
|-
| $00:0144 || INT_POL_REG0 || Interrupt polarity #0
|-
| $00:0145 || INT_POL_REG1 || Interrupt polarity #1
|-
| $00:0146 || INT_POL_REG2 || Interrupt polarity #2
|-
| $00:0147 || INT_POL_REG3 || Interrupt polarity #3---FMX Model only
|-
| $00:0148 || INT_EDGE_REG0 || Enable Edge Detection #0
|-
| $00:0149 || INT_EDGE_REG1 || Enable Edge Detection #1
|-
| $00:014A || INT_EDGE_REG2 || Enable Edge Detection #2
|-
| $00:014B || INT_EDGE_REG3 || Enable Edge Detection #3---FMX Model only
|-
| $00:0148 || INT_MASK_REG0 || Enable Interrupt #0
|-
| $00:0149 || INT_MASK_REG1 || Enable Interrupt #1
|-
| $00:014A || INT_MASK_REG2 || Enable Interrupt #2
|-
| $00:014B || INT_MASK_REG3 || Enable Interrupt #3---FMX Model only
|}

There are several interrupts the GABE can handle, distributed over four blocks:

{| class="wikitable"
|-
!Block !! Bit !! Name !! Function
|-
| 0 || $01 || FNX0_INT00_SOF || Start of Frame @60Hz
|-
| 0 || $02 || FNX0_INT01_SOL || Start of Line (programmable)
|-
| 0 || $04 || FNX0_INT02_TMR0 || Timer 0
|-
| 0 || $08 || FNX0_INT03_TMR1 || Timer 1
|-
| 0 || $10 || FNX0_INT04_TMR2 || Timer 2
|-
| 0 || $20 || FNX0_INT05_RTC || Real Time Clock
|-
| 0 || $40 || FNX0_INT06_FCC || Floppy Drive Controller
|-
| 0 || $80 || FNX0_INT07_MOUSE || Mouse Interrupt (INT12 in SuperIO IOspace)
|-
| 1 || $01 || FNX1_INT00_KBD || Keyboard Interrupt
|-
| 1 || $02 || FNX1_INT01_SC0 || VICKY_II (INT2) Sprite 2 Sprite Collision
|-
| 1 || $04 || FNX1_INT02_SC1 || VICKY_II (INT3) Sprite 2 Tiles Collision
|-
| 1 || $08 || FNX1_INT03_COM2 || Serial Port 2 (Internal)
|-
| 1 || $10 || FNX1_INT04_COM1 || Serial Port 1 (External)
|-
| 1 || $20 || FNX1_INT05_MPU401 || Midi Controller Interrupt
|-
| 1 || $40 || FNX1_INT06_LPT || Parallel Port
|-
| 1 || $80 || FNX1_INT07_SDCARD || SD Card Controller Interrupt (CH376S, if present)
|-
| 2 || $01 || FNX2_INT00_OPL3 || OPL3
|-
| 2 || $02 || FNX2_INT01_GABE_INT0 || GABE (INT0) - TBD
|-
| 2 || $04 || FNX2_INT02_GABE_INT1 || GABE (INT1) - TBD
|-
| 2 || $08 || FNX2_INT03_SDMA || VICKY_II (INT4)
|-
| 2 || $10 || FNX2_INT04_VDMA || VICKY_II (INT5) -- Vicky DMA completion
|-
| 2 || $20 || FNX2_INT05_GABE_INT2 || GABE (INT2) - TBD
|-
| 2 || $40 || FNX2_INT06_EXT || External Expansion
|-
| 2 || $80 || FNX2_INT07_SDCARD_INS || SDCARD Insertion
|-
| 3 || $01 || FNX3_INT00_OPN2 || OPN2
|-
| 3 || $02 || FNX3_INT01_OPM || OPM
|-
| 3 || $04 || FNX3_INT02_IDE || HDD IDE Interrupt
|-
| 3 || $08 || FNX3_INT03_TBD || TBD
|-
| 3 || $10 || FNX3_INT04_TBD || TBD
|-
| 3 || $20 || FNX3_INT05_TBD || TBD
|-
| 3 || $40 || FNX3_INT06_TBD || TBD
|-
| 3 || $80 || FNX3_INT07_TBD || TBD
|}

=== GABE SID Emulation ($AF:E400 – $AF:E41F) ===

GABE emulates the SID sound chip. Currently, the FMX provides one SID unit.
Although the real SID chip provides analog to digital conversion for two
potentiometer inputs for paddles, the C256's paddle inputs are provided through
a different chip, so the POT registers listed below are not useful.

For complete information on how to use these registers, please consult documentation
on the SID chips.

All registers are write-only, except where noted otherwise.

{| class="wikitable"
|-
! Start Address !! End Address !! Register Name !! Additional Information
|-
| $AF:E400 || $AF:E401 || SID0_V1_FREQ || SID0 V1 Frequency (16-bits)
|-
| $AF:E402 || $AF:E403 || SID0_V1_PW || SID0 V1 Pulse Width (12-bits)
|-
| $AF:E404 || || SID0_V1_CTRL || SID0 V1 Control (8-bits)
|-
| $AF:E405 || || SID0_V1_ATCK_DECY || SID0 V1 Attack/Decay (8-bits)
|-
| $AF:E406 || || SID0_V1_SSTN_RLSE || SID0 V1 Sustain/Release (8-bits)
|-
| $AF:E407 || $AF:E408 || SID0_V2_FREQ || SID0 V2 Frequency (16-bits)
|-
| $AF:E409 || $AF:E40A || SID0_V2_PW || SID0 V2 Pulse Width (12-bits)
|-
| $AF:E40B || || SID0_V2_CTRL || SID0 V2 Control (8-bits)
|-
| $AF:E40C || || SID0_V2_ATCK_DECY || SID0 V2 Attack/Decay (8-bits)
|-
| $AF:E40D || || SID0_V2_SSTN_RLSE || SID0 V2 Sustain/Release (8-bits)
|-
| $AF:E40E || $AF:E40F || SID0_V3_FREQ || SID0 V3 Frequency (16-bits)
|-
| $AF:E410 || $AF:E411 || SID0_V3_PW || SID0 V3 Pulse Width (12-bits)
|-
| $AF:E412 || || SID0_V3_CTRL || SID0 V3 Control (8-bits)
|-
| $AF:E413 || || SID0_V3_ATCK_DECY || SID0 V3 Attack/Decay (8-bits)
|-
| $AF:E414 || || SID0_V3_SSTN_RLSE || SID0 V3 Sustain/Release (8-bits)
|-
| $AF:E415 || || SID0_FC_LO || SID0 Filter Frequency LOW (3 bits)
|-
| $AF:E416 || || SID0_FC_HI || SID0 Filter Frequency HIGH (8 bits)
|-
| $AF:E417 || || SID0_RES_FILT || SID0 Resonance / Filter (8-bits)
|-
| $AF:E418 || || SID0_MODE_VOL || SID0 Mode / Volume (8-bits)
|-
| $AF:E419 || || SID0_POT_X || SID0 POT X (Read only, C256 - NOT USED)
|-
| $AF:E41A || || SID0_POT_Y || SID0 POT Y (Read only, C256 - NOT USED)
|-
| $AF:E41B || || SID0_OSC3_RND || SID0 OSC3 / RANDOM (Read only, 8-bits)
|-
| $AF:E41C || || SID0_ENV3 || SID0 ENV3 (Read only, 8-bits)
|}

=== GABE Trinity Joystick/Gamepad and DIP Switch Registers ($AF:E800 – $AF:E80E) ===

GABE provides access to the Trinity chip, which provides access to the joystick ports and the DIP switches.
The joystick ports can be used in two modes: default mode, where they work like Atari style joysticks, and NES mode
where they can interface with either NES or SNES game pads.

[[File:Joystick Ports.jpg|800px|FMX Joystick Ports Configuration]]

{| class="wikitable"
|-
! Address !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:E800 || JOYSTICK0 || BUTTON2 || BUTTON1 || 0 || BUTTON0 || RIGHT || LEFT || DOWN || UP || Left-most joystick port
|-
| $AF:E801 || JOYSTICK1 || BUTTON2 || BUTTON1 || 0 || BUTTON0 || RIGHT || LEFT || DOWN || UP || Next to joystick port 0
|-
| $AF:E802 || JOYSTICK2 || 0 || 0 || 0 || BUTTON0 || RIGHT || LEFT || DOWN || UP || Next to joystick port 1
|-
| $AF:E803 || JOYSTICK3 || 0 || 0 || 0 || BUTTON0 || RIGHT || LEFT || DOWN || UP || Right-most joystick port
|-
| $AF:E804 || JOYSTICK_MODE || NES_TRIG || 0 || 0 || 0 || NES_DONE || NES_JOY || NES_EN1 || NES_EN0 || Control SNES compatibility
|-
| $AF:E805 || REVOFPCB_C ||colspan="8"| "C" || Board identification code byte (expect "C")
|-
| $AF:E806 || REVOFPCB_4 ||colspan="8"| "4" || Board identification code byte (expect "4")
|-
| $AF:E807 || REVOFPCB_A ||colspan="8"| "A" || Board identification code byte (expect "A")
|-
| $AF:E808 || NES_SNES0_DAT_LO ||colspan="8"| see below || Port 0: NES or SNES gamepad data (low byte)
|-
| $AF:E809 || SNES0_DAT_HI ||colspan="8"| see below|| Port 0: NES or SNES gamepad data (highbyte)
|-
| $AF:E80A || NES_SNES1_DAT_LO ||colspan="8"| see below || Port 1: NES or SNES gamepad data (low byte)
|-
| $AF:E80B || SNES1_DAT_HI ||colspan="8"| see below || Port 1: NES or SNES gamepad data (highbyte)
|-
| $AF:E80C || CFP9301_REV ||colspan="8"| revision || Trinity revision code
|-
| $AF:E80D || DIP_USER ||colspan="8"| user || Switches 3 through 5. User defined meaning.
|-
| $AF:E80E || DIP_BOOTMODE || HD_INSTALLED || 0 || 0 || 0 || 0 || 0 || BM1 || BM0 || Boot control switches.
|}

{| class="wikitable"
|+ SNES mode
|-
! Address !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:E808 || NES_SNES0_DAT_LO || B || Y || SELECT || START || UP || DOWN || LEFT || RIGHT || NES data if NES_JOY = 1 and NES_EN0 = 1
|-
| $AF:E809 || SNES0_DAT_HI || 0 || 0 || 0 || 0 || A || X || L || R || NES data if NES_JOY = 1 and NES_EN0 = 1)
|-
| $AF:E80A || NES_SNES1_DAT_LO || B || Y || SELECT || START || UP || DOWN || LEFT || RIGHT || NES data if NES_JOY = 1 and NES_EN1 = 1
|-
| $AF:E80B || SNES1_DAT_HI || 0 || 0 || 0 || 0 || A || X || L || R || NES data if NES_JOY = 1 and NES_EN1 = 1
|}

{| class="wikitable"
|+ NES mode
|-
! Address !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:E808 || NES_SNES0_DAT_LO || A || B || SELECT || START || UP || DOWN || LEFT || RIGHT || NES data if NES_JOY = 0 and NES_EN0 = 1
|-
| $AF:E809 || SNES0_DAT_HI ||colspan="2"| N/A || Unused if NES_EN0 = 0
|-
| $AF:E80A || NES_SNES1_DAT_LO || A || B || SELECT || START || UP || DOWN || LEFT || RIGHT || NES data if NES_JOY = 0 and NES_EN1 = 1
|-
| $AF:E80B || SNES1_DAT_HI ||colspan="2"| N/A || Unused in NES mode
|}

==== NES Control Bits ====

;NES_TRIG
:Set to one to trigger the serializer to read the gamepad.

;NES_DONE
:Poll to see if the serializer has finished reading the gamepad.

;NES_JOY
:If 1, sets SNES compatibility. If 0, sets NES compatibility.

;NES_EN1
:If 1, enables NES/SNES compatibility on port 1. If 0, joysticks work like Atari joysticks

;NES_EN0
:If 1, enables NES/SNES compatibility on port 0. If 0, joysticks work like Atari joysticks

==== Boot Mode ====

Switches 0 and 1 allow you to select the boot mode for the FMX. Note that the switches are active low:
a switch in the "On" position registers as a 0.

{| class="wikitable"
|-
! BM1 || BM0 !! Boot Mode
|-
| 0 || 0 || Boots from the IDE drive DIP switch 8 must be set (HD_INSTALLED).
|-
| 0 || 1 || Boots from the SD card
|-
| 1 || 0 || Boots from the floppy drive
|-
| 1 || 1 || Boots to BASIC
|}

=== GABE IDE Registers ($AF:E830 – $AF:E839) ===

GABE provides an IDE interface to a hard drive (if installed). This is done through the Unity chip and uses standard IDE interface command, error, and status codes.

{| class="wikitable"
! Address !! R/W !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:E830 || x || IDE_DATA || D7 || D6 || D5 || D4 || D3 || D2 || D1 || D0 || 8-bit data read/write
|-
| $AF:E831 || R || IDE_ERROR || BBK || UNC || MC || IDNF || MCR || ABRT || TK0NF || AMNF || Error code for the transaction
|-
| $AF:E832 || W || IDE_SECT_CNT || SC7 || SC6 || SC5 || SC4 || SC3 || SC2 || SC1 || SC0 || Sector count
|-
| $AF:E833 || W || IDE_SECT_SRT || SS7 || SS6 || SS5 || SS4 || SS3 || SS2 || SS1 || SS0 || Sector start (0 = 256), start at 1
|-
| $AF:E834 || W || IDE_CLDR_LO || C7 || C6 || C5 || C4 || C3 || C2 || C1 || C0 || Cylinder Number (low)
|-
| $AF:E835 || W || IDE_CLDR_HI || C15 || C14 || C13 || C12 || C11 || C10 || C9 || C8 || Cylinder Number (high)
|-
| $AF:E836 || W || IDE_HEAD || 1 || 0 || 1 || M/S || H3 || H2 || H1 || H0 || Head number and Master (0) / Slave(1) device
|-
| $AF:E837 || W || IDE_CMD_STAT || CMD7 || CMD6 || CMD5 || CMD4 || CMD3 || CMD2 || CMD1 || CMD0 || Send a command to the drive
|-
| $AF:E837 || R || IDE_CMD_STAT || BSY || DRDY || DF || DSC || DRQ || CORR || IDX || ERR || Get the status of device. Reading this will clear the Interrupt Registers
|-
| $AF:E838 || X || IDE_DATA_LO || D7 || D6 || D5 || D4 || D3 || D2 || D1 || D0 || 16-bit data transfer registers (low byte)
|-
| $AF:E839 || X || IDE_DATA_HI || D15 || D14 || D13 || D12 || D11 || D10 || D9 || D8 || 16-bit data transfer registers (high byte)
|}

==== GABE IDE Status Flags ====

;BSY
:Device is busy if set

;DRDY
:Device is ready for a command if set

;DF
:Device fault

;DSC
:Device seek complete. If set, the head has stopped moving and is over a track.

;DRQ
:Device is ready to transfer a data byte (either read or write) if set.

;CORR
:If set, indicates that data was corrected automatically.

;IDX
:A vendor specific status

;ERR
:If set, an error occurred with additional data in the error register.

==== GABE IDE Error Flags ====

;BBK
:Bad block

;UNC
:Uncorrectable data error

;MC
:Media changed

;IDNF
:ID mark not found

;MCR
:Media change requested

;ABRT
:Command aborted

;TK0NF
:Track 0 not found

;AMNF
:Address mark not found

=== GABE Control Registers ($AF:E880 – $AF:E887) ===

{| class="wikitable"
|-
!Start Address
!Ending Address
!Register Description
!Additional Info
|-
|$AF:E880 || || GABE_MSTR_CTRL
|-
|$AF:E881 || || Reserved
|-
|$AF:E882 || || GABE_RST_AUTH0 || Must Contain the BYTE $AD for Reset to Activate
|-
|$AF:E883 || || GABE_RST_AUTH1 || Must Contain the BYTE $DE for Reset to Activate
|-
|$AF:E884 || $AF:E885 || GABE_RNG_DATASEED || On read: 16-bit random data. On write, set 16-bit RNG seed.
|-
|$AF:E886 || || GABE_RNG_STATCTRL || On read: 8-bit status. On write: 8-bit control
|-
|$AF:E887 || || GABE_SYS_STAT || 8-bit system status
|}

==== GABE Master Control Register ($AF:E880) ====

{| class="wikitable"
|-
!7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
|GABE_CTRL_WRM_RST || || || GABE_CTRL_BUZZER || || || GABE_CTRL_SDC_LED || GABE_CTRL_PWR_LED
|}

; GABE_CTRL_PWR_LED
: Turns the power LED (next to the reset button) on or off.

; GABE_CTRL_SDC_LED
: Turns the SDC activity LED (next to the SDC slot) on or off.

; GABE_CTRL_BUZZER
: Turns the built-in piezo buzzer on or off.

; GABE_CTRL_WRM_RST
: Triggers a warm reset of the board (GABE_RST_AUTH0 must be set to $AD and GABE_RST_AUTH1 to $DE in order to trigger the reset).

==== GABE Random Number Generator Status and Control ($AF:E886) ====

{| class="wikitable"
|-
! R/W !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| R || GABE_RNG_LFSR_DONE || || || || || || ||
|-
| W || || || || || || || GABE_RNG_CTRL_DV || GABE_RNG_CTRL_EN
|}

; GABE_RNG_LFSR_DONE
: Indicates that output = seed database.

; GABE_RNG_CTRL_DV
: After setting the seed value, toggle this bit for the seed be registered.

; GABE_RNG_CTRL_EN
: Enable the LFSR block.

==== GABE System Status Register ($AF:E887) ====

{| class="wikitable"
|-
!7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| GABE_SYS_STAT_CPUX || GABE_SYS_STAT_CPUA || || || GABE_SYS_STAT_EXP || || GABE_SYS_STAT_MID1 || GABE_SYS_STAT_MID0
|}

; GABE_SYS_STAT_CPUX
: Indicates if the CPU's index registers are 8-bits or 16-bits wide.
; GABE_SYS_STAT_CPUA
: Indicates if the CPU's accumulator is 8-bits or 16-bits wide.
; GABE_SYS_STAT_EXP
: Indicates if the and expansion card is present (0).
; GABE_SYS_STAT_MID1 and GABE_SYS_STAT_MID0
: These two bits show the machine ID:

{| class="wikitable"
|-
!GABE_SYS_STAT_MID1 !! GABE_SYS_STAT_MID0 !! Machine
|-
| 0 || 0 || FMX - Development Platform
|-
| 0 || 1 || C256 Foenix - Dev Platform
|-
| 1 || 0 || C256 Foenix - User Version (65C816)
|-
| 1 || 1 || Reserved
|}

=== GABE SDC Interface ($AF:EA00) ===

GABE provides block-level access to the SPI interface of the SD card. Currently, there are other registers in that provide access to the SD card through a CH376S chip, but that interface should be considered deprecated in favor of this interface. Most FMX boards do not have the CH376S chip, leaving its position unpopulated on the board.

{| class="wikitable"
! Address !! R/W !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:EA00 || R || SDC_VERSION_REG || colspan="8"|version || Should read 12
|-
| $AF:EA01 || W || SDC_CONTROL_REG || x || x || x || x || x || x || x || RESET || Control register: RESET = 1 resets the core logic. Self clearing.
|-
| $AF:EA02 || W || SDC_TRANS_TYPE_REG ||x || x || x || x || x || x || colspan="2"|TRANS || Sets the type of transaction: 0 = Direct, 1 = INIT SD, 2 = Read Block, 3 = Write block
|-
| $AF:EA03 || W || SDC_TRANS_CONTROL_REG || x || x || x || x || x || x || x || START || Start transaction bit.
|-
| $AF:EA04 || R || SDC_TRANS_STATUS_REG || x || x || x || x || x || x || x || BUSY || Status of the transaction. BUSY = 1 indicates a transaction is in progress.
|-
| $AF:EA05 || R || SDC_TRANS_ERROR_REG || x || x || colspan="2"|WR_ERR || colspan="2"|RD_ERR || colspan="2"|TRANS_ERR || Error conditions for read, write, and transaction.
|-
| $AF:EA06 || RW || SDC_DIRECT_ACCESS_REG || colspan="8"|data || SPI Direct Read and Write - Set DATA before initiating direct Access Transaction
|-
| $AF:EA07 || W || SDC_SD_ADDR_7_0_REG || A7 || A6 || A5 || A4 || A3 || A2 || A1 || A0 || Set the ADDR before a block read or block write.
|-
| $AF:EA08 || W || SDC_SD_ADDR_15_8_REG || A15 || A14 || A13 || A12 || A11 || A10 || A9 || A8 || ADDR[8:0] always should be 0, since each block is 512 bytes
|-
| $AF:EA09 || W || SDC_SD_ADDR_23_16_REG || A23 || A22 || A21 || A20 || A19 || A18 || A7 || A6
|-
| $AF:EA0A || W || SDC_SD_ADDR_31_24_REG || A32 || A31 || A30 || A29 || A28 || A26 || A25 || A24
|-
| $AF:EA0B || W || SDC_SPI_CLK_DEL_REG || colspan="8"|clock delay
|-
| $AF:EA10 || R || SDC_RX_FIFO_DATA_REG || colspan="8"|data || Data from block read
|-
| $AF:EA12 || R || SDC_RX_FIFO_DATA_CNT_HI || CNT15 || CNT14 || CNT13 || CNT12 || CNT11 || CNT10 || CNT9 || CNT8 || How many bytes in the read FIFO (HI)
|-
| $AF:EA13 || R || SDC_RX_FIFO_DATA_CNT_LO || CNT7 || CNT6 || CNT5 || CNT4 || CNT3 || CNT2 || CNT1 || CNT0 || How many bytes in the read FIFO (LOW)
|-
| $AF:EA14 || W || SDC_RX_FIFO_CTRL_REG || x || x || x || x || x || x || x || CLEAR || CLEAR = 1, clear the read FIFO. Bit is self-clearing.
|-
| $AF:EA20 || W || SDC_TX_FIFO_DATA_REG || colspan="8"|data || Write data block here.
|-
| $AF:EA21 || W || SDC_TX_FIFO_CTRL_REG || x || x || x || x || x || x || x || CLEAR || CLEAR = 1, clear the write FIFO. Bit is self-clearing.
|}

==== GABE: SDC_TRANS_ERROR_REG ($AF:EA05) ====

Lists any error conditions on reads, writes, or general transactions:

{| class="wikitable"
|+ TRANS_ERR codes [1:0]
! Code !! Condition
|-
| 00 || No INIT error
|-
| 01 || INIT CMD0 error
|-
| 10 || INIT CMD1 error
|}

{| class="wikitable"
|+ RD_ERR codes [3:2]
! Code !! Condition
|-
| 00 || No read error
|-
| 01 || CMD error
|-
| 10 || Token error
|}

{| class="wikitable"
|+ WR_ERR codes [5:4]
! Code !! Condition
|-
| 00 || No write error
|-
| 01 || CMD error
|-
| 10 || Data error
|-
| 11 || Busy error
|}

=== GABE SN76489 Interface ($AF:F100) ===

GABE provides the interface to the SN76489 sound chip on the Foenix FMX. This chip uses only a single write-only address: $AF:F100. The SN76489 has four voices: three tone generators, and one noise generator. Each voice has a frequency and an attenuation setting. For full details on how to use the SN76489 chip, please consult the official documentation, but here is a brief summary.

==== Playing a Tone ====

To change the frequency of a tone generator, two bytes are sent to the chip in order:

{| class="wikitable"
|-
! !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| First || 1 ||colspan="2"| Channel || 0 || F3 || F2 || F1 || F0
|-
| Second || 0 || x || F9 || F8 || F7 || F6 || F5 || F4
|}

The actual frequency played depends on the clock driving the chip: freq = N / (32 * F), where N = 3575800 (for the FMX), and F is the 10-bit number sent to the chip. The "Channel" number above must be 0, 1, or 3.

==== Play a Noise ====

To play a noise, only a single byte is written to the chip:

{| class="wikitable"
|-
! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| 1 || 1 || 1 || 0 || x || NF|| NF1 || NF0
|}

The NF bit controls the type of noise generated, and the NF bits control the base frequency of the noise.

==== Setting the Volume ====

The volumes of each of the four voices can be set independently. To set the volume of a single voice, a single byte is sent to the chip:

{| class="wikitable"
|-
! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| 1 ||colspan="2"| Channel || 1 || A3 || A2 || A1 || A0
|}

The "Channel" bits are the number of the voice to change: 0, 1, 2, or 3. The four bit value A is the level of attenuation, where 0 is fully on, and 15 is fully off.

GABE

2021-08-02T15:12:51Z

PJW: /* GABE Control Registers ($AF:E880 – $AF:E887) */

== GABE -- The System Control, I/O, and Sound Chip ==

"GABE" is the name of the system controller chip of the C256 Foenix RevC board, and performs several functions including system bus management, math coprocessing, I/O, and sound.
The RevB version of the C256 had two chips "Gavin" and "Beatrix" that were combined into a single master chip called "GABE".

GABE has several key functions:
* System start up
* Debug interface control and bus mastering
* I/O interfacing
* Math coprocessor
* Sound chip interfacing and emulation

=== GABE System Startup Process ===

When the C256 Foenix powers up, GABE takes control and coordinates the startup process.
It first copies the flash data out of flash and into system RAM, starting at bank $38 on the FMX ($18 on the RevB).
GABE also copies the first bank of flash data down to bank $00 of system RAM
before control is given to the CPU and the CPU's RESET is triggered.
This process ensures that the kernel, hardware vectors, and interrupt handlers are all in place prior to the CPU
taking control and resetting the first time on power up.

The mapping of flash memory locations to system RAM is thus:

{| class="wikitable"
|-
!Flash Range !! RAM Range
|-
|$F8:0000...$FF:FFFF || $38:0000...$3F:FFFF
|-
|$F8:0000...$F8:FFFF || $00:0000...$00:FFFF
|}

=== GABE Integer Math Coprocessor ($00:0100 – $00:012B) ===

GABE provides an easy to use integer math coprocessor in the form of two 16-multipliers (one signed, one unsigned),
two 16-bit dividers (one signed, one unsigned), and a single 32-bit adder. Using the coprocessor is straight-forward:
the operands are written to the correct registers, and the result is read from the output registers. The operations
are all performed within a single CPU clock cycle, so no waiting is required.

{| class="wikitable"
|-
!Start Address
!End Address
!Register Name
!Additional Info
|-
| $00:0100 || $00:0101 || UNSIGNED_MULT_A || A operand for unsigned multiplication (16-bit)
|-
| $00:0102 || $00:0103 || UNSIGNED_MULT_B || B operand for unsigned multiplication (16-bit)
|-
| $00:0104 || $00:0107 || UNSIGNED_MULT_RESULT || Result for unsigned multiplication (32-bit)
|-
| $00:0108 || $00:0109 || SIGNED_MULT_A || A operand for signed multiplication (16-bit)
|-
| $00:010A || $00:010B || SIGNED_MULT_B || B operand for signed multiplication (16-bit)
|-
| $00:010C || $00:010F || SIGNED_MULT_RESULT || Result for signed multiplication (32-bit)
|-
| $00:0110 || $00:0111 || UNSIGNED_DIV_DEM || Denominator for unsigned division (16-bit)
|-
| $00:0112 || $00:0113 || UNSIGNED_DIV_NUM || Numerator for unsigned division (16-bit)
|-
| $00:0114 || $00:0115 || UNSIGNED_DIV_QUO || Quotient for unsigned division (16-bit)
|-
| $00:0116 || $00:0117 || UNSIGNED_DIV_REM || Remainder for unsigned division (16-bit)
|-
| $00:0118 || $00:0119 || SIGNED_DIV_DEM || Denominator for signed division (16-bit)
|-
| $00:011A || $00:011B || SIGNED_DIV_NUM || Numerator for signed division (16-bit)
|-
| $00:011C || $00:011D || SIGNED_DIV_QUO || Quotient for signed division (16-bit)
|-
| $00:011E || $00:011F || SIGNED_DIV_REM || Remainder for signed division (16-bit)
|-
| $00:0120 || $00:0123 || ADDER32_A || A operand for 32-bit addition (32-bits)
|-
| $00:0124 || $00:0127 || ADDER32_B || B operand for 32-bit addition (32-bits)
|-
| $00:0128 || $00:012B || ADDER32_R || Result of 32-bit addition (32-bits)
|}

=== GABE Keyboard Ports ===

{| class="wikitable"
|-
! Address !! R/W !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:1060 || X || KBD_DATA || D7 || D6 || D5 || D4 || D3 || D2 || D1 || D0 || Keyboard data port
|-
| $AF:1061 || X || PORTB || D7 || D6 || D5 || D4 || D3 || D2 || D1 || D0
|-
| $AF:1064 || R || KBD_STATUS || PAR_E || RX_TO || TX_TO || KBD_INH || CMD || SYS || IN_F || OUT_F || Keyboard Status
|-
| $AF:1064 || W || KBD_CMD || CMD7 || CMD6 || CMD5 || CMD4 || CMD3 || CMD2 || CMD1 || CMD0 || Keyboard Command
|}

==== GABE Keyboard Status Flags ====

;PAR_E
:Parity error

;RX_TO
:Time out reading data

;TX_TO
:Time out transmitting data

;CMD
:If 0, then data written to input buffer is data for PS/2 device. If 1, then data written to input buffer is data for PS/2 controller command

;SYS
:Flag to the firmware that the keyboard has past POST

;IN_F
:Input buffer is full

;OUT_F
:Output buffer is full

=== GABE Floating Point Math Coprocessor ($AF:E200 – AFE20F) ===

GABE provides a floating point math coprocessor, providing addition, subtraction, multiplication, and division for 32-bit floating point numbers.
Additionally, the coprocessor allows for conversion between a fixed point format and 32-bit IEEE 754 floating point format.
The floating point coprocessor is a little more complex than the integer coprocessor, with each math unit having input multiplexers that control
where the inputs come from, and with the output registers having their own multiplexer. Finally, the output of the multiplier and divider units
can be used directly as inputs to the adder/subtracter.

[[File:FMX Floating Point.jpg|800px|FMX Floating Point Math Coprocessor]]

{| class="wikitable"
|-
! Start Address !! End Address !! Register Name !! Additional Information
|-
| $AF:E200 || || FP_MATH_CTRL0 || Controls input multiplexers, Adder function, and Adder multiplexers
|-
| $AF:E201 || || FP_MATH_CTRL1 || Controls output multiplexers
|-
| $AF:E202 || || FP_MATH_CTRL2 || Unused: reserved
|-
| $AF:E203 || || FP_MATH_CTRL3 || Unused: reserved
|-
| $AF:E204 || || FP_MATH_MULT_STAT || Status of the multiplier
|-
| $AF:E205 || || FP_MATH_DIV_STAT || Status of the divider
|-
| $AF:E206 || || FP_MATH_ADD_STAT || Status of the adder/subtracter
|-
| $AF:E207 || || FP_MATH_CONV_STAT || Status of the converters
|-
| $AF:E208 || $AF:E20B || FP_MATH_INPUT0 || Input 0 (write only)
|-
| $AF:E20C || $AF:E20F || FP_MATH_INPUT1 || Input 1 (write only)
|-
| $AF:E208 || $AF:E20B || FP_MATH_OUTPUT_FP || Result in IEEE 754 format (read only)
|-
| $AF:E20C || $AF:E20F || FP_MATH_OUTPUT_FIXED || Result in 20.12 fixed point format (read only)
|}

==== GABE Register FP_MATH_CTRL0 ($AF:E200) ====

{| class="wikitable"
|-
! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
|colspan="2"|FP_MATH_CTRL0_ADD_IN1_MUX ||colspan="2"|FP_MATH_CTRL0_ADD_IN0_MUX || FP_MATH_CTRL0_ADD_SUB || || FP_MATH_CTRL0_INPUT1_MUX || FP_MATH_CTRL0_INPUT0_MUX
|}

; FP_MATH_CTRL0_INPUT0_MUX
: If 0, Input0 is assumed to be in IEEE format. If 1, it is assumed to be in 20.12 fixed point format and will be converted to IEEE.

; FP_MATH_CTRL0_INPUT1_MUX
: If 0, Input1 is assumed to be in IEEE format. If 1, it is assumed to be in 20.12 fixed point format and will be converted to IEEE.

; FP_MATH_CTRL0_ADD_SUB
: If 0, the adder will perform a subtract operation. If 1, it will perform an addition.

; FP_MATH_CTRL0_ADD_IN0_MUX
: Selects the source for input 0 of the adder unit.

; FP_MATH_CTRL0_ADD_IN1_MUX
: Selects the source for input 1 of the adder unit.

{| class="wikitable"
|+ Adder Source Selector Codes
|-
! Control Bits !! Input
|-
| 00 || Input 0
|-
| 01 || Input 1
|-
| 10 || Output of the multiplier
|-
| 11 || Output of the divider
|}

==== GABE Register FP_MATH_CTRL1 ($AF:E201) ====

{| class="wikitable"
|-
! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
|colspan="6"| ||colspan="2"| FP_MATH_CTRL1_OUTPUT_MUX0
|}

; FP_MATH_CTRL1_OUTPUT_MUX0
: Selects which functional block provides the output result:

{| class="wikitable"
|+ Result Source Selector Codes
|-
! Control Bits !! Output Source
|-
| 00 || Result of multiplier is the routed to the output registers
|-
| 01 || Result of divider is the routed to the output registers
|-
| 10 || Result of adder is the routed to the output registers
|-
| 11 || 1.0 is routed to the output registers
|}

==== GABE Registers: FP Status Registers ($AF:E204 – $AF:E207) ====

These registers contain the status flags for the various functional units. The status flags are all roughly similar across the four units:

{| class="wikitable"
|+ Status Codes
|-
! Code !! Meaning
|-
| $01 || Result was not a number (NAN)
|-
| $02 || Overflow
|-
| $04 || Underflow
|-
| $08 || Result was 0.0
|-
| $10 || Division by 0.0 was attempted
|}

=== GABE Timer Registers ($00:0160 – $00:017F) ===

* Timer0 and Timer1 count system clock transitions (14318180Hz)
* Timer2 is clocked from VICKY's Start-of-Frame output (50hz).
* To create interrupts at a set interval for timer 0 and 1 divide the clock frequency by the desired interval. So if one wishes 4 interrupts every second use 14318180 divided by 4.

{| class="wikitable"
|-
!Start Address
!End Address
!Register Name
!Additional Info
|-
!colspan="4" style="text-align:left;" | Timer 0
|-
| $00:0160 || || TIMER0_CTRL_REG || Timer 0 control register
|-
| $00:0161 || || TIMER0_CHARGE_L || Timer 0 precharge register lower byte, loaded when counting down
|-
| $00:0162 || || TIMER0_CHARGE_M || Timer 0 precharge register middle byte, loaded when counting down
|-
| $00:0163 || || TIMER0_CHARGE_H || Timer 0 precharge register high byte, loaded when counting down
|-
| $00:0164 || || TIMER0_CMP_REG || Timer 0 compare register
|-
| $00:0165 || || TIMER0_CMP_L || Timer 0 compare register lower byte, loaded when counting up
|-
| $00:0166 || || TIMER0_CMP_M || Timer 0 compare register middle byte, loaded when counting up
|-
| $00:0167 || || TIMER0_CMP_H || Timer 0 compare register high byte, loaded when counting up
|-
!colspan="4" style="text-align:left;" | Timer 1
|-
| $00:0168 || || TIMER1_CTRL_REG || Timer 1 control register
|-
| $00:0169 || || TIMER1_CHARGE_L || Timer 1 precharge register lower byte, loaded when counting down
|-
| $00:016A || || TIMER1_CHARGE_M || Timer 1 precharge register middle byte, loaded when counting down
|-
| $00:016B || || TIMER1_CHARGE_H || Timer 1 precharge register high byte, loaded when counting down
|-
| $00:016C || || TIMER1_CMP_REG || Timer 1 compare register
|-
| $00:016D || || TIMER1_CMP_L || Timer 1 compare register lower byte, loaded when counting up
|-
| $00:016E || || TIMER1_CMP_M || Timer 1 compare register middle byte, loaded when counting up
|-
| $00:016F || || TIMER1_CMP_H || Timer 1 compare register high byte, loaded when counting up
|-
!colspan="4" style="text-align:left;" | Timer 2
|-
| $00:0170 || || TIMER2_CTRL_REG || Timer 2 control register
|-
| $00:0171 || || TIMER2_CHARGE_L || Timer 2 precharge register lower byte, loaded when counting down
|-
| $00:0172 || || TIMER2_CHARGE_M || Timer 2 precharge register middle byte, loaded when counting down
|-
| $00:0173 || || TIMER2_CHARGE_H || Timer 2 precharge register high byte, loaded when counting down
|-
| $00:0174 || || TIMER2_CMP_REG || Timer 2 compare register
|-
| $00:0175 || || TIMER2_CMP_L || Timer 2 compare register lower byte, loaded when counting up
|-
| $00:0176 || || TIMER2_CMP_M || Timer 2 compare register middle byte, loaded when counting up
|-
| $00:0177 || || TIMER2_CMP_H || Timer 2 compare register high byte, loaded when counting up
|-
|}

{| class="wikitable"
|-
!Register
!Value
!Name
!Additional Info
|-
| TIMER<X>_CTRL_REG || 0x01 || TMR_EN || Enabled the timer
|-
| TIMER<X>_CTRL_REG || 0x02 || TMR_SCLR || Set when counting up
|-
| TIMER<X>_CTRL_REG || 0x04 || TMR_SLOAD|| Set when counting down
|-
| TIMER<X>_CTRL_REG || 0x08 || TMR_UPDWN|| Set when counting up (1 = Up, 0 = Down)
|-
| TIMER<X>_CMP_REG || 0x01 || TMR_CMP_RECLR|| Set to one for it to cycle when Counting up
|-
| TIMER<X>_CMP_REG || 0x02 || TMR_CMP_RELOAD|| Set to one for it to reload when Counting Down
|-
|}

==== C pseudo code for counting up ====
TIMER1_CHARGE_L = 0x00; 
TIMER1_CHARGE_M = 0x00; 
TIMER1_CHARGE_H = 0x00; 
TIMER1_CMP_L = clockValue & 0xFF; 
TIMER1_CMP_M = (clockValue >> 8) & 0xFF; 
TIMER1_CMP_H = (clockValue >> 16) & 0xFF; 
 
TIMER1_CMP_REG = TMR_CMP_RECLR; 
TIMER1_CTRL_REG = TMR_EN | TMR_UPDWN | TMR_SCLR; 

==== C pseudo code for counting down ====
TIMER1_CHARGE_L = (clockValue >> 0) & 0xFF; 
TIMER1_CHARGE_M = (clockValue >> 8) & 0xFF; 
TIMER1_CHARGE_H = (clockValue >> 16) & 0xFF; 
TIMER1_CMP_L = 0x00; 
TIMER1_CMP_M = 0x00; 
TIMER1_CMP_H = 0x00; 
 
TIMER1_CMP_REG = TMR_CMP_RELOAD; 
TIMER1_CTRL_REG = TMR_EN | TMR_SLOAD; 
 

=== GABE Interrupt Control Registers ($00:0140 – $00:014B) ===

There are four types of interrupt control register that GABE provides: pending, polarity, edge detection, and mask.
Each interrupt that is supported has a bit position in each of the 24 or 32 bits provided by the register types.

; Pending
: The pending registers indicate if an interrupt of a particular type has been triggered and needs processing. An interrupt handler should also write to this register to clear the pending flag, once the interrupt has been processed.

; Polarity
: This register indicates if the interrupt is triggered by a high or low signal on the input to GABE.

; Edge
: This register indicates if the interrupt is triggered by an transition (edge) or by a high or low value.

; Mask
: This register indicates if the associated interrupt will trigger an IRQ to the processor. Interrupt signals with a mask bit of 0 will be ignored, while those with a mask bit of 1 will trigger an interrupt to the CPU.

{| class="wikitable"
|-
!Start
!Register Description
!Additional Info
|-
| $00:0140 || INT_PENDING_REG0 || Interrupt pending #0
|-
| $00:0141 || INT_PENDING_REG1 || Interrupt pending #1
|-
| $00:0142 || INT_PENDING_REG2 || Interrupt pending #2
|-
| $00:0143 || INT_PENDING_REG3 || Interrupt pending #3---FMX Model only
|-
| $00:0144 || INT_POL_REG0 || Interrupt polarity #0
|-
| $00:0145 || INT_POL_REG1 || Interrupt polarity #1
|-
| $00:0146 || INT_POL_REG2 || Interrupt polarity #2
|-
| $00:0147 || INT_POL_REG3 || Interrupt polarity #3---FMX Model only
|-
| $00:0148 || INT_EDGE_REG0 || Enable Edge Detection #0
|-
| $00:0149 || INT_EDGE_REG1 || Enable Edge Detection #1
|-
| $00:014A || INT_EDGE_REG2 || Enable Edge Detection #2
|-
| $00:014B || INT_EDGE_REG3 || Enable Edge Detection #3---FMX Model only
|-
| $00:0148 || INT_MASK_REG0 || Enable Interrupt #0
|-
| $00:0149 || INT_MASK_REG1 || Enable Interrupt #1
|-
| $00:014A || INT_MASK_REG2 || Enable Interrupt #2
|-
| $00:014B || INT_MASK_REG3 || Enable Interrupt #3---FMX Model only
|}

There are several interrupts the GABE can handle, distributed over four blocks:

{| class="wikitable"
|-
!Block !! Bit !! Name !! Function
|-
| 0 || $01 || FNX0_INT00_SOF || Start of Frame @60Hz
|-
| 0 || $02 || FNX0_INT01_SOL || Start of Line (programmable)
|-
| 0 || $04 || FNX0_INT02_TMR0 || Timer 0
|-
| 0 || $08 || FNX0_INT03_TMR1 || Timer 1
|-
| 0 || $10 || FNX0_INT04_TMR2 || Timer 2
|-
| 0 || $20 || FNX0_INT05_RTC || Real Time Clock
|-
| 0 || $40 || FNX0_INT06_FCC || Floppy Drive Controller
|-
| 0 || $80 || FNX0_INT07_MOUSE || Mouse Interrupt (INT12 in SuperIO IOspace)
|-
| 1 || $01 || FNX1_INT00_KBD || Keyboard Interrupt
|-
| 1 || $02 || FNX1_INT01_SC0 || VICKY_II (INT2) Sprite 2 Sprite Collision
|-
| 1 || $04 || FNX1_INT02_SC1 || VICKY_II (INT3) Sprite 2 Tiles Collision
|-
| 1 || $08 || FNX1_INT03_COM2 || Serial Port 2 (Internal)
|-
| 1 || $10 || FNX1_INT04_COM1 || Serial Port 1 (External)
|-
| 1 || $20 || FNX1_INT05_MPU401 || Midi Controller Interrupt
|-
| 1 || $40 || FNX1_INT06_LPT || Parallel Port
|-
| 1 || $80 || FNX1_INT07_SDCARD || SD Card Controller Interrupt (CH376S, if present)
|-
| 2 || $01 || FNX2_INT00_OPL3 || OPL3
|-
| 2 || $02 || FNX2_INT01_GABE_INT0 || GABE (INT0) - TBD
|-
| 2 || $04 || FNX2_INT02_GABE_INT1 || GABE (INT1) - TBD
|-
| 2 || $08 || FNX2_INT03_SDMA || VICKY_II (INT4)
|-
| 2 || $10 || FNX2_INT04_VDMA || VICKY_II (INT5) -- Vicky DMA completion
|-
| 2 || $20 || FNX2_INT05_GABE_INT2 || GABE (INT2) - TBD
|-
| 2 || $40 || FNX2_INT06_EXT || External Expansion
|-
| 2 || $80 || FNX2_INT07_SDCARD_INS || SDCARD Insertion
|-
| 3 || $01 || FNX3_INT00_OPN2 || OPN2
|-
| 3 || $02 || FNX3_INT01_OPM || OPM
|-
| 3 || $04 || FNX3_INT02_IDE || HDD IDE Interrupt
|-
| 3 || $08 || FNX3_INT03_TBD || TBD
|-
| 3 || $10 || FNX3_INT04_TBD || TBD
|-
| 3 || $20 || FNX3_INT05_TBD || TBD
|-
| 3 || $40 || FNX3_INT06_TBD || TBD
|-
| 3 || $80 || FNX3_INT07_TBD || TBD
|}

=== GABE SID Emulation ($AF:E400 – $AF:E41F) ===

GABE emulates the SID sound chip. Currently, the FMX provides one SID unit.
Although the real SID chip provides analog to digital conversion for two
potentiometer inputs for paddles, the C256's paddle inputs are provided through
a different chip, so the POT registers listed below are not useful.

For complete information on how to use these registers, please consult documentation
on the SID chips.

All registers are write-only, except where noted otherwise.

{| class="wikitable"
|-
! Start Address !! End Address !! Register Name !! Additional Information
|-
| $AF:E400 || $AF:E401 || SID0_V1_FREQ || SID0 V1 Frequency (16-bits)
|-
| $AF:E402 || $AF:E403 || SID0_V1_PW || SID0 V1 Pulse Width (12-bits)
|-
| $AF:E404 || || SID0_V1_CTRL || SID0 V1 Control (8-bits)
|-
| $AF:E405 || || SID0_V1_ATCK_DECY || SID0 V1 Attack/Decay (8-bits)
|-
| $AF:E406 || || SID0_V1_SSTN_RLSE || SID0 V1 Sustain/Release (8-bits)
|-
| $AF:E407 || $AF:E408 || SID0_V2_FREQ || SID0 V2 Frequency (16-bits)
|-
| $AF:E409 || $AF:E40A || SID0_V2_PW || SID0 V2 Pulse Width (12-bits)
|-
| $AF:E40B || || SID0_V2_CTRL || SID0 V2 Control (8-bits)
|-
| $AF:E40C || || SID0_V2_ATCK_DECY || SID0 V2 Attack/Decay (8-bits)
|-
| $AF:E40D || || SID0_V2_SSTN_RLSE || SID0 V2 Sustain/Release (8-bits)
|-
| $AF:E40E || $AF:E40F || SID0_V3_FREQ || SID0 V3 Frequency (16-bits)
|-
| $AF:E410 || $AF:E411 || SID0_V3_PW || SID0 V3 Pulse Width (12-bits)
|-
| $AF:E412 || || SID0_V3_CTRL || SID0 V3 Control (8-bits)
|-
| $AF:E413 || || SID0_V3_ATCK_DECY || SID0 V3 Attack/Decay (8-bits)
|-
| $AF:E414 || || SID0_V3_SSTN_RLSE || SID0 V3 Sustain/Release (8-bits)
|-
| $AF:E415 || || SID0_FC_LO || SID0 Filter Frequency LOW (3 bits)
|-
| $AF:E416 || || SID0_FC_HI || SID0 Filter Frequency HIGH (8 bits)
|-
| $AF:E417 || || SID0_RES_FILT || SID0 Resonance / Filter (8-bits)
|-
| $AF:E418 || || SID0_MODE_VOL || SID0 Mode / Volume (8-bits)
|-
| $AF:E419 || || SID0_POT_X || SID0 POT X (Read only, C256 - NOT USED)
|-
| $AF:E41A || || SID0_POT_Y || SID0 POT Y (Read only, C256 - NOT USED)
|-
| $AF:E41B || || SID0_OSC3_RND || SID0 OSC3 / RANDOM (Read only, 8-bits)
|-
| $AF:E41C || || SID0_ENV3 || SID0 ENV3 (Read only, 8-bits)
|}

=== GABE Trinity Joystick/Gamepad and DIP Switch Registers ($AF:E800 – $AF:E80E) ===

GABE provides access to the Trinity chip, which provides access to the joystick ports and the DIP switches.
The joystick ports can be used in two modes: default mode, where they work like Atari style joysticks, and NES mode
where they can interface with either NES or SNES game pads.

[[File:Joystick Ports.jpg|800px|FMX Joystick Ports Configuration]]

{| class="wikitable"
|-
! Address !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:E800 || JOYSTICK0 || BUTTON2 || BUTTON1 || 0 || BUTTON0 || RIGHT || LEFT || DOWN || UP || Left-most joystick port
|-
| $AF:E801 || JOYSTICK1 || BUTTON2 || BUTTON1 || 0 || BUTTON0 || RIGHT || LEFT || DOWN || UP || Next to joystick port 0
|-
| $AF:E802 || JOYSTICK2 || 0 || 0 || 0 || BUTTON0 || RIGHT || LEFT || DOWN || UP || Next to joystick port 1
|-
| $AF:E803 || JOYSTICK3 || 0 || 0 || 0 || BUTTON0 || RIGHT || LEFT || DOWN || UP || Right-most joystick port
|-
| $AF:E804 || JOYSTICK_MODE || NES_TRIG || 0 || 0 || 0 || NES_DONE || NES_JOY || NES_EN1 || NES_EN0 || Control SNES compatibility
|-
| $AF:E805 || REVOFPCB_C ||colspan="8"| "C" || Board identification code byte (expect "C")
|-
| $AF:E806 || REVOFPCB_4 ||colspan="8"| "4" || Board identification code byte (expect "4")
|-
| $AF:E807 || REVOFPCB_A ||colspan="8"| "A" || Board identification code byte (expect "A")
|-
| $AF:E808 || NES_SNES0_DAT_LO ||colspan="8"| see below || Port 0: NES or SNES gamepad data (low byte)
|-
| $AF:E809 || SNES0_DAT_HI ||colspan="8"| see below|| Port 0: NES or SNES gamepad data (highbyte)
|-
| $AF:E80A || NES_SNES1_DAT_LO ||colspan="8"| see below || Port 1: NES or SNES gamepad data (low byte)
|-
| $AF:E80B || SNES1_DAT_HI ||colspan="8"| see below || Port 1: NES or SNES gamepad data (highbyte)
|-
| $AF:E80C || CFP9301_REV ||colspan="8"| revision || Trinity revision code
|-
| $AF:E80D || DIP_USER ||colspan="8"| user || Switches 3 through 5. User defined meaning.
|-
| $AF:E80E || DIP_BOOTMODE || HD_INSTALLED || 0 || 0 || 0 || 0 || 0 || BM1 || BM0 || Boot control switches.
|}

{| class="wikitable"
|+ SNES mode
|-
! Address !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:E808 || NES_SNES0_DAT_LO || B || Y || SELECT || START || UP || DOWN || LEFT || RIGHT || NES data if NES_JOY = 1 and NES_EN0 = 1
|-
| $AF:E809 || SNES0_DAT_HI || 0 || 0 || 0 || 0 || A || X || L || R || NES data if NES_JOY = 1 and NES_EN0 = 1)
|-
| $AF:E80A || NES_SNES1_DAT_LO || B || Y || SELECT || START || UP || DOWN || LEFT || RIGHT || NES data if NES_JOY = 1 and NES_EN1 = 1
|-
| $AF:E80B || SNES1_DAT_HI || 0 || 0 || 0 || 0 || A || X || L || R || NES data if NES_JOY = 1 and NES_EN1 = 1
|}

{| class="wikitable"
|+ NES mode
|-
! Address !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:E808 || NES_SNES0_DAT_LO || A || B || SELECT || START || UP || DOWN || LEFT || RIGHT || NES data if NES_JOY = 0 and NES_EN0 = 1
|-
| $AF:E809 || SNES0_DAT_HI ||colspan="2"| N/A || Unused if NES_EN0 = 0
|-
| $AF:E80A || NES_SNES1_DAT_LO || A || B || SELECT || START || UP || DOWN || LEFT || RIGHT || NES data if NES_JOY = 0 and NES_EN1 = 1
|-
| $AF:E80B || SNES1_DAT_HI ||colspan="2"| N/A || Unused in NES mode
|}

==== NES Control Bits ====

;NES_TRIG
:Set to one to trigger the serializer to read the gamepad.

;NES_DONE
:Poll to see if the serializer has finished reading the gamepad.

;NES_JOY
:If 1, sets SNES compatibility. If 0, sets NES compatibility.

;NES_EN1
:If 1, enables NES/SNES compatibility on port 1. If 0, joysticks work like Atari joysticks

;NES_EN0
:If 1, enables NES/SNES compatibility on port 0. If 0, joysticks work like Atari joysticks

==== Boot Mode ====

Switches 0 and 1 allow you to select the boot mode for the FMX. Note that the switches are active low:
a switch in the "On" position registers as a 0.

{| class="wikitable"
|-
! BM1 || BM0 !! Boot Mode
|-
| 0 || 0 || Boots from the IDE drive DIP switch 8 must be set (HD_INSTALLED).
|-
| 0 || 1 || Boots from the SD card
|-
| 1 || 0 || Boots from the floppy drive
|-
| 1 || 1 || Boots to BASIC
|}

=== GABE IDE Registers ($AF:E830 – $AF:E839) ===

GABE provides an IDE interface to a hard drive (if installed). This is done through the Unity chip and uses standard IDE interface command, error, and status codes.

{| class="wikitable"
! Address !! R/W !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:E830 || x || IDE_DATA || D7 || D6 || D5 || D4 || D3 || D2 || D1 || D0 || 8-bit data read/write
|-
| $AF:E831 || R || IDE_ERROR || BBK || UNC || MC || IDNF || MCR || ABRT || TK0NF || AMNF || Error code for the transaction
|-
| $AF:E832 || W || IDE_SECT_CNT || SC7 || SC6 || SC5 || SC4 || SC3 || SC2 || SC1 || SC0 || Sector count
|-
| $AF:E833 || W || IDE_SECT_SRT || SS7 || SS6 || SS5 || SS4 || SS3 || SS2 || SS1 || SS0 || Sector start (0 = 256), start at 1
|-
| $AF:E834 || W || IDE_CLDR_LO || C7 || C6 || C5 || C4 || C3 || C2 || C1 || C0 || Cylinder Number (low)
|-
| $AF:E835 || W || IDE_CLDR_HI || C15 || C14 || C13 || C12 || C11 || C10 || C9 || C8 || Cylinder Number (high)
|-
| $AF:E836 || W || IDE_HEAD || 1 || 0 || 1 || M/S || H3 || H2 || H1 || H0 || Head number and Master (0) / Slave(1) device
|-
| $AF:E837 || W || IDE_CMD_STAT || CMD7 || CMD6 || CMD5 || CMD4 || CMD3 || CMD2 || CMD1 || CMD0 || Send a command to the drive
|-
| $AF:E837 || R || IDE_CMD_STAT || BSY || DRDY || DF || DSC || DRQ || CORR || IDX || ERR || Get the status of device. Reading this will clear the Interrupt Registers
|-
| $AF:E838 || X || IDE_DATA_LO || D7 || D6 || D5 || D4 || D3 || D2 || D1 || D0 || 16-bit data transfer registers (low byte)
|-
| $AF:E839 || X || IDE_DATA_HI || D15 || D14 || D13 || D12 || D11 || D10 || D9 || D8 || 16-bit data transfer registers (high byte)
|}

==== GABE IDE Status Flags ====

;BSY
:Device is busy if set

;DRDY
:Device is ready for a command if set

;DF
:Device fault

;DSC
:Device seek complete. If set, the head has stopped moving and is over a track.

;DRQ
:Device is ready to transfer a data byte (either read or write) if set.

;CORR
:If set, indicates that data was corrected automatically.

;IDX
:A vendor specific status

;ERR
:If set, an error occurred with additional data in the error register.

==== GABE IDE Error Flags ====

;BBK
:Bad block

;UNC
:Uncorrectable data error

;MC
:Media changed

;IDNF
:ID mark not found

;MCR
:Media change requested

;ABRT
:Command aborted

;TK0NF
:Track 0 not found

;AMNF
:Address mark not found

=== GABE Control Registers ($AF:E880 – $AF:E887) ===

{| class="wikitable"
|-
!Start Address
!Ending Address
!Register Description
!Additional Info
|-
|$AF:E880 || || GABE_MSTR_CTRL
|-
|$AF:E881 || || Reserved
|-
|$AF:E882 || || GABE_RST_AUTH0 || Must Contain the BYTE $AD for Reset to Activate
|-
|$AF:E883 || || GABE_RST_AUTH1 || Must Contain the BYTE $DE for Reset to Activate
|-
|$AF:E884 || $AF:E885 || GABE_RNG_DATASEED || On read: 16-bit random data. On write, set 16-bit RNG seed.
|-
|$AF:E886 || || GABE_RNG_STATCTRL || On read: 8-bit status. On write: 8-bit control
|-
|$AF:E887 || || GABE_SYS_STAT || 8-bit system status
|}

==== GABE Master Control Register ($AF:E880) ====

{| class="wikitable"
|-
!7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
|GABE_CTRL_WRM_RST || || || GABE_CTRL_BUZZER || || || GABE_CTRL_SDC_LED || GABE_CTRL_PWR_LED
|}

; GABE_CTRL_PWR_LED
: Turns the power LED (next to the reset button) on or off.

; GABE_CTRL_SDC_LED
: Turns the SDC activity LED (next to the SDC slot) on or off.

; GABE_CTRL_BUZZER
: Turns the built-in piezo buzzer on or off.

; GABE_CTRL_WRM_RST
: Triggers a warm reset of the board (GABE_RST_AUTH0 must be set to $AD and GABE_RST_AUTH1 to $DE in order to trigger the reset).

==== GABE Random Number Generator Status and Control ($AF:E886) ====

==== GABE System Status Register ($AF:E887) ====

{| class="wikitable"
|-
!7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| GABE_SYS_STAT_CPUX || GABE_SYS_STAT_CPUA || || || GABE_SYS_STAT_EXP || || GABE_SYS_STAT_MID1 || GABE_SYS_STAT_MID0
|}

; GABE_SYS_STAT_CPUX
: Indicates if the CPU's index registers are 8-bits or 16-bits wide.
; GABE_SYS_STAT_CPUA
: Indicates if the CPU's accumulator is 8-bits or 16-bits wide.
; GABE_SYS_STAT_EXP
: Indicates if the and expansion card is present (0).
; GABE_SYS_STAT_MID1 and GABE_SYS_STAT_MID0
: These two bits show the machine ID:

{| class="wikitable"
|-
!GABE_SYS_STAT_MID1 !! GABE_SYS_STAT_MID0 !! Machine
|-
| 0 || 0 || FMX - Development Platform
|-
| 0 || 1 || C256 Foenix - Dev Platform
|-
| 1 || 0 || C256 Foenix - User Version (65C816)
|-
| 1 || 1 || Reserved
|}

=== GABE SDC Interface ($AF:EA00) ===

GABE provides block-level access to the SPI interface of the SD card. Currently, there are other registers in that provide access to the SD card through a CH376S chip, but that interface should be considered deprecated in favor of this interface. Most FMX boards do not have the CH376S chip, leaving its position unpopulated on the board.

{| class="wikitable"
! Address !! R/W !! Name !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0 !! Description
|-
| $AF:EA00 || R || SDC_VERSION_REG || colspan="8"|version || Should read 12
|-
| $AF:EA01 || W || SDC_CONTROL_REG || x || x || x || x || x || x || x || RESET || Control register: RESET = 1 resets the core logic. Self clearing.
|-
| $AF:EA02 || W || SDC_TRANS_TYPE_REG ||x || x || x || x || x || x || colspan="2"|TRANS || Sets the type of transaction: 0 = Direct, 1 = INIT SD, 2 = Read Block, 3 = Write block
|-
| $AF:EA03 || W || SDC_TRANS_CONTROL_REG || x || x || x || x || x || x || x || START || Start transaction bit.
|-
| $AF:EA04 || R || SDC_TRANS_STATUS_REG || x || x || x || x || x || x || x || BUSY || Status of the transaction. BUSY = 1 indicates a transaction is in progress.
|-
| $AF:EA05 || R || SDC_TRANS_ERROR_REG || x || x || colspan="2"|WR_ERR || colspan="2"|RD_ERR || colspan="2"|TRANS_ERR || Error conditions for read, write, and transaction.
|-
| $AF:EA06 || RW || SDC_DIRECT_ACCESS_REG || colspan="8"|data || SPI Direct Read and Write - Set DATA before initiating direct Access Transaction
|-
| $AF:EA07 || W || SDC_SD_ADDR_7_0_REG || A7 || A6 || A5 || A4 || A3 || A2 || A1 || A0 || Set the ADDR before a block read or block write.
|-
| $AF:EA08 || W || SDC_SD_ADDR_15_8_REG || A15 || A14 || A13 || A12 || A11 || A10 || A9 || A8 || ADDR[8:0] always should be 0, since each block is 512 bytes
|-
| $AF:EA09 || W || SDC_SD_ADDR_23_16_REG || A23 || A22 || A21 || A20 || A19 || A18 || A7 || A6
|-
| $AF:EA0A || W || SDC_SD_ADDR_31_24_REG || A32 || A31 || A30 || A29 || A28 || A26 || A25 || A24
|-
| $AF:EA0B || W || SDC_SPI_CLK_DEL_REG || colspan="8"|clock delay
|-
| $AF:EA10 || R || SDC_RX_FIFO_DATA_REG || colspan="8"|data || Data from block read
|-
| $AF:EA12 || R || SDC_RX_FIFO_DATA_CNT_HI || CNT15 || CNT14 || CNT13 || CNT12 || CNT11 || CNT10 || CNT9 || CNT8 || How many bytes in the read FIFO (HI)
|-
| $AF:EA13 || R || SDC_RX_FIFO_DATA_CNT_LO || CNT7 || CNT6 || CNT5 || CNT4 || CNT3 || CNT2 || CNT1 || CNT0 || How many bytes in the read FIFO (LOW)
|-
| $AF:EA14 || W || SDC_RX_FIFO_CTRL_REG || x || x || x || x || x || x || x || CLEAR || CLEAR = 1, clear the read FIFO. Bit is self-clearing.
|-
| $AF:EA20 || W || SDC_TX_FIFO_DATA_REG || colspan="8"|data || Write data block here.
|-
| $AF:EA21 || W || SDC_TX_FIFO_CTRL_REG || x || x || x || x || x || x || x || CLEAR || CLEAR = 1, clear the write FIFO. Bit is self-clearing.
|}

==== GABE: SDC_TRANS_ERROR_REG ($AF:EA05) ====

Lists any error conditions on reads, writes, or general transactions:

{| class="wikitable"
|+ TRANS_ERR codes [1:0]
! Code !! Condition
|-
| 00 || No INIT error
|-
| 01 || INIT CMD0 error
|-
| 10 || INIT CMD1 error
|}

{| class="wikitable"
|+ RD_ERR codes [3:2]
! Code !! Condition
|-
| 00 || No read error
|-
| 01 || CMD error
|-
| 10 || Token error
|}

{| class="wikitable"
|+ WR_ERR codes [5:4]
! Code !! Condition
|-
| 00 || No write error
|-
| 01 || CMD error
|-
| 10 || Data error
|-
| 11 || Busy error
|}

=== GABE SN76489 Interface ($AF:F100) ===

GABE provides the interface to the SN76489 sound chip on the Foenix FMX. This chip uses only a single write-only address: $AF:F100. The SN76489 has four voices: three tone generators, and one noise generator. Each voice has a frequency and an attenuation setting. For full details on how to use the SN76489 chip, please consult the official documentation, but here is a brief summary.

==== Playing a Tone ====

To change the frequency of a tone generator, two bytes are sent to the chip in order:

{| class="wikitable"
|-
! !! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| First || 1 ||colspan="2"| Channel || 0 || F3 || F2 || F1 || F0
|-
| Second || 0 || x || F9 || F8 || F7 || F6 || F5 || F4
|}

The actual frequency played depends on the clock driving the chip: freq = N / (32 * F), where N = 3575800 (for the FMX), and F is the 10-bit number sent to the chip. The "Channel" number above must be 0, 1, or 3.

==== Play a Noise ====

To play a noise, only a single byte is written to the chip:

{| class="wikitable"
|-
! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| 1 || 1 || 1 || 0 || x || NF|| NF1 || NF0
|}

The NF bit controls the type of noise generated, and the NF bits control the base frequency of the noise.

==== Setting the Volume ====

The volumes of each of the four voices can be set independently. To set the volume of a single voice, a single byte is sent to the chip:

{| class="wikitable"
|-
! 7 !! 6 !! 5 !! 4 !! 3 !! 2 !! 1 !! 0
|-
| 1 ||colspan="2"| Channel || 1 || A3 || A2 || A1 || A0
|}

The "Channel" bits are the number of the voice to change: 0, 1, 2, or 3. The four bit value A is the level of attenuation, where 0 is fully on, and 15 is fully off.

Foenix Kernel Documentation

2021-06-01T17:46:27Z

PJW:

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

Foenix Kernel Documentation

2021-06-01T17:41:49Z

PJW: /* Interrupt Jump Table */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (no longer used)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Console Special Characters ==

The console routines support several special control codes for both input and output.
When the key on the keyboard is pressed, the associated code is returned by the GET routines.
If the code is printed through the PUTC or PUTS, the associated operation will be performed on the screen.
Note that this means that any graphics characters associated with those code points will not be displayed by PUTC or PUTS.
If those characters must be displayed, they would have to be written to the text memory directly.

{| class="wikitable"
! Code !! Name !! Keyboard !! Description
|-
| $08 || BS || Backspace || Deletes the character to the left of the cursor, pulling characters in from the right.
|-
| $09 || TAB || TAB || Moves the cursor right to the next tabulated column (every eight columns).
|-
| $0A || LF || N/A || Puts the cursor at column 0 on the next line on the same column.
|-
| $0D || CR || RETURN || Creates a newline on the screen. Puts the cursor at column 0 on the next line.
|-
| $0F || INS || Insert || Inserts a blank space under the cursor (pushing characters to the right).
|-
| $11 || UP || Up Arrow || Moves the cursor up one row.
|-
| $1D || RIGHT || Right Arrow || Moves the cursor right one column. May wrap to the next line.
|-
| $7F || DEL || Delete || Deletes the character under the cursor, pulling characters in from the right.
|-
| $91 || DOWN || Down Arrow || Moves the cursor down one row. May scroll the screen.
|-
| $9D || LEFT || Left Arrow || Moves the cursor left one column.
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

Foenix Kernel Documentation

2021-06-01T17:41:05Z

PJW: /* Interrupt Jump Table */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank, used by floppy drive code)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0 (used by floppy drive code and DELAY call)
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt (used by kernel to handle mouse)
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt (used by kernel to handle keyboard input)
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collision
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (CH376S???)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Console Special Characters ==

The console routines support several special control codes for both input and output.
When the key on the keyboard is pressed, the associated code is returned by the GET routines.
If the code is printed through the PUTC or PUTS, the associated operation will be performed on the screen.
Note that this means that any graphics characters associated with those code points will not be displayed by PUTC or PUTS.
If those characters must be displayed, they would have to be written to the text memory directly.

{| class="wikitable"
! Code !! Name !! Keyboard !! Description
|-
| $08 || BS || Backspace || Deletes the character to the left of the cursor, pulling characters in from the right.
|-
| $09 || TAB || TAB || Moves the cursor right to the next tabulated column (every eight columns).
|-
| $0A || LF || N/A || Puts the cursor at column 0 on the next line on the same column.
|-
| $0D || CR || RETURN || Creates a newline on the screen. Puts the cursor at column 0 on the next line.
|-
| $0F || INS || Insert || Inserts a blank space under the cursor (pushing characters to the right).
|-
| $11 || UP || Up Arrow || Moves the cursor up one row.
|-
| $1D || RIGHT || Right Arrow || Moves the cursor right one column. May wrap to the next line.
|-
| $7F || DEL || Delete || Deletes the character under the cursor, pulling characters in from the right.
|-
| $91 || DOWN || Down Arrow || Moves the cursor down one row. May scroll the screen.
|-
| $9D || LEFT || Left Arrow || Moves the cursor left one column.
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}

Foenix Kernel Documentation

2021-06-01T17:39:59Z

PJW: /* Interrupt Jump Table */

= Foenix Kernel Documentation =

== Kernel Essentials ==
Source Code: https://github.com/Trinity-11/Kernel_FMX

The Foenix Kernel resides in bank $19 (U) or bank $39 (U+/FMX) of the system RAM. It provides for the initialization of the hardware and a certain minimalist level of access to the hardware.
Kernel routines are called through a kernel jump table that starts at $00:1000.
All kernel routines must be called using the JSL instruction (long, or 24-bit subroutine call), since they all terminate with an RTL.
This allows the kernel routines to be called from anywhere in system memory.

== Kernel Calls ==

{| class="wikitable"
|-
! Name !! Address !! Description
|-
| BOOT || $00:1000 || Cold boot routine
|-
| PUTC || $00:1018 || Print a character to the currently selected channel. [See [[ANSI Support]] for more details.]
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || ASCII code of the character to print
|}
|-
| PUTS || $00:101C || Print a null-terminated ASCII string to the currently selected channel
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the first character to print
|}
|-
| GETSCANCODE || $00:1028 || [v0.4] Get the next scancode from the keyboard (A = scancode, 0 if none available). See [[C256 Keyboard]] for details.
|-
| GETLOCKS|| $00:102C || [v0.4] Get the state of the lock keys on the keyboard (A[2] = CAPS, A[1] = NUM, A[0] = SCROLL). See [[C256 Keyboard]] for details.
|-
| SETIN || $00:1038 || Set the current input channel used by the GET subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Keyboard
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
|}
|-
| SETOUT || $00:103C || Set the current output channel used by the PUT subroutines
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| A || 8 || Input channel to use
* 0 = Screen
* 1 = COM1 (external serial)
* 2 = COM2 (internal serial)
* 4 = EVID video expansion card (if present)
|}
|-
| GETCH || $00:1048 | Get a character from the input channel. A=0 and Carry=1 if no data is waiting.
|-
| GETCHW || $00:104C || Get a character from the input channel. Waits until data received. A=0 and Carry=1 if no data is waiting
|-
| GETCHE || $00:1050 || Get a character from the input channel and echo to the screen. Wait if data is not ready.
|-
| PRINTCR || $00:106C || Print Carriage Return
|-
| PRINTH || $00:1078 || Print hex value in memory.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| B || 8 || Bank containing the data to print
|-
| X || 16 || Address within that bank of the last byte to print
|-
| Y || 16 || Number of bytes to print
|}
|-
| PRINTAH || $00:1080 || Prints hex value in A. Printed value is 2 wide if M flag is 1, 4 wide if M
|-
| LOCATE || $00:1084 || Move the cursor to a new position on the screen.
{| class="wikitable"
|-
! Register !! Width !! Contents
|-
| X || 16 || The column for the cursor
|-
| Y || 16 || The row for the cursor
|}
|-
| CSRRIGHT || $00:1090 || Move the cursor one position to the right
|-
| CSRLEFT || $00:1094 || Move the cursor one position to the left
|-
| CSRUP || $00:1098 || Move the cursor up one row
|-
| CSRDOWN || $00:109C || Move the cursor down one row
|-
| CSRHOME || $00:10A0 || Move the cursor to the upper-left corner
|-
| SCROLLUP || $00:10A4 || Scroll the screen up one line. Creates an empty line at the bottom.
|-
| CLRSCREEN || $00:10B0 || Clear the screen
|-
| INITCHLUT || $00:10B4 || Init character look-up table
|-
| INITSUPERIO || $00:10B8 || Init Super-IO chip
|-
| INITKEYBOARD || $00:10BC || Init keyboard
|-
| INITRTC || $00:10C0 || Init Real-Time Clock
|-
| INITCURSOR || $00:10C4 || Init the Cursors registers
|-
| INITFONTSET || $00:10C8 || Init the Internal FONT Memory
|-
| INITGAMMATABLE || $00:10CC || Init the RGB GAMMA Look Up Table
|-
| INITALLLUT || $00:10D0 || Init the Graphic Engine (Bitmap/Tile/Sprites) LUT
|-
| INITVKYTXTMODE || $00:10D4 || Init the Text Mode @ Reset Time
|-
| INITVKYGRPMODE || $00:10D8 || Init the Basic Registers for the Graphic Mode
|-
| F_OPEN || $00:10F0 || Open a file for reading/writing. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CREATE || $00:10F4 || Create a new file and write its first cluster. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_CLOSE || $00:10F8 || Close a file (make sure last cluster is written). DOS_FD_PTR points to a file descriptor for the file.
|-
| F_WRITE || $00:10FC || Write the current cluster to the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_READ || $00:1100 || Read the next cluster from the file. DOS_FD_PTR points to a file descriptor for the file.
|-
| F_DELETE || $00:1104 || Delete a file / directory. DOS_PATH_BUFF = a buffer containing the full path to the file (NULL terminated).
|-
| F_DIROPEN || $00:1108 || Open a directory and seek the first directory entry. NOTE: currently only works with the root directory.
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_FD_PTR || IN || Points to a file descriptor for the path to lookup. NOTE: currently unused.
|-
| DOS_DIR_PTR || OUT || Pointer to the first FAT directory entry in that directory.
|}
|-
| F_DIRNEXT || $00:110C || seek to the next directory of an open directory
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_DIR_PTR || IN || Pointer to the current FAT directory entry.
|-
| DOS_DIR_PTR || OUT || Pointer to the next FAT directory entry.
|}
|-
| F_DIRREAD || $00:1110 || Read the directory entry for the specified file
{| class="wikitable"
|-
! Variable !! Direction !! Contents
|-
| DOS_PATH_BUFF || IN || The buffer containing the path to the file to lookup.
|-
| DOS_DIR_PTR || OUT || Pointer to the FAT directory entry for that file.
|}
|-
| F_DIRWRITE || $00:1114 || Write any changes in the current directory cluster back to the drive
|-
| F_LOAD || $00:1118 || load a binary file into memory, supports multiple file formats
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to lookup.
|-
| DOS_DST_PTR || Pointer to the location to load the file (any value > $3F:FFFF to load the file where the file specifies).
|}
|-
| F_SAVE || $00:111C || Save memory to a binary file
{| class="wikitable"
|-
! Variable !! Contents
|-
| DOS_FD_PTR || Points to a file descriptor for the file to create.
|-
| DOS_SRC_PTR || Address of the first byte to save.
|-
| DOS_END_PTR || Address of the last byte to save.
|}

|-
| CMDBLOCK || $00:1120 || Send a command to a block device.
{| class="wikitable"
|-
! Variable !! Contents
|-
| BIOS_DEV || The target device
|-
| X || The number of the command to send. Command numbers are device dependent, but typical examples are: 1 = Turn on spindle motor, 2 = Turn off spindle motor, 3 = Recalibrate.
|}
|-
| F_RUN || $00:1124 || Load and run a binary file from a block device. DOS_RUN_PARAMS is a pointer to the ASCIIZ string specifying the path of the file to execute and any parameters to it.
|-
| F_MOUNT || $00:1128 || Mount the designated block device. BIOS_DEV is the device number to mount.
|-
| F_COPY || $00:1130 || Copy a file. DOS_STR1_PTR is the path of the source file to copy. DOS_STR2_PTR is the path of the destination.
|-
| F_ALLOCFD || $00:1134 || Allocate a file descriptor from the kernel. DOS_FD_PTR will point to the file descriptor allocated, if one is available. There
is a limit of 8 file descriptors that can be allocated at any one time.
|-
| F_FREEFD || $00:1138 || Return a file descriptor to the kernel. DOS_FD_PTR points to the file descriptor to return to the kernel. It must have been
allocated previously through F_ALLOCFD.

|-
| TESTBREAK || $00:113C || [v0.4] Check if BREAK was pressed recently by the user (C is set if true, clear if false)
|-
| SETTABLE || $00:1140 || [v0.4] Set the keyboard scan code -> character translation tables (B:X points to the new tables). See [[C256 Keyboard]] for details.
|-
| READVRAM || $00:1144 || [v0.4] Read a byte from video RAM at B:X. Result in A. C clear on success, set on failure (timeout).
|-
| SETHANDLER || $00:1148 || [v0.4] Set the handler for the interrupt # in A (A[7..4] = block number, A[3..0] = interrupt) to the FAR routine at Y:X
|-
| DELAY || $00:114C || [v0.4] Wait at least Y:X ticks of the system clock.
|}

=== DOS Calling Conventions ===

The DOS file routines use several variables to communicate with the calling program. All DOS routines will return with the carry bit set on success.
If the routine was unable to complete successfully or needs to return a negative condition, the carry bit will be clear and DOS_STATUS and BIOS_STATUS
variables may contain non-zero status codes describing the nature of the failure.

{| class="wikitable"
|-
! Variable !! Address !! Width (bytes) !! Purpose
|-
| DOS_FD_PTR || $00:0340 || 4 || A pointer to a file descriptor structure (defined below).
|-
| DOS_PATH_BUFF || $00:0400 || 256 || A buffer space for storing a path to a file or directory.
|-
| DOS_DIR_PTR || $00:0338 || 4 || A pointer to a directory entry. The layout of the entry is identical to that used in the FAT file system.
|-
| DOS_DST_PTR || $00:0354 || 4 || A pointer to a block of memory to be filled from the disk.
|-
| DOS_SRC_PTR || $00:0350 || 4 || A pointer to a block of memory to write to disk.
|-
| DOS_END_PTR || $00:0358 || 4 || A pointer to the last byte of a block of memory.
|-
| DOS_STATUS || $00:032E || 1 || A status code for DOS operations. $00 = success
|-
| BIOS_STATUS || $00:0320 || 1 || A status code for sector level operations. $00 = success
|}

==== File Descriptor ====

Most DOS subroutines take a pointer to a file descriptor as an argument. This file descriptor contains several elements needed to manage a file,
including the buffer containing the current cluster of the file:

{| class="wikitable"
! Name !! Offset !! Width (bytes) !! Purpose
|-
| STATUS || 0 || 1 || A special status byte containing information about the file's state
{| class="wikitable"
|-
! Name !! Value !! Purpose
|-
| FD_STAT_READ || $01 || The file is open for reading
|-
| FD_STAT_WRITE || $02 || The file is open for writing
|-
| FD_STAT_OPEN || $40 || The file is open.
|-
| FD_STAT_ERROR || $60 || There is an error with the file.
|-
| FD_STAT_EOF || $80 || The file is being read and has reach the end of the file.
|}

|-
| DEV || 1 || 1 || A byte containing the device number for the file (should not be modified by the user program).
|-
| PATH || 2 || 4 || A pointer to a null-terminated string containing the path to the file. Set by the user program.
|-
| CLUSTER || 6 || 4 || The ID of the current cluster being read or written. Usually set by DOS.
|-
| FIRST_CLUSTER || 10 || 4 || The ID of the first cluster of the file. Usually set by DOS.
|-
| BUFFER || 14 || 4 || Pointer to the buffer containing a cluster's worth of data. Provided by the user program. Used by DOS to read or write the disk.
|-
| SIZE || 18 || 4 || The size of the file in bytes.
|-
| CREATE_DATE || 22 || 2 || The creation date in the same format as used by FAT.
|-
| CREATE_TIME || 24 || 2 || The creation time in the same format as used by FAT.
|-
| MODIFIED_DATE || 26 || 2 || The modification date in the same format as used by FAT.
|-
| MODIFIED_TIME || 28 || 2 || The modification time in the same format as used by FAT.
|}

== Interrupt Jump Table ==

The kernel provides a jump table for interrupt handler support. When an interrupt is triggered of any particular type, the kernel interrupt handler will
jump to the vector for that interrupt. The vector should point to a subroutine that returns to the caller through an RTL instruction.
Each vector entry is four bytes long. The first byte is a JML opcode. The next three bytes are the long (24-bit) address of the interrupt handler routine.
Currently, the kernel only supports a few interrupts in this manner. All system interrupts will eventually have an entry in this table.

A program needing to take control of one of these interrupts can replace the 24-bit address of the appropriate jump table entry (with interrupts disabled).
It is recommended to save the previous value and restore it before quitting. As of v0.4, the kernel includes a convenience routine SETHANDLER which will set the
vector to an address provided. The vector is specified in Y:X (Y contains the bank of the handler, X contains the 16-bit address within the bank). The
number of the interrupt is provided in A, with A[7..4] containing the block number, and A[3..0] containing the interrupt number.

{| class="wikitable"
|-
! Interrupt !! Block !! Number !! Address !! Purpose
|-
| VEC_INT00_SOF || 0 || 0 || $00:1700 || Start Of Frame (vertical blank)
|-
| VEC_INT01_SOL || 0 || 1 || $00:1704 || Start Of Line (horizontal blank)
|-
| VEC_INT02_TMR0 || 0 || 2 || $00:1708 || Timer 0
|-
| VEC_INT03_TMR1 || 0 || 3 || $00:170C || Timer 1
|-
| VEC_INT04_TMR2 || 0 || 4 || $00:1710 || Timer 2
|-
| VEC_INT05_RTC || 0 || 5 || $00:1714 || Real Time Clock interrupt
|-
| VEC_INT06_FDC || 0 || 6 || $00:1718 || Floppy Drive Controller interrupt
|-
| VEC_INT07_MOUSE || 0 || 7 || $00:171C || Mouse interrupt
|-
| VEC_INT10_KBD || 1 || 0 || $00:1720 || Keyboard interrupt
|-
| VEC_INT11_COL0 || 1 || 1 || $00:1724 || VICKY_II (INT2) Sprite Collisio
|-
| VEC_INT12_COL1 || 1 || 2 || $00:1728 || VICKY_II (INT3) Bitmap Collision
|-
| VEC_INT13_COM2 || 1 || 3 || $00:172C || Serial port #2 interrupt
|-
| VEC_INT14_COM1 || 1 || 4 || $00:1730 || Serial port #1 interrupt
|-
| VEC_INT15_MIDI || 1 || 5 || $00:1734 || MIDI controller interrupt
|-
| VEC_INT16_LPT || 1 || 6 || $00:1738 || Parallel port interrupt
|-
| VEC_INT17_SDC || 1 || 7 || $00:173C || SD Card Controller interrupt (CH376S???)
|-
| VEC_INT20_OPL || 2 || 0 || $00:1740 || OPL3
|-
| VEC_INT21_GABE0 || 2 || 1 || $00:1744 || GABE (INT0) - TBD
|-
| VEC_INT22_GABE1 || 2 || 2 || $00:1748 || GABE (INT1) - TBD
|-
| VEC_INT23_VDMA || 2 || 3 || $00:174C || VICKY_II (INT4) - VDMA Interrupt
|-
| VEC_INT24_COL2 || 2 || 4 || $00:1750 || VICKY_II (INT5) Tile Collision
|-
| VEC_INT25_GABE2 || 2 || 5 || $00:1754 || GABE (INT2) - TBD
|-
| VEC_INT26_EXT || 2 || 6 || $00:1758 || External Expansion
|-
| VEC_INT17_SDINS || 2 || 7 || $00:175C || SDCARD Insertion
|-
| VEC_INT30_OPN2 || 3 || 0 || $00:1760 || OPN2
|-
| VEC_INT31_OPM || 3 || 1 || $00:1764 || OPM
|-
| VEC_INT32_IDE || 3 || 2 || $00:1768 || HDD IDE Interrupt
|}

== Console Special Characters ==

The console routines support several special control codes for both input and output.
When the key on the keyboard is pressed, the associated code is returned by the GET routines.
If the code is printed through the PUTC or PUTS, the associated operation will be performed on the screen.
Note that this means that any graphics characters associated with those code points will not be displayed by PUTC or PUTS.
If those characters must be displayed, they would have to be written to the text memory directly.

{| class="wikitable"
! Code !! Name !! Keyboard !! Description
|-
| $08 || BS || Backspace || Deletes the character to the left of the cursor, pulling characters in from the right.
|-
| $09 || TAB || TAB || Moves the cursor right to the next tabulated column (every eight columns).
|-
| $0A || LF || N/A || Puts the cursor at column 0 on the next line on the same column.
|-
| $0D || CR || RETURN || Creates a newline on the screen. Puts the cursor at column 0 on the next line.
|-
| $0F || INS || Insert || Inserts a blank space under the cursor (pushing characters to the right).
|-
| $11 || UP || Up Arrow || Moves the cursor up one row.
|-
| $1D || RIGHT || Right Arrow || Moves the cursor right one column. May wrap to the next line.
|-
| $7F || DEL || Delete || Deletes the character under the cursor, pulling characters in from the right.
|-
| $91 || DOWN || Down Arrow || Moves the cursor down one row. May scroll the screen.
|-
| $9D || LEFT || Left Arrow || Moves the cursor left one column.
|}

== Special Kernel Variables ==

The kernel keeps track of several variables.
Most kernel variables should be left alone by applications, but there are some which an application might want to set or read.

{| class="wikitable"
|-
! Start Address !! End Address !! Name !! R/W || Description
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000C || $00:000E || SCREENBEGIN || RO || Address of the first character of the text display
|-
| $00:000F || $00:0010 || COLS_VISIBLE || RW || The number of columns currently displayed
|-
| $00:0013 || $00:0014 || LINES_VISIBLE || RW || The number of rows currently displayed
|-
| $00:0017 || $00:0018 || CURSORPOS || RO || The address of the text character under the cursor
|-
| $00:001A || $00:001B || CURSORX || RO || The address of the text character under the cursor
|-
| $00:001C || $00:001D || CURSORY || RO || The address of the text character under the cursor
|-
| $00:001E || || CURCOLOR || RW || The foreground and background colors to be used when printing via PUTC and PUTS
|-
| $00:001F || $00:0020 || COLORPOS || RO || The address of the text color cell under the cursor
|}