[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

Unlike most other Exec Device drivers, SANA-II drivers have no internal
buffers. Instead, they read/write to/from an abstract data structure
allocated by the driver user. The driver accesses these buffers only via
functions that the driver user provides to the driver. The driver user
must provide two functions--one copies data to the abstract data structure
and one copies data from the abstract data structure. The driver user can
therefore choose the data structure used for buffer management by both the
driver and driver user in order to have efficient memory and CPU usage
overall.

The IOSana2Req contains a pointer to data and the length of said data. A
driver is not allowed to make assumptions about how the data is stored.
The driver cannot directly manipulate or examine the buffer in any manner.
The driver can only access the buffer by calling the functions provided by
the driver user.

Before calling OpenDevice(), the driver user points ios2_BufferManagement
to a list of tags (defined in <devices/sana2.h>) which include pointers to
the buffer management functions required by the driver (defined below).
The driver will fail to open if the driver user does not supply all of the
required functions.  If the device opens successfully, the driver sets
ios2_BufferManagement to a value which this opener must use in all future
calls to the driver.  This "magic cookie" is used from then on to access
these functions (a "magic cookie" is a value which one software entity
passes to another but which is only meaningful to one of the software
entities).  The driver user may not use the "magic cookie" in any way--it
is for the driver to do with as it wishes.  The driver could in theory
choose to just copy the tag list to driver-owned memory and then parse the
list for every IORequest, but it is much more efficient for the driver to
create some sort of table of functions and to point ios2_BufferManagement
to that table.

The specification currently includes only two tags for the OpenDevice()
ios2_BufferManagement tag list:

    S2_CopyToBuff  - This is a pointer to a function which conforms to
             the CopyToBuff Autodoc.

    S2_CopyFromBuff - This is a pointer to a function which conforms to
             the CopyFromBuff Autodoc.