Freescale Semiconductor SEC2SWUG - Manual (Page 5)

SEC 2.0 Reference Device Driver User’s Guide, Rev. 0
Freescale Semiconductor PRELIMINARY—SUBJECT TO CHANGE WITHOUT NOTICE 5
User Interface
2.1.5 Deferred Service Routine
The ProcessingComplete() routine completes the request outside of the interrupt service routine, and runs in a
non-ISR context. This routine depends on the IsrMsgQId queue and processes messages written to the queue by
the interrupt service routine. This function will determine which request is complete, and notify the calling task
using any handler specified by that calling task. It will then check the remaining content of the process request
queue, and schedule any queued requests.
3 User Interface
3.1 Application Interface
In order to make a request of the SEC2 device, the calling application populates a request structure with information
describing the request. These structures are described in
Section 4, “Individual Request Type Descriptions,” and
include items such as operation ID, channel, callback routines (success and error), and data.
Once the request is prepared, the application calls ioctl() with the prepared request. This function is a standard
system call used by operating system I/O subsystems to implement special-purpose functions. It typically follows
the format:
int ioctl(int fd, /* file descriptor */
int function, /* function code */
int arg /* arbitrary argument (driver dependent) */
The function code (second argument) is defined as the I/O control code. This code will specify the driver-specific
operation to be performed by the device in question. The third argument is the pointer to the SEC2 user request
structure which contains information needed by the driver to perform the function requested.
The following is a list of guidelines to be followed by the end-user application when preparing a request structure:
• The first member of every request structure is an operation ID (opID). The operation ID is used by the
device driver to determine the format of the request structure.
• While all requests have a “channel” member, it's presence is a holdover from earlier variations of the
security engine. For SEC2, it no longer has a valid use, and is retained solely to maintaining request
compatibility for applications written for older security engines.
• All process request structures have a status member. This value is filled in by the device driver when the
interrupt for the operation occurs and it reflects the status of the operation as indicated by the interrupt. The
valid values for this status member are DONE (normal status) or ERROR (error status).
• All process request structures have two notify members, notify and notify_on_error. These notify
members can be used by the device driver to notify the application when its request has been completed.
They may be the same function, or different, as required by the caller's operational requirements.
• All process request structures have a next request member. This allows the application to chain multiple
process requests together.
• It is the application's choice to use a notifier function or to poll the status member.