Freescale Semiconductor SEC2SWUG specifications Scatter-Gather Buffer Management, Notifyonerror

User Interface
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.

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:

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.

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

SEC 2.0 Reference Device Driver User’s Guide, Rev. 0

12 PRELIMINARY—SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor