From bf6a5efd7e011350b1ba1d91a8fdfdf5b2bb6ea8 Mon Sep 17 00:00:00 2001 From: "matthias@quintern.xyz" Date: Thu, 8 Aug 2024 20:39:25 +0200 Subject: [PATCH] fix doc format --- .doxygen_config | 2 +- .extra_docs.s65 | 5 ++ programs/memcopy.s65 | 4 +- programs/print_slow.s65 | 2 +- programs/ps2_keyboard_simple_handler.s65 | 2 +- programs/ps2_keyboard_text_handler.s65 | 4 +- programs/sleep.s65 | 4 +- spicode.s65 | 2 +- system/buffer.h65 | 60 +++++++++++++----------- system/io_W65C22.h65 | 6 +-- system/irq_handler.h65 | 4 +- system/keypad.h65 | 2 +- system/lcd.h65 | 4 +- system/lcd.s65 | 6 +-- system/ps2_keyboard.h65 | 6 +-- system/ps2_keyboard.s65 | 26 +++++----- system/spi.h65 | 2 +- system/system.h65 | 32 +++++++------ util/parity.h65 | 4 +- util/parity.s65 | 2 +- util/string.h65 | 2 +- util/string.s65 | 2 +- 22 files changed, 98 insertions(+), 85 deletions(-) diff --git a/.doxygen_config b/.doxygen_config index 3df9fd4..9efb390 100644 --- a/.doxygen_config +++ b/.doxygen_config @@ -294,7 +294,7 @@ ALIASES = "modifies=\par Modifies Registers^^" \ "macro=\qualifier macro \brief" \ "function=\qualifier subroutine \brief" \ "module=\file ^^ \brief" \ - "clock_dependant=\xrefitem clock_dependant \"Clock Speed Dependance\" \"Clock frequency dependant code\"" + "clock_dependent=\xrefitem clock_dependant \"Clock Speed Dependence\" \"Clock speed dependent code\"" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For diff --git a/.extra_docs.s65 b/.extra_docs.s65 index f726379..ad2c1cb 100644 --- a/.extra_docs.s65 +++ b/.extra_docs.s65 @@ -65,3 +65,8 @@ ;; ;;******************************************************************************** +;;******************************************************************************** +;; @defgroup system +;; @brief Core code +;; +;;******************************************************************************** diff --git a/programs/memcopy.s65 b/programs/memcopy.s65 index b1b877c..298c152 100644 --- a/programs/memcopy.s65 +++ b/programs/memcopy.s65 @@ -11,7 +11,7 @@ INCLUDE_MEMCOPY = 1 ;; @param ARG0-1: Source address ;; @param ARG2-3: Target address ;; @param Y: Number of bytes to copy -;; @modifies: A,Y +;; @modifies A,Y ;;******************************************************************************** .proc memcopy cpy #0 @@ -31,7 +31,7 @@ INCLUDE_MEMCOPY = 1 ;; @param ARG0-1: Source address ;; @param ARG2-3: Target address ;; @param ARG5-6: Number of bytes to copy (LE) -;; @modifies: A,Y +;; @modifies A,Y ;;******************************************************************************** .proc memcopy16 lda ARG6 diff --git a/programs/print_slow.s65 b/programs/print_slow.s65 index 087ad52..9197c94 100644 --- a/programs/print_slow.s65 +++ b/programs/print_slow.s65 @@ -10,7 +10,7 @@ ;; @param ARG0-1: Address of the string to print ;; @param x: time to sleep in centiseconds ;; @ingroup applications -;; @clock_dependant +;; @clock_dependent ;;******************************************************************************** .proc print_slow ldy #$00 diff --git a/programs/ps2_keyboard_simple_handler.s65 b/programs/ps2_keyboard_simple_handler.s65 index a99e3f5..a52156b 100644 --- a/programs/ps2_keyboard_simple_handler.s65 +++ b/programs/ps2_keyboard_simple_handler.s65 @@ -9,7 +9,7 @@ scancode: .res 1 ;;******************************************************************************** ;; @function Initialize the keyboard handler ;; @returns Z: Z = 1 => success, Z = 0 => failure -;; @details: +;; @details ;; Initializes the PS/2 keyboard driver and the handler. ;; If any PS/2 command fails, init returns with Z = 0. The failed command (and parameter) can be loaded from `ps2kb::send_cmd` and `ps2kb::send_data` ;; After init, the keyboard will be able to send scancodes. diff --git a/programs/ps2_keyboard_text_handler.s65 b/programs/ps2_keyboard_text_handler.s65 index 1102b1a..e14ac9e 100644 --- a/programs/ps2_keyboard_text_handler.s65 +++ b/programs/ps2_keyboard_text_handler.s65 @@ -19,7 +19,7 @@ keycode: .res 1 ;;******************************************************************************** ;; @function Initialize the keyboard handler ;; @returns Z: Z = 1 => success, Z = 0 => failure -;; @details: +;; @details ;; Initializes the PS/2 keyboard driver and the handler. ;; If any PS/2 command fails, init returns with Z = 0. The failed command (and parameter) can be loaded from `ps2kb::send_cmd` and `ps2kb::send_data` ;; After init, the keyboard will be able to send scancodes. @@ -232,7 +232,7 @@ update_leds: ;; @details ;; Unset modifier bits if a mod key is released. ;; @param X: The scancode -;; @modifies: +;; @modifies ;;******************************************************************************** .proc break_key ; rmb kb::PREVIOUS::BREAK, kb::previous_scancode diff --git a/programs/sleep.s65 b/programs/sleep.s65 index ace5cee..2718697 100644 --- a/programs/sleep.s65 +++ b/programs/sleep.s65 @@ -9,9 +9,9 @@ ;; @details ;; Interrupts might change the actual time to finish ;; To be exact, time_cs is in units of 0.010244s -;; @modifies: ARG15 +;; @modifies ARG15 ;; @ingroup applications -;; @clock_dependant +;; @clock_dependent ;;******************************************************************************** .proc sleep _VAR_1 = ARG15 diff --git a/spicode.s65 b/spicode.s65 index 5fa6cda..57e8eeb 100644 --- a/spicode.s65 +++ b/spicode.s65 @@ -1,6 +1,6 @@ ;;******************************************************************************** ;; @file -;; @details: +;; @details ;; This code is loaded to the computer via a SPI interface ;; Currently, it must be loaded to $5000, where the main loop will begin ;;******************************************************************************** diff --git a/system/buffer.h65 b/system/buffer.h65 index 5cccb5c..e530ace 100644 --- a/system/buffer.h65 +++ b/system/buffer.h65 @@ -1,16 +1,20 @@ -;******************************************************************************** -; @module ringbuffer -; @type utility -; @details -; Size of the ringbuffer is RBUF_MEM_END - RBUF_MEM_START - 2, since two bytes -; are used by the read and write pointer -; The RBUF_NAME variable must be defined, the functions will then be exported -; as rb__ where = init, read or write -; @requires -; RBUF_MEM_START: First address of ringbuffer memory space -; RBUF_MEM_END: Last address of ringbuffer memory space -; RBUF_NAME: Name of the ringbuffer -;******************************************************************************** +;;******************************************************************************** +;; @module ringbuffer +;; @details +;; Size of the ringbuffer is RBUF_MEM_END - RBUF_MEM_START - 2, since two bytes +;; are used by the read and write pointer +;; The `RBUF_NAME` variable must be defined, the functions will then be exported +;; as `rb__` where `` = `init`, `read` or `write` +;; +;; @note +;; Doxygen can not generate proper documentation for this module, because +;; all names are defined using macros +;; @requires +;; RBUF_MEM_START: First address of ringbuffer memory space +;; RBUF_MEM_END: Last address of ringbuffer memory space +;; RBUF_NAME: Name of the ringbuffer +;; @ingroup utility +;;******************************************************************************** .code .ifndef RBUF_MEM_START @@ -36,9 +40,9 @@ RB_LENGTH = RBUF_MEM_END - RBUF_MEM_START - 2 .endif -;******************************************************************************** -; @function Initialize the buffer -;******************************************************************************** +;;******************************************************************************** +;; @function Initialize the buffer +;;******************************************************************************** .ident(.concat(_RBUF_NAME, "_init")): .scope stz RB_WRITE @@ -46,13 +50,13 @@ RB_LENGTH = RBUF_MEM_END - RBUF_MEM_START - 2 rts .endscope -;******************************************************************************** -; @function Read a value from the buffer -; @details -; If there is no value to be read, the Pz will be set -; @returns A: value -; @modifies: A, X -;******************************************************************************** +;;******************************************************************************** +;; @function Read a value from the buffer +;; @details +;; If there is no value to be read, the Pz will be set +;; @returns A: value +;; @modifies A, X +;;******************************************************************************** .ident(.concat(_RBUF_NAME, "_read")): .scope ldx RB_READ @@ -72,11 +76,11 @@ RB_LENGTH = RBUF_MEM_END - RBUF_MEM_START - 2 rts .endscope -;******************************************************************************** -; @function Write a value to the buffer -; @param A: value to store -; @modifies: X -;******************************************************************************** +;;******************************************************************************** +;; @function Write a value to the buffer +;; @param A: value to store +;; @modifies X +;;******************************************************************************** .ident(.concat(_RBUF_NAME, "_write")): .scope ; lda kp_VALUES, x ; load the char in a diff --git a/system/io_W65C22.h65 b/system/io_W65C22.h65 index 31d3ba8..3c3eeca 100644 --- a/system/io_W65C22.h65 +++ b/system/io_W65C22.h65 @@ -1,6 +1,6 @@ ;;******************************************************************************** ;; @module IO-W65C22 -;; @type utility +;; @ingroup system ;; @device Western Design - W65C22N Versatile Interface Adapter ;; @details ;;******************************************************************************** @@ -139,7 +139,7 @@ INCLUDE_IOW65C22 = 1 ;;******************************************************************************** ;; @macro Enable an interrupt source -;; @modifies: A +;; @modifies A ;; @param flag: A flag of the interrupt flag register (IO::IRQ) ;;******************************************************************************** .macro IO_EnableIRQ ioaddr, flag @@ -148,7 +148,7 @@ INCLUDE_IOW65C22 = 1 .endmacro ;;******************************************************************************** ;; @macro Disable an interrupt source -;; @modifies: A +;; @modifies A ;; @param flag: A flag of the interrupt flag register (IO::IRQ) ;;******************************************************************************** .macro IO_DisableIRQ ioaddr, flag diff --git a/system/irq_handler.h65 b/system/irq_handler.h65 index 1964091..5a780d4 100644 --- a/system/irq_handler.h65 +++ b/system/irq_handler.h65 @@ -1,6 +1,6 @@ ;;******************************************************************************** -;; @module irq_handler -;; @type system +;; @module WIP irq handler with jump tables and stuff +;; @ingroup system ;;******************************************************************************** .ifndef INCLUDE_IRQ_HANDLER INCLUDE_IRQ_HANDLER = 1 diff --git a/system/keypad.h65 b/system/keypad.h65 index d5582d0..bda0a85 100644 --- a/system/keypad.h65 +++ b/system/keypad.h65 @@ -1,12 +1,12 @@ ;;******************************************************************************** ;; @module keypad4x4 -;; @type driver ;; @device 4x4 Matrix Keypad ;; @details ;; The LCD must be connected to a W65C22N Interface Chip: ;; - IO.RA0-7 -> ;; @requires KP_IO: Base Address of IO Chip ;; @depends IO-W65C22N +;; @ingroup drivers ;;******************************************************************************** .ifndef INCLUDE_KEYPAD INCLUDE_KEYPAD = 1 diff --git a/system/lcd.h65 b/system/lcd.h65 index 3b10363..69f619d 100644 --- a/system/lcd.h65 +++ b/system/lcd.h65 @@ -1,6 +1,6 @@ ;;******************************************************************************** ;; @module LCD-W164B -;; @ingroup driver +;; @ingroup drivers ;; @device ELECTRONIC ASSEMBLY - W164B-NLW ;; @details ;; The LCD must be connected to a W65C22N Interface Chip: @@ -18,7 +18,7 @@ INCLUDE_LCD = 1 ;;******************************************************************************** ;; @brief LCD character display -;; @ingroup driver +;; @ingroup drivers ;;******************************************************************************** .scope lcd LCD_IO = IO1 diff --git a/system/lcd.s65 b/system/lcd.s65 index a419c28..7ed8ec6 100644 --- a/system/lcd.s65 +++ b/system/lcd.s65 @@ -45,7 +45,7 @@ _charcount: .res 1 ;;******************************************************************************** ;; @function Set the cursor to a position ;; @param A: cursor position: `(lcd::LINEX + offset)`, where offset € [$0, $f] -;; @details: +;; @details ;; If the position is too large, it will be set to char 4 in line 2 ;; @returns A: the cursor position ;;******************************************************************************** @@ -109,7 +109,7 @@ _charcount: .res 1 ;;******************************************************************************** ;; @function Print a null-terminated string ;; @param ARG0-1 Address of the string to print -;; @modifies: A,Y +;; @modifies A,Y ;; @returns Y: Length of the string ;;******************************************************************************** .proc print @@ -143,7 +143,7 @@ _charcount: .res 1 ;; @param A: The ASCII code: 0-7 ;; @param ARG0-1: Start address of the 8 bytes describing the character ;; @returns: C: 0 => success, 1 => invalid argument -;; @modifies: A,Y +;; @modifies A,Y ;;******************************************************************************** .proc set_custom_char cmp #8 diff --git a/system/ps2_keyboard.h65 b/system/ps2_keyboard.h65 index 7e365d5..174d272 100644 --- a/system/ps2_keyboard.h65 +++ b/system/ps2_keyboard.h65 @@ -1,7 +1,7 @@ ;;******************************************************************************** ;; @module ps2_keyboard ;; @ingroup drivers -;; @details: +;; @details ;; Support for a PS2 Keyboard using the shift register of a 6522 VIA ;; @section reading Reading a scancode/command answer ;; Pressing a key causes 11 bits to be sent: 1 start - 8 scancode - 1 parity - 1 stop @@ -49,7 +49,7 @@ VIA = IO1 ;; Calculate the appropriate value using: @f$ N_\text{cycles} = 230 \times f_\text{in MHZ} @f$ ;; - 230 \@ 1MHz ;; - 400 \@ 1.84 MHz -;; @clock_dependant +;; @clock_dependent TIMER_RECV = 400 ;; @brief #clock cycles to wait after loading the SR a second time while sending a command to the keyboard ;; @details @@ -61,7 +61,7 @@ TIMER_RECV = 400 ;; Values that seem to work: ;; - 230 \@ 1MHz ;; - 400 \@ 1.84 MHz -;; @clock_dependant +;; @clock_dependent TIMER_SEND = 400 PULL_REG = IO::RANH diff --git a/system/ps2_keyboard.s65 b/system/ps2_keyboard.s65 index 841c197..b2fb5c5 100644 --- a/system/ps2_keyboard.s65 +++ b/system/ps2_keyboard.s65 @@ -25,7 +25,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ; these are macros and not subroutines to save time during the interrupt handler (no jsr, rts) ;;******************************************************************************** ;; @macro Enable the clock signal from the keyboard -;; @modifies: A +;; @modifies A ;; @details ;; Stop pulling the keyboards clock low ;;******************************************************************************** @@ -38,7 +38,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;;******************************************************************************** ;; @macro Disable the clock signal from the keyboard -;; @modifies: A +;; @modifies A ;; @details ;; Pulls the keyboards clock low ;;******************************************************************************** @@ -56,7 +56,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;;******************************************************************************** ;; @macro Stop pulling the keyboard data pin low -;; @modifies: A +;; @modifies A ;;******************************************************************************** .macro _StopPullDataLow ; set pin to input @@ -67,7 +67,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;;******************************************************************************** ;; @macro Pull the keyboard data pin low -;; @modifies: A +;; @modifies A ;;******************************************************************************** .macro _PullDataLow ; set pin to output @@ -88,7 +88,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;; - Initialize variables to 0 ;; - Clear the VIAs shift register and set T2 to oneshote mode ;; - Set scancode_handler to immediately return (dont handle scancodes) -;; @modifies: A +;; @modifies A ;;******************************************************************************** .proc init _DisableClock @@ -113,7 +113,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;; @details ;; - use the shift register interrupts to read the first 8 bits ;; - configure timer for timing the read of the last 3 bits -;; @modifies: A +;; @modifies A ;;******************************************************************************** .proc begin_receive ; disable timer interrupts (this might be called while waiting on the last 3 bits) @@ -154,7 +154,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;;******************************************************************************** ;; @function Read the first 8 bits an -;; @modifies: A +;; @modifies A ;; @details ;; - read shift register ;; - disable shift register interrupts @@ -181,7 +181,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;;******************************************************************************** ;; @function Read the last 3 bits after after timer 2 is up -;; @modifies: A +;; @modifies A ;; @details ;; - read shift register ;; - disable timer 2 interrupts @@ -260,7 +260,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;; ;; If ANY of the bytes in cmd_response is 0xFE, the command failed. ;; -;; @modifies: A,X,Y +;; @modifies A,X,Y ;; @param A: The command byte ;; @param X: The data byte or NO_DATA if only the command byte should be sent ;; @param Y: The number of data bytes expected to receive. Must be one of {0, 1, 2} @@ -284,7 +284,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;;******************************************************************************** ;; @function Send a byte to the keyboard -;; @modifies: A,X,Y +;; @modifies A,X,Y ;; @param A: The byte to send ;; @details ;; - pull clock low to stop keyboard transmissions @@ -343,7 +343,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;;******************************************************************************** ;; @function Send the lasts 3 bits -;; @modifies: A +;; @modifies A ;; @details ;; - load the remaining 3 bits of the transmission into the shift register ;; - disable shift register interrupts @@ -365,7 +365,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;;******************************************************************************** ;; @function Setup VIA to receive the keyboard's answer -;; @modifies: A +;; @modifies A ;; @details ;; - disable timer 2 interrupts ;; - pull clock low @@ -416,7 +416,7 @@ scancode_handler: .res 2 ;; pointer to a function that handles new scanco ;; ;; If ANY of the bytes in cmd_response is 0xFE, the command failed. ;; -;; @modifies: A,X,Y +;; @modifies A,X,Y ;; @param A: The command byte ;; @param X: The data byte or NO_DATA if only the command byte should be sent ;; @param Y: The number of data bytes expected to receive. Must be one of {0, 1, 2} diff --git a/system/spi.h65 b/system/spi.h65 index 9687e16..4281203 100644 --- a/system/spi.h65 +++ b/system/spi.h65 @@ -14,7 +14,7 @@ INCLUDE_SPI = 1 ;; @details ;; This requires the data line to be hooked up to `CB2` and the clock to `CB1`. ;; The VIA will be set to shift in the data into the shift register under the external clock. -;; @ingroup driver +;; @ingroup drivers ;; @see via_hardware_bug "VIA external clock bug" ;;******************************************************************************** .scope spi_p diff --git a/system/system.h65 b/system/system.h65 index 098989d..d51ae35 100644 --- a/system/system.h65 +++ b/system/system.h65 @@ -1,21 +1,25 @@ -;******************************************************************************** -; @module system -; @type header -; @details -; Variable definitions for the current hardware setup -;******************************************************************************** +;;******************************************************************************** +;; @module system +;; @ingroup system +;; @details +;; Variable definitions for the current hardware setup +;;******************************************************************************** .ifndef INCLUDE_SYSTEM INCLUDE_SYSTEM = 1 -; reserved RAM addresses -; 00-0f - free use (Z0-Z15) -; 10-1f - arguments / return values (ARG0-ARG15) -; 20-ff - free -; 0100 - 01FF Stack -; 0200,0201 keybuffer write/read pointer -; 0202-02ff keybuffer -; 0300 lcd character counter +;;******************************************************************************** +;; @page system_stuff More System stuff +;; @subsubsection ram_reserved Reserved RAM addresses +;; - 00-0f - free use (Z0-Z15) +;; - 10-1f - arguments / return values (ARG0-ARG15) +;; - 20-ff - free +;; - 0100 - 01FF Stack +;; - 0200,0201 keypad keybuffer write/read pointer +;; - 0202-02ff keypad keybuffer +;; - 0300 lcd character counter +;; @ingroup system +;;******************************************************************************** .include "io_W65C22.h65" .include "utility.h65" diff --git a/util/parity.h65 b/util/parity.h65 index 3b78ad3..f0d63f2 100644 --- a/util/parity.h65 +++ b/util/parity.h65 @@ -5,7 +5,7 @@ INCLUDE_PARITY = 1 ;;******************************************************************************** ;; @macro Calculate even parity -;; @modifies: A, X, Y +;; @modifies A, X, Y ;; @returns A: 0 - even number of set bits, 1 - uneven number of set bits ;; @returns Y: The number of set bits in the byte ;;******************************************************************************** @@ -21,7 +21,7 @@ INCLUDE_PARITY = 1 ;; @details ;; Count the number of set bits in Y. ;; -;; @modifies: A, X, Y +;; @modifies A, X, Y ;; @returns A: 1 - even number of set bits, 0 - uneven number of set bits ;; @returns Y: The number of set bits in the byte ;;******************************************************************************** diff --git a/util/parity.s65 b/util/parity.s65 index a340bbb..f0385ac 100644 --- a/util/parity.s65 +++ b/util/parity.s65 @@ -4,7 +4,7 @@ ;; @details ;; Count the number of set bits in Y. ;; -;; @modifies: A, X, Y +;; @modifies A, X, Y ;; @returns Y: The number of set bits in the byte ;;******************************************************************************** .proc count_set_bits diff --git a/util/string.h65 b/util/string.h65 index b14bba0..2e47a5e 100644 --- a/util/string.h65 +++ b/util/string.h65 @@ -46,7 +46,7 @@ Import str, uint8_to_hex_str, uint_to_hex_str ;; @param out: Output string address ;; @param x0-x9: Additional parameters ;; @warning Addresses as additional paramters must be passed like this `#addr` -;; @modifies: A, X, Y, ARG4, ARG5 +;; @modifies A, X, Y, ARG4, ARG5 ;; @see str::strf ;;******************************************************************************** .macro Strf fmt,out,x0,x1,x2,x3,x4,x5,x6,x7,x8,x9 diff --git a/util/string.s65 b/util/string.s65 index b427311..5781d16 100644 --- a/util/string.s65 +++ b/util/string.s65 @@ -31,7 +31,7 @@ digits: .res 1 ;; @param ARG2-3: Output string address ;; @param ARG4+: Additional parameters ;; @returns -;; @modifies: A, X, Y, ARG4, ARG5 +;; @modifies A, X, Y, ARG4, ARG5 ;;******************************************************************************** .proc strf stz out_idx