Freescale Semiconductor SEC2SWUG - Manual (Page 12)

SEC 2.0 Reference Device Driver User’s Guide, Rev. 0
12 PRELIMINARY—SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor
User Interface
The additional data in the process request structures is specific to each request; refer to the specific structure for this
information.
3.3.7 Scatter-Gather Buffer Management
A unique feature of the SEC 2.0 processor is the hardware's ability to read and act on a scatter-gather description list
for a data buffer. This allows the hardware to more efficiently deal with buffers located in memory belonging to a
non-privileged process; memory which may not be contiguous, but instead may be at scattered locations determined
by the memory management scheme of the host system. Any data buffer in any request may be “marked” as a
scattered memory buffer by the requestor as needed.
For the requestor to do so, two actions must be taken:
• A linked list of structures of type EXT_SCATTER_ELEMENT , one per memory fragment, must be constructed
to describe the whole of the buffer's content.
• The buffer pointer shall reference the head of this list, not the data itself. The buffers containing scatter
references shall be marked in the request's
scatterBufs element. Which bits get marked shall be
determined by a helper function that understands the mapping used on an individual request basis.
3.3.7.1 Building the Local Scatter/Gather List with EXT_SCATTER_ELEMENT
Since individual operating systems shall have their own internal means defining memory mapping constructs, the
driver cannot be designed with specific knowledge of one particular mapping method. Therefore, a generic memory
fragment definition structure,
EXT_SCATTER_ELEMENT is defined for this purpose.
Each EXT_SCATTER_ELEMENT describes one contiguous fragment of user memory, and is designed so that multiple
fragments can be tied together into a single linked list. It contains these elements:
With this, the caller must construct the list of all the fragments needed to describe the buffer, NULL terminate the end
of the list, and pass the head as the buffer pointer argument. This list must remain intact until completion of the
request.
3.3.7.2 Scatter Buffer Marking
For reasons of legacy compatibility, the structure of all driver request types maintains the same size and form as prior
versions, with a minor change in that a size-compatible
scatterBufs element was added as a modification to the
channel element in other versions. This allows the caller a means of indicating which buffers in the request are
notify_on_error pointer to the notify on error routine that will be called when the request has completed
unsuccessfully. May instead be a process ID if a user-state signal handler will flag
completion. Refer back to
notifyFlags for more info.
ctxNotifyOnErr context area that is filled in by the driver when there is an error.
status will contain the returned status of request.
nextReq pointer to next request which allows for multiple request to be linked together and sent
via a single
ioctl function call.
void *next; pointer to next fragment in list, NULL if at end of list.
void *fragment; pointer to contiguous data fragment.
unsigned short size; size of this fragment in bytes.