MatthiasQuintern/6502-OS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc improvements

Browse Source
This commit is contained in:
matthias@quintern.xyz 2024-08-08 21:11:25 +02:00
parent bf6a5efd7e
commit ed279e4776
22 changed files with 115 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.doxygen_config
View File

@ -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

2
.extra_docs.s65
View File

@ -60,7 +60,7 @@
;;********************************************************************************
;;********************************************************************************
;; @defgroup utility
;; @defgroup libs Libraries
;; @brief Code that does something useful and is intended to be used in other code
;;
;;********************************************************************************

4
doxy-asm65.py
View File

@ -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 = "<string(s)>";`
# - 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}")

6
programs/dht.s65
View File

@ -1,8 +1,10 @@
;;********************************************************************************
;; @module SPI
;; @type driver
;; @file
;; @brief DHT22 driver (WIP)
;; @ingroup driver
;; @details
;; @depends IO-W65C22N
;;
;;********************************************************************************
;;TODO EVERYTHING

5
programs/ps2_keyboard_simple_handler.h65
View File

@ -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.

5
programs/ps2_keyboard_text_handler.h65
View File

@ -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.

2
programs/ps2_keyboard_util.s65
View File

@ -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

3
programs/viu.s65
View File

@ -1,5 +1,6 @@
;;********************************************************************************
;; @module VIU - VI Unimproved
;; @file
;; @brief VIU - VI Unimproved
;;********************************************************************************
.include "lcd.h65"
.include "ps2_keyboard_text_handler.h65"

5
system/buffer.h65
View File

@ -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

105
system/io_W65C22.h65
View File

@ -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

3
system/irq_handler.h65
View File

@ -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

4
system/keypad.h65
View File

@ -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 ->

3
system/lcd.h65
View File

@ -1,5 +1,6 @@
;;********************************************************************************
;; @module LCD-W164B
;; @file
;; @brief LCD-W164B driver
;; @ingroup drivers
;; @device ELECTRONIC ASSEMBLY - W164B-NLW
;; @details

17
system/ps2_keyboard.h65
View File

@ -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

3
system/spi.h65
View File

@ -1,5 +1,6 @@
;;********************************************************************************
;; @module SPI-P
;; @file
;; @brief SPI Perpiheral
;; @details
;; Support being a peripheral SPI device.
;; @depends IO-W65C22N

5
system/system.h65
View File

@ -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

6
util/bit_macros.h65
View File

@ -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

7
util/math.h65
View File

@ -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

6
util/parity.h65
View File

@ -1,6 +1,12 @@
.ifndef INCLUDE_PARITY
INCLUDE_PARITY = 1
;;********************************************************************************
;; @file
;; @brief Macros for calculating parity
;; @ingroup libs
;;********************************************************************************
.import count_set_bits
;;********************************************************************************

7
util/parity.s65
View File

@ -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

6
util/string.h65
View File

@ -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

3
utility.h65
View File

@ -1,11 +1,10 @@
.ifndef INCLUDE_UTILITY
INCLUDE_UTILITY = 1
;;********************************************************************************
;; @file
;; @brief Various useful macros
;; @ingroup utility
;; @ingroup libs
;;********************************************************************************
.macpack longbranch ; jeq, jge...