Revision 3

   $Id: SANA2Revision3 1.1 1996/07/14 22:18:55 heinz Exp $

Enhancement to SANA-IIR2 (S2R2) for better buffer management

================================================

It has been observed that the standard buffer management callbacks may not be very efficient for certain types of hardware. They also do not allow driver DMA access. Therefore the original S2R2 specification has been enhanced to allow for more flexible buffer management. This enhancement is fully backwards compatible. This document together with the original S2R2 documentation, should be referred to as "SANA-IIR3" or S2R3. Future enhancements shall be built upon S2R3.

All the new features are completely optional and do not collide with existing features. They may be used only when the protocol stack asks for them on opening a driver.

The enhancements consist of several new tags that may be specified by a protocol stack on OpenDevice() to offer certain data transfer options. It is up to the device driver to chose which callbacks to use at what time. These tags are advisory only and may be ignored by the driver for any data buffer at any time.

1. define S2_CopyToBuff16 (S2_Dummy + 4)
2. define S2_CopyFromBuff16 (S2_Dummy + 5)
3. define S2_CopyToBuff32 (S2_Dummy + 6)
4. define S2_CopyFromBuff32 (S2_Dummy + 7)

   These are optional callbacks presented to the device with the
   same calling interface as for S2_CopyToBuff or S2_CopyFromBuff,
   respectively. The difference to the original callbacks is the
   required and guaranteed transfer size and alignment for
   accessing the device's buffer for a single piece of a data of
   either 16 or 32 bits, a data word. The copy function called may
   only use 16/32 bit aligned read/write commands of 16/32 bits at
   once to transfer the data words, respectively. If the buffer
   data length is not a multiple of the required data word
   transfer size, the last data word transfer may contain garbage
   padding in either transfer direction.

   These tags have been added to support direct writes into
   hardware buffers that do not allow arbitrarily sized or aligned
   accesses.

1. define S2_DMACopyToBuff32 (S2_Dummy + 8)
2. define S2_DMACopyFromBuff32 (S2_Dummy + 9)

   If the protocol stack wants to optionally enhance data transfer
   efficiency with DMA supporting devices, it may pass any of
   these optional tags to the device on OpenDevice().

   If the device driver supports DMA, it may call the respective
   callback with the abstract magic cookie ios2_Data in register
   A0. The callback may return NULL in D0. In this case, the
   driver may not use DMA for this buffer. Alternatively, the
   callback may return the address of the actual data buffer
   in D0, if it has these characteristics:

   - The buffer is in contigous memory. Depending on the intended
     data direction, it shall be readable or writable.
   - The buffer is aligned on a 32 bit boundary.
   - The buffer size shall be a multiple of 32 bit and it is at
     least >= ios2_DataLength.

   It is up to the driver to decide if it can use DMA for this
   buffer and it shall fall back to the standard CPU callbacks if
   necessary. The data transfer method actually used by the driver
   will not be known in advance by the protocol stack.

It is obviously non conforming and always has been that way for SANA-II device developers to define their own tags.

Heinz Wrobel <heinz@amiga.de>