Skip to ContentSun and Oracle Channel Sun How to Buy Log In

Writing FCode 3.x Programs

Inom

Driver Developer Site 1.0 AnswerBook

Hitta mer dokumentation

Supportresurser som ingår

Ladda ner denna bok i PDF

Block and Byte Devices

8

Block Devices

Block devices are nonvolatile mass storage devices whose information can be accessed in any order. Hard disks, floppy disks, and CD-ROMs are examples of block devices. OpenBoot typically uses block devices for booting.

This device type generally applies to disk devices, but as far as OpenBoot is concerned, it simply means that the device "looks like a disk" at the OpenBoot software interface level.

The block device's FCode must declare the block device type, and implement the methods open and close, as well as the methods described in "Required Methods".

Although packages of the block device type present a byte-oriented interface to the rest of the system, the associated hardware devices are usually block-oriented i.e. the device reads and writes data in blocks (groups of, for example, 512 or 2048 bytes). The standard /deblocker support package assists in the presentation of a byte-oriented interface overlaying a block-oriented interface, implementing a buffering layer that hides the underlying block length.

Block devices are often subdivided into several logical partitions, as defined by a disk label - a special block, usually the first one on the device, which contains information about the device. The driver is responsible for appropriately interpreting a disk label. The driver may use the standard /disk-label support package if the device does not implement a specialized label. The /disk-label support package interprets a system-dependent label format.

Since the disk booting protocol usually depends on the label format, the standard /disk-label support package also implements a load method for the corresponding boot protocol.

Byte Devices

Byte devices are sequential-access mass storage devices, for example tape devices. OpenBoot typically uses byte devices for booting.

The byte device's FCode program must declare the byte device type, and implement the open and close methods in addition to those described in "Required Methods".

Although packages of the byte device type present a byte-oriented interface to the rest of the system, the associated hardware devices are usually record-oriented; the device reads and writes data in records containing more than one byte. The records may be fixed or variable length. The standard /deblocker support package assists in presenting a byte-oriented interface overlaying a record-oriented interface, implementing a buffering layer that hides the underlying record structure.

Required Methods

`block-size` ( -- block-len )

Returns the record size block-len (in bytes) of all data transfers to or from the device. The most common value for block-len is 512.

This method is only required if the /deblocker support package is used.

`load` ( addr -- size )

load works differently for block and byte devices:

With block devices, it loads a stand-alone program from the device into memory at addr. size is the size in bytes of the program loaded. If the device can contain several such programs, the instance arguments returned by my-args can be used to select the program desired. open is executed before load is invoked.

With byte devices, load reads a stand-alone program from the tape file specified by the value of the argument string given by my-args. That value is the string representation of a decimal integer. If the argument string is null, tape file 0 is used. load places the program in memory at addr, returning the size of the read-in program in bytes.

`max-transfer` ( -- max-len )

Returns the size in bytes of the largest single transfer that the device can perform. max-transfer is expected to be a multiple of block-size.

This method is only required if the /deblocker support package is used.

`read` ( addr len -- actual )

Read at most len bytes from the device into memory at addr. actual is the number of bytes read. If the number of bytes read is 0 or negative, the read failed. Note that len need not be a multiple of the device's normal block size.

