Llosa de Viango Tollos – DOGXL.c



Getting started



  Tollos libraries

  Device libraries





  Sample application


DOGXL.c – DOGXL LCD driver

This module provides the glue between tollosDraw and a DOGXL LCD screen, including a screen buffer.

Measured performance, etc.:

  • Time to write all pels using drawSetPelIO: 7.7ms (96 MHz MCU)
  • Time to send whole buffer to DOGXL: 5.3 ms (12 MHz SPI)
  • Power consumption: 1.04 mA @ 3.3V (160L-7, all pels full on).

This glue assumes the DOGXL is attached to a microcontroller in the 3-wire 9-bit SPI configuration, using the primary SPI port and associated select line (as defined by the spi9 glue functions), and with the SPI clock set to 12 MHz.

This 3-wire 9-bit SPI combination is about 33x faster than 400 kHz I2C and theoretically could write the 4160-byte screen buffer in 3.12 ms, running the bus clock at 12 MHz. In practice, there is some inter-byte overhead and the measured time is 5.3 ms.

At this speed it is unlikely to be valuable to double-buffer the screen in order to only send changes, because the inter-byte overhead is already significant.

The screen buffer for DOGXL is maintained in the order that is is required for sending to the display; this is determined by the UC1610 controller on the display.

Each byte stored covers one pel in each of four rows in a column of four pels (4 rows together are called a ‘page’ in the UC1610 datasheet). The byte in which a given pel is to be found is therefore given by ((DOGY−1-y)/4)*160+x, with the two bits being determined by y%4. Note that the two bits for the top row go into the two least significant bits of the byte.

The “lookup tables” pelshift and pelmasks are used to speed up the retrieval and setting of a pel within a byte.

X and Y coordinates are always checked so there is no possibility of buffer overrun or addressing exception.

Pel data values are not checked on set (they may cause local pel corruption but will not cause addressing errors).
 drawClearIO   set every pel to the same value
 drawFromRGBIO   convert RGB to a pel value
 drawGetPelIO   get pel value
 drawInitIO   initialize display and discover its configuration
 drawRawIO   read and/or write the screen buffer ‘as is’
 drawSetPelIO   set pel to a new value
 drawStopIO   stop the display device
 drawToRGBIO   convert pel value to RGB
 drawWriteIO   write buffer to screen (draw)

drawClearIO – set every pel to the same value

void drawClearIO(int pel);

pel – new value for the screen

This sets every pel in the screen buffer to the provided value.

drawFromRGBIO – convert RGB to a pel value

int drawFromRGBIO(drawRGB rgb);

rgb – colour value [0..255 in each]

returns the corresponding pel value

This converts standard RGB to a private pel value suitable for use in drawSetPelIO, etc.

drawGetPelIO – get pel value

int drawGetPelIO(int x, int y);

x – pel X coordinate

y – pel Y coordinate

returns the value of the pel at x, y

If x or y is too large or less than zero, 0 is returned.

drawInitIO – initialize display and discover its configuration

int drawInitIO(drawConfig *config);

config – configuration structure (always set)

returns 0 if OK, negative if error (e.g., device not available, or bus error)

This function initializes the display, clears the screen buffer to white, and sets the configuration structure so the caller can determine the device geometry and characteristics. The screen buffer is cleared and the configuration is set even if an error occurred during hardware initialization.

The DOGXL device is write only when SPI-connected, so this function always returns 0 unless there is an SPI bus error.

drawRawIO – read and/or write the screen buffer ‘as is’

void drawRawIO(byte *to, const byte *from);

to – first byte to copy screen buffer to, or NULL for no read

from – first byte to copy screen buffer to, or NULL for no write

This function is used to provide private access to the screen buffer, which will be in device-specific format. The entire buffer is copied, with a read (copy to the caller) taking place before the write (copy to the screen buffer)

This is intended for experimental use or when performance is critical. Tollos code rules do not permit direct cross-module memory sharing, so a copy is still necessary.

drawSetPelIO – set pel to a new value

void drawSetPelIO(int x, int y, int pel);

x – pel X coordinate

y – pel Y coordinate

pel – new value for the pel

If x or y is too large or less than zero, this function has no effect. If pel is too large some pels in the buffer may be undefined.

The code below runs in about 1.85 us on a 96 MHz MCU, so to write every pel on the screen individually takes about 7.7ms.

drawStopIO – stop the display device

void drawStopIO(void);

This puts the device into a clean or low power/off mode. For LCDs this should save power as well as properly discharging the display.

drawToRGBIO – convert pel value to RGB

void drawToRGBIO(int pel, drawRGB *rgb);

pel – pel value to convert

rgb – returned colour value [0..255 in each]

This converts a private pel value back to standard RGB.

drawWriteIO – write buffer to screen (draw)

int drawWriteIO(void);

returns 0 if OK, negative if error (e.g., bus error)

This function sends the screen buffer to the device.

For the DOGXL, this is done by sending a ‘page’ at a time, where a page is four rows of pels, starting at the top of the screen. The bytes to be sent are a vertical swathe of the pels, 2 bits per row.

Later a dirty flag per page might be added, so that only changed pages will be sent.

The entire screen buffer could be sent as a single write; the send by page has the advantage that if a noise burst corrupts a transmission then only one page will be corrupt instead of perhaps the entire screen.

The time to write all 26 pages to the DOGXL using this code and an SPI clock of 12 MHz (the maximum, using the 3-wire 9-bit connection) is 5.3 ms (800,000 9-bit ‘bytes’ per second).

Tollos and these web pages were written by Mike Cowlishaw; Please send me any corrections, suggestions, etc.
All content © Mike Cowlishaw, 2010–2012, except where marked otherwise. All rights reserved. The pages here are for non-commercial use only (see the separate licence for Tollos source code). Privacy policy: the Speleotrove website records no personal information and sets no ‘cookies’. However, statistics, etc. might be recorded by the web hosting service.

This page was last updated on 2011-01-11 by c2wiki.