|
|
udi_intr_attach_req(3udi)
Request an interrupt attachment
#include <udi.h>void udi_intr_attach_req ( udi_intr_attach_cb_t *intr_attach_cb );ARGUMENTS intr_attach_cb is a pointer to an interrupt attach control block.
TARGET CHANNEL The target channel for this operation is the bound bus bridge channel connecting a device driver with its parent bus bridge driver, established during the initial binding between the child device and its bus bridge.
DESCRIPTION An interrupt handler driver uses this operation to request an interrupt dispatcher driver to begin accepting interrupts for the handler driver's device and delivering them to the handler. If a device has multiple interrupt sources, the interrupt handler indicates which one to attach by using interrupt_idx in the control block.
The handler driver must prepare for the udi_intr_attach_req operation by allocating an interrupt attach control block, filling in the relevant members of the control block, and spawning its end of a new interrupt event channel.
The new channel will be used to send interrupt event operations from the interrupt dispatcher to the handler. The handler driver spawns its end by calling udi_channel_spawn, passing in its end of the bus bridge channel and setting spawn index equal to the interrupt_idx for this attachment. Using interrupt_idx for the spawn index ensures that it is unique with respect to any other spawn operations in progress on the same bus bridge channel, allowing the environment use this index to match up the two parts of the spawn operation.
Next, the interrupt handler sends the interrupt control block to the dispatcher driver with a udi_intr_attach_req operation.
When the interrupt dispatcher driver receives this request, it spawns its end of the new interrupt event channel, calling udi_channel_spawn, passing in its end of the bus bridge channel and using interrupt_idx for the spawn index. The dispatcher then sends a udi_intr_attach_ack operation back on the original channel to the handler driver, which may now reuse the spawn index.
The handler driver can issue an udi_intr_attach_req for an interrupt_idx that is already attached (i.e., uses the same interrupt_idx as an existing attachment), in which case the udi_intr_attach_req simply changes the interrupt pre-processing for that interrupt source and ignores all other parameters. No channels are spawned and no other actions are taken when interrupt pre-processing is updated through this re-attachment operation.
If preprocessing_handle is not null (use UDI_HANDLE_IS_NULL to test it), events on this channel will be preprocessed. Otherwise, the handler driver must ensure that the handler's end of the new channel is anchored in an interrupt region (i.e. a region with the "interrupt" attribute set in the driver's static driver properties; see Section 1.4, "Extensions to Static Driver Properties").
Some of the advantages of interrupt preprocessing are that the interrupt handler does not need to be in an interrupt region and that the udi_intr_event_ind handler code is not restricted in the operations it may perform before responding with udi_intr_event_rdy, unlike in the non-preprocessed case. There are, however, some restrictions on interrupt preprocessing as discussed in detail in the udi_intr_event_ind operation description.
When the preprocessing trans list is executed, the dispatcher will invoke the trans list at one of four start_label entry points (i.e. the trans list should contain UDI_PIO_LABEL transactions for each of these values, with the exception of zero which implies the beginning of the transaction list):
0 The dispatcher will invoke the preprocessing trans list with this start_label value to enable or re-enable interrupts (at the device level), once the dispatcher has received at least min_event_pend interrupt control blocks. When started from this point, the trans list is responsible for enabling interrupts from the device then proceeding as for start_label 1 below (if applicable). Drivers that cannot determine whether their device asserted an interrupt must instead exit with a UDI_INTR_UNCLAIMED result code and not perform label 1 processing.
1 The dispatcher will invoke the preprocessing trans list at this label to handle the normal interrupt condition. The trans list should process the indicated interrupt(s), placing any interrupt information in the associated buffer, and return an appropriate exit code to the dispatcher as defined on page 5-27.
2 The dispatcher will invoke the preprocessing trans list at this label to handle the interrupt overrun condition. This condition occurs when an unmasked interrupt occurs and the dispatcher has only one udi_intr_event_cb_t available from the handler; any subsequent interrupts would not have an event control block or associated buffer to handle the interrupt. The trans list must check for an actual interrupt: if the device is not interrupting, the trans list must return UDI_INTR_UNCLAIMED; if the trans list handles the interrupt completely and no handler notification is needed, then UDI_INTR_NO_EVENT must be returned; in either of these cases the overrun situation is not encountered. Otherwise, the trans list must process the interrupt and then disable further interrupts from the device (if possible). Interrupts will be re-enabled by an entry into the trans list at start_label value 0 after min_event_pending number of additional udi_intr_event_cb_t control blocks have been supplied to the dispatcher by the handler.
3 The dispatcher will invoke the preprocessing trans list at this label to handle any interrupts received during the overrun condition. This entry point is used if interrupts are received after issuing a label 2 preprocessing operation to disable interrupts (i.e. the label position 2 entry point is unable to disable interrupts from the device and/or if the device is used in a shared interrupt situation) or if any interrupts are received before the dispatcher has enough interrupt event control blocks to use label 1. This trans list must determine if additional interrupts are being signalled by the device and, if so, dismiss the interrupt while discarding any associated data and return a status of UDI_INTR_NO_EVENT. If the device is not indicating an interrupt, UDI_INTR_UNCLAIMED must be returned by the trans list. When the transaction list is entered at this label, the exit code must be one of UDI_INTR_NO_EVENT or UDI_INTR_UNCLAIMED. All PIO preprocessing trans lists entered at label 3 should operate as if there is no associated control block or buffer, even if the handler has supplied more interrupt control blocks; interrupt processing will resume normally once the handler has supplied the min_event_pend number of control blocks and the PIO trans list has been entered at label 0.
Any interrupts for the selected interrupt source that are processed by the dispatcher after receiving a udi_intr_attach_req with a non-null preprocessing_handle will be preprocessed. This means that the dispatcher will use udi_pio_trans to execute the specified trans list (associated with preprocessing_handle). This trans list must include all operations necessary to de-assert its interrupt (if it was asserted) in all cases.
When the dispatcher calls udi_pio_trans it will set the buf argument to the buffer passed in the udi_intr_event_cb_t from the udi_intr_event_rdy. This buffer must have been pre-allocated by the handler to contain the data to be returned by the interrupt dispatcher; the buffer will not be extended as part of the interrupt handling operation. The trans list can use this buffer to pass data to the handler driver's upper-level handler.
If the bus type supports event info, the dispatcher driver must set the mem_ptr argument to point to a memory block containing the event info for this interrupt. Otherwise, mem_ptr must be set to NULL.
The preprocessing trans list must only use the first byte of the control block's scratch space to pass back the status of the interrupt preprocessing as specified in the udi_intr_event_cb_t description. No other references can be made to scratch space since the size and contents are unspecified beyond the first byte.
The result from the udi_pio_trans call (set with UDI_PIO_END) is used to determine the disposition of the interrupt, as described in udi_intr_event_cb_t and udi_intr_event_ind.
The bridge driver must free the preprocessing_handle after it has finished with it (as a result of either another udi_intr_attach_req with a new handle or a udi_intr_detach_req), by using udi_pio_unmap.
warnings The mem_ptr value must follow the rules for memory object usage described in Section 5.2.1.1, "Using Memory Pointers with Asynchronous Service Calls," on page 5-2 of the UDI Core Specification.
REFERENCES udi_intr_attach_cb_t, udi_channel_spawn, udi_intr_attach_ack, udi_intr_event_ind, udi_pio_trans, udi_pio_map, udi_pio_unmap