diff --git a/.gitignore b/.gitignore index 73283f815..f07c2e3d3 100644 --- a/.gitignore +++ b/.gitignore @@ -47,7 +47,6 @@ firmware/sources/interface/*.o *.dump *.log *.aux -documents/release/api.* documents/release/basic.pdf basic/scripts/__pycache__/tokens.cpython-311.pyc firmware/common/include/data/prompt.h diff --git a/documents/release/api.md b/documents/release/api.md new file mode 100644 index 000000000..4d16d7148 --- /dev/null +++ b/documents/release/api.md @@ -0,0 +1,585 @@ +--- +fontfamilyoptions: sfdefault +fontsize: 12pt +--- + +# Neo6502 Messaging API + +The Neo6502 API is a messaging system. There are no methods to access +the hardware directly. Messages are passed via the block of memory from +`$FF00` to `$FF0F`, as specified in the \"API Messaging Addresses\" +table on the following page. + +The kernel include file `documents/release/neo6502.inc` specifies the +beginning of this address range as the identifier `ControlPort`, along +with the addresses of `WaitMessage` and `SendMessage` (described later), +various related kernel jump vectors, and some helper functions. + +The application include files `examples/assembly/neo6502.asm.inc` and +`examples/C/neo6502.h` also specify the beginning of this address range +as the identifier `ControlPort`. The assembly include also specifies +`ControlPort` and the other controls as `API_COMMAND`, `API_FUNCTION`, +`API_ERROR`, `API_STATUS`, and `API_PARAMETERS`. The C header also +specifies `ControlPort` and the other controls as `API_COMMAND_ADDR`, +`API_FUNCTION_ADDR`, `API_ERROR_ADDR`, `API_STATUS_ADDR`, and +`API_PARAMETERS_ADDR`. + +API Commands/Functions are grouped by functionality. For example, Group +1 are system-related, and Group 2 are console-I/O-related. + +Command/Function Parameters are notated in this document as `Params[0]` +through `Params[7]`, or as a list or range (eg: `Params[1,2]`, +`Params[0..7]`). Note that these are referring to a mapping to memory +locations. The numbers represent offsets from the Parameters base +address `$FF04`. Ie: the actual bytes are not necessarily all distinct +\"parameters\" in the conventional sense. Depending on the routine, a +logical parameter may be an individual byte, one or more bits of a byte +interpreted as a composite or bit-field, or multiple adjacent bytes +interpreted as 16 or 32 bit values. For example, the list `Params[0,1]` +would indicate a single logical parameter, comprised of the two adjacent +bytes `$FF04` and `$FF05`. The range `Params[4..7]` would indicate a +single logical parameter, spanning consecutive bytes between `$FF08` and +`$FF0B`. + +**Note that strings referenced by Parameters are not ASCIIZ, but are +length-prefixed.** The first byte represents the length of the string +(not counting itself). The string begins at the second byte. +Consequently, strings must be 256 bytes or less (not counting the length +header). + +\newpage + +**API Messaging Addresses**\ + ++------------+---+------------------------+------------------------+ +| Group | | Group selector and | | +| | | status. Writing a | | +| | | non-zero value to this | | +| | | location triggers the | | +| | | routine specified in | | +| | | `$FF01`. The system | | +| | | will respond by | | +| | | setting the 'Error', | | +| | | 'Information', and | | +| | | 'Parameters' values | | +| | | appropriately. Upon | | +| | | completion, this | | +| | | memory location will | | +| | | be will cleared. | | ++------------+---+------------------------+------------------------+ +| Function | | A command or function | | +| | | within the selected | | +| | | Group. For example, | | +| | | Group 1 Function 0 | | +| | | writes a value to the | | +| | | console; and Group 1 | | +| | | Function 1 reads the | | +| | | keyboard. | | ++------------+---+------------------------+------------------------+ +| Error | | Return any error | | +| | | values, 0 = no error. | | ++------------+---+------------------------+------------------------+ +| | | `bit-7` | Set (`1`) if the | +| | | | ESCape key has been | +| | | | pressed. This is not | +| | | | automatically reset. | ++------------+---+------------------------+------------------------+ +| | | `bit-6` | *unused* | ++------------+---+------------------------+------------------------+ +| | | `bit-5` | *unused* | ++------------+---+------------------------+------------------------+ +| | | `bit-4` | *unused* | ++------------+---+------------------------+------------------------+ +| | | `bit-3` | *unused* | ++------------+---+------------------------+------------------------+ +| | | `bit-2` | *unused* | ++------------+---+------------------------+------------------------+ +| | | `bit-1` | *unused* | ++------------+---+------------------------+------------------------+ +| | | `bit-0` | *unused* | ++------------+---+------------------------+------------------------+ +| Parameters | | This memory block is | | +| | | notated in this | | +| | | document as | | +| | | `Params[0]` through | | +| | | `Params[7]`, or as a | | +| | | composite list or | | +| | | range (eg: | | +| | | `Params[1,2]`, | | +| | | `Params[0..7]`). Some | | +| | | Functions require | | +| | | Parameters in these | | +| | | locations and some | | +| | | return values in these | | +| | | locations; yet others | | +| | | do neither. | | ++------------+---+------------------------+------------------------+ +| Reserved | | Reserved. | | ++------------+---+------------------------+------------------------+ + +\newpage + +## API Interfacing Protocol + +Neo6502 application programmers should interact with the API per the +following algorithm: + +1. Wait for any pending command to complete. There is a subroutine + `WaitMessage` which does this for the developer. + +2. Setup the Function code at `$FF01`; and any Parameters across + `$FF04..$FF0B`. To print a character for example, set `$FF01` to + `$06` and set `$FF04` to the character's ASCII value. To draw a + line, set `$FF01` to `$02` and set `$FF04..$FF0B` as four 16-bit + pixel coordinates: + + **Params** + +3. Setup the command code at `$FF00`. This triggers the routine; so + mind that the Function code and Parameters are setup sanely prior. + On a technical point, both implementations process the message + immediately on write. + +4. Optionally, wait for completion. Most commands (eg: writing to the + console) do not require waiting, as any subsequent command will + wait/queue as per step 1. Query commands (e.g. reading from the + keyboard queue), return a value in a parameter. Programs must wait + until the control address `$FF00` has been cleared before reading + the result of a query. + +\newpage + +There is a support function `SendMessage`, which in-lines the command +and function. E.g.: this code from the Kernel: + +jsr KSendMessage ; send message for command 2,1 (read keyboard) + +.byte 2,1 + +jsr KWaitMessage ; wait to receive the result message + +lda DParameters ; read result + +The instructions above are equivalent to the following explicit steps: + +lda #1 + +sta DFunction + +lda #2 + +sta DCommand ; trigger API function 2,1 (read keyboard) + +Loop: + +lda DCommand ; load the result - non-zero until the routine\'s +completion + +bne Loop ; wait for API routine to complete + +lda DParameters ; read result (a key-code) + +\newpage + +## Mathematical Interface + +The mathematical interface of the API functions largely as a helper +system for the BASIC interpreted, but it is open to any developer who +wishes to avail themselves of the functionality. It is strongly advised +that function 32 of Group 4 (NumberToDecimal) is not used as this is +extremely specific and as such is not documented. + +The interface is used in a stack environment, but is designed so it +could be used in either a stack environment or a fixed location +environment. The Neo6502 BASIC stack is also 'split', so elements are +not consecutive, though they can be. + +Parameter 0 and 1 specify the address of the registers 1 and 2. Register +1 starts at this address, Register 2 starts at the next address. +Parameter 2 specifies the step to the next register. Therefore they are +interleaved by default at present. + +So if Parameters 0 and 1 are 8100 and Parameter 2 is 4, the 5 byte +registers are + +Register 1: 8100,8104,8108,810C,8110 + +Register 2: 8101,8105,8109,810D,8111 + +Bytes 1-4 of the 'register' are the number, which can be either an +integer (32 bit signed) or a standard 'C' float (e.g. the IEEE Single +Precision Float format). Bit 0 is the type byte, and the relevant bit is +bit 6, which is set to indicate bytes 1-4 are a float value, and is set +on return. + +Binary functions that use int and float combined (one is int and one is +float) normally return a float. + +\newpage + +# Console Codes + +The following are console key codes. They can be printed in BASIC +programs using `chr$(n)`, and are also related to the character keys +returned by `inkey$()`. The `key()` function uses physical key numbers. +Some control codes do not have corresponding keyboard keys; and some +console outputs are not yet implemented. + +`Backspace` (8), `Tab` (9), `Enter/CR` (13), `Escape` (27), and the +printable characters (32..127) are the standard ASCII set. Other typical +control keys (eg: Home and arrows) are mapped into the 0..31 range. + +**Console Key Codes - Non-Printable**\ + ++----+----+-------------+-------------------------------+ +| 1 | A | Left Arrow | Cursor Left | ++----+----+-------------+-------------------------------+ +| 4 | D | Right Arrow | Cursor Right | ++----+----+-------------+-------------------------------+ +| 5 | E | Insert | Insertion Mode | ++----+----+-------------+-------------------------------+ +| 6 | F | Page Down | Cursor Page Down | ++----+----+-------------+-------------------------------+ +| 7 | G | End | Cursor Line End | ++----+----+-------------+-------------------------------+ +| 8 | H | Backspace | Delete Character Left | ++----+----+-------------+-------------------------------+ +| 9 | I | Tab | Tab Character | ++----+----+-------------+-------------------------------+ +| 10 | J | | Line Feed | ++----+----+-------------+-------------------------------+ +| 12 | L | | Clear Screen | ++----+----+-------------+-------------------------------+ +| 13 | M | Enter | Carriage Return (Accept Line) | ++----+----+-------------+-------------------------------+ +| 18 | R | Page Up | Cursor Page Up | ++----+----+-------------+-------------------------------+ +| 19 | S | Down | Cursor Down | ++----+----+-------------+-------------------------------+ +| 20 | T | Home | Cursor Line Begin | ++----+----+-------------+-------------------------------+ +| 22 | V | | Cursor Down (8 Lines) | ++----+----+-------------+-------------------------------+ +| 23 | W | Up | Cursor Up | ++----+----+-------------+-------------------------------+ +| 24 | X | | Cursor Color Inverse | ++----+----+-------------+-------------------------------+ +| 26 | Z | Delete | Delete Character Right | ++----+----+-------------+-------------------------------+ +| 27 | \[ | Escape | Exit | ++----+----+-------------+-------------------------------+ + +**Console Key Codes - Printable**\ + ++-------+-----------+---------------------------+ +| 20-7F | ASCII Set | Standard ASCII Characters | ++-------+-----------+---------------------------+ +| 80-8F | | Set Foreground Color | ++-------+-----------+---------------------------+ +| 90-9F | | Set Background Color | ++-------+-----------+---------------------------+ +| C0-FF | | User-definable Characters | ++-------+-----------+---------------------------+ + +\newpage + +# Graphics + +## Graphics Settings + +Function 5,1 configures the global graphics system settings. Not all +Parameters are relevant for all graphics commands; but all Parameters +will be set by this command. So mind their values. + +The actual color of each drawn pixel will be computed at runtime by +AND'ing the existing pixel color with the value specified in +`Params[0]`, then XOR'ing the result with the value specified in +`Params[1]`. + +The value in `Params[2]` is a flag which determines the paint fill mode +for the Draw Rectangle and Draw Ellipse commands: reset (`0`) for +outline, set (`1`) for solid fill. + +The value in `Params[3]` is the draw extent (window) for the Draw Image +command. + +The value in `Params[4]` is a bit-field of flags for the Draw Image +command, which determine if the image will be inverted (flipped) +horizontally or vertically: `bit-0` for horizontal, `bit-1` for +vertical, reset (`0`) for normal, set (`1`) for inverted. + +For the \"Draw Rectangle\" and \"Draw Ellipse\" commands, the given +order and position of the coordinates are not significant. To be +precise, one is \"a corner\" and the other is \"the opposite corner\". +For the \"Draw Ellipse\" command, these corners are referring to the +bounding-box. The coordinates for an ellipse will lie outside of the +ellipse itself. + +\newpage + +## Graphics Data + +Graphics data files are conventionally named ending in the .gfx suffix; +though this is not mandatory. The format is quite simple. + +**Graphics Data Format**\ + ++--------+-------+--------------------------------+ +| 0 | 1 | Graphics Data Format ID | ++--------+-------+--------------------------------+ +| 1 | Count | Number of 16x16 tiles in use | ++--------+-------+--------------------------------+ +| 2 | Count | Number of 16x16 sprites in use | ++--------+-------+--------------------------------+ +| 3 | Count | Number of 32x32 sprites in use | ++--------+-------+--------------------------------+ +| 4..255 | | Reserved | ++--------+-------+--------------------------------+ +| 256 | Raw | Sprites graphics data | ++--------+-------+--------------------------------+ + +The layout of sprites graphics data is all of the 16x16 tiles, followed +by all the 16x16 sprites, followed by all the 32x32 sprites, all in +their respective orders. As there is currently only about 20kB of +Graphics Memory, these should be used somewhat sparingly. + +Each byte specifies 2 pixels. The upper 4 bits represent the first pixel +colour; and the lower 4 bits represent the second pixel colour. So tiles +and 16x16 sprites occupy 16x16/2 bytes (128 bytes) each. Each 32x32 +sprite occupies 32x32/2 bytes (512 bytes). Colour 0 is transparent for +sprites (colour 9 should be used for a black pixel). + +The release package includes Python scripts for creating graphics files, +which allow you to design graphics using your preferred editing tools +(eg: Gimp, Inkscape, Krita, etc). There is an example in the `crossdev/` +directory, which demonstrates how to get started importing graphics into +the Neo6502. + +\newpage + +## Pixel Colors + +**Pixel Colors**\ + ++-------+-------------------+ +| `$80` | Black/Transparent | ++-------+-------------------+ +| `$81` | Red | ++-------+-------------------+ +| `$82` | Green | ++-------+-------------------+ +| `$83` | Yellow | ++-------+-------------------+ +| `$84` | Blue | ++-------+-------------------+ +| `$85` | Magenta | ++-------+-------------------+ +| `$86` | Cyan | ++-------+-------------------+ +| `$87` | White | ++-------+-------------------+ +| `$88` | Black | ++-------+-------------------+ +| `$89` | Dark Grey | ++-------+-------------------+ +| `$8A` | Dark Green | ++-------+-------------------+ +| `$8B` | Orange | ++-------+-------------------+ +| `$8C` | Dark Orange | ++-------+-------------------+ +| `$8D` | Brown | ++-------+-------------------+ +| `$8E` | Pink | ++-------+-------------------+ +| `$8F` | Light Grey | ++-------+-------------------+ + +\newpage + +# Tile Maps + +A tile map occupies an area of user memory in 65C02. It is comprised of +three meta-data bytes, followed by one byte for each tile, which is it's +tile number in the graphic file (refer to the following section). + +`F0-FF` are special reserved tile numbers, `F0` is a transparent tile; +and `F1-FF` are a solid tile in the current palette colour. The format +is very simple. + +**Tile Maps Format**\ + ++-----+--------+---------------------------------------------+ +| 0 | 1 | Graphics Data Format ID | ++-----+--------+---------------------------------------------+ +| 1 | Width | Width of tile-map (number of tiles) | ++-----+--------+---------------------------------------------+ +| 2 | Height | Height of tile-map (number of tiles) | ++-----+--------+---------------------------------------------+ +| 3.. | Raw | Tiles graphics data (width \* height bytes) | ++-----+--------+---------------------------------------------+ + +\newpage + +# Sprites + +The Neo6502 graphics system has one sprite layer (z-plane) in the +conventional sense. Technically, there is no \"sprite layer\", per-se. +The system uses palette manipulation to create, what is in practice, a +pair of 4-bit bit-planes. The sprite graphics are in the upper nibble, +the background is in the lower nibble, and the background is drawn only +if the sprite graphic layer is zero. It's this top nibble which is read +by Function 5,36 \"Read Sprite Pixel\". + +Function 6,2 sets or updates a sprite. These parameters (eg: the X and Y +coordinates) cannot be set independently. To retain/reuse the current +value of a parameter for a subsequent call, set each of the associated +byte(s) to `$80` (eg: `$80,$80,$80,$80` for coordinates). + +The 'Sprite' Parameter `Params[0]` specifies the index of the sprite in +the graphics system. Sprite 0 is the turtle sprite. + +`Params[1,2]`,`Params[3,4]` specifies the X and Y screen coordinates. + +Bits 0-5 of the 'Image' Parameter `Params[5]` specify the index of a +specific graphic within the sprites data. Bit 6 of the 'Image' Parameter +specifies the sprite dimensions: reset (`0`) for 16x16, set (`1`) for +32x32. In practice, the index is the same as the sprite number +(`$80`-`$BF` for 16x16 sprites, `$C0`-`$FF` for 32x32 sprites), but +without bit-7 set. + +The value in `Params[6]` specifies a bit-field of flags, which +determines if the graphic will be inverted (flipped) horizontally or +vertically: `bit-0` for horizontal, `bit-1` for vertical, reset (`0`) +for normal, set (`1`) for inverted. + +`Params[7]` specifies the anchor alignment. + +\newpage + +## Sprite Anchors + +The table below shows the valid anchor alignments for a sprite. The +anchor position is the origin of the relative coordinate given. That is, +coordinates 0,0 of the sprite will coincide with one of the positions +shown in the table below. The default anchor alignment is zero +(middle-center). + +**Sprite Anchors**\ + ++------------+-------------+------------+ +| 7 | 8 | 9 | ++------------+-------------+------------+ +| | | | ++------------+-------------+------------+ +| | | | ++------------+-------------+------------+ +| 4 | 0/5 | 6 | ++------------+-------------+------------+ +| | | | ++------------+-------------+------------+ +| | | | ++------------+-------------+------------+ +| 1 | 2 | 3 | ++------------+-------------+------------+ + +To the right are two examples. Assume this is a 32x32 sprite. In the +upper example, the anchor point is at 8, the top-center. Considering the +origin at the bottom-left, this sprite is drawn at 16,32, the midpoint +of the top of the square. + +In the lower example, the anchor point is at 0; and this sprite is drawn +at 16,16 (the middle of the square). The anchor point should be +something like the centre point. So for a walking character, this might +be anchor point 2 (the bottom-center). + +\newpage + +# Sound + +Function 8,4 queues a sound. Queued sounds are played sequentially, each +after the previous has completed, such that sounds within a channel +queue will not conflict, interrupt, or overlap. + +Frequency is in units of Hertz. Duration is in units of 100ths of a +second. Slide is a gradual linear change in frequency, in units of Hz +per 100th of a second. Sound target type 0 is the beeper. Currently, the +beeper is the only available sound target. + +**Queue Sound Parameters** + ++-------+-------+-------+-------+-------+-------+-------+-------+ +| FF04 | FF05 | FF06 | FF07 | FF08 | FF09 | FF0A | FF0B | ++-------+-------+-------+-------+-------+-------+-------+-------+ +|Channel| Freq | Freq | Length| Length| Slide | Slide | Target| +| | Low | High | Low | High | Low | High | | ++-------+-------+-------+-------+-------+-------+-------+-------+ + +\newpage + +# Sound Effects + +Function 8,5 plays a sound effect immediately. These will be synthesised +to the best ability of the available hardware. These are predefined as: + ++------+------------+ +| `0` | positive | ++------+------------+ +| `1` | negative | ++------+------------+ +| `2` | error | ++------+------------+ +| `3` | confirm | ++------+------------+ +| `4` | reject | ++------+------------+ +| `5` | sweep | ++------+------------+ +| `6` | coin | ++------+------------+ +| `7` | las70 | ++------+------------+ +| `8` | powerup | ++------+------------+ +| `9` | victory | ++------+------------+ +| `10` | defeat | ++------+------------+ +| `11` | fanfare | ++------+------------+ +| `12` | alarm 1 | ++------+------------+ +| `13` | alarm 2 | ++------+------------+ +| `14` | alarm 3 | ++------+------------+ +| `15` | ringtone 1 | ++------+------------+ +| `16` | ringtone 2 | ++------+------------+ +| `17` | ringtone 3 | ++------+------------+ +| `18` | danger | ++------+------------+ +| `19` | expl100 | ++------+------------+ +| `20` | expl50 | ++------+------------+ +| `21` | expl20 | ++------+------------+ +| `22` | las30 | ++------+------------+ +| `23` | las10 | ++------+------------+ + +\newpage + +# API Functions + +The following tables are a comprehensive list of all supported API +functions. + +For the convenience of application programmers, the application include +files `examples/C/neo6502.h` and `examples/assembly/neo6502.asm.inc` +define macros for these groups, their functions, and common parameters +(colors, musical notes, etc). diff --git a/documents/release/source/api.gen.md b/documents/release/source/api.gen.md new file mode 100644 index 000000000..9068785d4 --- /dev/null +++ b/documents/release/source/api.gen.md @@ -0,0 +1,622 @@ +--- + +fontfamilyoptions: sfdefault + +fontsize: 12pt + +--- + + + +# Group 1 : System + +## Function 0 : DSP Reset + +Resets the messaging system and component systems. Normally, should not be used. + +## Function 1 : Timer + +Deposit the value (32-bits) of the 100Hz system timer into Parameters:0..3. + +## Function 2 : Key Status + +Deposits the state of the specified keyboard key into Parameter:0. State of keyboard modifiers (Shift/Ctrl/Alt/Meta) is returned in Parameter:1. The key which to query is specified in Parameter:0. + +## Function 3 : Basic + +Loads and allows the execution of BASIC via a indirect jump through address zero. + +## Function 4 : Credits + +Print the Neo6502 project contributors (stored in flash memory). + +## Function 5 : Serial Status + +Check the serial port to see if there is a data transmission. + +## Function 6 : Locale + +Set the locale code specified in Parameters:0,1 as upper-case ASCII letters. Parameter:0 takes the first letter and Parameter:1 takes the second letter. For example: French (FR) would require Parametr 0 being $46 and Parameter 1 being $52 + +## Function 7 : System Reset + +System Reset. This is a full hardware reset. It resets the RP2040 using the Watchdog timer, and this also resets the 65C02. + +## Function 8 : MOS + +Do a MOS command (a '* command') these are specified in the Wiki as they will be steadily expanded. + +## Function 9 : Sweet 16 Virtual Machine + +Execute Sweet 16 VM Code with the register set provided. The error return value is actually a re-entrant call for Windows emulation ; if it returns non-zero it means the VM has been executed, if it returns zero then the emulation can update as at the end of a normal frame. + +\newpage + +# Group 2 : Console + +## Function 0 : Write Character + +Console out (duplicate of Function 6 for backward compatibility). + +## Function 1 : Read Character + +Read and remove a key press from the keyboard queue into Parameter:0. This is the ASCII value of the keystroke. If there are no key presses in the queue, Parameter:0 will be zero. Note that this Function is best for text input, but not for games. Function 7,1 is more optimal for games, as this only detects key presses, you cannot check whether the key is currently down or not. + +## Function 2 : Console Status + +Check to see if the keyboard queue is empty. If it is, Parameter:0 will be $FF, otherwise it will be $00 + +## Function 3 : Read Line + +Input the current line below the cursor into Parameters:0,1 as a length-prefixed string; and move the cursor to the line below. Handles multiple-line input. + +## Function 4 : Define Hotkey + +Define the function key F1..F10 specified in Parameter:0 as 1..10 to emit the length-prefixed string stored at the memory location specified in Parameters:2,3. F11 and F12 cannot currently be defined. + +## Function 5 : Define Character + +Define a font character specified in Parameter:0 within the range of 192..255. Fill bits 0..5 (columns) of Parameters:1..7 (rows) with the character bitmap. + +## Function 6 : Write Character + +Write the character specified in Parameter:0 to the console at the cursor position. Refer to Section "Console Codes" for details. + +## Function 7 : Set Cursor Pos + +Move the cursor to the screen character cell Parameter:0 (X), Parameter:1 (Y). + +## Function 8 : List Hotkeys + +Display the current function key definitions. + +## Function 9 : Screen Size + +Returns the console size in characters, in Parameter:0 (height) and Parameter:1 (width). + +## Function 10 : Insert Line + +This is a support function which inserts a blank line in the console and should not be used. + +## Function 11 : Delete Line + +This is a support function which deletes a line in the console and should not be used. + +## Function 12 : Clear Screen + +Clears the screen. + +## Function 13 : Cursor Position + +Returns the current screen character cell of the cursor in Parameter:0 (X), Parameter:1 (Y). + +## Function 14 : Clear Region + +Erase all characters within the rectangular region specified in Parameters:0,1 (begin X,Y) and Parameters:2,3 (end X,Y). + +## Function 15 : Set Text Color + +Sets the foreground colour to Parameter:0 and the background colour to Parameter:1. + +## Function 16 : Cursor Inverse + +Toggles the cursor colour between normal and inverse (ie: swaps FG and BG colors). This should not be used. + +## Function 17 : Tab() implementation + +Internal helper. + +\newpage + +# Group 3 : File I/O + +## Function 1 : List Directory + +Display the file listing of the present directory. + +## Function 2 : Load File + +Load a file by name into memory. On input: Parameters:0,1 points to the length-prefixed filename string; Parameters:2,3 contains the location to write the data to. If the address is $FFFF, the file will instead be loaded into the graphics working memory, used for sprites, tiles, images. On output: Parameter:0 contains an error/status code. + +## Function 3 : Store File + +Saves data in memory to a file. On input: Parameters:0,1 points to the length-prefixed filename string; Parameters:2,3 contains the location to read data from; Parameters:4,5 specified the number of bytes to store. On output: Parameter:0 contains an error/status code. + +## Function 4 : File Open + +Opens a file into a specific channel. On input: Parameter:0 contains the file channel to open; Parameters:1,2 points to the length-prefixed filename string; Parameter:3 contains the open mode. See below. Valid open modes are: 0 opens the file for read-only access; 1 opens the file for write-only access; 2 opens the file for read-write access; 3 creates the file if it doesn't already exist, truncates it if it does, and opens the file for read-write access. Modes 0 to 2 will fail if the file does not already exist. If the channel is already open, the call fails. Opening the same file more than once on different channels has undefined behaviour, and is not recommended. + +## Function 5 : File Close + +Closes a particular channel. On input: Parameter:0 contains the file channel to close. + +## Function 6 : File Seek + +Seeks the file opened on a particular channel to a location. On input: Parameter:0 contains the file channel to operate on; Parameters:1..4 contains the file location. You can seek beyond the end of a file to extend the file. However, whether the file size changes when the seek happens, or when you perform the write is undefined behavior. + +## Function 7 : File Tell + +Returns the current seek location for the file opened on a particular channel. On input: Parameter:0 contains the file channel to operate on. On output: Parameters:1..4 contains the seek location within the file. + +## Function 8 : File Read + +Reads data from an opened file. On input: Parameter:0 contains the file channel to operate on. Parameters:1,2 points to the destination in memory, or $FFFF to read into graphics memory. Parameters:2,3 contains the amount of data to read. On output: Parameters:3,4 is updated to contain the amount of data actually read. Data is read from the current seek position, which is advanced after the read. + +## Function 9 : File Write + +Writes data to an opened file. On input: Parameter:0 contains the file channel to operate on; Parameters:1,2 points to the data in memory; Parameters:3,4 contains the amount of data to write. On output: Parameters:3,4 is updated to contain the amount of data actually written. Data is written to the current seek position, which is advanced after the write. + +## Function 10 : File Size + +Returns the current size of an opened file. On input: Parameter:0 contains the file channel to operate on. On output: Parameters:1..4 contains the size of the file. This call should be used on open files, and takes into account any buffered data which has not yet been written to disk. Consequently, this may return a different size than Function 3,16 "File Stat". + +## Function 11 : File Set Size + +Extends or truncates an opened file to a particular size. On input: Parameter:0 contains the file channel to operate on; Parameters:1..4 contains the new size of the file. + +## Function 12 : File Rename + +Renames a file. On input: Parameters:0,1 points to the length-prefixed string for the old name; Parameters:2,3 points to the length-prefixed string for the new name. Files may be renamed across directories. + +## Function 13 : File Delete + +Deletes a file or directory. On input: Parameters:0,1 points to the length-prefixed filename string. Deleting a file which is open has undefined behaviour. Directories may only be deleted if they are empty. + +## Function 14 : Create Directory + +Creates a new directory. On input: Parameters:0,1 points to the length-prefixed filename string. + +## Function 15 : Change Directory + +Changes the current working directory. On input: Parameters:0,1 points to the length-prefixed path string. + +## Function 16 : File Stat + +Retrieves information about a file by name. On input: Parameters:0,1 points to the length-prefixed filename string. Parameters:0..3 contains the length of the file; Parameter:4 contains the attributes bit-field of the file. If the file is open for writing, this may not return the correct size due to buffered data not having been flushed to disk. File attributes are a bitfield as follows: 0,0,0,Hidden, Read Only, Archive, System, Directory. + +## Function 17 : Open Directory + +Opens a directory for enumeration. On input: Parameters:0,1 points to the length-prefixed filename string. Only one directory at a time may be opened. If a directory is already open when this call is made, it is automatically closed. However, an open directory may make it impossible to delete the directory; so closing the directory after use is good practice. + +## Function 18 : Read Directory + +Reads an item from the currently open directory. On input: Parameters:0,1 points to a length-prefixed buffer for returning the filename. Parameters:0,1 is unchanged, but the buffer is updated to contain the length-prefixed filename (without any leading path); Parameters:2..5 contains the length of the file; Parameter:6 contains the file attributes, as described by Function 3,16 "File Stat". If there are no more items to read, this call fails and an error is flagged. + +## Function 19 : Close Directory + +Closes any directory opened previously by Function 3,17 "Open Directory". + +## Function 20 : Copy File + +Copies a file. On input: Parameters:0,1 points to the length-prefixed old filename; Parameters:2,3 points to the length-prefixed new filename. Only single files may be copied, not directories. + +## Function 21 : Set file attributes + +Sets the attributes for a file. On input: Parameters:0,1 points to the length-prefixed filename; Parameter:2 is the attribute bitfield. (See Stat File for details.) The directory bit cannot be changed. Obviously. + +## Function 32 : List Filtered + +Prints a filtered file listing of the current directory to the console. On input: Parameters:0,1 points to the filename search string. Files will only be shown if the name contains the search string (ie: a substring match). + +\newpage + +# Group 4 : Mathematics + +## Function 0 : Addition + +Register1 := Register 1 + Register2 + +## Function 1 : Subtraction + +Register1 := Register 1 - Register2 + +## Function 2 : Multiplication + +Register1 := Register 1 * Register2 + +## Function 3 : Decimal Division + +Register1 := Register 1 / Register2 (floating point) + +## Function 4 : Integer Division + +Register1 := Register 1 / Register2 (integer result) + +## Function 5 : Integer Modulus + +Register1 := Register 1 mod Register2 + +## Function 6 : Compare + +Parameter:0 := Register 1 compare Register2 : returns $FF, 0, 1 for less equal and greater. Note: float comparison is approximate because of rounding. + +## Function 16 : Negate + +Register1 := -Register 1 + +## Function 17 : Floor + +Register1 := floor(Register 1) + +## Function 18 : Square Root + +Register1 := square root(Register 1) + +## Function 19 : Sine + +Register1 := sine(Register 1) angles in degrees/radians + +## Function 20 : Cosine + +Register1 := cosine(Register 1) angles in degrees/radians + +## Function 21 : Tangent + +Register1 := tangent(Register 1) angles in degrees/radians + +## Function 22 : Arctangent + +Register1 := arctangent(Register 1) angles in degrees/radians + +## Function 23 : Exponent + +Register1 := e to the power of Register 1 + +## Function 24 : Logarithm + +Register1 := log(Register 1) natural logarithm + +## Function 25 : Absolute Value + +Register1 := absolute value(Register 1) + +## Function 26 : Sign + +Register1 := sign(Register 1), returns -1 0 or 1 + +## Function 27 : Random Decimal + +Register1 := random float from 0-1 + +## Function 28 : Random Integer + +Register1 := random integer from 0 to (Register 1-1) + +## Function 32 : Number to Decimal + +Helper function for tokeniser, do not use. + +## Function 33 : String to Number + +Convert the length prefixed string at Parameters:4,5 to a constant in Register1. + +## Function 34 : Number to String + +Convert the constant in Register1 to a length prefixed string which is stored at Parameters:4,5 + +## Function 35 : Set Degree/Radian Mode + +Sets the use of degrees (the default) when non zero, radians when zero. + +\newpage + +# Group 5 : Graphics + +## Function 1 : Set Defaults + +Configure the global graphics system settings. Not all parameters are relevant for all graphics commands; but all parameters will be set by this command. So mind their values. Refer to Section "Graphics Settings" for details. The parameters are And, Or, Fill Flag, Extent, and Flip. Bit 0 of flip sets the horizontal flip, Bit 1 sets the vertical flip. + +## Function 2 : Draw Line + +Draw a line between the screen coordinates specified in Parameters:0,1,Parameters:2,3 (begin X,Y) and Parameters:4,5,Parameters:6,7 (end X,Y). + +## Function 3 : Draw Rectangle + +Draw a rectangle spanning the screen coordinates specified in Parameters:0,1,Parameters:2,3 (corner X,Y) and Parameters:4,5,Parameters:6,7 (opposite corner X,Y). + +## Function 4 : Draw Ellipse + +Draw an ellipse spanning the screen coordinates specified in Parameters:0,1,Parameters:2,3 (corner X,Y) and Parameters:4,5,Parameters:6,7 (opposite corner X,Y). + +## Function 5 : Draw Pixel + +Draw a single pixel at the screen coordinates specified in Parameters:0,1,Parameters:2,3 (X,Y). + +## Function 6 : Draw Text + +Draw the length-prefixed string of text stored at the memory location specified in Parameters:4,5 at the screen character cell specified in Parameters:0,1,Parameters:2,3 (X,Y). + +## Function 7 : Draw Image + +Draw the image with image ID in Parameter:4 at the screen coordinates Parameters:0,1,Parameters:2,3 (X,Y). The extent and flip settings influence this command. + +## Function 8 : Draw Tilemap + +Draw the current tilemap at the screen coordinates specified in Parameters:0,1,Parameters:2,3 (top-left X,Y) and Parameters:4,5,Parameters:6,7 (bottom-right X,Y) using current graphics settings. + +## Function 32 : Set Palette + +Set the palette colour at the index spcified in Parameter:0 to the values in Parameter:1,Parameter:2,Parameter:3 (RGB). + +## Function 33 : Read Pixel + +Read a single pixel at the screen coordinates specified in Parameters:0,1,Parameters:2,3 (X,Y). When the routine completes, the result will be in Parameter:0. If sprites are in use, this will be the background only (0..15), if sprites are not in use it may return (0..255) + +## Function 34 : Reset Palette + +Reset the palette to the defaults. + +## Function 35 : Set Tilemap + +Set the current tilemap. Parameters:0,1 is the memory address of the tilemap, and Parameters:2,3,Parameters:4,5 (X,Y) specifies the offset into the tilemap, in units of pixels, of the top-left pixel of the tile. + +## Function 36 : Read Sprite Pixel + +Read Pixel from the sprite layer at the screen coordinates specified in Parameters:0,1,Parameters:2,3 (X,Y). When the routine completes, the result will be in Parameter:0. Refer to Section "Pixel Colors" for details. + +## Function 37 : Frame Count + +Deposit into Parameters:0..3, the number of v-blanks (full screen redraws) which have occurred since power-on. This is updated at the start of each v-blank period. + +## Function 38 : Get Palette + +Get the palette colour at the index spcified in Parameter:0. Values are returned in Parameter:1,Parameter:2,Parameter:3 (RGB). + +## Function 39 : Write Pixel + +Write Pixel index Parameter:4 to the screen coordinate specified in Parameters:0,1,Parameters:2,3 (X,Y). + +## Function 64 : Set Color + +Set Color Sets the current drawing colour to Parameter:0 + +## Function 65 : Set Solid Flag + +Set Solid Flag Sets the solid flag to Parameter:0, which indicates either solid fill (for shapes) or solid background (for images and fonts) + +## Function 66 : Set Draw Size + +Set Draw Size Sets the drawing scale for images and fonts to Parameter:0 + +## Function 67 : Set Flip Bits + +Set Flip Bits Sets the flip bits for drawing images. Bit 0 set causes a horizontal flip, bit 1 set causes a vertical flip. + +\newpage + +# Group 6 : Sprites + +## Function 1 : Sprite Reset + +Reset the sprite system. + +## Function 2 : Sprite Set + +Set or update the sprite specified in Parameter:0. The parameters are : Sprite Number, X Low, X High, Y Low, Y High, Image, Flip and Anchor and Flags Bit 0 of flags specifies 32 bit sprites. Values that are $80 or $8080 are not updated. + +## Function 3 : Sprite Hide + +Hide the sprite specified in Parameter:0. + +## Function 4 : Sprite Collision + +Parameter:0 is non-zero if the distance is less than or equal to Parameter:2 between the center of the sprite with index specified in Parameter:0 and the center of the sprite with index specified in Parameter:1 . + +## Function 5 : Sprite Position + +Deposit into Parameters:1..4, the screen coordinates of the sprite with the index specified in Parameter:0. + +\newpage + +# Group 7 : Controller + +## Function 1 : Read Default Controller + +This reads the status of the base controller into Parameter:0, and is a compatibility API call. \newline The base controller is the keyboard keys (these are WASD+OPKL or Arrow Keys+ZXCV) or the gamepad controller buttons. Either works. The 8 bits of the returned byte are the following buttons, most significant first : Y X B A Down Up Right Left + +## Function 2 : Read Controller Count + +This returns the number of game controllers plugged in to the USB System into Parameter:0. This does not include the keyboard based controller, only physical controller hardware. + +## Function 3 : Read Controller + +This returns a specific controller status. Controller 0 is the keyboard controller, Controllers 1 upwards are those physical USB devices. This returns a 32 bit value in Parameters:0..3 which currently is compatible with function 1, but allows for expansion. The 8 bits of the returned byte are the following buttons, most significant first : Y X B A Down Up Right Left + +\newpage + +# Group 8 : Sound + +## Function 1 : Reset Sound + +Reset the sound system. This empties all channel queues and silences all channels immediately. + +## Function 2 : Reset Channel + +Reset the sound channel specified in Parameter:0. + +## Function 3 : Beep + +Play the startup beep immediately. + +## Function 4 : Queue Sound + +Queue a sound. Refer to Section \#\ref{sound} "Sound" for details. The parameters are : Channel, Frequency Low, Frequency High, Duration Low, Duration High, Slide Low, Slide High and Source. + +## Function 5 : Play Sound + +Play the sound effect specified in Parameter:1 on the channel specified in Parameter:0 immediately, clearing the channel queue. + +## Function 6 : Sound Status + +Deposit in Parameter:0 the number of notes outstanding before silence in the queue of the channel specified in Parameter:0, including the current playing sound, if any. + +\newpage + +# Group 9 : Turtle Graphics + +## Function 1 : Turtle Initialise + +Initialise the turtle graphics system. Parameter:0 is the sprite number to use for the turtle, as the turtle graphics system “adopts” one of the sprites. The icon is not currently re-definable, and initially the turtle is hidden. + +## Function 2 : Turtle Turn + +Turn the turtle right by Parameter:0,1 degrees. Show if hidden. To turn left, turn by a negative amount. + +## Function 3 : Turtle Move + +Move the turtle forward by Parameter:0,1 degrees, drawing in colour Parameter:2, pen down flag in Parameter:3. Show if hidden. + +## Function 4 : Turtle Hide + +Hide the turtle. + +## Function 5 : Turtle Home + +Move the turtle to the home position (in the center, pointing upward). + +\newpage + +# Group 10 : UExt I/O + +## Function 1 : UExt Initialise + +Initialise the UExt I/O system. This resets the IO system to its default state, where all UEXT pins are I/O pins, inputs and enabled. + +## Function 2 : Write GPIO + +This copies the value Parameter:1 to the output latch for UEXT pin Parameter:0. This will only display on the output pin if it is enabled, and its direction is set to "Output" direction. + +## Function 3 : Read GPIO + +If the pin is set to "Input" direction, reads the level on pin on UEXT port Parameter:0. If it is set to "Output" direction, reads the output latch for pin on UEXT port Parameter:0. If the read is successful, the result will be in Parameter:0. + +## Function 4 : Set Port Direction + +Set the port direction for UEXT Port Parameter:0 to the value in Parameter:1. This can be $01 (Input), $02 (Output), or $03 (Analogue Input). + +## Function 5 : Write I2C + +Write to I2C Device Parameter:0, Register Parameter:1, value Parameter:2. No error is flagged if the device is not present. + +## Function 6 : Read I2C + +Read from I2C Device Parameter:0, Register Parameter:1. If the read is successful, the result will be in Parameter:0. If the device is not present, this will flag an error. Use FUNCTION 10,2 first, to check for its presence. + +## Function 7 : Read Analog + +Read the analogue value on UEXT Pin Parameter:0. This has to be set to analogue type to work. Returns a value from 0..4095 stored in Parameters:0,1, which represents an input value of 0 to 3.3 volts. + +## Function 8 : I2C Status + +Try to read from I2C Device Parameter:0. If present, then Parameter:0 will contain a non-zero value. + +## Function 9 : Read I2C Block + +Try to read a block of memory from I2C Device Parameter:0 into memory at Parameters:1,2, length Parameters:3,4. + +## Function 10 : Write I2C Block + +Try to write a block of memory to I2C Device Parameter:0 from memory at Parameters:1,2, length Parameters:3,4. + +## Function 11 : Read SPI Block + +Try to read a block of memory from SPI Device into memory at Parameters:1,2, length Parameters:3,4. + +## Function 12 : Write SPI Block + +Try to write a block of memory to SPI Device from memory at Parameters:1,2, length Parameters:3,4. + +## Function 13 : Read UART Block + +Try to read a block of memory from UART into memory at Parameters:1,2, length Parameters:3,4. This can fail with a timeout. + +## Function 14 : Write UART Block + +Try to write a block of memory to UART from memory at Parameters:1,2, length Parameters:3,4. + +## Function 15 : Set UART Speed and Protocol + +Set the Baud Rate and Serial Protocol for the UART interface. The baud rate is in Parameters:0..3 and the protocol number is Parameter:4. Currently only 8N1 is supported, this is protocol 0. + +## Function 16 : Write byte to UART + +Write byte Parameter:0 to the UART + +## Function 17 : Read byte from UART + +Read a byte from the UART. It is returned in Parameter:0 + +## Function 18 : Check if Byte Available + +See if a byte is available in the UART input buffer. If available Parameter:0 is non zero. + +\newpage + +# Group 11 : Mouse + +## Function 1 : Move display cursor + +Positions the display cursor at Parameters:0,1,Parameters:2,3 + +## Function 2 : Set mouse display cursor on/off + +Shows or hides the mouse cursor depending on the Parameter:0 + +## Function 3 : Get mouse state + +Returns the mouse position (screen pixel, unsigned) in x Parameters:0,1 and y Parameters:2,3, buttonstate in Parameter:4 (button 1 is 0x1, button 2 0x2 etc., set when pressed), scrollwheelstate in Parameter:5 as uint8 which changes according to scrolls. + +## Function 4 : Test mouse present + +Returns non zero if a mouse is plugged in in Parameter:0 + +## Function 5 : Select mouse Cursor + +Select a mouse cursor in Parameter:0 ; returns error status if the cursor is not available. + +\newpage + +# Group 12 : Blitter + +## Function 1 : Blitter Busy + +Returns a non zero value in Parameter:1 if the blitter/DMA system is currently transferring data, used to check availability and transfer completion. + +## Function 2 : Simple Blit Copy + +Copy Parameters:6,7 bytes of internal memory from Parameter:0:Parameters:1,2 to Parameter:3:Parameters:4,5. Sets error flag if the transfer is not possible (e.g. illegal write addresses). The upper 8 bits of the address are : 6502 RAM (00) VideoRAM (80,81) Graphics RAM(90) + +\newpage + +# Group 13 : Editor + +## Function 1 : Initialise Editor + +Initialises the editor + +## Function 2 : Reenter the Editor + +Re-enters the system editor. Returns the function required for call out, the editors sort of 'call backs' - see editor specification. + +\newpage + diff --git a/documents/release/source/api.out b/documents/release/source/api.out deleted file mode 100644 index 5ce39705d..000000000 --- a/documents/release/source/api.out +++ /dev/null @@ -1,7 +0,0 @@ -\BOOKMARK [1][-]{section.1}{\376\377\000N\000e\000o\0006\0005\0000\0002\000\040\000M\000e\000s\000s\000a\000g\000i\000n\000g\000\040\000A\000P\000I}{}% 1 -\BOOKMARK [1][-]{section.2}{\376\377\000A\000P\000I\000\040\000F\000u\000n\000c\000t\000i\000o\000n\000s}{}% 2 -\BOOKMARK [1][-]{section.3}{\376\377\000C\000o\000n\000s\000o\000l\000e\000\040\000C\000o\000d\000e\000s}{}% 3 -\BOOKMARK [1][-]{section.4}{\376\377\000G\000r\000a\000p\000h\000i\000c\000s}{}% 4 -\BOOKMARK [1][-]{section.5}{\376\377\000T\000i\000l\000e\000\040\000M\000a\000p\000s}{}% 5 -\BOOKMARK [1][-]{section.6}{\376\377\000S\000p\000r\000i\000t\000e\000s}{}% 6 -\BOOKMARK [1][-]{section.7}{\376\377\000S\000o\000u\000n\000d}{}% 7 diff --git a/documents/release/source/api.synctex.gz b/documents/release/source/api.synctex.gz deleted file mode 100644 index 3eecb235d..000000000 Binary files a/documents/release/source/api.synctex.gz and /dev/null differ diff --git a/documents/release/source/api.tex.in b/documents/release/source/api.tex.in deleted file mode 100644 index eff03c192..000000000 --- a/documents/release/source/api.tex.in +++ /dev/null @@ -1,705 +0,0 @@ -%% meta-data %% - -\documentclass[12pt]{article} -\usepackage{caption} -\usepackage{fullpage} -\usepackage{graphicx} -\usepackage{hyperref} -\usepackage{longtable} -\usepackage{makecell} -\usepackage{multirow} -\usepackage{paralist} -\usepackage{tabularx} -\usepackage{wrapfig} - - -%% configuration %% - -\title{Neo6502 Assembly - Messaging API} -\author{Paul Robson \\ Bill Auger} -\date{@DATE@} - -\renewcommand{\familydefault}{\sfdefault} -\graphicspath{ {./img/} % WRT local editor (eg: texworks) - {./documents/release/source/img/} % WRT command line - {../documents/release/source/img/} } % WRT Makefile -\setcounter{tocdepth}{1} -\hypersetup{hidelinks , linktoc=all} - - -%% generic macros %% - -% \MonoSp presents the given argument as a smaller mono-spaced font -\newcommand{\MonoSp}[1] {\fontsize{10pt}{10pt}\selectfont\texttt{#1}\normalsize} - -% \HeaderCenter forces a header of a left-justified column to be centered -\newcommand{\HeaderCenter}[1] {\makecell[tc]{\textbf{#1}}} - -% \Param presents the given argument as a "Param" in bold, mono-spaced font -\newcommand{\Param}[1] {\textbf{\texttt{Params[#1]}}} - -% \ParamBits illustrates a bit-field -\newcommand{\ParamBits}[9] { - \fontsize{10pt}{10pt}\selectfont - \textbf{#1} - \newline - \begin{tabular}{ | c | c | c | c | c | c | c | c | } - \hline - bit-7 & bit-6 & bit-5 & bit-4 & bit-3 & bit-2 & bit-1 & bit-0 \\ \hline - #2 & #3 & #4 & #5 & #6 & #7 & #8 & #9 \\ \hline - \end{tabular} - \normalsize - \newline -} - - -%% special case macros %% - -% \AddressCol expects to occupy a multicolumn(x2) column -% used in the "API Messaging Addresses" table, along with \BitsCol -\newcommand{\AddressCol}[1] { \multicolumn{2}{c|}{\MonoSp{#1}} } - -% \BitsCol expects to occupy the second and third to last columns -% within a multirow(x8) row -% used in the "API Messaging Addresses" table, along with \AddressCol -\newcommand{\BitsCol}[9]{ - \multirow{8}{*}{\MonoSp{#1}} & \MonoSp{bit-7} & #2 \\ \cline{3-4} - & & \MonoSp{bit-6} & #3 \\ \cline{3-4} - & & \MonoSp{bit-5} & #4 \\ \cline{3-4} - & & \MonoSp{bit-4} & #5 \\ \cline{3-4} - & & \MonoSp{bit-3} & #6 \\ \cline{3-4} - & & \MonoSp{bit-2} & #7 \\ \cline{3-4} - & & \MonoSp{bit-1} & #8 \\ \cline{3-4} - & & \MonoSp{bit-0} & #9 \\ \cline{3-4} - \hline -} - -% \ApiFnRow could technically work anyplace, -% but is mainly relevant for the API Functions table -\newcommand{\ApiFnRow}[3] { - \makecell[tc]{#1 \\ #2} & - \makecell[tl]{\MonoSp{LDA \#\$0#1} \\ \MonoSp{STA \$FF01}} & - #3 \\ \hline -} - -% \ParamsBytes could technically work anyplace, -% but is specifically for illustrating the Parameters to an API Function -\newcommand{\ParamsBytes}[9] { - \fontsize{10pt}{10pt}\selectfont - \textbf{#1} - \newline - \begin{tabular}{ | c | c | c | c | c | c | c | c | } \hline - P0 & P1 & P2 & P3 & P4 & P5 & P6 & P7 \\ - \hline - \MonoSp{\$FF04} & \MonoSp{\$FF05} & \MonoSp{\$FF06} & \MonoSp{\$FF07} & - \MonoSp{\$FF08} & \MonoSp{\$FF09} & \MonoSp{\$FF0A} & \MonoSp{\$FF0B} \\ \hline - \MonoSp{#2} & \MonoSp{#3} & \MonoSp{#4} & \MonoSp{#5} & - \MonoSp{#6} & \MonoSp{#7} & \MonoSp{#8} & \MonoSp{#9} \\ \hline - \end{tabular} - \normalsize - \newline -} - -% \SpriteParamBits could technically work anyplace, -% but is specialized to illustrate the Sprite bit-field layout -\newcommand{\SpriteParamBits}[4] { - \fontsize{10pt}{10pt}\selectfont - \textbf{#1} - \newline - \begin{tabular}{ | c | c | c | c | c | c | c | c | } \hline - \MonoSp{bit-7} & \MonoSp{bit-6} & \MonoSp{bit-5} & \MonoSp{bit-4} & - \MonoSp{bit-3} & \MonoSp{bit-2} & \MonoSp{bit-1} & \MonoSp{bit-0} \\ \hline - \MonoSp{#2} & \MonoSp{#3} & \multicolumn{6}{c|}{\MonoSp{#4}} \\ \hline - \end{tabular} - \normalsize - \newline -} - - -%% document body %% - -\begin{document} - -\maketitle - -\begin{center} - \includegraphics[scale=2.0]{neo6502-text-logo.png} -\end{center} - -\tableofcontents - - -\pagebreak - - -\section{Neo6502 Messaging API}\label{api} - -The Neo6502 API is a messaging system. -There are no methods to access the hardware directly. -Messages are passed via the block of memory from \MonoSp{\$FF00} to \MonoSp{\$FF0F}, -as specified in the "API Messaging Addresses" table on the following page. -\newline - -The kernel include file \MonoSp{documents/release/neo6502.inc} -specifies the beginning of this address range as the identifier \MonoSp{ControlPort}, -along with the addresses of \MonoSp{WaitMessage} and \MonoSp{SendMessage} (described later), -various related kernel jump vectors, and some helper functions. -\newline - -The application include files \MonoSp{examples/assembly/neo6502.asm.inc} -and \MonoSp{examples/C/neo6502.h} -also specify the beginning of this address range as the identifier \MonoSp{ControlPort}. -The assembly include also specifies \MonoSp{ControlPort} and the other controls as -\MonoSp{API\_COMMAND}, \MonoSp{API\_FUNCTION}, \MonoSp{API\_ERROR}, -\MonoSp{API\_STATUS}, and \MonoSp{API\_PARAMETERS}. -The C header also specifies \MonoSp{ControlPort} and the other controls as -\MonoSp{API\_COMMAND\_ADDR}, \MonoSp{API\_FUNCTION\_ADDR}, -\MonoSp{API\_ERROR\_ADDR}, \MonoSp{API\_STATUS\_ADDR}, -and \MonoSp{API\_PARAMETERS\_ADDR}. -\newline - -API Commands/Functions are grouped by functionality. -For example, Group 1 are system-related, and Group 2 are console-I/O-related. -All Groups and their Commands/Functions are shown in the following table. -\newline - -Command/Function Parameters are notated in this document as \Param{0} through \Param{7}, -or as a list or range (eg: \Param{1,2}, \Param{0..7}). -Note that these are referring to a mapping to memory locations. -The numbers represent offsets from the Parameters base address \MonoSp{\$FF04}. -Ie: the actual bytes are not necessarily all distinct "parameters" in the conventional sense. -Depending on the routine, a logical parameter may be an individual byte, -one or more bits of a byte interpreted as a composite or bit-field, -or multiple adjacent bytes interpreted as 16 or 32 bit values. -For example, the list \Param{0,1} would indicate a single logical parameter, -comprised of the two adjacent bytes \MonoSp{\$FF04} and \MonoSp{\$FF05}. -The range \Param{4..7} would indicate a single logical parameter, -spanning consecutive bytes between \MonoSp{\$FF08} and \MonoSp{\$FF0B}. -\newline - -\textbf{Note that strings referenced by Parameters are not ASCIIZ, but are length-prefixed.} -The first byte represents the length of the string (not counting itself). The string begins at the second byte. -Consequently, strings must be 256 bytes or less (not counting the length header). -\newline - - -\pagebreak - - -\begin{table}[h] -\centering\textbf{API Messaging Addresses} \\ -\begin{tabularx}{1\textwidth}{|>{\centering\arraybackslash}m{0.150\textwidth}| - >{\centering\arraybackslash}m{0.075\textwidth}| - >{\centering\arraybackslash}m{0.075\textwidth}| - >{\arraybackslash}m{0.594\textwidth}|} - \hline - \textbf{Meta} & \multicolumn{2}{c|}{\textbf{Address}} & \HeaderCenter{Contents} \\ \hline - Group & \AddressCol{\MonoSp{\$FF00}} & - Group selector and status. - Writing a non-zero value to this location triggers the routine specified in \MonoSp{\$FF01}. - The system will respond by setting the 'Error', 'Information', and 'Parameters' - values appropriately. - Upon completion, this memory location will be will cleared. - \\ \hline - Function & \AddressCol{\$FF01} & - A command or function within the selected Group. - For example, Group 1 Function 0 writes a value to the console; - and Group 1 Function 1 reads the keyboard. - \\ \hline - Error & \AddressCol{\$FF02} & - Return any error values, 0 = no error. - \\ \hline - \multirow{8}{*}{Information} & - \BitsCol{\$FF03}{ % address - Set (\MonoSp{1}) if the ESCape key has been pressed. % desc of bit0 - This is not automatically reset. % desc of bit0 - }{\textit{unused}}{\textit{unused}}{\textit{unused}} % desc of bits1..3 - {\textit{unused}}{\textit{unused}}{\textit{unused}}{\textit{unused}} % desc of bits4..7 - Parameters & \AddressCol{\$FF04..B} & - This memory block is notated in this document as \Param{0} through \Param{7}, - or as a composite list or range (eg: \Param{1,2}, \Param{0..7}). - Some Functions require Parameters in these locations - and some return values in these locations; yet others do neither. - \\ \hline - Reserved & \AddressCol{\$FF0C..F} & - Reserved. - \\ \hline -\end{tabularx} -\end{table} - - -\pagebreak - - -\subsection{API Interfacing Protocol}\label{subsec:api-protocol} - -Neo6502 application programmers should interact with the API -per the following algorithm: - -\begin{enumerate} - \item Wait for any pending command to complete. - There is a subroutine \MonoSp{WaitMessage} which does this for the developer. - \item Setup the Function code at \MonoSp{\$FF01}; - and any Parameters across \MonoSp{\$FF04..\$FF0B}. - To print a character for example, set \MonoSp{\$FF01} to \MonoSp{\$06} - and set \MonoSp{\$FF04} to the character's ASCII value. - To draw a line, set \MonoSp{\$FF01} to \MonoSp{\$02} - and set \MonoSp{\$FF04..\$FF0B} as four 16-bit pixel coordinates: - - \ParamsBytes{Params}{srcX lo}{srcX hi}{srcY lo}{srcY hi}{destX lo}{destX hi}{destY lo}{destY hi} - \item Setup the command code at \MonoSp{\$FF00}. This triggers the routine; - so mind that the Function code and Parameters are setup sanely prior. - On a technical point, both implementations process the message immediately on write. -% Q2: both implementations of what? -% eg: "... both the _?_ and the _?_ implementation process the message immediately ..." - \item Optionally, wait for completion. - Most commands (eg: writing to the console) do not require waiting, - as any subsequent command will wait/queue as per step 1. - Query commands (e.g. reading from the keyboard queue), - return a value in a parameter. - Programs must wait until the control address \MonoSp{\$FF00} has been cleared - before reading the result of a query. -\end{enumerate} - -There is a support function \MonoSp{SendMessage}, -which in-lines the command and function. -E.g.: this code from the Kernel: - -% Q1: KSendMessage/KWaitMessage or SendMessage/WaitMessage ? -\begin{verbatim} -jsr KSendMessage ; send message for command 2,1 (read keyboard) -.byte 2,1 -jsr KWaitMessage ; wait to receive the result message -lda DParameters ; read result -\end{verbatim} - -The instructions above are equivalent to the following explicit steps: -\begin{verbatim} -lda #1 -sta DFunction -lda #2 -sta DCommand ; trigger API function 2,1 (read keyboard) -Loop: -lda DCommand ; load the result - non-zero until the routine's completion -bne Loop ; wait for API routine to complete -lda DParameters ; read result (a key-code) -\end{verbatim} - - -\pagebreak - - -\subsection{Mathematical Interface}\label{subsec:api-protocol-maths} - -The mathematical interface of the API functions largely as a helper system for the BASIC interpreted, but it is -open to any developer who wishes to avail themselves of the functionality. It is strongly advised that function 32 -of Group 4 (NumberToDecimal) is not used as this is extremely specific and as such is not documented. -\newline - -The interface is used in a stack environment, but is designed so it could be used in either a stack environment or a -fixed location environment. The Neo6502 BASIC stack is also 'split', so elements are not consecutive, though they -can be. -\newline - -Parameter 0 and 1 specify the address of the registers 1 and 2. Register 1 starts at this address, Register 2 starts at the -next address. Parameter 2 specifies the step to the next register. Therefore they are interleaved by default at present. -\newline - -So if Parameters 0 and 1 are 8100 and Parameter 2 is 4, the 5 byte registers are - -\begin{verbatim} -Register 1: 8100,8104,8108,810C,8110 -Register 2: 8101,8105,8109,810D,8111 -\end{verbatim} - -Bytes 1-4 of the 'register' are the number, which can be either an integer (32 bit signed) or a standard 'C' float (e.g. the -IEEE Single Precision Float format). Bit 0 is the type byte, and the relevant bit is bit 6, which is set to indicate bytes 1-4 -are a float value, and is set on return. -\newline - -Binary functions that use int and float combined (one is int and one is float) normally return a float. - -\pagebreak - - -\section{API Functions}\label{api-functions} - -The following tables are a comprehensive list of all supported API functions. -\newline - -For the convenience of application programmers, -the application include files \MonoSp{examples/C/neo6502.h} -and \MonoSp{examples/assembly/neo6502.asm.inc} -define macros for these groups, their functions, -and common parameters (colors, musical notes, etc). - - -@FN_TABLES@ - - -\pagebreak - - -\section{Console Codes}\label{console-codes} - -The following are console key codes. -They can be printed in BASIC programs using \MonoSp{chr\$(n)}, -and are also related to the character keys returned by \MonoSp{inkey\$()}. -The \MonoSp{key()} function uses physical key numbers. -Some control codes do not have corresponding keyboard keys; -and some console outputs are not yet implemented. -\newline - -\MonoSp{Backspace} (8), \MonoSp{Tab} (9), \MonoSp{Enter/CR} (13), \MonoSp{Escape} (27), -and the printable characters (32..127) are the standard ASCII set. -Other typical control keys (eg: Home and arrows) are mapped into the 0..31 range. - -\begin{table}[h] -\centering\textbf{Console Key Codes - Non-Printable} \\ -\begin{tabular}{ | c | c | c | l | } \hline -\textbf{ASCII} & \textbf{CTRL+Key} & \textbf{Key} & \HeaderCenter{Output} \\ \hline -1 & A & Left Arrow & Cursor Left \\ \hline -4 & D & Right Arrow & Cursor Right \\ \hline -% Q5: Insert,PageDown,End dont work? -5 & E & Insert & Insertion Mode \\ \hline -6 & F & Page Down & Cursor Page Down \\ \hline -7 & G & End & Cursor Line End \\ \hline -8 & H & Backspace & Delete Character Left \\ \hline -% Q7: Backspace behaves only as overwrite mode -9 & I & Tab & Tab Character \\ \hline -% Q8: Tab behaves only as overwrite mode but does not delete chars -10 & J & & Line Feed \\ \hline -12 & L & & Clear Screen \\ \hline -13 & M & Enter & Carriage Return (Accept Line) \\ \hline -18 & R & Page Up & Cursor Page Up \\ \hline -19 & S & Down & Cursor Down \\ \hline -20 & T & Home & Cursor Line Begin \\ \hline -22 & V & & Cursor Down (8 Lines) \\ \hline -23 & W & Up & Cursor Up \\ \hline -24 & X & & Cursor Color Inverse \\ \hline -% Q6: Cursor Color Inverse doesnt work as expected? -26 & Z & Delete & Delete Character Right \\ \hline -27 & [ & Escape & Exit \\ \hline -\end{tabular} -\end{table} - -\begin{table}[h] -\centering\textbf{Console Key Codes - Printable} \\ -\begin{tabular}{ | c | c | l | } \hline -\textbf{Hex} & \textbf{Key} & \HeaderCenter{Output} \\ \hline -20-7F & ASCII Set & Standard ASCII Characters \\ \hline -80-8F & & Set Foreground Color \\ \hline -90-9F & & Set Background Color \\ \hline -C0-FF & & User-definable Characters \\ \hline -\end{tabular} -\end{table} - - -\pagebreak - - -\section{Graphics}\label{graphics} - -\subsection{Graphics Settings}\label{subsec:graphics-settings} - -Function 5,1 configures the global graphics system settings. -Not all Parameters are relevant for all graphics commands; -but all Parameters will be set by this command. So mind their values. -\newline - -The actual color of each drawn pixel will be computed at runtime -by AND'ing the existing pixel color with the value specified in \Param{0}, -then XOR'ing the result with the value specified in \Param{1}. -\newline - -The value in \Param{2} is a flag which determines the paint fill mode -for the Draw Rectangle and Draw Ellipse commands: -reset (\MonoSp{0}) for outline, set (\MonoSp{1}) for solid fill. -\newline - -The value in \Param{3} is the draw extent (window) for the Draw Image command. -\newline - -The value in \Param{4} is a bit-field of flags for the Draw Image command, -which determine if the image will be inverted (flipped) horizontally or vertically: -\MonoSp{bit-0} for horizontal, \MonoSp{bit-1} for vertical, -reset (\MonoSp{0}) for normal, set (\MonoSp{1}) for inverted. -\newline - -For the "Draw Rectangle" and "Draw Ellipse" commands, -the given order and position of the coordinates are not significant. -To be precise, one is "a corner" and the other is "the opposite corner". -For the "Draw Ellipse" command, these corners are referring to the bounding-box. -The coordinates for an ellipse will lie outside of the ellipse itself. - - -\pagebreak - - -\subsection{Graphics Data}\label{subsec:graphics-data} - -Graphics data files are conventionally named ending in the .gfx suffix; -though this is not mandatory. -The format is quite simple. - -\begin{table}[h] -\centering\textbf{Graphics Data Format} \\ -\begin{tabular}{ | c | c | l | } \hline -\textbf{Offset} & \textbf{Data} & \HeaderCenter{Description} \\ \hline -0 & 1 & Graphics Data Format ID \\ \hline -1 & Count & Number of 16x16 tiles in use \\ \hline -2 & Count & Number of 16x16 sprites in use \\ \hline -3 & Count & Number of 32x32 sprites in use \\ \hline -4..255 & & Reserved \\ \hline -256 & Raw & Sprites graphics data \\ \hline -\end{tabular} -\end{table} - -The layout of sprites graphics data is all of the 16x16 tiles, -followed by all the 16x16 sprites, -followed by all the 32x32 sprites, all in their respective orders. -As there is currently only about 20kB of Graphics Memory, -these should be used somewhat sparingly. -\newline - -Each byte specifies 2 pixels. The upper 4 bits represent the first pixel colour; -and the lower 4 bits represent the second pixel colour. -So tiles and 16x16 sprites occupy 16x16/2 bytes (128 bytes) each. -Each 32x32 sprite occupies 32x32/2 bytes (512 bytes). -Colour 0 is transparent for sprites (colour 9 should be used for a black pixel). -\newline -% Q9: just to note: the original api.pfd has: -% > each tile takes 16x16/2 bytes (64 bytes) as does each sprite16 - -The release package includes Python scripts for creating graphics files, -which allow you to design graphics using your preferred editing tools -(eg: Gimp, Inkscape, Krita, etc). -There is an example in the \MonoSp{crossdev/} directory, -which demonstrates how to get started importing graphics into the Neo6502. - - -\pagebreak - - -\subsection{Pixel Colors}\label{subsec:graphics-colors} - -\begin{table}[h] -\centering\textbf{Pixel Colors} \\ -\begin{tabular}{ | c | c | } \hline -\textbf{Byte} & \textbf{Color} \\ \hline -\MonoSp{\$80} & Black/Transparent \\ \hline -\MonoSp{\$81} & Red \\ \hline -\MonoSp{\$82} & Green \\ \hline -\MonoSp{\$83} & Yellow \\ \hline -\MonoSp{\$84} & Blue \\ \hline -\MonoSp{\$85} & Magenta \\ \hline -\MonoSp{\$86} & Cyan \\ \hline -\MonoSp{\$87} & White \\ \hline -\MonoSp{\$88} & Black \\ \hline -\MonoSp{\$89} & Dark Grey \\ \hline -\MonoSp{\$8A} & Dark Green \\ \hline -\MonoSp{\$8B} & Orange \\ \hline -\MonoSp{\$8C} & Dark Orange \\ \hline -\MonoSp{\$8D} & Brown \\ \hline -\MonoSp{\$8E} & Pink \\ \hline -\MonoSp{\$8F} & Light Grey \\ \hline -\end{tabular} -\end{table} - - -\pagebreak - - -\section{Tile Maps}\label{tilemaps} - -A tile map occupies an area of user memory in 65C02. -It is comprised of three meta-data bytes, followed by one byte for each tile, -which is it's tile number in the graphic file (refer to the following section). -\newline - -\MonoSp{F0-FF} are special reserved tile numbers, -\MonoSp{F0} is a transparent tile; -and \MonoSp{F1-FF} are a solid tile in the current palette colour. -The format is very simple. - -\begin{table}[h] -\centering\textbf{Tile Maps Format} \\ -\begin{tabular}{ | c | c | l | } \hline -\textbf{Offset} & \textbf{Data} & \HeaderCenter{Description} \\ \hline -0 & 1 & Graphics Data Format ID \\ \hline -1 & Width & Width of tile-map (number of tiles) \\ \hline -2 & Height & Height of tile-map (number of tiles) \\ \hline -3.. & Raw & Tiles graphics data (width * height bytes) \\ \hline -\end{tabular} -\end{table} - - -\pagebreak - - -\section{Sprites}\label{sprite} - -The Neo6502 graphics system has one sprite layer (z-plane) in the conventional sense. -Technically, there is no "sprite layer", per-se. -The system uses palette manipulation to create, what is in practice, -a pair of 4-bit bit-planes. -The sprite graphics are in the upper nibble, the background is in the lower nibble, -and the background is drawn only if the sprite graphic layer is zero. -It's this top nibble which is read by Function 5,36 "Read Sprite Pixel". -\newline - -Function 6,2 sets or updates a sprite. -These parameters (eg: the X and Y coordinates) cannot be set independently. -To retain/reuse the current value of a parameter for a subsequent call, -set each of the associated byte(s) to \MonoSp{\$80} -(eg: \MonoSp{\$80,\$80,\$80,\$80} for coordinates). -\newline - -The 'Sprite' Parameter \Param{0} specifies the index of the sprite in the graphics system. -Sprite 0 is the turtle sprite. -\newline - -\Param{1,2},\Param{3,4} specifies the X and Y screen coordinates. -\newline - -Bits 0-5 of the 'Image' Parameter \Param{5} specify -the index of a specific graphic within the sprites data. -Bit 6 of the 'Image' Parameter specifies the sprite dimensions: -reset (\MonoSp{0}) for 16x16, set (\MonoSp{1}) for 32x32. -In practice, the index is the same as the sprite number -(\MonoSp{\$80}-\MonoSp{\$BF} for 16x16 sprites, -\MonoSp{\$C0}-\MonoSp{\$FF} for 32x32 sprites), but without bit-7 set. -\newline - -The value in \Param{6} specifies a bit-field of flags, -which determines if the graphic will be inverted (flipped) horizontally or vertically: -\MonoSp{bit-0} for horizontal, \MonoSp{bit-1} for vertical, -reset (\MonoSp{0}) for normal, set (\MonoSp{1}) for inverted. -\newline - -\Param{7} specifies the anchor alignment. -Refer to Section \#\ref{subsec:sprite-anchors} "Sprite Anchors" for details. -\newline - - -\pagebreak - - -\subsection{Sprite Anchors}\label{subsec:sprite-anchors} - -The table below shows the valid anchor alignments for a sprite. -The anchor position is the origin of the relative coordinate given. -That is, coordinates 0,0 of the sprite -will coincide with one of the positions shown in the table below. -The default anchor alignment is zero (middle-center). -% Q20: the above is probably not an accurate description -% how is this used? - eg: what may be different if the anchor was chosen poorly? -% is this for alignment/positioning? -% is it a pivot point for rotation? - -\begin{table}[h] -\centering\textbf{Sprite Anchors} \\ -\begin{tabular}{| l | c | r | } \hline -7~~~~~~~~~&~~~~~8~~~~~&~~~~~~~~~9 \\ - & & \\ - & & \\ \hline - & & \\ -4 & 0/5 & 6 \\ - & & \\ \hline - & & \\ - & & \\ -1 & 2 & 3 \\ -\hline -\end{tabular} -\end{table} - -\begin{wrapfigure}[11]{r}{0pt} - \includegraphics[width=0.25\textwidth]{neo6502-rocket.png} -\end{wrapfigure} -~\newline - -To the right are two examples. Assume this is a 32x32 sprite. -In the upper example, the anchor point is at 8, the top-center. -Considering the origin at the bottom-left, -this sprite is drawn at 16,32, the midpoint of the top of the square. -% same as Q20: what is "the square"? - is this the bounding box of the sprite? -% with respect to the origin, -% both diagrams show the image drawn in exactly the same place -\newline - -In the lower example, the anchor point is at 0; -and this sprite is drawn at 16,16 (the middle of the square). -The anchor point should be something like the centre point. -So for a walking character, this might be anchor point 2 (the bottom-center). -% same as Q20: "something like" is rather vague -% rather "The anchor point should be ...": -% "... thought of as the center point of" ... but of what? (eg: rotation?) -% or: -% "... placed near the center point of" ...but of what? -% Anchor point 8 in the example image is not the center point of the image -% nor is it the center point of the diagram. -% The diagrams do not demonstrate anything that the table above does not -% would this be better described as a "pivot point"? -% Maybe the diagram of anchor point 8 should be re-centered about anchor point 8? -% Maybe the rocket should be re-centered about anchor point 8? -% Or is this the point which corresponds to the coordinates -% WRT Function 6,2 "Sprite Set" and/or Function 6,2 "Sprite Get Position"? -% Or is this related to collision detection? - - -\pagebreak - - -\section{Sound}\label{sound} - -Function 8,4 queues a sound. Queued sounds are played sequentially, -each after the previous has completed, -such that sounds within a channel queue will not conflict, interrupt, or overlap. -\newline - -Frequency is in units of Hertz. -Duration is in units of 100ths of a second. -Slide is a gradual linear change in frequency, in units of Hz per 100th of a second. -Sound target type 0 is the beeper. -Currently, the beeper is the only available sound target. - -\begin{center} -\ParamsBytes{Queue Sound Parameters}{Channel}{Freq hi}{Freq lo}{Duration lo} - {Duration hi}{Slide lo}{Slide hi}{Target} -\end{center} - -Function 8,5 plays a sound effect immediately. These will be synthesised to the best -ability of the available hardware. These are predefined as: - -\begin{table}[h] -\centering\textbf{Sound Effects} \\ -\begin{tabular}{ | c | c | } \hline -\textbf{Number} & \textbf{Effect} \\ \hline -\MonoSp{0} & positive \\ \hline -\MonoSp{1} & negative \\ \hline -\MonoSp{2} & error \\ \hline -\MonoSp{3} & confirm \\ \hline -\MonoSp{4} & reject \\ \hline -\MonoSp{5} & sweep \\ \hline -\MonoSp{6} & coin \\ \hline -\MonoSp{7} & las70 \\ \hline -\MonoSp{8} & powerup \\ \hline -\MonoSp{9} & victory \\ \hline -\MonoSp{10} & defeat \\ \hline -\MonoSp{11} & fanfare \\ \hline -\MonoSp{12} & alarm 1 \\ \hline -\MonoSp{13} & alarm 2 \\ \hline -\MonoSp{14} & alarm 3 \\ \hline -\MonoSp{15} & ringtone 1 \\ \hline -\MonoSp{16} & ringtone 2 \\ \hline -\MonoSp{17} & ringtone 3 \\ \hline -\MonoSp{18} & danger \\ \hline -\MonoSp{19} & expl100 \\ \hline -\MonoSp{20} & expl50 \\ \hline -\MonoSp{21} & expl20 \\ \hline -\MonoSp{22} & las30 \\ \hline -\MonoSp{23} & las10 \\ \hline -\end{tabular} -\end{table} - -\end{document} diff --git a/documents/release/source/api.toc b/documents/release/source/api.toc deleted file mode 100644 index 0e29e51d1..000000000 --- a/documents/release/source/api.toc +++ /dev/null @@ -1,13 +0,0 @@ -\contentsline {section}{\numberline {1}Neo6502 Messaging API}{2}{section.1}% -\contentsline {subsection}{\numberline {1.1}API Interfacing Protocol}{4}{subsection.1.1}% -\contentsline {subsection}{\numberline {1.2}Mathematical Interface}{5}{subsection.1.2}% -\contentsline {section}{\numberline {2}API Functions}{6}{section.2}% -\contentsline {section}{\numberline {3}Console Codes}{23}{section.3}% -\contentsline {section}{\numberline {4}Graphics}{24}{section.4}% -\contentsline {subsection}{\numberline {4.1}Graphics Settings}{24}{subsection.4.1}% -\contentsline {subsection}{\numberline {4.2}Graphics Data}{25}{subsection.4.2}% -\contentsline {subsection}{\numberline {4.3}Pixel Colors}{26}{subsection.4.3}% -\contentsline {section}{\numberline {5}Tile Maps}{27}{section.5}% -\contentsline {section}{\numberline {6}Sprites}{28}{section.6}% -\contentsline {subsection}{\numberline {6.1}Sprite Anchors}{29}{subsection.6.1}% -\contentsline {section}{\numberline {7}Sound}{30}{section.7}% diff --git a/documents/release/source/img/neo6502-rocket.png b/documents/release/source/img/neo6502-rocket.png deleted file mode 100644 index fc30c1b67..000000000 Binary files a/documents/release/source/img/neo6502-rocket.png and /dev/null differ diff --git a/documents/release/source/img/neo6502-text-logo.png b/documents/release/source/img/neo6502-text-logo.png deleted file mode 100644 index 2147fe761..000000000 Binary files a/documents/release/source/img/neo6502-text-logo.png and /dev/null differ diff --git a/firmware/common/config/display/group2_console.inc b/firmware/common/config/display/group2_console.inc index 472b37457..4306d8ffd 100644 --- a/firmware/common/config/display/group2_console.inc +++ b/firmware/common/config/display/group2_console.inc @@ -27,10 +27,10 @@ GROUP 2 Console FUNCTION 1 Read Character *(DPARAMS) = KBDGetKey(); DOCUMENTATION - Read and remove a key press from the keyboard queue into \Param{0}. + Read and remove a key press from the keyboard queue into Parameter:0. This is the ASCII value of the keystroke. - If there are no key presses in the queue, \Param{0} will be zero. - \newline + If there are no key presses in the queue, Parameter:0 will be zero. + Note that this Function is best for text input, but not for games. Function 7,1 is more optimal for games, as this only detects key presses, you cannot check whether the key is currently down or not. @@ -39,40 +39,38 @@ GROUP 2 Console *(DPARAMS) = KBDIsKeyAvailable() ? 0xFF: 0; DOCUMENTATION // Function 2 is key available in queue Check to see if the keyboard queue is empty. - If it is, \Param{0} will be \MonoSp{$FF}, otherwise it will be \MonoSp{$00}. + If it is, Parameter:0 will be $FF, otherwise it will be $00 FUNCTION 3 Read Line CONGetScreenLine(DSPGetInt16(DCOMMAND,4)); DOCUMENTATION - Input the current line below the cursor into \Param{0,1} as a length-prefixed string; + Input the current line below the cursor into Parameters:0,1 as a length-prefixed string; and move the cursor to the line below. Handles multiple-line input. FUNCTION 4 Define Hotkey *DERROR = KBDSetFunctionKey(*(DCOMMAND+4),DSPGetString(DCOMMAND,6)); DOCUMENTATION - Define the function key F1..F10 (\MonoSp{$01..$0A}) specified in \Param{0} to emit the - length-prefixed string stored at the memory location specified in \Param{2,3}. - For example, in a block of in-line assembly within a BASIC program, - the string: \MonoSp{06,12,108,105,115,116,13} would clear the screen (\MonoSp{12}), - then list the program (\MonoSp{108}='l',\MonoSp{105}='i',\MonoSp{115}='s',\MonoSp{116}='t',\MonoSp{13}='ENTER'). - \newline F11 and F12 cannot currently be defined. + Define the function key F1..F10 specified in Parameter:0 as 1..10 to emit the + length-prefixed string stored at the memory location specified in Parameters:2,3. + + F11 and F12 cannot currently be defined. FUNCTION 5 Define Character *DERROR = CONUpdateUserFont(DPARAMS); DOCUMENTATION - Define a font character specified in \Param{0} within the range of 192..255. - Fill bits 0..5 (columns) of \Param{1..7} (rows) with the character bitmap. + Define a font character specified in Parameter:0 within the range of 192..255. + Fill bits 0..5 (columns) of Parameters:1..7 (rows) with the character bitmap. FUNCTION 6 Write Character CONWrite(*DPARAMS); DOCUMENTATION - Write the character specified in \Param{0} to the console at the cursor position. - Refer to Section \#\ref{console-codes} "Console Codes" for details. + Write the character specified in Parameter:0 to the console at the cursor position. + Refer to Section "Console Codes" for details. FUNCTION 7 Set Cursor Pos *DERROR = CONSetCursorPosition(DPARAMS[0],DPARAMS[1]); DOCUMENTATION - Move the cursor to the screen character cell \Param{0} (X), \Param{1} (Y). + Move the cursor to the screen character cell Parameter:0 (X), Parameter:1 (Y). FUNCTION 8 List Hotkeys KBDShowFunctionKeys(); @@ -82,7 +80,7 @@ GROUP 2 Console FUNCTION 9 Screen Size CONGetScreenSizeChars(&DPARAMS[0],&DPARAMS[1]); DOCUMENTATION - Returns the console size in characters, in \Param{0} (height) and \Param{1} (width). + Returns the console size in characters, in Parameter:0 (height) and Parameter:1 (width). FUNCTION 10 Insert Line CONInsertLine(DPARAMS[0]); @@ -103,18 +101,18 @@ GROUP 2 Console CONGetCursorPosition(&DPARAMS[0],&DPARAMS[1]); DOCUMENTATION Returns the current screen character cell of the cursor - in \Param{0} (X), \Param{1} (Y). + in Parameter:0 (X), Parameter:1 (Y). FUNCTION 14 Clear Region CONClearArea(DPARAMS[0],DPARAMS[1],DPARAMS[2],DPARAMS[3]); DOCUMENTATION Erase all characters within the rectangular region specified - in \Param{0,1} (begin X,Y) and \Param{2,3} (end X,Y). + in Parameters:0,1 (begin X,Y) and Parameters:2,3 (end X,Y). FUNCTION 15 Set Text Color CONSetForeBackColour(DPARAMS[0],DPARAMS[1]); DOCUMENTATION - Sets the foreground colour to \Param{0} and the background colour to \Param{1}. + Sets the foreground colour to Parameter:0 and the background colour to Parameter:1. FUNCTION 16 Cursor Inverse CONReverseCursorBlock(); diff --git a/firmware/common/config/display/group5_graphics.inc b/firmware/common/config/display/group5_graphics.inc index aa3c2d3c4..7e6ecec1a 100644 --- a/firmware/common/config/display/group5_graphics.inc +++ b/firmware/common/config/display/group5_graphics.inc @@ -24,77 +24,72 @@ GROUP 5 Graphics Configure the global graphics system settings. Not all parameters are relevant for all graphics commands; but all parameters will be set by this command. So mind their values. - Refer to Section \#\ref{subsec:graphics-settings} "Graphics Settings" for details. - \newline - \ParamsBytes{Graphics Settings}{AND}{XOR}{Fill}{Extent} - {Flip}{unused}{\textit{unused}}{\textit{unused}} - \newline - \ParamBits{$FF08 - Flip Axis Flags}{0}{0}{0}{0}{0}{0}{Vertical}{Horizontal} + Refer to Section "Graphics Settings" for details. + + The parameters are And, Or, Fill Flag, Extent, and Flip. Bit 0 of flip + sets the horizontal flip, Bit 1 sets the vertical flip. FUNCTION 2 Draw Line GFXGraphicsCommand(2,DCOMMAND); DOCUMENTATION Draw a line between the screen coordinates specified - in \Param{0,1},\Param{2,3} (begin X,Y) - and \Param{4,5},\Param{6,7} (end X,Y). - \newline - \ParamsBytes{Draw Line Parameters}{X lo}{X hi}{Y lo}{Y hi} - {X' lo}{X' hi}{Y' lo}{Y' hi} + in Parameters:0,1,Parameters:2,3 (begin X,Y) + and Parameters:4,5,Parameters:6,7 (end X,Y). FUNCTION 3 Draw Rectangle GFXGraphicsCommand(3,DCOMMAND); DOCUMENTATION Draw a rectangle spanning the screen coordinates specified - in \Param{0,1},\Param{2,3} (corner X,Y) - and \Param{4,5},\Param{6,7} (opposite corner X,Y). + in Parameters:0,1,Parameters:2,3 (corner X,Y) + and Parameters:4,5,Parameters:6,7 (opposite corner X,Y). FUNCTION 4 Draw Ellipse GFXGraphicsCommand(4,DCOMMAND); DOCUMENTATION Draw an ellipse spanning the screen coordinates specified - in \Param{0,1},\Param{2,3} (corner X,Y) - and \Param{4,5},\Param{6,7} (opposite corner X,Y). + in Parameters:0,1,Parameters:2,3 (corner X,Y) + and Parameters:4,5,Parameters:6,7 (opposite corner X,Y). FUNCTION 5 Draw Pixel GFXGraphicsCommand(5,DCOMMAND); DOCUMENTATION Draw a single pixel at the screen coordinates specified - in \Param{0,1},\Param{2,3} (X,Y). + in Parameters:0,1,Parameters:2,3 (X,Y). FUNCTION 6 Draw Text GFXGraphicsCommand(6,DCOMMAND); DOCUMENTATION Draw the length-prefixed string of text stored - at the memory location specified in \Param{4,5} - at the screen character cell specified in \Param{0,1},\Param{2,3} (X,Y). + at the memory location specified in Parameters:4,5 + at the screen character cell specified in Parameters:0,1,Parameters:2,3 (X,Y). FUNCTION 7 Draw Image GFXGraphicsCommand(7,DCOMMAND); DOCUMENTATION - Draw the image with image ID in \Param{4} - at the screen coordinates \Param{0,1},\Param{2,3} (X,Y). + Draw the image with image ID in Parameter:4 + at the screen coordinates Parameters:0,1,Parameters:2,3 (X,Y). The extent and flip settings influence this command. FUNCTION 8 Draw Tilemap *DERROR = TMPDrawTileMap(DCOMMAND); DOCUMENTATION Draw the current tilemap at the screen coordinates specified - in \Param{0,1},\Param{2,3} (top-left X,Y) - and \Param{4,5},\Param{6,7} (bottom-right X,Y) + in Parameters:0,1,Parameters:2,3 (top-left X,Y) + and Parameters:4,5,Parameters:6,7 (bottom-right X,Y) using current graphics settings. FUNCTION 32 Set Palette GFXSetPalette(DPARAMS[0],DPARAMS[1],DPARAMS[2],DPARAMS[3]); DOCUMENTATION - Set the palette colour at the index spcified in \Param{0} - to the values in \Param{1},\Param{2},\Param{3} (RGB). + Set the palette colour at the index spcified in Parameter:0 + to the values in Parameter:1,Parameter:2,Parameter:3 (RGB). FUNCTION 33 Read Pixel GFXGraphicsCommand(33,DCOMMAND); DOCUMENTATION Read a single pixel at the screen coordinates specified - in \Param{0,1},\Param{2,3} (X,Y). - When the routine completes, the result will be in \Param{0}. If sprites are in use, this will be the + in Parameters:0,1,Parameters:2,3 (X,Y). + When the routine completes, the result will be in Parameter:0. If sprites are in use, this will be the background only (0..15), if sprites are not in use it may return (0..255) FUNCTION 34 Reset Palette @@ -106,58 +101,60 @@ GROUP 5 Graphics TMPSelectTileMap(cpuMemory+DSPGetInt16(DCOMMAND,4),DSPGetInt16(DCOMMAND,6),DSPGetInt16(DCOMMAND,8)); DOCUMENTATION Set the current tilemap. - \Param{0,1} is the memory address of the tilemap, - and \Param{2,3},\Param{4,5} (X,Y) specifies the offset into the tilemap, + Parameters:0,1 is the memory address of the tilemap, + and Parameters:2,3,Parameters:4,5 (X,Y) specifies the offset into the tilemap, in units of pixels, of the top-left pixel of the tile. FUNCTION 36 Read Sprite Pixel GFXGraphicsCommand(36,DCOMMAND); DOCUMENTATION Read Pixel from the sprite layer at the screen coordinates - specified in \Param{0,1},\Param{2,3} (X,Y). - When the routine completes, the result will be in \Param{0}. - Refer to Section \#\ref{graphics-colors} "Pixel Colors" for details. + specified in Parameters:0,1,Parameters:2,3 (X,Y). + When the routine completes, the result will be in Parameter:0. + Refer to Section "Pixel Colors" for details. FUNCTION 37 Frame Count *((uint32_t *)DPARAMS) = RNDGetFrameCount(); DOCUMENTATION - Deposit into \Param{0..3}, + Deposit into Parameters:0..3, the number of v-blanks (full screen redraws) which have occurred since power-on. This is updated at the start of each v-blank period. FUNCTION 38 Get Palette GFXGetPalette(DPARAMS[0],&DPARAMS[1],&DPARAMS[2],&DPARAMS[3]); DOCUMENTATION - Get the palette colour at the index spcified in \Param{0}. - Values are returned in \Param{1},\Param{2},\Param{3} (RGB). + Get the palette colour at the index spcified in Parameter:0. + Values are returned in Parameter:1,Parameter:2,Parameter:3 (RGB). FUNCTION 39 Write Pixel GFXSetDrawColour(DPARAMS[4]);GFXGraphicsCommand(5,DCOMMAND); DOCUMENTATION - Write Pixel index \Param{4} to the screen coordinate specified in - \Param{0,1},\Param{2,3} (X,Y). + Write Pixel index Parameter:4 to the screen coordinate specified in + Parameters:0,1,Parameters:2,3 (X,Y). FUNCTION 64 Set Color GFXSetDrawColour(DPARAMS[0]); DOCUMENTATION Set Color - \newline Sets the current drawing colour to \Param{0} + Sets the current drawing colour to Parameter:0 FUNCTION 65 Set Solid Flag GFXSetSolidFlag(DPARAMS[0]); DOCUMENTATION Set Solid Flag - \newline Sets the solid flag to \Param{0}, which indicates either solid fill (for shapes) or solid background (for images and fonts) + + Sets the solid flag to Parameter:0, which indicates either solid fill (for shapes) or solid background (for images and fonts) FUNCTION 66 Set Draw Size GFXSetDrawSize(DPARAMS[0]); DOCUMENTATION Set Draw Size - \newline Sets the drawing scale for images and fonts to \Param{0} + + Sets the drawing scale for images and fonts to Parameter:0 FUNCTION 67 Set Flip Bits GFXSetFlipBits(DPARAMS[0]); DOCUMENTATION Set Flip Bits - \newline Sets the flip bits for drawing images. Bit 0 set causes a horizontal flip, bit 1 set causes a vertical flip. + Sets the flip bits for drawing images. Bit 0 set causes a horizontal flip, bit 1 set causes a vertical flip. diff --git a/firmware/common/config/display/group6_sprites.inc b/firmware/common/config/display/group6_sprites.inc index 462eb8c21..61ffa74ec 100644 --- a/firmware/common/config/display/group6_sprites.inc +++ b/firmware/common/config/display/group6_sprites.inc @@ -26,30 +26,29 @@ GROUP 6 Sprites FUNCTION 2 Sprite Set *DERROR = SPRUpdate(DPARAMS); DOCUMENTATION - Set or update the sprite specified in \Param{0}. - \newline - \ParamsBytes{Sprite Parameters}{Sprite}{X lo}{X hi}{Y lo}{Y hi}{Image}{Flip}{Anchor} - \newline - \SpriteParamBits{$FF09 - Image Parameters}{0}{32-bit}{Index} - \newline - \ParamBits{$FF0A - Flip Axis Flags}{0}{0}{0}{0}{0}{0}{Vertical}{Horizontal} - \newline values that are $80 or $8080 are not updated. + Set or update the sprite specified in Parameter:0. + + The parameters are : Sprite Number, X Low, X High, Y Low, Y High, Image, Flip and Anchor and Flags + + Bit 0 of flags specifies 32 bit sprites. + + Values that are $80 or $8080 are not updated. FUNCTION 3 Sprite Hide SPRHide(DPARAMS); DOCUMENTATION - Hide the sprite specified in \Param{0}. + Hide the sprite specified in Parameter:0. FUNCTION 4 Sprite Collision DPARAMS[0] = SPRCollisionCheck(DERROR,DPARAMS[0],DPARAMS[1],DPARAMS[2]); DOCUMENTATION - \Param{0} is non-zero if the distance is less than or equal to \Param{2} - between the center of the sprite with index specified in \Param{0} - and the center of the sprite with index specified in \Param{1} . + Parameter:0 is non-zero if the distance is less than or equal to Parameter:2 + between the center of the sprite with index specified in Parameter:0 + and the center of the sprite with index specified in Parameter:1 . FUNCTION 5 Sprite Position *DERROR = SPRGetSpriteData(DPARAMS); DOCUMENTATION - Deposit into \Param{1..4}, the screen coordinates of the sprite - with the index specified in \Param{0}. + Deposit into Parameters:1..4, the screen coordinates of the sprite + with the index specified in Parameter:0. diff --git a/firmware/common/config/display/group9_turtle.inc b/firmware/common/config/display/group9_turtle.inc index c7c853c71..04e7740a4 100644 --- a/firmware/common/config/display/group9_turtle.inc +++ b/firmware/common/config/display/group9_turtle.inc @@ -22,20 +22,20 @@ GROUP 9 Turtle Graphics TTLInitialise(DPARAMS[0]); DOCUMENTATION Initialise the turtle graphics system. - \Param{0} is the sprite number to use for the turtle, + Parameter:0 is the sprite number to use for the turtle, as the turtle graphics system “adopts” one of the sprites. The icon is not currently re-definable, and initially the turtle is hidden. FUNCTION 2 Turtle Turn TTLRotate(DSPGetInt16(DCOMMAND,4)); DOCUMENTATION - Turn the turtle right by \Param{0}\Param{1} degrees. Show if hidden. To turn left, turn by a negative amount. + Turn the turtle right by Parameter:0,1 degrees. Show if hidden. To turn left, turn by a negative amount. FUNCTION 3 Turtle Move TTLMove(DSPGetInt16(DCOMMAND,4),DCOMMAND[6],DCOMMAND[7]); DOCUMENTATION - Move the turtle forward by \Param{0}\Param{1} degrees, drawing in colour \Param{2}, - pen down flag in \Param{3}. Show if hidden. + Move the turtle forward by Parameter:0,1 degrees, drawing in colour Parameter:2, + pen down flag in Parameter:3. Show if hidden. FUNCTION 4 Turtle Hide TTLHide(); diff --git a/firmware/common/config/mathematics/group4_binary.inc b/firmware/common/config/mathematics/group4_binary.inc index bdaf38389..e6eadf34f 100644 --- a/firmware/common/config/mathematics/group4_binary.inc +++ b/firmware/common/config/mathematics/group4_binary.inc @@ -87,6 +87,6 @@ } *DPARAMS = r; DOCUMENTATION - \Param{0} := Register 1 compare Register2 : returns $FF, 0, 1 for less equal and greater. - \newline + Parameter:0 := Register 1 compare Register2 : returns $FF, 0, 1 for less equal and greater. + Note: float comparison is approximate because of rounding. diff --git a/firmware/common/config/mathematics/group4_other.inc b/firmware/common/config/mathematics/group4_other.inc index ee774901d..e4c9fd40d 100644 --- a/firmware/common/config/mathematics/group4_other.inc +++ b/firmware/common/config/mathematics/group4_other.inc @@ -20,12 +20,12 @@ FUNCTION 33 String to Number MATHConvertStringToNumber(DCOMMAND); DOCUMENTATION - Convert the length prefixed string at \Param{4,5} to a constant in Register1. + Convert the length prefixed string at Parameters:4,5 to a constant in Register1. FUNCTION 34 Number to String MATHConvertNumberToString(DCOMMAND); DOCUMENTATION - Convert the constant in Register1 to a length prefixed string which is stored at \Param{4,5} + Convert the constant in Register1 to a length prefixed string which is stored at Parameters:4,5 FUNCTION 35 Set Degree/Radian Mode MATHSetAngleMeasure(DPARAMS[0] != 0); diff --git a/firmware/common/config/miscellany/group11_mouse.inc b/firmware/common/config/miscellany/group11_mouse.inc index f28d12e2e..8491f6b53 100644 --- a/firmware/common/config/miscellany/group11_mouse.inc +++ b/firmware/common/config/miscellany/group11_mouse.inc @@ -20,27 +20,27 @@ GROUP 11 Mouse FUNCTION 1 Move display cursor MSESetPosition(DSPGetInt16(DCOMMAND,4),DSPGetInt16(DCOMMAND,6)); DOCUMENTATION - Positions the display cursor at \Param{0,1},\Param{2,3} + Positions the display cursor at Parameters:0,1,Parameters:2,3 FUNCTION 2 Set mouse display cursor on/off MSESetVisible(DCOMMAND[4] != 0); DOCUMENTATION - Shows or hides the mouse cursor depending on the \Param{0} + Shows or hides the mouse cursor depending on the Parameter:0 FUNCTION 3 Get mouse state MSEGetState((uint16_t*)DPARAMS, (uint16_t*)(DPARAMS + 2), DPARAMS + 4, DPARAMS + 5); DOCUMENTATION - Returns the mouse position (screen pixel, unsigned) in x \Param{0,1} and y \Param{2,3}, - buttonstate in \Param{4} (button 1 is 0x1, button 2 0x2 etc., set when pressed), - scrollwheelstate in \Param{5} as uint8 which changes according to scrolls. + Returns the mouse position (screen pixel, unsigned) in x Parameters:0,1 and y Parameters:2,3, + buttonstate in Parameter:4 (button 1 is 0x1, button 2 0x2 etc., set when pressed), + scrollwheelstate in Parameter:5 as uint8 which changes according to scrolls. FUNCTION 4 Test mouse present *DPARAMS = MSEMousePresent() ? 1 : 0; DOCUMENTATION - Returns non zero if a mouse is plugged in in \Param{0} + Returns non zero if a mouse is plugged in in Parameter:0 FUNCTION 5 Select mouse Cursor *DERROR = CURSetCurrent(DPARAMS[0]); DOCUMENTATION - Select a mouse cursor in \Param{0} ; returns error status if the cursor is not available. + Select a mouse cursor in Parameter:0 ; returns error status if the cursor is not available. \ No newline at end of file diff --git a/firmware/common/config/miscellany/group7_controller.inc b/firmware/common/config/miscellany/group7_controller.inc index a58bd8ed5..3d49585ed 100644 --- a/firmware/common/config/miscellany/group7_controller.inc +++ b/firmware/common/config/miscellany/group7_controller.inc @@ -26,21 +26,22 @@ GROUP 7 Controller } DOCUMENTATION - This reads the status of the base controller into \Param{0}, and is a compatibility + This reads the status of the base controller into Parameter:0, and is a compatibility API call. \newline The base controller is the keyboard keys (these are WASD+OPKL or Arrow Keys+ZXCV) or the gamepad controller buttons. Either works. - \newline - \ParamBits{$FF04 - Controller Flags}{Y}{X}{B}{A}{Down}{Up}{Right}{Left} + The 8 bits of the returned byte are the following buttons, most significant first : + + Y X B A Down Up Right Left FUNCTION 2 Read Controller Count *DPARAMS = GMPGetControllerCount(); DOCUMENTATION - This returns the number of game controllers plugged in to the USB System into \Param{0}. This does not include the + This returns the number of game controllers plugged in to the USB System into Parameter:0. This does not include the keyboard based controller, only physical controller hardware. FUNCTION 3 Read Controller @@ -57,8 +58,8 @@ GROUP 7 Controller This returns a specific controller status. Controller 0 is the keyboard controller, Controllers 1 upwards are those physical USB devices. - This returns a 32 bit value in \Param{0..3} which currently is compatible with function 1, but allows for expansion. + This returns a 32 bit value in Parameters:0..3 which currently is compatible with function 1, but allows for expansion. - \newline - \ParamBits{$FF04 - Controller Flags}{Y}{X}{B}{A}{Down}{Up}{Right}{Left} + The 8 bits of the returned byte are the following buttons, most significant first : + Y X B A Down Up Right Left diff --git a/firmware/common/config/miscellany/group8_sound.inc b/firmware/common/config/miscellany/group8_sound.inc index 8a39723e0..b4c14386f 100644 --- a/firmware/common/config/miscellany/group8_sound.inc +++ b/firmware/common/config/miscellany/group8_sound.inc @@ -27,7 +27,7 @@ GROUP 8 Sound FUNCTION 2 Reset Channel *DERROR = SNDResetChannel(*DPARAMS); DOCUMENTATION - Reset the sound channel specified in \Param{0}. + Reset the sound channel specified in Parameter:0. FUNCTION 3 Beep SNDStartup(); @@ -40,24 +40,23 @@ GROUP 8 Sound su.slide = DSPGetInt16(DCOMMAND,9); *DERROR = SNDPlay(DPARAMS[0],&su); DOCUMENTATION - Queue a sound. - Refer to Section \#\ref{sound} "Sound" for details. - \newline - \ParamsBytes{Queue Sound Parameters}{Chan}{Frq hi}{Frq lo}{Dur lo} - {Dur hi}{Sld lo}{Sld hi}{Source} + Queue a sound. Refer to Section \#\ref{sound} "Sound" for details. + + The parameters are : Channel, Frequency Low, Frequency High, + Duration Low, Duration High, Slide Low, Slide High and Source. FUNCTION 5 Play Sound *DERROR = SFXPlay(DPARAMS[0],DPARAMS[1]); DOCUMENTATION - Play the sound effect specified in \Param{1} - on the channel specified in \Param{0} immediately, clearing the channel queue. + Play the sound effect specified in Parameter:1 + on the channel specified in Parameter:0 immediately, clearing the channel queue. FUNCTION 6 Sound Status i1 = SNDGetNoteCount(DPARAMS[0]); DPARAMS[0] = i1 & 0xFF; *DERROR = (i1 < 0) ? 1 : 0; DOCUMENTATION - Deposit in \Param{0} the number of notes outstanding before silence - in the queue of the channel specified in \Param{0}, + Deposit in Parameter:0 the number of notes outstanding before silence + in the queue of the channel specified in Parameter:0, including the current playing sound, if any. diff --git a/firmware/common/config/system/group10_uext.inc b/firmware/common/config/system/group10_uext.inc index e81ae9eea..f9cd53ed5 100644 --- a/firmware/common/config/system/group10_uext.inc +++ b/firmware/common/config/system/group10_uext.inc @@ -27,7 +27,7 @@ GROUP 10 UExt I/O FUNCTION 2 Write GPIO *DERROR = IOWrite(DPARAMS[0],DPARAMS[1] != 0); DOCUMENTATION - This copies the value \Param{1} to the output latch for UEXT pin \Param{0}. + This copies the value Parameter:1 to the output latch for UEXT pin Parameter:0. This will only display on the output pin if it is enabled, and its direction is set to "Output" direction. @@ -35,28 +35,28 @@ GROUP 10 UExt I/O *DERROR = IORead(DPARAMS[0],&b1); DPARAMS[0] = b1 ? 0xFF:0; DOCUMENTATION - If the pin is set to "Input" direction, reads the level on pin on UEXT port \Param{0}. - If it is set to "Output" direction, reads the output latch for pin on UEXT port \Param{0}. - If the read is successful, the result will be in \Param{0}. + If the pin is set to "Input" direction, reads the level on pin on UEXT port Parameter:0. + If it is set to "Output" direction, reads the output latch for pin on UEXT port Parameter:0. + If the read is successful, the result will be in Parameter:0. FUNCTION 4 Set Port Direction *DERROR = IOSetDirection(DPARAMS[0],DPARAMS[1]); DOCUMENTATION - Set the port direction for UEXT Port \Param{0} to the value in \Param{1}. + Set the port direction for UEXT Port Parameter:0 to the value in Parameter:1. This can be $01 (Input), $02 (Output), or $03 (Analogue Input). FUNCTION 5 Write I2C *DERROR = IOI2CWriteRegister(DPARAMS[0],DPARAMS[1],DPARAMS[2]); DOCUMENTATION - Write to I2C Device \Param{0}, Register \Param{1}, value \Param{2}. + Write to I2C Device Parameter:0, Register Parameter:1, value Parameter:2. No error is flagged if the device is not present. FUNCTION 6 Read I2C *DERROR = IOI2CReadRegister(DPARAMS[0],DPARAMS[1],&u2); DPARAMS[0] = u2; DOCUMENTATION - Read from I2C Device \Param{0}, Register \Param{1}. - If the read is successful, the result will be in \Param{0}. + Read from I2C Device Parameter:0, Register Parameter:1. + If the read is successful, the result will be in Parameter:0. If the device is not present, this will flag an error. Use FUNCTION 10,2 first, to check for its presence. @@ -64,63 +64,63 @@ GROUP 10 UExt I/O *DERROR = IOReadAnalogue(DPARAMS[0],&u3); DPARAMS[0] = u3 & 0xFF;DPARAMS[1] = (u3 >> 8); DOCUMENTATION - Read the analogue value on UEXT Pin \Param{0}. + Read the analogue value on UEXT Pin Parameter:0. This has to be set to analogue type to work. - Returns a value from 0..4095 stored in \Param{0,1}, + Returns a value from 0..4095 stored in Parameters:0,1, which represents an input value of 0 to 3.3 volts. FUNCTION 8 I2C Status DPARAMS[0] = (IOI2CReadBlock(DPARAMS[0],&u2,1) == 0) ? 1 : 0; DOCUMENTATION - Try to read from I2C Device \Param{0}. - If present, then \Param{0} will contain a non-zero value. + Try to read from I2C Device Parameter:0. + If present, then Parameter:0 will contain a non-zero value. FUNCTION 9 Read I2C Block *DERROR = IOI2CReadBlock(DPARAMS[0],cpuMemory+DSPGetInt16(DCOMMAND,5),DSPGetInt16(DCOMMAND,7)); DOCUMENTATION - Try to read a block of memory from I2C Device \Param{0} into memory - at \Param{1,2}, length \Param{3,4}. + Try to read a block of memory from I2C Device Parameter:0 into memory + at Parameters:1,2, length Parameters:3,4. FUNCTION 10 Write I2C Block *DERROR = IOI2CWriteBlock(DPARAMS[0],cpuMemory+DSPGetInt16(DCOMMAND,5),DSPGetInt16(DCOMMAND,7)); DOCUMENTATION - Try to write a block of memory to I2C Device \Param{0} from memory - at \Param{1,2}, length \Param{3,4}. + Try to write a block of memory to I2C Device Parameter:0 from memory + at Parameters:1,2, length Parameters:3,4. FUNCTION 11 Read SPI Block *DERROR = IOSPIReadBlock(cpuMemory+DSPGetInt16(DCOMMAND,5),DSPGetInt16(DCOMMAND,7)); DOCUMENTATION Try to read a block of memory from SPI Device into memory - at \Param{1,2}, length \Param{3,4}. + at Parameters:1,2, length Parameters:3,4. FUNCTION 12 Write SPI Block *DERROR = IOSPIWriteBlock(cpuMemory+DSPGetInt16(DCOMMAND,5),DSPGetInt16(DCOMMAND,7)); DOCUMENTATION Try to write a block of memory to SPI Device from memory - at \Param{1,2}, length \Param{3,4}. + at Parameters:1,2, length Parameters:3,4. FUNCTION 13 Read UART Block *DERROR = IOUARTReadBlock(cpuMemory+DSPGetInt16(DCOMMAND,5),DSPGetInt16(DCOMMAND,7)); DOCUMENTATION Try to read a block of memory from UART into memory - at \Param{1,2}, length \Param{3,4}. This can fail with a timeout. + at Parameters:1,2, length Parameters:3,4. This can fail with a timeout. FUNCTION 14 Write UART Block *DERROR = IOUARTWriteBlock(cpuMemory+DSPGetInt16(DCOMMAND,5),DSPGetInt16(DCOMMAND,7)); DOCUMENTATION Try to write a block of memory to UART from memory - at \Param{1,2}, length \Param{3,4}. + at Parameters:1,2, length Parameters:3,4. FUNCTION 15 Set UART Speed and Protocol *DERROR = 0;IOUARTInitialise(DSPGetInt16(DCOMMAND,4)+(DSPGetInt16(DCOMMAND,6) << 16),DPARAMS[4]); DOCUMENTATION - Set the Baud Rate and Serial Protocol for the UART interface. The baud rate is in \Param{0,1,2,3} - and the protocol number is \Param{4}. Currently only 8N1 is supported, this is protocol 0. + Set the Baud Rate and Serial Protocol for the UART interface. The baud rate is in Parameters:0..3 + and the protocol number is Parameter:4. Currently only 8N1 is supported, this is protocol 0. FUNCTION 16 Write byte to UART *DERROR = 0;SERWriteByte(DPARAMS[0]); DOCUMENTATION - Write byte \Param{0} to the UART + Write byte Parameter:0 to the UART FUNCTION 17 Read byte from UART if (SERIsByteAvailable()) { @@ -130,9 +130,9 @@ GROUP 10 UExt I/O *DERROR = 1; } DOCUMENTATION - Read a byte from the UART. It is returned in \Param{0} + Read a byte from the UART. It is returned in Parameter:0 FUNCTION 18 Check if Byte Available DPARAMS[0] = SERIsByteAvailable() ? 1 : 0; DOCUMENTATION - See if a byte is available in the UART input buffer. If available \Param{0} is non zero. \ No newline at end of file + See if a byte is available in the UART input buffer. If available Parameter:0 is non zero. \ No newline at end of file diff --git a/firmware/common/config/system/group12_blitter.inc b/firmware/common/config/system/group12_blitter.inc index 85f1e1c65..5c3774c27 100644 --- a/firmware/common/config/system/group12_blitter.inc +++ b/firmware/common/config/system/group12_blitter.inc @@ -20,13 +20,13 @@ GROUP 12 Blitter FUNCTION 1 Blitter Busy DPARAMS[0] = 0; DOCUMENTATION - Returns a non zero value in \Param{1} if the blitter/DMA system is currently transferring data, used to check availability + Returns a non zero value in Parameter:1 if the blitter/DMA system is currently transferring data, used to check availability and transfer completion. FUNCTION 2 Simple Blit Copy *DERROR = BLTSimpleCopy(DPARAMS[0],DSPGetInt16(DCOMMAND,5),DPARAMS[3],DSPGetInt16(DCOMMAND,8),DSPGetInt16(DCOMMAND,10)); DOCUMENTATION - Copy \Param{6,7} bytes of internal memory from \Param{0}:\Param{1,2} to \Param{3}:\Param{4,5}. Sets error flag if the transfer is not + Copy Parameters:6,7 bytes of internal memory from Parameter:0:Parameters:1,2 to Parameter:3:Parameters:4,5. Sets error flag if the transfer is not possible (e.g. illegal write addresses). The upper 8 bits of the address are : 6502 RAM (00) VideoRAM (80,81) Graphics RAM(90) diff --git a/firmware/common/config/system/group1_system.inc b/firmware/common/config/system/group1_system.inc index 93f834f16..ad15e9eb2 100644 --- a/firmware/common/config/system/group1_system.inc +++ b/firmware/common/config/system/group1_system.inc @@ -26,16 +26,16 @@ GROUP 1 System FUNCTION 1 Timer *((uint32_t *)DPARAMS) = TMRRead(); // (assumes littleendian) DOCUMENTATION - Deposit the value (32-bits) of the 100Hz system timer into \Param{0..3}. + Deposit the value (32-bits) of the 100Hz system timer into Parameters:0..3. FUNCTION 2 Key Status i1 = DPARAMS[0]; DPARAMS[0] = (i1 < KBD_MAX_KEYCODE) ? KBDGetStateArray()[i1] : 0; DPARAMS[1] = KBDGetModifiers(); DOCUMENTATION - Deposits the state of the specified keyboard key into \Param{0}. - State of keyboard modifiers (Shift/Ctrl/Alt/Meta) is returned in \Param{1}. - The key which to query is specified in \Param{0}. + Deposits the state of the specified keyboard key into Parameter:0. + State of keyboard modifiers (Shift/Ctrl/Alt/Meta) is returned in Parameter:1. + The key which to query is specified in Parameter:0. FUNCTION 3 Basic MEMLoadBasic(); @@ -55,13 +55,10 @@ GROUP 1 System FUNCTION 6 Locale LOCSetLocale(DPARAMS[0],DPARAMS[1]); DOCUMENTATION - Set the locale code specified in \Param{0,1} as upper-case ASCII letters. - \Param{0} takes the first letter and \Param{1} takes the second letter. - For example: - \begin{description}\itemsep0pt - \item English:\MonoSp{~\Param{0}\textless-$45} ('E') and \MonoSp{\Param{1}\textless-$4E} ('N') - \item French:\MonoSp{~\Param{0}\textless-$46} ('F') and \MonoSp{\Param{1}\textless-$52} ('R') - \end{description} + Set the locale code specified in Parameters:0,1 as upper-case ASCII letters. + Parameter:0 takes the first letter and Parameter:1 takes the second letter. + + For example: French (FR) would require Parametr 0 being $46 and Parameter 1 being $52 FUNCTION 7 System Reset ResetSystem(); diff --git a/firmware/common/config/system/group3_fileio.inc b/firmware/common/config/system/group3_fileio.inc index b06eb4cbf..4cfbca2d1 100644 --- a/firmware/common/config/system/group3_fileio.inc +++ b/firmware/common/config/system/group3_fileio.inc @@ -28,58 +28,45 @@ GROUP 3 File I/O *DERROR = FIOReadFile(DSPGetStdString(DCOMMAND,4),DSPGetInt16(DCOMMAND,6),DCOMMAND); DOCUMENTATION Load a file by name into memory. On input: - - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed filename string; - \item \Param{2,3} contains the location to write the data to. If the - address is \MonoSp{$FFFF}, the file will instead be loaded into the + + Parameters:0,1 points to the length-prefixed filename string; + Parameters:2,3 contains the location to write the data to. If the + address is $FFFF, the file will instead be loaded into the graphics working memory, used for sprites, tiles, images. - \end{compactitem} - + On output: - - \begin{compactitem} - \item \Param{0} contains an error/status code. - \end{compactitem} + Parameter:0 contains an error/status code. + FUNCTION 3 Store File *DERROR = FIOWriteFile(DSPGetStdString(DCOMMAND,4),DSPGetInt16(DCOMMAND,6),DSPGetInt16(DCOMMAND,8)); DOCUMENTATION Saves data in memory to a file. On input: + + Parameters:0,1 points to the length-prefixed filename string; + Parameters:2,3 contains the location to read data from; + Parameters:4,5 specified the number of bytes to store. - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed filename string; - \item \Param{2,3} contains the location to read data from; - \item \Param{4,5} specified the number of bytes to store. - \end{compactitem} - - On output: - - \begin{compactitem} - \item \Param{0} contains an error/status code. - \end{compactitem} + On output: + Parameter:0 contains an error/status code. + FUNCTION 4 File Open *DERROR = FIOOpenFileHandle(DPARAMS[0],DSPGetStdString(DPARAMS,1),DPARAMS[3]); DOCUMENTATION Opens a file into a specific channel. On input: - - \begin{compactitem} - \item \Param{0} contains the file channel to open; - \item \Param{1,2} points to the length-prefixed filename string; - \item \Param{3} contains the open mode. See below. - \end{compactitem} + + Parameter:0 contains the file channel to open; + Parameters:1,2 points to the length-prefixed filename string; + Parameter:3 contains the open mode. See below. Valid open modes are: - - \begin{compactitem} - \item 0 opens the file for read-only access; - \item 1 opens the file for write-only access; - \item 2 opens the file for read-write access; - \item 3 creates the file if it doesn't already exist, truncates it if it + 0 opens the file for read-only access; + 1 opens the file for write-only access; + 2 opens the file for read-write access; + 3 creates the file if it doesn't already exist, truncates it if it does, and opens the file for read-write access. - \end{compactitem} - + Modes 0 to 2 will fail if the file does not already exist. If the channel is already open, the call fails. Opening the same file more than once on different channels has undefined behaviour, and is not @@ -90,20 +77,16 @@ GROUP 3 File I/O DOCUMENTATION Closes a particular channel. On input: - \begin{compactitem} - \item \Param{0} contains the file channel to close. - \end{compactitem} - + Parameter:0 contains the file channel to close. + FUNCTION 6 File Seek *DERROR = FIOSeekFileHandle(DPARAMS[0],DSPGetInt32(DPARAMS,1)); DOCUMENTATION Seeks the file opened on a particular channel to a location. On input: - - \begin{compactitem} - \item \Param{0} contains the file channel to operate on; - \item \Param{1,2,3,4} contains the file location. - \end{compactitem} - + + Parameter:0 contains the file channel to operate on; + Parameters:1..4 contains the file location. + You can seek beyond the end of a file to extend the file. However, whether the file size changes when the seek happens, or when you perform the write is undefined behavior. @@ -116,16 +99,13 @@ GROUP 3 File I/O } DOCUMENTATION Returns the current seek location for the file opened on a particular channel. On input: - - \begin{compactitem} - \item \Param{0} contains the file channel to operate on. - \end{compactitem} - + + Parameter:0 contains the file channel to operate on. + On output: - - \begin{compactitem} - \item \Param{1,2,3,4} contains the seek location within the file. - \end{compactitem} + + Parameters:1..4 contains the seek location within the file. + FUNCTION 8 File Read { @@ -135,19 +115,15 @@ GROUP 3 File I/O } DOCUMENTATION Reads data from an opened file. On input: - - \begin{compactitem} - \item \Param{0} contains the file channel to operate on. - \item \Param{1,2} points to the destination in memory, - or \MonoSp{$FFFF} to read into graphics memory. - \item \Param{2,3} contains the amount of data to read. - \end{compactitem} + + Parameter:0 contains the file channel to operate on. + Parameters:1,2 points to the destination in memory, + or $FFFF to read into graphics memory. + Parameters:2,3 contains the amount of data to read. On output: - - \begin{compactitem} - \item \Param{3,4} is updated to contain the amount of data actually read. - \end{compactitem} + + Parameters:3,4 is updated to contain the amount of data actually read. Data is read from the current seek position, which is advanced after the read. @@ -159,18 +135,14 @@ GROUP 3 File I/O } DOCUMENTATION Writes data to an opened file. On input: - - \begin{compactitem} - \item \Param{0} contains the file channel to operate on; - \item \Param{1,2} points to the data in memory; - \item \Param{3,4} contains the amount of data to write. - \end{compactitem} - - On output: - - \begin{compactitem} - \item \Param{3,4} is updated to contain the amount of data actually written. - \end{compactitem} + + Parameter:0 contains the file channel to operate on; + Parameters:1,2 points to the data in memory; + Parameters:3,4 contains the amount of data to write. + + On output: + Parameters:3,4 is updated to contain the amount of data actually written. + Data is written to the current seek position, which is advanced after the write. @@ -182,17 +154,12 @@ GROUP 3 File I/O } DOCUMENTATION Returns the current size of an opened file. On input: - - \begin{compactitem} - \item \Param{0} contains the file channel to operate on. - \end{compactitem} + + Parameter:0 contains the file channel to operate on. On output: - - \begin{compactitem} - \item \Param{1,2,3,4} contains the size of the file. - \end{compactitem} - + Parameters:1..4 contains the size of the file. + This call should be used on open files, and takes into account any buffered data which has not yet been written to disk. Consequently, this may return a different size than Function 3,16 "File Stat". @@ -203,11 +170,10 @@ GROUP 3 File I/O } DOCUMENTATION Extends or truncates an opened file to a particular size. On input: - - \begin{compactitem} - \item \Param{0} contains the file channel to operate on; - \item \Param{1,2,3,4} contains the new size of the file. - \end{compactitem} + + Parameter:0 contains the file channel to operate on; + Parameters:1..4 contains the new size of the file. + FUNCTION 12 File Rename { @@ -216,10 +182,8 @@ GROUP 3 File I/O DOCUMENTATION Renames a file. On input: - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed string for the old name; - \item \Param{2,3} points to the length-prefixed string for the new name. - \end{compactitem} + Parameters:0,1 points to the length-prefixed string for the old name; + Parameters:2,3 points to the length-prefixed string for the new name. Files may be renamed across directories. @@ -229,10 +193,8 @@ GROUP 3 File I/O } DOCUMENTATION Deletes a file or directory. On input: - - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed filename string. - \end{compactitem} + + Parameters:0,1 points to the length-prefixed filename string. Deleting a file which is open has undefined behaviour. Directories may only be deleted if they are empty. @@ -244,9 +206,7 @@ GROUP 3 File I/O DOCUMENTATION Creates a new directory. On input: - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed filename string. - \end{compactitem} + Parameters:0,1 points to the length-prefixed filename string. FUNCTION 15 Change Directory { @@ -254,10 +214,8 @@ GROUP 3 File I/O } DOCUMENTATION Changes the current working directory. On input: - - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed path string. - \end{compactitem} + + Parameters:0,1 points to the length-prefixed path string. FUNCTION 16 File Stat { @@ -269,25 +227,18 @@ GROUP 3 File I/O } DOCUMENTATION Retrieves information about a file by name. On input: + + Parameters:0,1 points to the length-prefixed filename string. - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed filename string. - \end{compactitem} - - On output: - - \begin{compactitem} - \item \Param{0,1,2,3} contains the length of the file; - \item \Param{4} contains the attributes bit-field of the file. - \end{compactitem} - + Parameters:0..3 contains the length of the file; + Parameter:4 contains the attributes bit-field of the file. + If the file is open for writing, this may not return the correct size due to buffered data not having been flushed to disk. - File attributes are a bitfield as follows: + File attributes are a bitfield as follows: 0,0,0,Hidden, Read Only, Archive, + System, Directory. - \newline - \ParamBits{File attributes}{0}{0}{0}{Hidden}{Read only}{Archive}{System}{Directory} FUNCTION 17 Open Directory { @@ -296,9 +247,7 @@ GROUP 3 File I/O DOCUMENTATION Opens a directory for enumeration. On input: - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed filename string. - \end{compactitem} + Parameters:0,1 points to the length-prefixed filename string. Only one directory at a time may be opened. If a directory is already open when this call is made, it is automatically closed. However, an @@ -318,16 +267,12 @@ GROUP 3 File I/O DOCUMENTATION Reads an item from the currently open directory. On input: - \begin{compactitem} - \item \Param{0,1} points to a length-prefixed buffer for returning the filename. - \end{compactitem} - - \begin{compactitem} - \item \Param{0,1} is unchanged, but the buffer is updated to contain the + Parameters:0,1 points to a length-prefixed buffer for returning the filename. + + Parameters:0,1 is unchanged, but the buffer is updated to contain the length-prefixed filename (without any leading path); - \item \Param{2,3,4,5} contains the length of the file; - \item \Param{6} contains the file attributes, as described by Function 3,16 "File Stat". - \end{compactitem} + Parameters:2..5 contains the length of the file; + Parameter:6 contains the file attributes, as described by Function 3,16 "File Stat". If there are no more items to read, this call fails and an error is flagged. @@ -342,34 +287,28 @@ GROUP 3 File I/O *DERROR = FIOCopyFile(DSPGetStdString(DPARAMS, 0), DSPGetStdString(DPARAMS, 2)); DOCUMENTATION Copies a file. On input: - - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed old filename; - \item \Param{2,3} points to the length-prefixed new filename. - \end{compactitem} - + + Parameters:0,1 points to the length-prefixed old filename; + Parameters:2,3 points to the length-prefixed new filename. + Only single files may be copied, not directories. FUNCTION 21 Set file attributes *DERROR = FIOSetFileAttributes(DSPGetStdString(DPARAMS, 0), DPARAMS[2]); DOCUMENTATION Sets the attributes for a file. On input: - - \begin{compactitem} - \item \Param{0,1} points to the length-prefixed filename; - \item \Param{2} is the attribute bitfield. (See Stat File for details.) - \end{compactitem} - + + Parameters:0,1 points to the length-prefixed filename; + Parameter:2 is the attribute bitfield. (See Stat File for details.) + The directory bit cannot be changed. Obviously. FUNCTION 32 List Filtered FIODirectory(DSPGetString(DCOMMAND,4)); DOCUMENTATION Prints a filtered file listing of the current directory to the console. On input: - - \begin{compactitem} - \item \Param{0,1} points to the filename search string. - \end{compactitem} - + + Parameters:0,1 points to the filename search string. + Files will only be shown if the name contains the search string (ie: a substring match). diff --git a/firmware/common/scripts/makedispatch.py b/firmware/common/scripts/makedispatch.py index 77421edda..52b9074ba 100755 --- a/firmware/common/scripts/makedispatch.py +++ b/firmware/common/scripts/makedispatch.py @@ -27,8 +27,7 @@ DOCS_DIR = os.path.join(ROOT_DIR , 'documents' , 'release' , 'source') CFG_DIR = os.path.join(ROOT_DIR , 'firmware' , 'common' , 'config' ) CFG_FILE = os.path.join(CFG_DIR , 'dispatch.config' ) -TEX_IN_FILE = os.path.join(DOCS_DIR , 'api.tex.in' ) -TEX_OUT_FILE = os.path.join(DOCS_DIR , 'api.tex' ) +TEX_OUT_FILE = os.path.join(DOCS_DIR , 'api.gen.md' ) ANCHORS = ( 'GROUP' , 'FUNCTION' , 'DOCUMENTATION' ) @@ -199,45 +198,31 @@ def renderTableHead(self,fn_table_tex,header): def renderTableTail(self,fn_table_tex): fn_table_tex.append('\\end{longtable*}') + def replaceParam(self,txt,oldDesc,newDesc): + return txt.replace("\\Param{"+oldDesc+"}","Parameters:"+newDesc) + # generate documentation source from template def renderDocs(self): group_ids = sorted(self.groups) - fn_table_tex = [] + fn_table_tex = ['---','fontfamilyoptions: sfdefault','fontsize: 12pt','---',''] - fn_table_tex.append('% makedispatch: BEGIN') for group_id in group_ids: group = self.groups[group_id] fn_ids = sorted(group.functions) - header = "Group %s - %s Functions" % (group_id , group.groupName) - # fn_ids = sorted([ fn_id for fn_id in group.functions.keys() ]) - - if group_id != group_ids[0]: - fn_table_tex.append('\\pagebreak') - self.renderTableHead(fn_table_tex , header) - + fn_table_tex.append("# Group {0} : {1}".format(group_id,group.groupName)) + fn_ids = sorted([ fn_id for fn_id in group.functions.keys() ]) for fn_id in fn_ids: - function = group.functions[fn_id] - fn_name = function.funcName - docLines = function.docLines if function.docLines[-1] else function.docLines[0:-2] - - fn_table_tex.append('\\ApiFnRow{%s}{%s}{' % (fn_id , fn_name)) - fn_table_tex.extend([ '\n'.join(docLines) , '}' ]) + function = group.functions[fn_id] + fn_name = function.funcName + fn_table_tex.append("## Function {0} : {1}".format(fn_id,fn_name)) + docLines = function.docLines if function.docLines[-1] else function.docLines[0:-2] + desc = " ".join(docLines) + fn_table_tex.append(desc) + fn_table_tex.append("\\newpage") - self.renderTableTail(fn_table_tex) - fn_table_tex.extend([ '' , '% makedispatch: END' , '' ]) - - with open(TEX_IN_FILE , 'r' , encoding='utf-8' ) as texi_file: - tex_in_lines = texi_file.readlines() with open(TEX_OUT_FILE , 'w' , encoding='utf-8' , newline='\n') as texi_file: - rev_date = str(date.fromtimestamp(os.stat(CFG_FILE).st_ctime)) - tex_subst = '\n'.join(fn_table_tex).replace(r'$' , '\$').replace('\\' , r'\\') - - texi_file.write('%\n% This file is automatically generated\n%\n\n\n') - for tex_in_line in tex_in_lines: - tex_out = re.sub(r'@DATE@' , rev_date , tex_in_line) - tex_out = re.sub(r'@FN_TABLES@' , tex_subst , tex_out ) - - texi_file.write(tex_out) + for tex_in_line in fn_table_tex: + texi_file.write(tex_in_line+"\n\n") def sendFile(self , in_file): # accept input file as path or filename - no assumption of PWD diff --git a/release/Makefile b/release/Makefile index f9d9a849a..9e3547998 100644 --- a/release/Makefile +++ b/release/Makefile @@ -82,11 +82,7 @@ all: documentation # *************************************************************************************** documentation: - # generate ODTs (requires 'pandoc') - pandoc -f latex -t odt -o $(DOCDIR)api.odt $(DOCDIR)source$(S)api.tex - # generate PDFs (requires 'texlive-latex', 'texlive-latexextra', 'texlive-latex-recommended') - # Yes, twice! The TOC and tables require two passes - pdflatex -output-directory=$(DOCDIR) $(DOCDIR)source$(S)api.tex - pdflatex -output-directory=$(DOCDIR) $(DOCDIR)source$(S)api.tex # generate BASIC PDF (requires 'pandoc') pandoc $(DOCDIR)basic.md -o $(DOCDIR)basic.pdf + # generate API PDF (requires 'pandoc') + pandoc $(DOCDIR)api.md $(DOCDIR)source$(S)api.gen.md -o $(DOCDIR)api.pdf