Add lcddrvce docs, update some API names, add more command macros, use enums for flag and field constants

Author: calc84maniac

docs/doxyfile

@@ -937,7 +937,8 @@ INPUT                  = ../src/graphx/graphx.h \
                          ../src/usbdrvce/usbdrvce.h \
                          ../src/srldrvce/srldrvce.h \
                          ../src/fatdrvce/fatdrvce.h \
-                         ../src/msddrvce/msddrvce.h
+                         ../src/msddrvce/msddrvce.h \
+                         ../src/lcddrvce/lcddrvce.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

docs/libraries/index.rst

@@ -19,6 +19,7 @@ Common libraries:
     fontlibc
     fileioc
     keypadc
+    lcddrvce
     libload
 
 USB Libraries:

docs/libraries/lcddrvce.rst

@@ -0,0 +1,37 @@
+.. _lcddrvce_h:
+
+lcddrvce.h
+==========
+
+.. code-block:: c
+
+    #include <lcddrvce.h>
+
+The :code:`lcddrvce` library is used for interacting with the Sitronix ST7789 LCD controller.
+
+.. contents:: :local:
+   :depth: 3
+
+Overview
+--------
+
+This library exposes interfaces to send any supported command to the LCD (this excludes read commands, which don't work reliably on CE hardware).
+
+Communication with the LCD controller is done over an SPI connection; however, the SPI hardware is also used to communicate with the ARM coprocessor on Python models.
+As such, the SPI hardware is not always set up properly to communicate with the LCD controller, and this library exists to provide a reliable and performant interface to the LCD across calculator models.
+
+Library Initialization
+----------------------
+
+The :code:`lcd_Init` and :code:`lcd_Cleanup` functions provide reference-counted initialization and cleanup of the SPI configuration.
+That means multiple calls to :code:`lcd_Init()` are allowed, and the SPI hardware is restored to its original settings only after the same number of calls to :code:`lcd_Cleanup()`.
+Since the configuration is set differently than the OS's default settings for performance reasons, it's not allowed to power off the calculator without cleaning up the library first.
+This means if calling certain functions like :code:`os_GetKey` which can auto-power-down the calculator, either the LCD library should be cleaned up or auto-power-down should be disabled with :code:`os_DisableAPD()`.
+When using this library as part of another library's implementation and performance is not critical, it's safest to call both :code:`lcd_Init()` and :code:`lcd_Cleanup()` each time commands need to be sent.
+That way, users of the library will be able to cleanup the SPI configuration whenever they need to.
+
+API Documentation
+-----------------
+
+.. doxygenfile:: lcddrvce.h
+   :project: CE C/C++ Toolchain

examples/library_examples/lcddrvce/gradient/src/main.c

@@ -17,10 +17,10 @@ int main(void)
     /* Switch RAM access to SPI and display mode to MCU */
     lcd_SetRamInterface(LCD_RAM_SPI | LCD_DM_MCU);
     /* Set 18bpp pixel format */
-    lcd_SetPixelFormat(LCD_RGB_18BPP | LCD_MCU_18BPP);
+    lcd_SetPixelFormat(LCD_SPI_18BPP | LCD_RGB_DEFAULT);
 
     /* Start RAM write command */
-    lcd_SendCommand(LCD_CMD_RAMWR);
+    lcd_StartPixelWrite();
 
     /* Generate and display gradient patterns */
     DrawGradient(0x040404);

examples/library_examples/lcddrvce/half_res/src/main.c

@@ -122,8 +122,8 @@ void SetHalfResMode(bool enable)
 
     typedef struct res_settings
     {
-        uint8_t frctrl2;
-        uint8_t bpa;
+        uint8_t frctrl;
+        uint8_t bp;
         uint16_t xe;
         uint8_t tfa;
         uint8_t ramctrl1;
@@ -134,8 +134,8 @@ void SetHalfResMode(bool enable)
     {
         {
             /* Default ST7789 settings */
-            .frctrl2 = LCD_FRCTRL2_DEFAULT,
-            .bpa = LCD_BPA_DEFAULT,
+            .frctrl = LCD_FRCTRL_DEFAULT,
+            .bp = LCD_BP_DEFAULT,
             .xe = LCD_WIDTH - 1,
             .tfa = 0,
             .ramctrl1 = LCD_RAMCTRL1_DEFAULT
@@ -145,11 +145,11 @@ void SetHalfResMode(bool enable)
              * Refreshes LCD in at most 16.51 ms after VSYNC, assuming worst case 9.5 MHz clock
              * Waits at least 3.42 ms after VSYNC to read LCD memory, assuming worst case 10.5 MHz clock
              */
-            .frctrl2 = 8, /* 378 clocks per line */
-            .bpa = 95,    /* 95 lines of back porch */
+            .frctrl = LCD_RTN_378 | LCD_NL_DEFAULT, /* 378 clocks per line */
+            .bp = 95, /* 95 lines of back porch */
             .xe = HALF_LCD_WIDTH - 1,
             .tfa = HALF_LCD_WIDTH,
-            .ramctrl1 = LCD_RAM_RGB | LCD_DM_VSYNC,
+            .ramctrl1 = LCD_DM_VSYNC | LCD_RAM_DEFAULT,
             /* With the following PL111 timing:
              * Refreshes LCD at 60 Hz = 24 MHz / (800*250*2), a VSYNC period of 16.67 ms
              * Outputs 38400 pixels to LCD memory within the first 3.40 ms after VSYNC
@@ -184,9 +184,9 @@ void SetHalfResMode(bool enable)
     lcd_Init();
 
     /* Set clocks per line */
-    lcd_SetNormalFrameRateControl(p->frctrl2);
+    lcd_SetNormalFrameRateControl(p->frctrl);
     /* Set back porch */
-    lcd_SendCommand1(LCD_CMD_PORCTRL, p->bpa);
+    lcd_SetNormalBackPorchControl(p->bp);
     /* Set horizontal output window */
     lcd_SetColumnAddress(0, p->xe);
     /* Set fixed left scroll area */

src/lcddrvce/lcddrvce.asm

@@ -14,13 +14,13 @@ library LCDDRVCE, 0
 	export lcd_Init
 	export lcd_Cleanup
 	export lcd_Wait
-	export lcd_SendCommandRaw
+	export lcd_SendSizedCommandRaw
 	export lcd_SendParamsRaw
 	export lcd_SendCommand
 	export lcd_SendCommand1
 	export lcd_SendCommand2
-	export lcd_SendCommandBytes
-	export lcd_SendCommandWords
+	export lcd_SendSizedCommandBytes
+	export lcd_SendSizedCommandWords
 	export lcd_SetUniformGamma
 	export lcd_SetDefaultGamma
 
@@ -134,14 +134,14 @@ _Gamma:
 	; Set positive gamma
 	ld bc, (14 shl 8) or $E0
 	push bc
-	call lcd_SendCommandRaw.entry
+	call lcd_SendSizedCommandRaw.entry
 	; Set negative gamma
 	ex de, hl
 	pop bc
 	inc c
-	jr lcd_SendCommandRaw.entry
+	jr lcd_SendSizedCommandRaw.entry
 
-lcd_SendCommandRaw:
+lcd_SendSizedCommandRaw:
 	pop hl
 	pop bc
 	pop de
@@ -222,17 +222,17 @@ _sendSingleByte:
 
 lcd_SendCommand:
 	ld b, 0+1
-	jr lcd_SendCommandBytes.entry
+	jr lcd_SendSizedCommandBytes.entry
 
 lcd_SendCommand1:
 	ld b, 1+1
-	jr lcd_SendCommandBytes.entry
+	jr lcd_SendSizedCommandBytes.entry
 
 lcd_SendCommand2:
 	ld b, 2+1
-	jr lcd_SendCommandBytes.entry
+	jr lcd_SendSizedCommandBytes.entry
 
-lcd_SendCommandBytes:
+lcd_SendSizedCommandBytes:
 	pop hl
 	pop bc
 	push bc
@@ -252,7 +252,7 @@ lcd_SendCommandBytes:
 	djnz .loop
 	ret
 
-lcd_SendCommandWords:
+lcd_SendSizedCommandWords:
 	ld hl, 4
 	add hl, sp
 	ld b, (hl)