Serial Devices

12

This chapter describes programming requirements for serial devices, and gives examples of serial device drivers. Serial devices are byte-oriented, sequentially-accessed devices such as asynchronous communication lines (often attached to a dumb terminal).

Required Methods

The serial device driver must declare the serial device type, and must implement the methods open and close, as well as the following:

`install-abort` ( -- )

Instruct the driver to begin periodic polling for a keyboard abort sequence. install-abort is executed when the device is selected as the console input device.

`read` ( addr len -- actual )

Read len bytes of data from the device into memory starting at addr. Return the number of bytes actually read, actual, or -2 if no bytes are currently available from the device. -1 is returned if other errors occur.

`remove-abort` ( -- )

Instruct the driver to cease periodic polling for a keyboard abort sequence. remove-abort is executed when the console input device is changed from this device to another.

`write` ( addr len -- actual )

Write len bytes of data to the device from memory starting at addr. Return the number of bytes actually written, actual.

Required Properties

These are the standard properties of a serial driver:

Table 12-1

Property Name	Value
`name`	`" SUNW,zs"`
`reg`	list of registers {device-dependent}
`device_type`	`" serial"`

Device Driver Examples

The following three examples are serial device drivers for the Zilog 8530 SCC (UART) chip.

The first sample is a short driver which simply creates a device node and declare the properties for the device.
The second sample is a more sophisticated driver that defines methods to control and access the device.
The third sample shows the complete serial device driver.

Simple Serial FCode Program


  \ This driver creates a device node and publishes the minimum required set of  
  \ properties.  
  fcode-version3  
     hex  
     " SUNW,zs" name  
     my-address 10.0000 + my-space 8 reg  
     7 encode-int " interrupts"  property  
  end0

Extended Serial FCode Program

Code Example 12-1 Extended Serial FCode Program


  \ In addition to publishing the properties, this sample driver  
  \ provides methods to access and control the serial ports.  
  \  
  \ The following main methods are provided:  
  \ - usea   ( -- )  
  \    Selects serial port A. All subsequent operations will  
  \         be directed to port A  
  \ - useb   ( -- )  
  \         Selects serial port B. All subsequent operations will  
  \         be directed to port B  
  \ - uemit  ( char -- )  
  \ Emits a given character to the selected serial port.  
  \ - ukey   ( -- key )  
  \ Retrieves a character from the selected serial port.  
  \ - read   ( addr len -- #read )  
  \  Reads "len" number of characters from the selected port,  
  \    and store them at "addr".  
  \ - write  ( addr len -- #written )  
  \  Writes "len" number of characters from the buffer located  
  \      at "addr" to the selected serial port.  
  
  fcode-version3  
  hex  
  
     " SUNW,zs" name  
     my-address 10.0000 + my-space 8 reg  
     7 encode-int " interrupts"    property

Code Example 12-1 Extended Serial FCode Program (Continued)


     : >phys-addr  ( offset -- phys.lo phys.mid phys.hi )  
       >r my-address r> 0 d+  my-space  
     ;  
     : do-map-in  ( offset size -- virt )  
       >r >phys-addr r>  " map-in" $call-parent  
     ;  
     : do-map-out ( virt size -- )  " map-out" $call-parent  ;  
  
     : /string  ( addr len n -- addr+n len-n )  tuck  -  -rot  +  swap  ;  
  
     1 constant RXREADY  \ received character available  
     4 constant TXREADY  \ transmit buffer empty  
  
     0 instance value  uart              \ define uart as an "per-instance" value.  
     0 instance value  uartbase  
     h# ff instance value  mask-#data    \ mask for #data bits  
     h# 10 instance buffer: mode-buf  
  
     \ The following line assumes that A2 selects the channel within the chip  
     : usea   ( -- )    uartbase 4 + to uart  ;  
     : useb   ( -- )    uartbase to uart  ;  
     : uctl!  ( c -- )  uart  rb!  ;  
     : uctl@  ( -- c )  uart  rb@  ;  
  
     \ The following line assumes that A1 chooses the command vs. data port  
     : udata!  ( c -- )  uart  2 + rb!  ;  
     : udata@  ( -- c )  uart  2 + rb@  ;  
  
     \ Test for "break" character received.  
     : ubreak?  ( -- flag )  10 uctl!  uctl@  h# 80 and  0<>  ;  
  
     \ Clear the break flag  
     : clear-break  ( -- )  
        begin  ubreak? 0=  until    \ Let break finish  
        udata@ drop                 \ Eat the null character  
        30 uctl!                    \ Reset errors  
     ;  
  
     : uemit? ( -- flag )  uctl@ TXREADY and  ;  
     : uemit  ( char -- )  begin  uemit?  until  udata!  ;

Code Example 12-1 Extended Serial FCode Program (Continued)


     : ukey? ( -- flag )  uctl@ RXREADY and  ;  
     : ukey  ( -- key )   begin  ukey?  until  udata@  ;  
  
     : uwrite              ( addr len -- #written )  
        tuck  bounds ?do   ( len )  
           i c@  uemit     ( len )  
        loop               ( len )  
     ;  
  
     : uread  ( addr len -- #read )             \ -2 for none available right now  
        ukey? 0=  if  2drop -2  exit  then      ( addr len )  
        tuck                                    ( len addr len )  
        begin  dup 0<>   ukey? 0<>  and  while  ( len addr len )  
           over  ukey mask-#data and swap c!    ( len addr len )  
           1 /string                            ( len addr' len' )  
        repeat                                  ( len addr' len' )  
        nip -                                   ( #read )  
     ;  
  
  external  
     : read   ( addr len -- #read )     uread   ;  
     : write  ( addr len -- #written )  uwrite  ;  
  
  end0