Freescale Semiconductor SEC2SWUG 3.3.7 Scatter-Gather Buffer Management

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 structu res is specific to each request; refer to the specific struct ure 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 scattere d locations deter mined

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 constr ucted

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.

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 designe d so that mul tiple

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 desc ribe 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.

For reasons of legacy compatibility , the s tructure of all dr iver reques t types m aintains the same size and fo rm 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.