`read-blocks` ( addr block# #blocks -- #read )

Read #blocks records of length block-size bytes each from the device, starting at device block block#, into memory at address addr. #read is the number of blocks actually read.

This method is only required if the /deblocker support package is used.

`seek` ( poslow poshigh -- status ) for block; ( offset file# -- error? ) for byte

seek works differently depending on whether it's being used with a block or byte device.

For block devices, seek sets the device position for the next read or write. The position is the byte offset from the beginning of the device specified by the 64-bit number which is the concatenation of poshigh and poslow. status is -1 if the seek fails, and 0 or 1 if it succeeds.

For byte devices, it seeks to the byte offset in file file#. If offset and file# are both 0, rewind the tape. error? is -1 if seek fails, and 0 if seek succeeds.

`write` ( addr len -- actual )

Write len bytes from memory at addr to the device. actual is the number of bytes written. If actual is less than len, the write did not succeed. len need not be a multiple of the device's normal block size.

`write-blocks` ( addr block# #blocks -- #written )

Write #blocks records of length block-size bytes each to the device, starting at block block#, from memory at addr. #written is the number of blocks actually written.

If the device is not capable of random access (e.g. a sequential access tape device), block# is ignored.

This method is only required if the /deblocker support package is used.

Required Properties

Table 8-1

Property Name	Sample Value
`name`	`" SUNW,my-scsi"`
`reg`	`list of registers (device-dependent)`
`device_type`	`block or byte`

Device Driver Examples

The structure of the device tree for the sample card supported by the sample device drivers in this chapter is as follows:

Figure 8-1

Simple Block Device Driver

Code Example 8-1 Simple Block Device Driver


  \ This is at a stage where each leaf node can be used only as a non-bootable device.  
  \ It only creates nodes and publishes necessary properties to identify the device.  
  fcode-version3  
  hex  
     " SUNW,my-scsi"  encode-string " name" property  
  
     h# 20.0000   constant scsi-offset  
     h# 40        constant /scsi  
     my-address scsi-offset + my-space /scsi  reg  
  
     new-device   \ missing "reg" indicates a SCSI "wild-card" node  
        " sd"     encode-string " name" property  
     finish-device  
  
     new-device   \ missing "reg" indicates a SCSI "wild-card" node  
         " st"    encode-string " name" property  
     finish-device  
  end0

Extended Block Device Driver

Code Example 8-2 Sample Driver for my-scsi Device


  \ It is still a non-bootable device. The purpose is to show how an intermediate stage  
  \ of driver can be used to debug board during development. In addition to publishing  
  \ the properties, this sample driver shows methods to access, test and control  
  \ "SUNW,my-scsi" device.  
  
  \ The following main methods are provided for "SUNW,my-scsi" device.  
  \  open  ( -- okay? )  
  \  close  ( -- )  
  \  reset  ( -- )  
  \  selftest  ( -- error? )  
  fcode-version3  
     hex  
     headers  
  
     h# 20.0000    constant scsi-offset  
     h# 40         constant /scsi  
     d# 25.000.000 constant clock-frequency

Code Example 8-2 Sample Driver for my-scsi Device (Continued)


     : identify-me ( -- )  
        " SUNW,my-scsi" encode-string " name" property  
        " scsi" device-type  
  
        my-address scsi-offset + my-space /scsi reg  
     ;  
     identify-me  
  
     h# 10.0000 constant dma-offset  
     h# 10      constant /dma  
     -1 instance value dma-chip  
  
     \ methods to access/control dma registers  
     : dmaaddress  ( -- addr )  dma-chip 4 +  ;  
     : dmacount    ( -- addr )  dma-chip 8 +  ;  
     : dmaaddr@    ( -- n )     dmaaddress rl@  ;  
     : dmaaddr!    ( n -- )     dmaaddress rl!  ;  
     : dmacount@   ( -- n )     dmacount rl@  ;  
     : dmacount!   ( n -- )     dmacount rl!  ;  
     : dma-chip@   ( -- n )     dma-chip rl@  ;  
     : dma-chip!   ( n -- )     dma-chip rl!  ;  
     : dma-btest   ( mask -- flag )  dma-chip@  and  ;  
     : dma-bset    ( mask -- )       dma-chip@  or  dma-chip!  ;  
     : dma-breset  ( mask -- )  not dma-btest  dma-chip!  ;  
  
     external  
  
     \ methods to allocate, map, unmap, free dma buffers  
     : decode-unit  ( addr len -- low high )          decode-2int  ;  
     : dma-alloc    ( size -- vaddr )                 " dma-alloc" $call-parent  ;  
     : dma-free     ( vaddr size -- )                 " dma-free" $call-parent  ;  
     : dma-map-in   ( vaddr size cache? -- devaddr )  " dma-map-in" $call-parent  ;  
     : dma-map-out  ( vaddr devaddr size -- )         " dma-map-out" $call-parent  ;  
  
     \ Dma-sync could be a dummy routine if the parent device doesn't support.  
     : dma-sync  ( virt-addr dev-addr size -- )  
        " dma-sync" my-parent ['] $call-method catch  if  
           2drop 2drop 2drop  
        then  
     ;  
  
     : map-in   ( addr space size -- virt )  " map-in"  $call-parent  ;

Code Example 8-2 Sample Driver for my-scsi Device (Continued)


     : map-out  ( virt size -- )             " map-out" $call-parent  ;  
  
     headers  
     : dma-open   ( -- )  
        my-address dma-offset +  my-space /dma map-in  to dma-chip  
     ;  
     : dma-close  ( -- )  dma-chip /dma map-out  -1 to dma-chip  ;  
  
     -1 instance value scsi-init-id  
     -1 instance value scsi-chip  
     h# 20 constant /mbuf  
     -1 instance value mbuf  
     -1 instance value mbuf-dma  
     d# 6 constant /sense  
     -1 instance value sense-command  
     -1 instance value sense-cmd-dma  
     d# 8 constant #sense-bytes  
     -1 instance value sense-buf  
     -1 instance value sense-buf-dma  
     -1 instance value mbuf0  
     d# 12 constant /cmdbuf  
     -1 instance value cmdbuf  
     -1 instance value cmdbuf-dma  
     -1 instance value scsi-statbuf  
  
     \ mapping and allocation routines for scsi  
     : map-scsi-chip  ( -- )  
        my-address scsi-offset +  my-space /scsi map-in  to scsi-chip  
     ;  
     : unmap-scsi-chip  ( -- )  scsi-chip /scsi map-out  -1 to scsi-chip  ;  
  
     \ After any changes to sense-command by CPU or any changes to sense-cmd-dma by  
     \ device, synchronize changes by issuing " sense-command sense-cmd-dma /sense  
     \ dma-sync " Similarly after any changes to sense-buf, sense-buf-dma, mbuf,  
     \  mbuf-dma, cmdbuf or cmdbuf-dma, synchronize changes by appropriately issuing  
     \  dma-sync map scsi chip and allocate buffers for "sense" command and status  
     : map-scsi  ( -- )  
        map-scsi-chip  
        /sense dma-alloc to sense-command  
        sense-command /sense false dma-map-in  to sense-cmd-dma  
        #sense-bytes dma-alloc to sense-buf  
        sense-buf #sense-bytes false dma-map-in  to sense-buf-dma

Code Example 8-2 Sample Driver for my-scsi Device (Continued)


        2 alloc-mem to scsi-statbuf  
     ;  
  
     \ free buffers for "sense" command and status and unmap scsi chip  
     : unmap-scsi  ( -- )  
        scsi-statbuf 2 free-mem  
        sense-buf sense-buf-dma #sense-bytes dma-sync  \ redundant  
        sense-buf sense-buf-dma #sense-bytes dma-map-out  
        sense-buf #sense-bytes dma-free  
        sense-command sense-cmd-dma /sense dma-sync     \ redundant  
        sense-command sense-cmd-dma /sense dma-map-out  
        sense-command /sense dma-free  
        -1 to sense-command  
        -1 to sense-cmd-dma  
        -1 to sense-buf  
        -1 to scsi-statbuf  
        -1 to sense-buf-dma  
        unmap-scsi-chip  
     ;  
  
     \ constants related to scsi commands  
     h#  0 constant nop  
     h#  1 constant flush-fifo  
     h#  2 constant reset-chip  
     h#  3 constant reset-scsi  
     h# 80 constant dma-nop  
  
     \ words to get scsi register addresses.  
     \ Each chip register is one byte, aligned on a 4-byte boundary.  
     : scsi+  ( offset -- addr )  scsi-chip +  ;  
     : transfer-count-lo     ( -- addr )  h#  0 scsi+  ;  
     : transfer-count-hi     ( -- addr )  h#  4 scsi+  ;  
     : fifo                  ( -- addr )  h#  8 scsi+  ;  
     : command               ( -- addr )  h#  c scsi+  ;  
     : configuration         ( -- addr )  h# 20 scsi+  ;  
     : scsi-test-reg         ( -- addr )  h# 28 scsi+  ;  
  
  
     \ Read only registers:  
     : scsi-status           ( -- addr )  h# 10 scsi+  ;  
     : interrupt-status      ( -- addr )  h# 14 scsi+  ;  
     : sequence-step         ( -- addr )  h# 18 scsi+  ;

Code Example 8-2 Sample Driver for my-scsi Device (Continued)


     : fifo-flags            ( -- addr )  h# 1c scsi+  ;  
  
     \ Write only registers:  
     : select/reconnect-bus-id  ( -- addr )  h# 10 scsi+  ;  
     : select/reconnect-timeout ( -- addr )  h# 14 scsi+  ;  
     : sync-period              ( -- addr )  h# 18 scsi+  ;  
     : sync-offset              ( -- addr )  h# 1c scsi+  ;  
     : clock-conversion-factor  ( -- addr )  h# 24 scsi+  ;  
  
     \ words to read from/store to scsi registers.  
     : cnt@      ( -- w )  transfer-count-lo rb@  transfer-count-hi rb@  bwjoin  ;  
     : fifo@     ( -- c )  fifo rb@  ;  
     : cmd@      ( -- c )  command rb@  ;  
     : stat@     ( -- c )  scsi-status rb@  ;  
     : istat@    ( -- c )  interrupt-status rb@  ;  
     : fifo-cnt  ( -- c )  fifo-flags rb@  h# 1f and ;  
     : data@     ( -- c )  begin  fifo-cnt  until  fifo@  ;  
     : seq@      ( -- c )  sequence-step rb@  h# 7 and ;  
  
     : fifo!  ( c -- )  fifo rb!  ;  
     : cmd!   ( c -- )  command rb!  ;  
     : cnt!   ( w -- )  wbsplit transfer-count-hi rb! transfer-count-lo rb!  ;  
     : targ!  ( c -- )  select/reconnect-bus-id rb!  ;  
     : data!  ( c -- )  begin  fifo-cnt d# 16 <>  until  fifo!  ;  
  
     \ scsi chip noop  and initialization  
     : scsi-nop   ( -- )  nop cmd!  ;  
     : init-scsi  ( -- )  reset-chip cmd!  scsi-nop  ;  
  
     : wait-istat-clear  ( -- error? )  
        d# 1000  
        begin  
           1 ms 1-  ( count )  
           dup 0=   ( count expired? )  
           istat@   ( count expired? istat )  
           0= or    ( count clear? )  
        until       ( count )  
        0=  if  
           istat@ 0<>  if  
              cr ." Can't clear ESP interrupts: "  
              ." Check SCSI Term. Power Fuse." cr  
              true  exit

Code Example 8-2 Sample Driver for my-scsi Device (Continued)


           then  
        then  
        false  
     ;  
  
     : clk-conv-factor  ( -- n )  clock-frequency d# 5.000.000 / 7 and  ;  
  
  
     \ initialize scsi chip, tune time amount, set async operation mode, and set scsi  
     \ bus id  
     : reset-my-scsi ( -- error? )  
        init-scsi  
        h# 93 select/reconnect-timeout rb!  
        0 sync-offset rb!  
        clk-conv-factor clock-conversion-factor rb!  
        h# 4 scsi-init-id 7 and or  configuration rb!  
        wait-istat-clear  
     ;  
  
     : reset-bus ( -- error? )  
        reset-scsi cmd!  wait-istat-clear  
     ;  
  
     : init-n-test  ( -- ok? ) reset-my-scsi 0=  ;  
  
     : get-buffers ( -- )  
        h# 8000 dma-alloc to mbuf0  
        /cmdbuf dma-alloc to cmdbuf  
        cmdbuf /cmdbuf false dma-map-in  to cmdbuf-dma  
     ;  
  
     : give-buffers ( -- )  
        mbuf0 h# 8000 dma-free  -1 to mbuf0  
        cmdbuf cmdbuf-dma /cmdbuf dma-sync             \ redundant  
        cmdbuf cmdbuf-dma /cmdbuf dma-map-out  
        cmdbuf /cmdbuf dma-free  
        -1 to cmdbuf  -1 to cmdbuf-dma  
     ;  
  
     : scsi-selftest ( -- fail? )  reset-my-scsi  ;  
  
     \ dma-alloc and dma-map-in mbuf-dma

Code Example 8-2 Sample Driver for my-scsi Device (Continued)


     : mbuf-alloc ( -- )  
        /mbuf dma-alloc  to mbuf  
        mbuf /mbuf false dma-map-in  to mbuf-dma  
     ;  
  
     \ dma-map-out and dma-free mbuf-dma  
     : mbuf-free ( -- )  
        mbuf mbuf-dma /mbuf dma-sync                \ redundant  
        mbuf mbuf-dma /mbuf dma-map-out  
        mbuf /mbuf dma-free  
        -1 to mbuf  
        -1 to mbuf-dma  
     ;  
  
     external  
     \ If any routine was using buffers allocated by dma-alloc, and was using dma mapped  
     \ by dma-map-in, it would have to dma-sync those buffers after making any changes to  
     \ them.  
     : open  ( -- success? )  
        dma-open  
        " scsi-initiator-id" get-inherited-property 0=  if  
           decode-int  to scsi-init-id  
           2drop  
           map-scsi  
           init-n-test                    ( ok? )  
           dup if                         ( true )  
              get-buffers                 ( true )  
           else  
              unmap-scsi dma-close        ( false )  
           then                           ( success? )  
        else  
           ." Missing initiator id" cr  false  
           dma-close  
        then                              ( success? )  
     ;  
  
     : close  ( -- )  
        give-buffers unmap-scsi dma-close  
     ;  
  
     : reset  ( -- )  
        dma-open map-scsi  
        h# 80 dma-breset

Code Example 8-2 Sample Driver for my-scsi Device (Continued)


        reset-my-scsi drop reset-bus drop  
        unmap-scsi dma-close  
     ;  
  
     \ if scsi-selftest was actually using buffers allocated by mbuf-alloc, it would  
     \ have to do dma-sync after any changes to mbuf or mbuf-dma.  
     : selftest  ( -- fail? )  
        map-scsi  
        mbuf-alloc  
        scsi-selftest  
        mbuf-free  
        unmap-scsi  
     ;  
  
     new-device  \ missing "reg" indicates a SCSI "wild-card" node  
        " sd"     encode-string " name" property  
     finish-device  
  
     new-device  \ missing "reg" indicates a SCSI "wild-card" node  
         " st"     encode-string " name" property  
     finish-device  
  end0