Freescale Semiconductor SEC2SWUG - Manual (Page 13)

SEC 2.0 Reference Device Driver User’s Guide, Rev. 0
Freescale Semiconductor PRELIMINARY—SUBJECT TO CHANGE WITHOUT NOTICE 13
User Interface
scatter-composed, as opposed to direct, contiguous memory (for instance, key data could be in contiguous system
memory, while ciphertext data will be in fragmented user memory).
A problem with marking buffers using this method is that there is no means for the caller to clearly identify which
bit in
scatterBufs matches any given pointer in the request, since the data description portion of different requests
cannot be consistent or of any particular order.
A helper function, MarkScatterBuffer() , is therefore made available by the driver to make the bit/pointer
association logic in the driver accessible to the caller. It's form is:
MarkScatterBuffer(void *request, void *buffer);
where request points to the request block being built (the opId element must be set prior to call), and buffer
points to the element within the request which references a scattered buffer. It will then mark the necessary bit in
scatterBufs that defines this buffer for this specific request type.
3.3.7.3 Direct Scatter-Gather Usage Example
In order to make this usage clear, an example is presented. Assume that a triple DES encryption operation is to be
constructed, where the input and output buffers are located in fragmented user memory, and the cipher keys and IV
are contained in system memory. A
DES_LOADCTX_CRYPT_REQ is zero-allocated as encReq , and constructed:
/* set up encryption operation */
encReq.opId = DPD_TDES_CBC_CTX_ENCRYPT;
encReq.notify = notifier;
encReq.notify_on_error = notifier;
encReq.inIvBytes = 8;
encReq.keyBytes = 24;
encReq.inBytes = bufsize;
encReq.inIvData = iv;
encReq.keyData = cipherKey;
encReq.inData = (unsigned char *)input; /* this buffer is scattered */
encReq.outIvBytes = 8;
encReq.outIvData = ctx;
encReq.outData = (unsigned char *)output; /* this buffer is scattered */
MarkScatterBuffer(&encReq, &encReq.input);
MarkScatterBuffer(&encReq, &encReq.output);
Upon completion of the two mark calls, encReq.scatterBufs will have two bits set within it that the driver
knows how to interpret as meaning that the intended buffers have scatter lists defined for them, and will process
them accordingly as the DPD is built for the hardware.