From ed279e4776fc1cd7c7c63e1ea6617ba8cbd31f13 Mon Sep 17 00:00:00 2001 From: "matthias@quintern.xyz" Date: Thu, 8 Aug 2024 21:11:25 +0200 Subject: [PATCH] doc improvements --- .doxygen_config | 2 +- .extra_docs.s65 | 2 +- doxy-asm65.py | 4 +- programs/dht.s65 | 6 +- programs/ps2_keyboard_simple_handler.h65 | 5 +- programs/ps2_keyboard_text_handler.h65 | 5 +- programs/ps2_keyboard_util.s65 | 2 +- programs/viu.s65 | 3 +- system/buffer.h65 | 5 +- system/io_W65C22.h65 | 105 ++++++++++++----------- system/irq_handler.h65 | 3 +- system/keypad.h65 | 4 +- system/lcd.h65 | 3 +- system/ps2_keyboard.h65 | 17 ++-- system/spi.h65 | 3 +- system/system.h65 | 5 +- util/bit_macros.h65 | 6 ++ util/math.h65 | 7 +- util/parity.h65 | 6 ++ util/parity.s65 | 7 +- util/string.h65 | 6 +- utility.h65 | 3 +- 22 files changed, 115 insertions(+), 94 deletions(-) diff --git a/.doxygen_config b/.doxygen_config index 9efb390..249c7db 100644 --- a/.doxygen_config +++ b/.doxygen_config @@ -290,11 +290,11 @@ TAB_SIZE = 4 # @} or use a double escape (\\{ and \\}) ALIASES = "modifies=\par Modifies Registers^^" \ - "type=\xrefitem type \"Code Type\" \"Code Type\"" \ "macro=\qualifier macro \brief" \ "function=\qualifier subroutine \brief" \ "module=\file ^^ \brief" \ "clock_dependent=\xrefitem clock_dependant \"Clock Speed Dependence\" \"Clock speed dependent code\"" + # "type=\xrefitem type \"Code Type\" \"Code Type\"" \ # 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 ad2c1cb..577bcd9 100644 --- a/.extra_docs.s65 +++ b/.extra_docs.s65 @@ -60,7 +60,7 @@ ;;******************************************************************************** ;;******************************************************************************** -;; @defgroup utility +;; @defgroup libs Libraries ;; @brief Code that does something useful and is intended to be used in other code ;; ;;******************************************************************************** diff --git a/doxy-asm65.py b/doxy-asm65.py index eda0fb8..9cd1c94 100644 --- a/doxy-asm65.py +++ b/doxy-asm65.py @@ -18,7 +18,7 @@ from typing import Callable # Parameters documented with the @param command are put into the paranthesis (function arguments) with `Param` as type (@ref handle_procedure) # - turns macros `.macro` into function statements with `macro` as return type with the parameter macros # as function arguments with `Param` type (@ref handle_procedure) -# - enums become ... enums, documentation of enum members after their name is also handled (@ref handle_procedure) +# - enums become ... enums, documentation of enum members after their name is also handled when using ;;< (@ref handle_procedure) # - labeled storage allocations with `.byte`, `.res`, `.ascii` etc. are turned into variable declarations with the label as variable name (@ref handle_procedure) # - if allocations are strings, they are concatenated together to `char * LABEL_NAME = "";` # - if there are multiple non-string allocations: `bytes LABEL_NAME[] = {alloc1, alloc2, ...};` @@ -87,7 +87,7 @@ def parse_custom_language(file_content: str): s += p_args s += ");\n" elif p_type == "enum": - p_code = re.sub(r"( *(?:;;.*)?\n)", r",\1", p_code) + p_code = re.sub(r"(.*=.*?)( *(?:;;.*)?\n)", r"\1,\2", p_code) s += f"enum {p_name}" + "{\n" + p_code + "};" else: raise NotImplementedError(f"handle_procedure not implemented for procedure type {p_type}") diff --git a/programs/dht.s65 b/programs/dht.s65 index fa10256..54bcc04 100644 --- a/programs/dht.s65 +++ b/programs/dht.s65 @@ -1,8 +1,10 @@ ;;******************************************************************************** -;; @module SPI -;; @type driver +;; @file +;; @brief DHT22 driver (WIP) +;; @ingroup driver ;; @details ;; @depends IO-W65C22N +;; ;;******************************************************************************** ;;TODO EVERYTHING diff --git a/programs/ps2_keyboard_simple_handler.h65 b/programs/ps2_keyboard_simple_handler.h65 index 6649611..1435742 100644 --- a/programs/ps2_keyboard_simple_handler.h65 +++ b/programs/ps2_keyboard_simple_handler.h65 @@ -1,6 +1,7 @@ ;;******************************************************************************** -;; @module ps2_keyboard_simple_handler -;; @type system +;; @file +;; @brief Simple PS/2 keyboard handler +;; @ingroup libs ;; @details: ;; This module processes keyboard scancodes from the ps2_keyboard driver. ;; It requires a PS/2 keyboard that supports scancode set 3. diff --git a/programs/ps2_keyboard_text_handler.h65 b/programs/ps2_keyboard_text_handler.h65 index d7f7a40..b2ef45d 100644 --- a/programs/ps2_keyboard_text_handler.h65 +++ b/programs/ps2_keyboard_text_handler.h65 @@ -1,7 +1,8 @@ ; normal ;;******************************************************************************** -;; @module ps2_keyboard_text_handler -;; @type system +;; @file +;; @brief PS/2 Keyboard handler for text input +;; @ingroup libs ;; @details ;; This module processes keyboard scancodes from the ps2_keyboard driver. ;; It requires a PS/2 keyboard that supports scancode set 3. diff --git a/programs/ps2_keyboard_util.s65 b/programs/ps2_keyboard_util.s65 index d47cf98..9f9628d 100644 --- a/programs/ps2_keyboard_util.s65 +++ b/programs/ps2_keyboard_util.s65 @@ -31,7 +31,7 @@ ;; - `B`: reprint menu ;; - `*`: jump home ;; For more details, see https://wiki.osdev.org/PS/2_Keyboard -;; @ingroup applications keyboard +;; @ingroup applications ;;******************************************************************************** .proc ps2_keyboard_util stz kp::_DEBUG_VAL diff --git a/programs/viu.s65 b/programs/viu.s65 index 65fedee..3af2da6 100644 --- a/programs/viu.s65 +++ b/programs/viu.s65 @@ -1,5 +1,6 @@ ;;******************************************************************************** -;; @module VIU - VI Unimproved +;; @file +;; @brief VIU - VI Unimproved ;;******************************************************************************** .include "lcd.h65" .include "ps2_keyboard_text_handler.h65" diff --git a/system/buffer.h65 b/system/buffer.h65 index e530ace..c3076cd 100644 --- a/system/buffer.h65 +++ b/system/buffer.h65 @@ -1,5 +1,6 @@ ;;******************************************************************************** -;; @module ringbuffer +;; @file +;; @brief 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 @@ -13,7 +14,7 @@ ;; 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 +;; @ingroup libs ;;******************************************************************************** .code diff --git a/system/io_W65C22.h65 b/system/io_W65C22.h65 index 3c3eeca..c115800 100644 --- a/system/io_W65C22.h65 +++ b/system/io_W65C22.h65 @@ -1,8 +1,9 @@ ;;******************************************************************************** -;; @module IO-W65C22 +;; @file +;; @brief VIA W65C22 header ;; @ingroup system -;; @device Western Design - W65C22N Versatile Interface Adapter ;; @details +;; @device Western Design - W65C22N Versatile Interface Adapter ;;******************************************************************************** .ifndef INCLUDE_IOW65C22 @@ -10,7 +11,7 @@ INCLUDE_IOW65C22 = 1 ;;******************************************************************************** ;; @brief Versatile Interface Adapter (VIA) W65C22 -;; @ingroup utility +;; @ingroup system ;; @device Western Design - W65C22N Versatile Interface Adapter ;; @todo rename to VIA ;; @warning @anchor via_hardware_bug @@ -29,22 +30,22 @@ INCLUDE_IOW65C22 = 1 ;; Use like this: `VIA_ADDRESS + IO::RB` ;;******************************************************************************** .enum - RB = $0 ;; Register B (ORB/IRB) - RA = $1 ;; Register A (ORA/IRA) - DDRB = $2 ;; Data Direction Register B - DDRA = $3 ;; Data Direction Register A - T1CL = $4 ;; Timer 1 Counter Low/High + RB = $0 ;;< Register B (ORB/IRB) + RA = $1 ;;< Register A (ORA/IRA) + DDRB = $2 ;;< Data Direction Register B + DDRA = $3 ;;< Data Direction Register A + T1CL = $4 ;;< Timer 1 Counter Low/High T1CH = $5 - T1LL = $6 ;; Timer 1 Latch Low/High + T1LL = $6 ;;< Timer 1 Latch Low/High T1LH = $7 - T2CL = $8 ;; Timer 2 Counter Low/High + T2CL = $8 ;;< Timer 2 Counter Low/High T2CH = $9 - SR = $a ;; Shift Register - ACR = $b ;; Auxiliary Control Register - PCR = $c ;; Peripheral Control Register - IFR = $d ;; Interrupt Flag Register - IER = $e ;; Interrupt Enable Register - RANH = $f ;; RA without handshake + SR = $a ;;< Shift Register + ACR = $b ;;< Auxiliary Control Register + PCR = $c ;;< Peripheral Control Register + IFR = $d ;;< Interrupt Flag Register + IER = $e ;;< Interrupt Enable Register + RANH = $f ;;< RA without handshake .endenum .enum ACR_MASK ; ACR Masks @@ -62,25 +63,25 @@ INCLUDE_IOW65C22 = 1 ;;******************************************************************************** .enum ACR ; SR Modes - SR_DISABLE = %00000000 ;; Disabled - SR_SIN_T2 = %00000100 ;; Shift in under control of T2 - SR_SIN_PHI2 = %00001000 ;; Shift in under control of PHI2 - SR_SIN_PHIE = %00001100 ;; Shift in under control of external clock - SR_SOUT_FREE_T2 = %00010000 ;; Shift out free running at T2 rate - SR_SOUT_T2 = %00010100 ;; Shift out under control of T2 - SR_SOUT_PHI2 = %00011000 ;; Shift out under control of PHI2 - SR_SOUT_PHIE = %00011100 ;; Shift out under control of external clock + SR_DISABLE = %00000000 ;;< Disabled + SR_SIN_T2 = %00000100 ;;< Shift in under control of T2 + SR_SIN_PHI2 = %00001000 ;;< Shift in under control of PHI2 + SR_SIN_PHIE = %00001100 ;;< Shift in under control of external clock + SR_SOUT_FREE_T2 = %00010000 ;;< Shift out free running at T2 rate + SR_SOUT_T2 = %00010100 ;;< Shift out under control of T2 + SR_SOUT_PHI2 = %00011000 ;;< Shift out under control of PHI2 + SR_SOUT_PHIE = %00011100 ;;< Shift out under control of external clock ; T1 Modes - T1_IRQ_LOAD = %00000000 ;; Timed interrupt each time T1 is loaded - T1_IRQ_CONT = %01000000 ;; Continuous interrupts - T1_IRQ_LOAD_PB7 = %10000000 ;; Timed interrupt each time T1 is loaded - PB7 One Shot output - T1_IRQ_CONT_PB7 = %11000000 ;; Continuous interrupts - PB7 Square wave output + T1_IRQ_LOAD = %00000000 ;;< Timed interrupt each time T1 is loaded + T1_IRQ_CONT = %01000000 ;;< Continuous interrupts + T1_IRQ_LOAD_PB7 = %10000000 ;;< Timed interrupt each time T1 is loaded - PB7 One Shot output + T1_IRQ_CONT_PB7 = %11000000 ;;< Continuous interrupts - PB7 Square wave output ; T2 Modes - T2_IRQ_LOAD = %00000000 ;; Timed interrupt each time T2 is loaded - T2_COUNT_PB6 = %00100000 ;; Count down with pulsen on PB6 + T2_IRQ_LOAD = %00000000 ;;< Timed interrupt each time T2 is loaded + T2_COUNT_PB6 = %00100000 ;;< Count down with pulsen on PB6 ; Latch - LATCH_DISABLE = %00000000 ;; `OR` this with IO::ACR_MASK::PA or IO::ACR_MASK::PB - LATCH_ENBLE = %00000011 ;; `OR` this with IO::ACR_MASK::PA or IO::ACR_MASK::PB + LATCH_DISABLE = %00000000 ;;< `OR` this with IO::ACR_MASK::PA or IO::ACR_MASK::PB + LATCH_ENBLE = %00000011 ;;< `OR` this with IO::ACR_MASK::PA or IO::ACR_MASK::PB .endenum .enum PCR_MASK ; PCR Masks @@ -97,29 +98,29 @@ INCLUDE_IOW65C22 = 1 ;;******************************************************************************** .enum PCR ; CA1 Modes - CA1_IN_AE = %00000000 ; Input-negative active edge - CA1_IP_AE = %00000001 ; Input-positive active edge + CA1_IN_AE = %00000000 ;;< Input-negative active edge + CA1_IP_AE = %00000001 ;;< Input-positive active edge ; CA2 Modes - CA2_IN_AE = %00000000 ; Input-negative active edge - CA2_IN_AE_IRQ_IND= %00000010 ; Independent interrupt input-negative edge - CA2_IP_AE = %00000100 ; Input-positive active edge - CA2_IP_AE_IRQ_IND= %00000110 ; Independent interrupt input-positive edge - CA2_OUT_HANDSHAKE= %00001000 ; Handshake output - CA2_OUT_PULSE = %00001010 ; Pulse output - CA2_OUT_LOW = %00001100 ; Low output - CA2_OUT_HIGH = %00001110 ; High output + CA2_IN_AE = %00000000 ;;< Input-negative active edge + CA2_IN_AE_IRQ_IND= %00000010 ;;< Independent interrupt input-negative edge + CA2_IP_AE = %00000100 ;;< Input-positive active edge + CA2_IP_AE_IRQ_IND= %00000110 ;;< Independent interrupt input-positive edge + CA2_OUT_HANDSHAKE= %00001000 ;;< Handshake output + CA2_OUT_PULSE = %00001010 ;;< Pulse output + CA2_OUT_LOW = %00001100 ;;< Low output + CA2_OUT_HIGH = %00001110 ;;< High output ; CB1 Modes - CB1_IN_AE = %00000000 ; Input-negative active edge - CB1_IP_AE = %00010000 ; Input-positive active edge + CB1_IN_AE = %00000000 ;;< Input-negative active edge + CB1_IP_AE = %00010000 ;;< Input-positive active edge ; CB2 Modes - CB2_IN_AE = %00000000 ; Input-negative active edge - CB2_IN_AE_IRQ_IND= %00100000 ; Independent interrupt input-negative edge - CB2_IP_AE = %01000000 ; Input-positive active edge - CB2_IP_AE_IRQ_IND= %01100000 ; Independent interrupt input-positive edge - CB2_OUT_HANDSHAKE= %10000000 ; Handshake output - CB2_OUT_PULSE = %10100000 ; Pulse output - CB2_OUT_LOW = %11000000 ; Low output - CB2_OUT_HIGH = %11100000 ; High output + CB2_IN_AE = %00000000 ;;< Input-negative active edge + CB2_IN_AE_IRQ_IND= %00100000 ;;< Independent interrupt input-negative edge + CB2_IP_AE = %01000000 ;;< Input-positive active edge + CB2_IP_AE_IRQ_IND= %01100000 ;;< Independent interrupt input-positive edge + CB2_OUT_HANDSHAKE= %10000000 ;;< Handshake output + CB2_OUT_PULSE = %10100000 ;;< Pulse output + CB2_OUT_LOW = %11000000 ;;< Low output + CB2_OUT_HIGH = %11100000 ;;< High output .endenum diff --git a/system/irq_handler.h65 b/system/irq_handler.h65 index 5a780d4..13a091a 100644 --- a/system/irq_handler.h65 +++ b/system/irq_handler.h65 @@ -1,5 +1,6 @@ ;;******************************************************************************** -;; @module WIP irq handler with jump tables and stuff +;; @file +;; @brief WIP irq handler with jump tables and stuff ;; @ingroup system ;;******************************************************************************** .ifndef INCLUDE_IRQ_HANDLER diff --git a/system/keypad.h65 b/system/keypad.h65 index bda0a85..02d7065 100644 --- a/system/keypad.h65 +++ b/system/keypad.h65 @@ -1,6 +1,6 @@ ;;******************************************************************************** -;; @module keypad4x4 -;; @device 4x4 Matrix Keypad +;; @file +;; @brief 4x4 Matrix Keypad driver ;; @details ;; The LCD must be connected to a W65C22N Interface Chip: ;; - IO.RA0-7 -> diff --git a/system/lcd.h65 b/system/lcd.h65 index 69f619d..110921d 100644 --- a/system/lcd.h65 +++ b/system/lcd.h65 @@ -1,5 +1,6 @@ ;;******************************************************************************** -;; @module LCD-W164B +;; @file +;; @brief LCD-W164B driver ;; @ingroup drivers ;; @device ELECTRONIC ASSEMBLY - W164B-NLW ;; @details diff --git a/system/ps2_keyboard.h65 b/system/ps2_keyboard.h65 index 174d272..4b7db9c 100644 --- a/system/ps2_keyboard.h65 +++ b/system/ps2_keyboard.h65 @@ -1,5 +1,6 @@ ;;******************************************************************************** -;; @module ps2_keyboard +;; @file +;; @brief PS/2 Keyboard driver ;; @ingroup drivers ;; @details ;; Support for a PS2 Keyboard using the shift register of a 6522 VIA @@ -77,17 +78,17 @@ RESEND = $fe ;; unsuccessful transmission .enum STATUS - RECEIVE_KEYS = %10000000 ;; keyboard sends scancodes - RECEIVE_ANSWER = %01000000 ;; keyboard replies to a command - SEND_CMD = %00100000 ;; host sends/sent the command byte - SEND_DATA = %00010000 ;; host sends/sent the data byte - SEND_RECV = %00001000 ;; keyboard sends additional data byte - SEND = SEND_CMD | SEND_DATA | SEND_RECV ;; host is sending something, only used for checking status + RECEIVE_KEYS = %10000000 ;;< keyboard sends scancodes + RECEIVE_ANSWER = %01000000 ;;< keyboard replies to a command + SEND_CMD = %00100000 ;;< host sends/sent the command byte + SEND_DATA = %00010000 ;;< host sends/sent the data byte + SEND_RECV = %00001000 ;;< keyboard sends additional data byte + SEND = SEND_CMD | SEND_DATA | SEND_RECV ;;< host is sending something, only used for checking status NONE = %00000000 .endenum .enum TYPEMATIC - REPEAT_MASK = %00011111 ;; 00000 = 30Hz, ..., 11111 = 2Hz + REPEAT_MASK = %00011111 ;;< 00000 = 30Hz, ..., 11111 = 2Hz DELAY250 = %00000000 DELAY500 = %00100000 DELAY750 = %01000000 diff --git a/system/spi.h65 b/system/spi.h65 index 4281203..3d8ac2f 100644 --- a/system/spi.h65 +++ b/system/spi.h65 @@ -1,5 +1,6 @@ ;;******************************************************************************** -;; @module SPI-P +;; @file +;; @brief SPI Perpiheral ;; @details ;; Support being a peripheral SPI device. ;; @depends IO-W65C22N diff --git a/system/system.h65 b/system/system.h65 index d51ae35..d37e87b 100644 --- a/system/system.h65 +++ b/system/system.h65 @@ -1,8 +1,9 @@ ;;******************************************************************************** -;; @module system +;; @file +;; @brief System header ;; @ingroup system ;; @details -;; Variable definitions for the current hardware setup +;; Variables for the current hardware setup ;;******************************************************************************** .ifndef INCLUDE_SYSTEM diff --git a/util/bit_macros.h65 b/util/bit_macros.h65 index c2acefe..1ac9886 100644 --- a/util/bit_macros.h65 +++ b/util/bit_macros.h65 @@ -1,3 +1,9 @@ +;;******************************************************************************** +;; @file +;; @brief Macros for bitwise operations +;; @ingroup libs +;;******************************************************************************** + ;;******************************************************************************** ;; @macro Use the bbs instruction by providing the bit as a mask ;; @details diff --git a/util/math.h65 b/util/math.h65 index 721d3eb..c270b86 100644 --- a/util/math.h65 +++ b/util/math.h65 @@ -1,14 +1,13 @@ ;;******************************************************************************** -;; @module math -;; @details -;; Math library +;; @file +;; @brief Math library ;;******************************************************************************** .ifndef INCLUDE_MATH INCLUDE_MATH = 1 ;;******************************************************************************** ;; @brief Math library -;; @ingroup utility +;; @ingroup libs ;;******************************************************************************** .scope math diff --git a/util/parity.h65 b/util/parity.h65 index f0d63f2..bbfd5e8 100644 --- a/util/parity.h65 +++ b/util/parity.h65 @@ -1,6 +1,12 @@ .ifndef INCLUDE_PARITY INCLUDE_PARITY = 1 +;;******************************************************************************** +;; @file +;; @brief Macros for calculating parity +;; @ingroup libs +;;******************************************************************************** + .import count_set_bits ;;******************************************************************************** diff --git a/util/parity.s65 b/util/parity.s65 index f0385ac..e9688c3 100644 --- a/util/parity.s65 +++ b/util/parity.s65 @@ -1,10 +1,9 @@ .export count_set_bits + ;;******************************************************************************** -;; @function Initialize the PS2 keyboard -;; @details -;; Count the number of set bits in Y. -;; +;; @function Count the number of set bits in the `A` register ;; @modifies A, X, Y +;; @param A: Byte to count the set bits in ;; @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 2e47a5e..ae9786b 100644 --- a/util/string.h65 +++ b/util/string.h65 @@ -1,7 +1,7 @@ ;;******************************************************************************** -;; @module string +;; @file +;; @brief String utility library ;; @details -;; String utility ;; @see str ;;******************************************************************************** .ifndef INCLUDE_STRING @@ -12,7 +12,7 @@ INCLUDE_STRING = 1 ;;******************************************************************************** ;; @brief String utility -;; @ingroup utility +;; @ingroup libs ;;******************************************************************************** .scope str Import str, strf, printf_buffer diff --git a/utility.h65 b/utility.h65 index 0b13a2a..1abf576 100644 --- a/utility.h65 +++ b/utility.h65 @@ -1,11 +1,10 @@ .ifndef INCLUDE_UTILITY INCLUDE_UTILITY = 1 - ;;******************************************************************************** ;; @file ;; @brief Various useful macros -;; @ingroup utility +;; @ingroup libs ;;******************************************************************************** .macpack longbranch ; jeq, jge...