         hw-lcd-hd44780u (libhd44780u.la :: hd44780u_component_library)

Synopsis:

   Simulates the Hitachi HD44780U LCD controller. The controller supports 1
   or 2 lines of 8 5X8 dots with cursor, or 1 line of 8 5X10 dots with
   cursor. The chip includes an 80 character display RAM, a 64 byte character
   generator RAM, and a 240 character ROM of predefined fonts. Two ROMS are
   available: hw-lcd-hd44780u-a00 specifies the Japanese standard font;
   hw-lcd-hd44780u-a02 is the European standard font.

     ----------------------------------------------------------------------

Functionality:

  Modelling:

   The LCD controller model is somewhat abstracted from the physical device:

     * All commands in the model are executed instantaneously, while the real
       device requires significant time to execute a command. As a result,
       the busy flag in the model is never set.

     * The real device has 40 segment driver pins, 16 common driver pins, and
       6 more pins related to data and clock. These are replaced by 2(!) pins
       in the model. The FR (frame) pin is driven to 1 to identify that a new
       frame is starting, and driven to 0 when the frame is finished. The
       row-col pin incorporates all the functionality of the row and column
       drivers on the real chip. This pin is driven once for each "on" pixel
       in the display, and the value on the pin is the [X,Y] co-ordinates of
       the pixel, encoded as two adjacent 16-bit values in the 32-bit pin
       value.

     * With these two pins, a display refresh cycle starts when the FR pin is
       asserted; the [X,Y] co-ordinates of all the "on" pixels are then
       transmitted on the row-col pin; and the FR pin is de-asserted to end
       the refresh cycle.

     * The physical device uses an external crystal to set the duty cycle.
       The model uses the refresh-period-msec attribute to communicate with
       the scheduler to set the refresh rate.

     * To reduce system overhead, the model tries to reduce its interaction
       with the scheduler and display. Specifically, a single refresh cycle
       is initiated if there is a write to the component, to capture any
       internal state changes that may affect the display. Because several
       writes are often required to effect a meaningful change, the refresh
       is delayed to occur refresh-period-msec milliseconds after the first
       write. As well, the refresh is continued periodically if blink is
       enabled.

   +-------------------------------------------------+
   |                    Behaviors                    |
   |-------------------------------------------------|
   | configuration | The refresh-period-msec         |
   |               | attribute is used specify the   |
   |               | refresh period (in              |
   |               | milliseconds) for continuous    |
   |               | update modes such as blink.     |
   |---------------+---------------------------------|
   |         debug | The boolean verbose? attribute  |
   |               | can be used to track internal   |
   |               | operations                      |
   |---------------+---------------------------------|
   |       display | See discussion of the FR and    |
   |               | row-col pins in Modeling        |
   |               | section above                   |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                 SID Conventions                 |
   |-------------------------------------------------|
   |   functional | supported | This is a functional |
   |              |           | component.           |
   |--------------+-----------+----------------------|
   | Save/restore | supported | Save/restore is      |
   |              |           | supported via the    |
   |              |           | state-snapshot       |
   |              |           | attribute            |
   |--------------+-----------+----------------------|
   | Triggerpoint | supported | Trigger point        |
   |              |           | support is available |
   |              |           | on the IR, DR, and   |
   |              |           | AC registers.        |
   +-------------------------------------------------+

     ----------------------------------------------------------------------

Environment:

   Related components

   Besides the CPU bus, the LCD controller is typically connected to a
   display of some kind. Clearly, the display component must be aware of the
   refresh protocol used by the HD44780U model. As well, the scheduler is
   typically used to set up the time between refreshes of the display.

   The following configuration file segment shows how the LCD controller can
   be connected to the lcd.tcl display and host-time scheduler:

       new hw-lcd-hd44780u-a00 lcd       # Standard Japanese font
       new hw-visual-lcd display         # The display is implemented in Tcl
       new sid-sched-host sched          # Use the real-time scheduler
      
       # scheduling (must appear before pin assignments)
       set sched num-clients 1
       set sched 0-regular? 1
       set sched 0-time 500              # in msec

       # display size is in pixels - ie. font-width*display-height
       set display width 40              # 8 chars X 5 pixels per char
       set display height 8              # single line of 8 pixels

       # connect the LCD to the scheduler
       connect-pin sched 0-event -> lcd refresh-sync-event
       connect-pin sched 0-control <- lcd refresh-sync-control
       # connect the LCD to the display
       connect-pin lcd row-col -> display row-col
       connect-pin lcd FR -> display FR

     ----------------------------------------------------------------------

Component Reference:

  Component: hw-lcd-hd44780u (Abstract)

   +-------------------------------------------------+
   |                      pins                       |
   |-------------------------------------------------|
   |  name   | direction |  legalvalues  | behaviors |
   |---------+-----------+---------------+-----------|
   | FR      | out       | binary        | display   |
   |---------+-----------+---------------+-----------|
   | row-col | out       | 2 shorts as a | display   |
   |         |           | 32-bit value  |           |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                      buses                      |
   |-------------------------------------------------|
   | name | addresses |     accesses     | behaviors |
   |------+-----------+------------------+-----------|
   | bus  | 0..1      | byte-wide access |           |
   +-------------------------------------------------+

   +------------------------------------------------------------+
   |                         attributes                         |
   |------------------------------------------------------------|
   |       name        |category| legal  |default|  behaviors  ||
   |                   |        | values | value |             ||
   |-------------------+--------+--------+-------+-------------||
   |                   |        |any     |       |             ||
   |refresh-period-msec|setting |positive|500    |configuration||
   |                   |        |value   |       |             ||
   |-------------------+--------+--------+-------+-------------||
   |verbose?           |setting |boolean |false  |debug        ||
   +------------------------------------------------------------+

  Variant: hw-lcd-hd44780u-a00

   Same as hw-lcd-hd44780u

  Variant: hw-lcd-hd44780u-a02

   Same as hw-lcd-hd44780u

     ----------------------------------------------------------------------

References:

   HD44780U (LCD-II) Dot Matrix Liquid Crystal Display Controller Driver
   (from the Hitachi web site)
