Design Document for my Bit-Banged HD44870 Kernel Module

HD44780 Driver Design Doc

HD44780 Bit-Banged Kernel Driver Design Document

KEY:
    * : Not yet implemented
    + : Not fully implemented/Behavior not finalized
    & : Implemented in kernel space, but not yet exported to user-space

Operations

- Initialize
- Cursor
- Display (on/off)
- Clear
- R/W DDRAM
- R/W CGRAM
- R/W Position (AC)
- Write Command &

Device Tree Bindings

- Screen Dimensions
    - Line Mode (1vs2) Currently based on number of rows ^
- Bus Width (currently called mode in the device tree node)
- Font Type *
- GPIO numbers

Safety Tests

- Valid address (R/W) *
    - Out of bounds *
    - Incontiguous *
- AC Save/Restore for read/write operations *
- Spin Lock on GPIO Operations *
- Spin Lock on operations that operate on the AC (R/W CGRAM, R/W DDRAM, R/W AC) *

Open Questions
- Which class is the appropriate one?
- What should the userspace interface look like?

Interface Thoughts
- dev node gives raw read/write access to DDRAM
- IOCTL and/or SYSFS provide more consise control faculties
   - R/W DDRAM
   - R/W CGRAM (possibly split into files for each character?)
   - Cursor Mode (ON/OFF/BLINK)
   - Display (ON/OFF)
   - Clear
   - Write raw command
- SYSFS presents information about the display
   - Dimensions
   - Data Bus Width
   - Font Type
   - AC current value

Device Tee Example (BeagleBone Black)

&am33xx_pinmux {
        ...
        lcd_pins_write: pinmux_lcd_pins_write {
                pinctrl-single,pins = <
                        0x2c (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* RS  gpio0[27] P8_17 */
                        0x8c (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* R/W gpio2[1]  P8_18 */
                        0x20 (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* E   gpio0[22] P8_19 */
                        0xe0 (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* DB4 gpio2[22] P8_27 */
                        0xe4 (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* DB5 gpio2[23] P8_29 */
                        0xe8 (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* DB6 gpio2[24] P8_28 */
                        0xec (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* DB7 gpio2[25] P8_30 */
                >;
        };
        lcd_pins_read: pinmux_lcd_pins_read {
                pinctrl-single,pins = <
                        0x2c (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* RS  gpio0[27] P8_17 */
                        0x8c (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* R/W gpio2[1]  P8_18 */
                        0x20 (PIN_OUTPUT_PULLDOWN | MUX_MODE7 ) /* E   gpio0[22] P8_19 */
                        0xe0 (PIN_INPUT_PULLDOWN | MUX_MODE7 ) /* DB4 gpio2[22] P8_27 */
                        0xe4 (PIN_INPUT_PULLDOWN | MUX_MODE7 ) /* DB5 gpio2[23] P8_29 */
                        0xe8 (PIN_INPUT_PULLDOWN | MUX_MODE7 ) /* DB6 gpio2[24] P8_28 */
                        0xec (PIN_INPUT_PULLDOWN | MUX_MODE7 ) /* DB7 gpio2[25] P8_30 */
                >;
        };
        ...
};

...

/ {
        lcd {
                compatible = "hitachi,hd44780";
                pinctrl-names = "write", "read";
                pinctrl-0 = <&lcd_pins_write>;
                pinctrl-1 = <&lcd_pins_read>;

                mode = "4-bit";
                rows = <2>;
                columns = <8>;

                rs-gpio  = <&gpio0 27 GPIO_ACTIVE_HIGH>;
                rw-gpio  = <&gpio2 1  GPIO_ACTIVE_HIGH>;
                e-gpio   = <&gpio0 22 GPIO_ACTIVE_HIGH>;

                db4-gpio = <&gpio2 22 GPIO_ACTIVE_HIGH>;
                db5-gpio = <&gpio2 23 GPIO_ACTIVE_HIGH>;
                db6-gpio = <&gpio2 24 GPIO_ACTIVE_HIGH>;
                db7-gpio = <&gpio2 25 GPIO_ACTIVE_HIGH>;

                status = "okay";
        };
};

I currently have a proof of concept implementation of the module, however there are still some open questions as to which operations to expose to user-space and how.

Removed access counter, as it will not be necessary if bin files are used.