avr: improved apidoc.

avr/modules/lcd/main.asm

@@ -66,13 +66,9 @@ LCD_BEGIN:
 
 
 ; ---------------------------------------------------------------------------
-; LCD_Init
+; @routine LCD_Init @global
 ;
-; IN:
+; @return CFLAG set if okay, cleared on error
-; - nothing
-; OUT:
-; - CFLAG: set if okay, clear on error
-; USED:
 
 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
+; Set TWI start condition, send address and LCD_MODE_MULTICMD
-; @param r20 first byte of command
+;
-; @param r21 second byte of command
+; @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:
+; @return CFLAG set if okay, cleared on error
-; - R18: X
+; @param R18 X
-; - R19: Y
+; @param R19 Y
-; OUT:
+; @clobbers r1, r2, r15, r16 (R16, R17, R18, R22)
-; - CFLAG: set if okay, cleared otherwise
-; REGS: 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:
+; @return CFLAG set if okay, cleared on error
-; - R16: data to write
+; @param  R16 data to write
-; OUT:
+; @clobbers r15, r16, r18, r19, r20, r21 (r17, r22)
-; - CFLAG: set if okay, cleared otherwise
-; REGS: 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:
+; @return CFLAG set if okay, cleared on error
-; - Z: position of string to print
+; @param Z position of string to print
-; OUT:
+; @clobbers r15, r16, Z (R17, R18, R22)
-; - CFLAG: set if okay, cleared otherwise
-; REGS: 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:
+; @return CFLAG set if okay, cleared on error
-; - R16: char
+; @param  R16 char
-; OUT:
+; @clobbers r15, r16, r17, Z
-; REGS: 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:
+; @return CFLAG set if okay, cleared on error
-; - R16: byte to convert to hex
+; @param  R16 byte to convert to hex
-; OUT:
+; @clobbers r15, r16, r17, Z
-; REGS: 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:
+; @return CFLAG set if okay, cleared on error
-; - r18: low byte of the word
+; @param  r18 low byte of the word
-; - r19: high byte of the word
+; @param  r19 high byte of the word
-; OUT:
+; @clobbers r15, r16, r17, Z
-; - CFLAG: set if okay, cleared otherwise
-; REGS: 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:
+; @return CFLAG set if okay, cleared on error
-; - r18: low byte of the word
+; @param  r18 low byte of the word
-; - r19: high byte of the word
+; @param  r19 high byte of the word
-; OUT:
+; @clobbers r16, (r17, r20, Z)
-; - CFLAG: set if okay, cleared otherwise
 
 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:
+; @return CFLAG set if okay, cleared on error
-; - R16: byte to convert to hex
+; @param  R16 byte to convert to hex
-; OUT:
+; @clobbers r16, r20 (r16, r17, Z)
-; - CFLAG: set if okay, cleared otherwise
-; REGS: r16, r20 (r16, r17)
 
 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:
+; @return R16 ASCII representation of that nibble (e.g. '0' for 0)
-; - R16: byte (in bits 0-3)
+; @param  R16 byte (in bits 0-3)
-; OUT:
+; @clobbers r16, r17
-; - R16: ASCII representation of that nibble (e.g. '0' for 0)
-; REGS: r16, r17
 
 lcdNibbleToAscii:
   andi r16, 0xf
@@ -594,19 +593,17 @@ lcdNibbleToAscii_l1:
   ldi r17, '0'
   add r16, r17
   ret
+; @end
 
 
 
 ; ---------------------------------------------------------------------------
-; lcdWriteCommandsFromFlash
+; @routine lcdWriteCommandsFromFlash
 ;
-; IN:
+; @return CFLAG set if okay, cleared on error
-; - R16: number of bytes to send
+; @param  R16 number of bytes to send
-; - Z=pointer to data
+; @param  Z   pointer to data
-; OUT:
+; @clobbers r16, r20, Z (r17, r18, r22)
-; - CFLAG: set if okay, cleared otherwise
-
-; REGS: 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:
+; @param R16 char
-; - R16: char
+; @clobbers r16, r19, Z (R17, R18, R22)
-; OUT:
-; REGS: 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:
+; @return Z   pos of character matrix (ready for LPM)
-; - R16: char
+; @param  R16 char to lookup
-; OUT:
+; @clobbers r16, r17, Z
-; - Z: pos of character matrix (ready for LPM)
-; REGS: 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:
+; @return R16 char
-; - R16: char
+; @param  R16 char
-; OUT:
+; @clobbers r16, r17
-; - R16: char
-; REGS: 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