From 0bc37343a55d9b5997dac03e2800bf038a8f5910 Mon Sep 17 00:00:00 2001 From: Martin Preuss Date: Tue, 10 Sep 2024 10:58:48 +0200 Subject: [PATCH] avr: improved apidoc. --- avr/modules/lcd/main.asm | 220 +++++++++++++++++++-------------------- 1 file changed, 108 insertions(+), 112 deletions(-) diff --git a/avr/modules/lcd/main.asm b/avr/modules/lcd/main.asm index 7b21f79..174c9b5 100644 --- a/avr/modules/lcd/main.asm +++ b/avr/modules/lcd/main.asm @@ -66,13 +66,9 @@ LCD_BEGIN: ; --------------------------------------------------------------------------- -; LCD_Init +; @routine LCD_Init @global ; -; IN: -; - nothing -; OUT: -; - CFLAG: set if okay, clear on error -; USED: +; @return CFLAG set if okay, cleared on error LCD_Init: ldi zl, LOW(lcdInitCommandsBegin) @@ -105,21 +101,18 @@ LCD_Init: sec ret +; @end ; --------------------------------------------------------------------------- -; LCD_Fini +; @routine LCD_Fini @global ; -; IN: -; - nothing -; OUT: -; - CFLAG: set if okay, clear on error -; USED: LCD_Fini: sec ret +; @end @@ -142,35 +135,50 @@ LCD_Sleep_send: +; --------------------------------------------------------------------------- +; @routine LCD_SetContrast @global +; +; @return nothing +; @param r16 1=sleep, 0=awake +; @clobbers r15, r16, r19 (R17, R18, R22) +; + +LCD_SetContrast: + ldi r20, 0x81 + mov r21, r16 + rjmp lcdTwoByteCommand +; @end + + + ; --------------------------------------------------------------------------- ; @routine lcdOneByteCommand ; Send a one byte command ; -; @return nothing +; @return CFLAG set if okay, cleared on error ; @param r20 first byte of command ; @clobbers r15, r16, r19 (R17, R18, R22) -; lcdOneByteCommand: in r15, SREG push r15 cli - rcall lcdBeginMultiCommand + rcall lcdBeginMultiCommand ; (r16, R17, R18, R22) brcc lcdOneByteCommand_error mov r16, r20 - rcall twiSendByteExpectAck ; (R16, R17, R18, R22) + rcall twiSendByteExpectAck ; (R16, R17, R18, R22) brcc lcdOneByteCommand_error - rcall twiStop ; (R22) + rcall twiStop ; (R22) pop r15 out SREG, r15 sec ret lcdOneByteCommand_error: - rjmp lcdTwiStopPopR15ClcRet ; (R22) + rjmp lcdTwiStopPopR15ClcRet ; (R22) ; @end @@ -179,7 +187,7 @@ lcdOneByteCommand_error: ; @routine lcdTwoByteCommand ; Send a two byte command ; -; @return nothing +; @return CFLAG set if okay, cleared on error ; @param r20 first byte of command ; @param r21 second byte of command ; @clobbers r15, r16, r19 (R17, R18, R22) @@ -190,38 +198,36 @@ lcdTwoByteCommand: push r15 cli - rcall lcdBeginMultiCommand + rcall lcdBeginMultiCommand ; (r16, R17, R18, R22) brcc lcdTwoByteCommand_error mov r16, r20 - rcall twiSendByteExpectAck ; (R16, R17, R18, R22) + rcall twiSendByteExpectAck ; (R16, R17, R18, R22) brcc lcdTwoByteCommand_error mov r16, r21 - rcall twiSendByteExpectAck ; (R16, R17, R18, R22) + rcall twiSendByteExpectAck ; (R16, R17, R18, R22) brcc lcdTwoByteCommand_error - rcall twiStop ; (R22) + rcall twiStop ; (R22) pop r15 out SREG, r15 sec ret lcdTwoByteCommand_error: - rjmp lcdTwiStopPopR15ClcRet ; (R22) + rjmp lcdTwiStopPopR15ClcRet ; (R22) ; @end ; --------------------------------------------------------------------------- ; @routine lcdBeginMultiCommand -; Send a two byte command ; -; @return nothing -; @param r20 first byte of command -; @param r21 second byte of command +; Set TWI start condition, send address and LCD_MODE_MULTICMD +; +; @return CFLAG set if okay, cleared on error ; @clobbers r16, (R17, R18, R22) -; lcdBeginMultiCommand: rcall twiStart ; (R22) @@ -245,17 +251,15 @@ lcdTwiStopPopR15ClcRet: ; --------------------------------------------------------------------------- -; LCD_SetCursor +; @routine LCD_SetCursor @global ; ; Set cursor. X is specified in pixels, Y is specified in character rows (8 pixels). ; Left upper corner is 0/0 (x/y), right lower corner is 127/7 ; -; IN: -; - R18: X -; - R19: Y -; OUT: -; - CFLAG: set if okay, cleared otherwise -; REGS: r1, r2, r15, r16 (R16, R17, R18, R22) +; @return CFLAG set if okay, cleared on error +; @param R18 X +; @param R19 Y +; @clobbers r1, r2, r15, r16 (R16, R17, R18, R22) LCD_SetCursor: in r15, SREG @@ -296,19 +300,18 @@ LCD_SetCursor: ret LCD_SetCursor_error: rjmp lcdTwiStopPopR15ClcRet ; (R22) +; @end ; --------------------------------------------------------------------------- -; LCD_Fill +; @routine LCD_Fill @global ; ; Fill display RAM with the given value. ; -; IN: -; - R16: data to write -; OUT: -; - CFLAG: set if okay, cleared otherwise -; REGS: r15, r16, r18, r19, r20, r21 (r17, r22) +; @return CFLAG set if okay, cleared on error +; @param R16 data to write +; @clobbers r15, r16, r18, r19, r20, r21 (r17, r22) LCD_Fill: in r15, SREG @@ -350,19 +353,18 @@ LCD_Fill_loopX: ret LCD_Fill_error: rjmp lcdTwiStopPopR15ClcRet ; (R22) +; @end ; --------------------------------------------------------------------------- -; LCD_PrintFromFlash +; @routine LCD_PrintFromFlash @global ; ; Print a string from flash at the current position. ; -; IN: -; - Z: position of string to print -; OUT: -; - CFLAG: set if okay, cleared otherwise -; REGS: r15, r16, Z (R17, R18, R22) +; @return CFLAG set if okay, cleared on error +; @param Z position of string to print +; @clobbers r15, r16, Z (R17, R18, R22) LCD_PrintFromFlash: in r15, SREG @@ -398,18 +400,18 @@ LCD_PrintFromFlash_end: LCD_PrintFromFlash_error: rjmp lcdTwiStopPopR15ClcRet ; (R22) +; @end ; --------------------------------------------------------------------------- -; LCD_PrintChar +; @routine LCD_PrintChar @global ; ; Print a character at the current position. ; -; IN: -; - R16: char -; OUT: -; REGS: r15, r16, r17, Z +; @return CFLAG set if okay, cleared on error +; @param R16 char +; @clobbers r15, r16, r17, Z LCD_PrintChar: in r15, SREG @@ -432,18 +434,18 @@ LCD_PrintChar: ret LCD_PrintChar_error: rjmp lcdTwiStopPopR15ClcRet ; (R22) +; @end ; --------------------------------------------------------------------------- -; LCD_PrintHexByte +; @routine LCD_PrintHexByte @global ; ; Convert a given byte into HEX and write it to the current position. ; -; IN: -; - R16: byte to convert to hex -; OUT: -; REGS: r15, r16, r17, Z +; @return CFLAG set if okay, cleared on error +; @param R16 byte to convert to hex +; @clobbers r15, r16, r17, Z LCD_PrintHexByte: in r15, SREG @@ -467,20 +469,19 @@ LCD_PrintHexByte: ret LCD_PrintHexByte_error: rjmp lcdTwiStopPopR15ClcRet ; (R22) +; @end ; --------------------------------------------------------------------------- -; LCD_PrintHexWord +; @routine LCD_PrintHexWord @global ; ; Convert a give word into HEX and write it to the current position. ; -; IN: -; - r18: low byte of the word -; - r19: high byte of the word -; OUT: -; - CFLAG: set if okay, cleared otherwise -; REGS: r15, r16, r17, Z +; @return CFLAG set if okay, cleared on error +; @param r18 low byte of the word +; @param r19 high byte of the word +; @clobbers r15, r16, r17, Z LCD_PrintHexWord: in r15, SREG @@ -514,47 +515,46 @@ LCD_PrintHexWord_errorNoPop: out SREG, r15 clc ret +; @end ; --------------------------------------------------------------------------- -; lcdPrintHexWord +; @routine lcdPrintHexWord ; ; Convert a given word into HEX and write it to the current position. ; -; IN: -; - r18: low byte of the word -; - r19: high byte of the word -; OUT: -; - CFLAG: set if okay, cleared otherwise +; @return CFLAG set if okay, cleared on error +; @param r18 low byte of the word +; @param r19 high byte of the word +; @clobbers r16, (r17, r20, Z) lcdPrintHexWord: mov r16, r19 push r18 - rcall lcdPrintHexByte + rcall lcdPrintHexByte ; (r16, r17, r20, Z) pop r18 brcc lcdPrintHexWord_error mov r16, r18 - rcall lcdPrintHexByte + rcall lcdPrintHexByte ; (r16, r17, r20, Z) brcc lcdPrintHexWord_error sec ret lcdPrintHexWord_error: clc ret +; @end ; --------------------------------------------------------------------------- -; lcdPrintHexByte +; @routine lcdPrintHexByte ; ; Convert a give byte into HEX and write it to the current position. ; -; IN: -; - R16: byte to convert to hex -; OUT: -; - CFLAG: set if okay, cleared otherwise -; REGS: r16, r20 (r16, r17) +; @return CFLAG set if okay, cleared on error +; @param R16 byte to convert to hex +; @clobbers r16, r20 (r16, r17, Z) lcdPrintHexByte: mov r20, r16 @@ -571,18 +571,17 @@ lcdPrintHexByte: lcdPrintHexByte_error: clc ret +; @end ; --------------------------------------------------------------------------- -; lcdNibbleToAscii +; @routine lcdNibbleToAscii ; ; Convert a nibble to an ASCII char. -; IN: -; - R16: byte (in bits 0-3) -; OUT: -; - R16: ASCII representation of that nibble (e.g. '0' for 0) -; REGS: r16, r17 +; @return R16 ASCII representation of that nibble (e.g. '0' for 0) +; @param R16 byte (in bits 0-3) +; @clobbers r16, r17 lcdNibbleToAscii: andi r16, 0xf @@ -594,19 +593,17 @@ lcdNibbleToAscii_l1: ldi r17, '0' add r16, r17 ret +; @end ; --------------------------------------------------------------------------- -; lcdWriteCommandsFromFlash +; @routine lcdWriteCommandsFromFlash ; -; IN: -; - R16: number of bytes to send -; - Z=pointer to data -; OUT: -; - CFLAG: set if okay, cleared otherwise - -; REGS: r16, r20, Z (r17, r18, r22) +; @return CFLAG set if okay, cleared on error +; @param R16 number of bytes to send +; @param Z pointer to data +; @clobbers r16, r20, Z (r17, r18, r22) lcdWriteCommandsFromFlash: rcall twiStart @@ -635,18 +632,17 @@ lcdWriteCommandsFromFlash_error: rcall twiStop clc ret +; @end ; --------------------------------------------------------------------------- -; lcdPrintOneChar +; @routine lcdPrintOneChar ; ; Print a character at the current position. ; -; IN: -; - R16: char -; OUT: -; REGS: r16, r19, Z (R17, R18, R22) +; @param R16 char +; @clobbers r16, r19, Z (R17, R18, R22) lcdPrintOneChar: rcall lcdGetCharMatrix ; (r16, r17, Z) @@ -666,18 +662,18 @@ lcdPrintOneChar_loop: lcdPrintOneChar_error: clc ret +; @end + ; --------------------------------------------------------------------------- -; lcdGetCharMatrix +; @routine lcdGetCharMatrix ; ; Get pointer to matrix of given char. ; -; IN: -; - R16: char -; OUT: -; - Z: pos of character matrix (ready for LPM) -; REGS: r16, r17, Z +; @return Z pos of character matrix (ready for LPM) +; @param R16 char to lookup +; @clobbers r16, r17, Z lcdGetCharMatrix: #ifdef LCD_MINIMAL_FONT @@ -730,17 +726,17 @@ lcdGetCharMatrix_l2: adc zh, r17 ret #endif +; @end + #ifdef LCD_MINIMAL_FONT ; --------------------------------------------------------------------------- -; Uppercase the given character if it is lower case. +; @routine Uppercase the given character if it is lower case. ; -; IN: -; - R16: char -; OUT: -; - R16: char -; REGS: r16, r17 +; @return R16 char +; @param R16 char +; @clobbers r16, r17 lcdUpcase: cpi r16, 'a' @@ -752,11 +748,11 @@ lcdUpcase: lcdUpcase_done: ret #endif +; @end + -; TODO: set adressing mode?? lcdInitCommandsBegin: ; 28 bytes -; .db LCD_MODE_MULTICMD, 0xa8, ((LCD_PAGE_COUNT*8)-1), 0x8d, 0x14, 0xaf, 0xa1, 0xc8 .db 0xae, 0x20, 0x00, 0xb0, 0xc8, 0x00, 0x10, 0x40 .db 0x81, 0x3f, 0xa1, 0xa6, 0xa8, LCD_HEIGHT-1, 0xa4, 0xd3 .db 0x00, 0xd5, 0xf0, 0xd9, 0x22, 0xda, 0x12, 0xdb