| LAT Internal Communications System: Software Interface Conceptual Design | ||
|---|---|---|
| Prev | Chapter 3. Event Processing | Next |
Event processing begins when the LCB raises the RESULT_READY interrupt. At this time the LEPI reads a result descriptor from the RESULTS FIFO.
From the result descriptor the LEPI can determine three important pieces of information:
Did a DMA error occur ?
Is the result a solicited command/response result ?
Is the result unsolicated event data?
Results for solicited command/response is previously discussed in Chapter 2.
The following sections describe error handling and event handling.
If the result descriptor indicates DMA errors the LEPI calls a user supplied error handling call-back function, passing in the error code as an argument.
See Section 3.3.1 for more about the error handler.
Event processing occurs within the user's event processing call-back function. From within this function the user has complete access to the event.
The first 32-bit word of the event result is called the summary word and contains a 16-bit error word and a 16-bit "event length" word. The size of the length word represents the length of the event packet payload plus the summary word.
After processing the event and when the user is completely finished with the memory that the event occupies, the LEPI needs to deallocate or free that memory in the circular buffer. This is accomplished by "freeing" the length of the event.
To free the event the user has two choices. The first choice is to use the return value from the event processing call-back function as the length of memory to free. Returning a value of 0 means "do not free any memory".
This method allows for a one-to-one correspondence between events and memroy deallocation. Every event is deallocated as it is processed.
The second choice is for the user to pass a length to the LEPI lepi_FreeEvent() function, whose prototype is shown below. The lepi_FreeEvent() function frees the amount of memory indicated by the length parameter.
Using the second method allows the user to defer the freeing of the event memory to a later time, after the event processing call-back function has returned. E.g. the user could bundle several deallocation requests into a single, large deallocation request. This may improve performance over the PCI bus.
This section details an event processing call-back function.
... time passes and myEventProc is called back ...
/* implementation of myEventProc */
int myEventProc( unsigned int *pEvent) {
/* process the event */
/* the return value of process_event() is the amount of
circular buffer memory the LEPI will free. */
return process_event( pEvent);
}
|
In the above example the process_event() function controls how much event memory to free. In the simple case process_event() would return the event length and the event would be freed.
A more complex example would be if process_event() returned 0. In this case process_event() would need to store the event length in memory for later deallocation with the lepi_FreeEvent() function.