Add millisecond delay function to tice.h (#71)

* Add millisecond delay function

* Add delay example

Still needed:
 * Screenshot (and include in readme?)
 * Discover expeced hash values for autotester
 * Confirm that autotester succeeds

* Optimize delay for size

* Don't bother to disable the timer after delay

* Atomically set timer control bits in delay

* Improve delay documentation and example

* Fix delay autotester

* Add screenshot and update readme for delay demo

Author: runer112

examples/delay/autotester.json

@@ -0,0 +1,31 @@
+{
+  "rom": "84pce_515.rom",
+  "transfer_files": [
+    "bin/DEMO.8xp"
+  ],
+  "target": {
+    "name": "DEMO",
+    "isASM": true
+  },
+  "sequence": [
+    "action|launch",
+    "hashWait|1",
+    "delay|4800",
+    "hashWait|2"
+  ],
+  "hashes": {
+    "1": {
+      "description": "Waiting for 5000 ms...",
+      "start": "vram_start",
+      "size": "vram_16_size",
+      "expected_CRCs": [ "690F0EEC" ]
+    },
+    "2": {
+      "description": "Done",
+      "start": "vram_start",
+      "size": "vram_16_size",
+      "expected_CRCs": [ "948248E" ],
+      "timeout": 250
+    }
+  }
+}

examples/delay/makefile

@@ -0,0 +1,33 @@
+# ----------------------------
+# Set NAME to the program name
+# Set DEBUGMODE to "DEBUG" to use debug functions
+# Set ICON to the png icon file name
+# Set DESCRIPTION to display within a compatible shell
+# Set COMPRESSED to "YES" to create a compressed program
+# ** Add all shared library names to L **
+# ----------------------------
+
+NAME        ?= DEMO
+DEBUGMODE   ?= NDEBUG
+COMPRESSED  ?= NO
+ICON        ?= iconc.png
+DESCRIPTION ?= "C SDK Demo"
+
+L ?= 
+
+# ----------------------------
+# Specify source and output locations
+# ----------------------------
+
+SRCDIR ?= src
+OBJDIR ?= obj
+BINDIR ?= bin
+GFXDIR ?= src/gfx
+
+# ----------------------------
+# Use OS helper functions (Advanced)
+# ----------------------------
+
+USE_FLASH_FUNCTIONS ?= YES
+
+include $(CEDEV)/include/.makefile

examples/delay/readme.md

@@ -0,0 +1,9 @@
+### Delay Demo
+
+Demonstrates using the millisecond delay function in tice.h.
+
+![Screenshot](screenshot.gif)
+
+---
+
+This demo is a part of the C SDK Toolchain for use on the CE.

examples/delay/src/main.c

@@ -0,0 +1,15 @@
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <tice.h>
+
+void main(void) {
+    /* Clear the homescreen */
+    os_ClrHome();
+
+    os_PutStrFull("Waiting for 5000 ms...");
+    delay(5000);
+    os_SetCursorPos(1, 22);
+    os_PutStrFull("Done");
+    delay(100);
+}

src/ce/delay.src

@@ -0,0 +1,93 @@
+	.assume adl=1
+	.def _delay
+
+mpTmrRange		equ 0F20000h
+
+tmr2Counter		equ 10h
+tmr2Load		equ 14h
+tmr2Match1		equ 18h
+tmr2Match2		equ 1Ch
+
+tmrCtrl			equ 30h
+
+bTmr2Enable		equ 3
+tmr2Enable		equ 1<<bTmr2Enable
+bTmr2Crystal		equ 4
+tmr2Crystal		equ 1<<bTmr2Crystal
+bTmr2Overflow		equ 5
+tmr2Overflow		equ 1<<bTmr2Overflow
+bTmr2CountUp		equ 10
+tmr2CountUp		equ 1<<bTmr2CountUp
+
+; void delay(uint16_t millis);
+
+_delay:
+; Read argument.
+	pop	de
+	ex	(sp),hl			; 0hl = millis
+	push	de
+; Abort ASAP if millis == 0.
+	ld	a,h
+	or	a,l
+	ret	z
+; Convert millis to CPU cycles by multiplying by 48000.
+; Subtract 2 to offset overhead and the unknown counter low byte.
+	ld	b,h
+	ld	c,l			; 0bc = millis
+	dec.s	bc			; bc = millis-1; need to set bcu = 0
+	srl	b
+	rr	c			; bc = (millis-1)>>1
+					;    = millis*(48000&0FFh)>>8,
+					;      off by -1 or -0.5
+	ld	e,l
+	ld	d,48000>>8		; 48000/256 == 187.5
+	ld	l,d
+	mlt	de			; de = (millis&0FFh)*(48000>>8)
+	mlt	hl			; hl = (millis>>8)*(48000>>8)
+	dec	hl
+	push	hl
+	dec	sp
+	pop	hl
+	inc	sp
+	ld	l,-2			; hl = (millis&0FF00h)*(48000>>8)-2
+	add	hl,de			; hl = millis*(48000>>8)-2
+	add	hl,bc			; hl ~ (millis*48000>>8)-3
+; Set up timer 2 control bits: disabled, CPU clock, no interrupt, count down.
+	ex	de,hl			; de ~ (millis*48000>>8)-3
+	ld	hl,mpTmrRange+tmrCtrl
+	res	bTmr2Enable,(hl)
+	res	bTmr2Crystal,(hl)
+	res	bTmr2Overflow,(hl)
+	inc	hl
+	res	bTmr2CountUp-8,(hl)
+; Set up timer 2 counter, match, and reload values.
+	ld	l,tmr2Counter+1
+	ld	(hl),de			; counter = millis*48000-768+0xxh
+	ld	l,tmr2Match1+3
+	ld	(hl),0FFh		; match1 = 0FFxxxxxxh
+	ld	l,tmr2Match2+3
+	ld	(hl),0FFh		; match2 = 0FFxxxxxxh
+	ld	l,tmr2Load+3
+	ld	(hl),0FEh		; reload = 0FExxxxxxh
+; Enable timer 2.
+	ld	l,tmrCtrl
+	set	bTmr2Enable,(hl)
+; Wait until timer 2 expires (underflows).
+; Will catch the underflow if not interrupted for a continuous period of
+; ((254-188)<<24)/48000000 ~ 23.1s.
+	ld	l,tmr2Counter+3
+	ld	a,1+((0FFFFh*24000<<1)-12>>24) ; = 188
+; 380 cc up to this point
+_delay_wait:
+	cp	a,(hl)
+	jr	nc,_delay_wait
+; 12-29 cc to exit waitloop
+; Done.
+	ret
+; ~421 cc up to this point
+; caller overhead:
+;	ld	bc,millis
+;	push	bc
+;	call	_delay
+;	pop	bc
+; ~485 cc total

src/ce/tice.h

@@ -26,6 +26,15 @@ extern "C" {
 #define randInt(min, max) \
 ((unsigned)rand() % ((max) - (min) + 1) + (min))
 
+/**
+ * Delays for a number of milliseconds.
+ * <p>
+ * Counts time spent while interrupted. Assumes a CPU clock speed of 48MHz.
+ *
+ * @param msec number of milliseconds
+ */
+void delay(uint16_t msec);
+
 /**
  * Gets a combination of the RTC time; useful for srand()
  */
@@ -104,7 +113,7 @@ extern "C" {
 #define timer_2_Counter          (*(volatile uint32_t*)0xF20010)
 #define timer_1_ReloadValue      (*(uint32_t*)0xF20004)
 #define timer_2_ReloadValue      (*(uint32_t*)0xF20014)
-#define timer_1_MatchValue_1     (*(uint32_t*)0xF20008) 
+#define timer_1_MatchValue_1     (*(uint32_t*)0xF20008)
 #define timer_1_MatchValue_2     (*(uint32_t*)0xF2000C)
 #define timer_2_MatchValue_1     (*(uint32_t*)0xF20018)
 #define timer_2_MatchValue_2     (*(uint32_t*)0xF2001C)
@@ -144,7 +153,7 @@ extern "C" {
 (240)
 
 /**
- * Total number of pixels in LCD 
+ * Total number of pixels in LCD
  */
 #define LCD_SIZE \
 (LCD_WIDTH*LCD_HEIGHT*2)
@@ -182,7 +191,7 @@ typedef struct { uint16_t len; char data[1]; } equ_t;
  */
 typedef struct { uint16_t size; uint8_t data[1]; } var_t;
 
-/** 
+/**
  * Gets an element from a matrix
  *
  * @param matrix Structure of matrix
@@ -192,12 +201,12 @@ typedef struct { uint16_t size; uint8_t data[1]; } var_t;
  */
 #define matrix_element(matrix, row, col) ((matrix)->items[(row)+(col)*(matrix)->rows])
 
-/** 
+/**
  * Resets the OS homescreen; accounts for split screen
  */
 #define os_ClrHome() do { _OS(asm_ClrLCD); _OS(asm_HomeUp); _OS(asm_DrawStatusBar); } while (0)
 
-/** 
+/**
  * Resets the OS homescreen fully
  */
 #define os_ClrHomeFull() do { _OS(asm_ClrLCDFull); _OS(asm_HomeUp); _OS(asm_DrawStatusBar); } while (0)
@@ -208,7 +217,7 @@ typedef struct { uint16_t size; uint8_t data[1]; } var_t;
 
 /**
  * Sets the calculator's date
- * 
+ *
  * Performs checks to ensure date is within range
  * @param day Day to set
  * @param month Month to set
@@ -218,7 +227,7 @@ void boot_SetDate(uint8_t day, uint8_t month, uint16_t year);
 
 /**
  * Gets the calculator's date
- * 
+ *
  * @param day Pointer to variable to store day
  * @param month Pointer to variable to store month
  * @param year Pointer to variable to store year
@@ -227,7 +236,7 @@ void boot_GetDate(uint8_t *day, uint8_t *month, uint16_t *year);
 
 /**
  * Sets the calculator's time
- * 
+ *
  * Performs checks to ensure time is within range
  * @param seconds Seconds to set
  * @param minutes Minutes to set
@@ -237,7 +246,7 @@ void boot_SetTime(uint8_t seconds, uint8_t minutes, uint8_t hours);
 
 /**
  * Gets the calculator's time
- * 
+ *
  * @param seconds Pointer to variable to store seconds
  * @param minutes Pointer to variable to store minutes
  * @param hours Pointer to variable to store hours
@@ -278,7 +287,7 @@ void boot_ClearVRAM(void);
  */
 bool boot_CheckOnPressed(void);
 
-/** 
+/**
  * Basically a reimplemented form of printf that prints to some debugging device
  *
  * @param string String to send to debug device
@@ -444,7 +453,7 @@ uint8_t os_GetFlagByte(int offset);
 
 /**
  * Get amount of free ram in order to allocate extra ram
- * 
+ *
  * @param free Set to start of free available ram
  * @returns Size of available ram
  */
@@ -570,7 +579,7 @@ real_t os_RealSub(const real_t *arg1, const real_t *arg2);
 
 /**
  * Rounds a real_t
- * 
+ *
  * @note digits must be in the range 0 - 9
  */
 real_t os_RealRound(const real_t *arg, char digits);
@@ -628,7 +637,7 @@ int os_RealToStr(char *result, const real_t *arg, int8_t maxLength, uint8_t mode
 
 /**
  *  This converts a ti-ascii string to a ti-float.
- * 
+ *
  *  String format regexp: / *[-\032+]?[0-9]*(\.[0-9]*)?([eE\033][-\032+]?[0-9]*)?/
  *  @param string TI-ascii string to convert
  *  @param end If non-null, pointer to end of parsed number is stored here
@@ -645,7 +654,7 @@ void os_ResetFlagBits(int16_t offset_pattern);
 
 /**
  * Gets a key from the OS
- * 
+ *
  * @returns Key code
  * @returns Extended key code in high byte
  */
@@ -664,7 +673,7 @@ typedef uint8_t sk_key_t;
  * const char *chars = "\0\0\0\0\0\0\0\0\0\0\"WRMH\0\0?[VQLG\0\0:ZUPKFC\0 YTOJEB\0\0XSNIDA\0\0\0\0\0\0\0\0";
  * uint8_t key, i = 0;
  * char buffer[50];
- * 
+ *
  * while((key = os_GetCSC()) != sk_Enter) {
  *     if(chars[key]) {
  *         buffer[i++] = chars[key];
@@ -959,7 +968,7 @@ typedef enum {
 #define os_Polar6LineColor   (*(uint8_t*)0xD024ED)
 #define os_SecULineColor     (*(uint8_t*)0xD024EE)
 #define os_SecVLineColor     (*(uint8_t*)0xD024EF)
-#define os_SecWLineColor     (*(uint8_t*)0xD024F0)   
+#define os_SecWLineColor     (*(uint8_t*)0xD024F0)
 
 #define os_AppErr1           ((char*)0xD025A9)             /**< String [1] for custom error */
 #define os_AppErr2           ((char*)0xD025B6)             /**< String [2] for custom error */
@@ -1560,7 +1569,7 @@ typedef enum {
 #define tXmax               0x0B
 #define tYmin               0x0C
 #define tYmax               0x0D
-#define tTmin               0x0E    
+#define tTmin               0x0E
 #define tTmax               0x0F
 #define tThetaMin           0x10
 #define tThetaMax           0x11
@@ -1939,4 +1948,3 @@ typedef enum {
 #endif
 
 #endif
-