From acfd12d8fd23b789a2c0082d1c16db855d8035d3 Mon Sep 17 00:00:00 2001
From: David Phillips <david@yeah.nah.nz>
Date: Tue, 18 May 2021 22:07:23 +1200
Subject: Document register definitions for most IP blocks

---
 README.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 124 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 51341f3..fb5af9e 100644
--- a/README.md
+++ b/README.md
@@ -7,26 +7,145 @@ sessions on various aspects of Linux kernel driver development - it's not on
 any real boards, it's just a teaching tool. I do have a VHDL implementation
 which I will include once the IP blocks are more stable.
 
-## Drivers for IP blocks
+## IP blocks
+
+Unless otherwise noted, for all reserved bits, read as "don't care" and write
+as 0.
 
 ### `cds9k-fan`
 
-FIXME
+	FIXME add description
+
+#### Register 0x0: FAN\_PWM
+
+Mode: read-write
+
+Write this register to set the fan PWM duty.
+
+	| Bits | 15 - 8   | 7 - 0    |
+	| ---- | -------- | -------- |
+	| Use  | reserved | duty_val |
+
+The value for `duty_val` can be determined as:
+
+	duty_val = duty_percent * 2.55
+
+i.e. a linear scaling from 0-100% to 0x0-0xFF
+
+#### Register 0x1: FAN\_TACH
+
+Mode: read-only
+
+Read this register to determine the fan tachometer reading (FIXME units TBD).
+
+	| Bits | 15 - 0   |
+	| ---- | -------- |
+	| Use  | reserved |
 
 
 ### `cds9k-led`
 
-FIXME
+The CDS9K LED control block allows PWM brightness control of a single LED (or
+LED die, in the case of multi-colour LEDs) as well as hardware-accelerated
+blinking with 50% duty and variable period.
+
+Two signals are generated internally: blink and PWM. These are ANDed together
+to form the LED output. A sample waveform diagram (relative timings not to
+scale):
+
+	blink   ----------------                ----------------                -
+	                        ----------------                ----------------
+	PWM     -    -    -    -    -    -    -    -    -    -    -    -    -
+	         ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
+	led     -    -    -    -                   -    -    -
+	drive    ---- ---- ---- ------------------- ---- ---- -------------------
+
+The `blink` signal has a fixed duty of 50% and a period programmable between
+20 milliseconds and 5.1 seconds. The PWM signal has a fixed period of 40
+microseconds (i.e. 25 kHz), and a duty programmable between 0 and 100%.
+
+#### Register 0x0: LED\_PWM\_DUTY
+
+Mode: read-write
+
+Write this register to set the LED PWM duty. The PWM duty can be calculated as:
+
+	| Bits | 15 - 8   | 7 - 0    |
+	| ---- | -------- | -------- |
+	| Use  | reserved | duty_val |
+
+The value for `duty_val` can be determined as:
+
+	duty_val = duty_percent * 2.55
+
+i.e. a linear scaling from 0-100% to 0x0-0xFF
+
+#### Register 0x0: LED\_BLINK\_PERIOD
+
+Mode: read-write
+
+Write this register to set the LED blink period. When a non-zero value is
+written to this register, the LED output is gated by a 50% duty square wave
+with period:
+
+	period_val = 20 milliseconds * LED_BLINK_PERIOD
+
+In this way, the LED can be blinked on and off with 50% duty at a programmable
+frequency. When the LED should be enabled during each cycle, it is driven at
+the PWM brightness programmed in the `LED_PWM_DUTY` register.
+
+	| Bits | 15 - 8   | 7 - 0      |
+	| ---- | -------- | ---------- |
+	| Use  | reserved | period_val |
 
 
 ### `cds9k-gpio`
 
-FIXME
+The CDS9K GPIO block provides access to 16 basic I/O lines. Interrupts and
+pull-ups/pull-downs are not available. GPIO lines are individually selectable
+between input/hi-z and output.
+
+#### Register: 0x0: PORT
+
+Mode: read-write
+
+	| Bits | 15 - 0 |
+	| ---- | ------ |
+	| Use  | port   |
+
+#### Register: 0x1: DIRECTION
+
+Mode: read-write
+
+	| Bits | 15 - 0         |
+	| ---- | -------------- |
+	| Use  | direction_mask |
 
 
 ### `cds9k-reset`
 
-FIXME
+The CDS9K reset control block exposes a single reset line which can be asserted
+and deasserted by writing different magic values to a single 16-bit register.
+
+#### Register: 0x0: REG0
+
+Mode: read-write
+
+Write as 0xDEAD to assert the reset, and write as 0x0000 to deassert the reset.
+
+	| Bits | 15 - 0      |
+	| ---- | ----------- |
+	| Use  | reset_magic |
+
+#### Register: 0x1: RESERVED
+
+Mode: read-only
+
+Write as 0xDEAD to assert the reset, and write as 0x0000 to deassert the reset.
+
+	| Bits | 15 - 0   |
+	| ---- | -------- |
+	| Use  | reserved |
 
 
 ## Misc drivers
-- 
cgit v1.1