MSOP_INTR_ATTACH(D2psm)

MSOP_INTR_ATTACH -- enable the specified interrupt slot

Synopsis

   ms_bool_t pfxintr_attach(ms_intr_dist_t *idpt)

Description

MSOP_INTR_ATTACH enters the interrupt slot specified by ms_intr_dist_t into the dispatching tables and enables distribution of the interrupts for this slot in the interrupt controllers, if it is not already enabled. If the interrupt was masked, it becomes unmasked. MSOP_INTR_ATTACH returns true if successful.

Details of the interrupt slot and its properties are held in the ms_intr_dist_t structure pointed to by the argument.

Interrupts are disabled on the CPU when MSOP_INTR_ATTACH is called.

When an interrupt delivery function in the PSM (see os_claim_vectors(D3psm)) determines that an interrupt source on this interrupt slot was the cause of the interrupt event, it must return the ms_intr_dist_t pointer so that the operating system may deliver the interrupt event appropriately.

The ms_intr_dist_t structure contains at least the following fields:

ms_islot_t msi_slot Interrupt slot

unsigned int msi_flags Miscellaneous flags

unsigned int msi_order Masking order

ms_cpu_t msi_cpu_dist CPUs to which interrupt can be sent

void *msi_mspec Reserved for PSM use

ms_slot is the interrupt slot specified for (or on behalf of) the driver. This slot uniquely identifies an interrupt from the point of view of the interrupt controllers. The core kernel handles sharing of multiple interrupt sources on a particular interrupt slot, for example, physical sharing of the same request line. The core kernel attaches multiple handlers to the same instance of ms_intr_dist_t. The operating system can determine the appropriate slot for a given interrupt source using the interrupt routing information in the Resource Topology Structure.

The following flags can be set in msi_flags:

MSI_MASK_ON_INTR: This flag is set by the operating system to indicate that whenever this interrupt is delivered, this interrupt slot should be masked for at least the current CPU, as if MSOP_INTR_MASK(D2psm) had been called. This may or may not require masking some or all other interrupt slots. The masking should be done implicitly in the interrupt delivery function. If MSI_MASK_ON_INTR is not set, no change should be made to the interrupt masking when this interrupt is delivered.
MSI_NONMASKABLE: This flag is set by the PSM in (rare) cases where the PSM will not be able to support masking, for example, on a CPU with no external interrupt controller. The caller must check this flag on return from MSOP_INTR_ATTACH. In this case, it must not call MSOP_INTR_MASK or MSOP_INTR_UNMASK(D2psm) for this interrupt slot. The caller is then responsible for doing its own masking, by enabling and disabling interrupts at the CPU if necessary. The PSM must not clear MSI_MASK_ON_INTR, but it may otherwise ignore it if it sets MSI_NONMASKABLE on each call to MSOP_INTR_ATTACH.
MSI_ITYPE_CONTINUOUS: This flag is set by the operating system if the interrupt should be handled in continuous assertion mode instead of one-shot mode.
MSI_ORDERED_COMPLETES: This flag is set by the PSM. It constrains the order of MSOP_INTR_COMPLETE(D2psm) operations.
MSI_EVENTS: This flag is set by the PSM if the PSM is permitted to post events by calling os_post_events(D3psm) while processing interrupts for this slot. Delivery events must not post any events during invocations that return an ms_intr_dist_t unless MSI_EVENTS is set.
The single exception to this rule is os_intr_dist_nop, which should always be treated as if it had MSI_EVENTS set. Similarly, os_intr_dist_stray should always be treated as if MSI_EVENTS is set.

msi_order is used only if MSI_MASK_ON_INTR is set and MSPARAM_INTR_ORDER_MAX is greater than zero. In this case, all other interrupt slots with msi_order values less than or equal to the current slot's msi_order value will be implicitly masked when interrupts are delivered via this slot.

msi_cpu_dist should be set to MS_CPU_ANY if the interrupt may be set to any CPU (either dynamically or statically), or to to a specific CPU number to which the interrupt must be sent. If the specified CPU is not active at the time of the attach operation or interrupt the result is undefined. The operating system must ensure that this does not occur. (A CPU is considered active if it has returned from MSOP_SELFINIT and has not since had MSOP_OFFLINE_PREP(D2psm) called.

If the interrupt source for this interrupt slot could come from an I/O bus which is accessible only from a specific CPU group (that is, if msr_priv is true), the interrupt is only delivered to CPUs in that CPU group.

MSOP_INTR_ATTACH undoes the effect of any previous MSOP_INTR_ATTACH for the same interrupt slot.

Once attached, neither the caller (the core kernel) nor the PSM may change any of the values in ms_intr_dist_t. If the core kernel wants to apply new values to this interrupt slot, it must create a new ms_intr_dist_t with the new values (but the same msi_slot), then call MSOP_INTR_ATTACH with the new structure and free the original structure. The caller need not call MSOP_INTR_ATTACH after changing private fields in ms_intr_dist_t (for example, for interrupt sharing), since PSMs do not access private fields.

Arguments

idpt: pointer to the interrupt descriptor

Return values

MSOP_INTR_ATTACH returns:

MS_FALSE: the interrupt cannot be attached, and is not supported.
MS_TRUE: the interrupt is enabled and ready to occur.

Usage

Hardware applicability

All.

Version applicability

psm: 2

References

MSOP_INTR_MASK(D2psm), MSOP_INTR_UNMASK(D2psm), MSOP_INTR_COMPLETE(D2psm), MSOP_OFFLINE_PREP(D2psm) os_claim_vectors(D3psm), os_post_events(D3psm),

`ms_islot_t msi_slot`	Interrupt slot
`unsigned int msi_flags`	Miscellaneous flags
`unsigned int msi_order`	Masking order
`ms_cpu_t msi_cpu_dist`	CPUs to which interrupt can be sent
`void *msi_mspec`	Reserved for PSM use