interruptswriting handlers interrupt handling This chapter describes mechanisms for handling interrupts, such as registering, servicing, and removing interrupts. This chapter provides information on the following subjects:Interrupt Handler Overview Device Interrupts Registering Interrupts Interrupt Handler Functionality Handling High-Level Interrupts interruptsdescription ofAn interrupt is a hardware signal from a device to a CPU. An interrupt tells the CPU that the device needs attention and that the CPU should stop any current activity and respond to the device. If the CPU is not performing a task that has higher priority than the priority of the interrupt, then the CPU suspends the current thread. The CPU then invokes the interrupt handler for the device that sent the interrupt signal. The job of the interrupt handler is to service the device and stop the device from interrupting. When the interrupt handler returns, the CPU resumes the work it was doing before the interrupt occurred.The Solaris DDI/DKI provides interfaces for performing the following tasks:Determining interrupt type and registration requirements Registering interrupts Servicing interrupts Masking interrupts Getting interrupt pending information Getting and setting priority information device interruptsinterrupts; interrupt handling interruptstypes ofautovectored interruptsI/O buses implement interrupts in two common ways: vectored and polled. Both methods commonly supply a bus-interrupt priority level. Vectored devices also supply an interrupt vector. Polled devices do not supply interrupt vectors.To stay current with changing bus technologies, the Solaris OS has been enhanced to accommodate both newer types of interrupts and more traditional interrupts that have been in use for many years. Specifically, the operating system now recognizes three types of interrupts:legacy interruptsdefinedinterruptslegacy definedLegacy interrupts – Legacy or fixed interrupts refer to interrupts that use older bus technologies. With these technologies, interrupts are signaled by using one or more external pins that are wired “out-of-band,” that is, separately from the main lines of the bus. Newer bus technologies such as PCI Express maintain software compatibility by emulating legacy interrupts through in-band mechanisms. These emulated interrupts are treated as legacy interrupts by the host OS. interruptsmessage-signaled definedmessage-signaled interruptsdefinedinterruptsMSI definedMSI interruptsdefinedMessage-signaled interrupts – Instead of using pins, message-signaled interrupts (MSI) are in-band messages and can target addresses in the host bridge. (See PCI Local Bus for more information on host bridges.) MSIs can send data along with the interrupt message. Each MSI is unshared so that an MSI that is assigned to a device is guaranteed to be unique within the system. A PCI function can request up to 32 MSI messages. interruptsMSI-X definedMSI-X interruptsdefinedExtended message-signaled interrupts – Extended message-signaled interrupts (MSI-X) are an enhanced version of MSIs. MSI-X interrupts have the following added advantages:Support 2048 messages rather than 32 messages Support independent message address and message data for each message Support per-message masking Enable more flexibility when software allocates fewer vectors than hardware requests. The software can reuse the same MSI-X address and data in multiple MSI-X slots. Some newer bus technologies such as PCI Express require MSIs but can accommodate legacy interrupts by using INTx emulation. INTx emulation is used for compatibility purposes, but is not considered to be good practice. interruptspriority levelsinterrupt handlinghigh-level interruptsA bus prioritizes a device interrupt at a bus-interrupt level. The bus interrupt level is then mapped to a processor-interrupt level. A bus interrupt level that maps to a CPU interrupt priority above the scheduler priority level is called a high-level interrupt. High-level interrupt handlers are restricted to calling the following DDI interfaces:mutex_enter functionmutex_exit functionmutex_enter9F and mutex_exit9F on a mutex that is initialized with an interrupt priority associated with the high-level interrupt ddi_intr_trigger_softint functioninterrupt handlingddi_intr_trigger_softint functionddi_intr_trigger_softint9F The following DDI get and put routines: ddi_get89F, ddi_put89F, ddi_get169F, ddi_put169F, ddi_get329F, ddi_put329F, ddi_get649F, and ddi_put649F. A bus-interrupt level by itself does not determine whether a device interrupts at a high level. A particular bus-interrupt level can map to a high-level interrupt on one platform, but map to an ordinary interrupt on another platform.ddi_intr_hilevel functioninterrupt handlingddi_intr_hilevel functionA driver is not required to support devices that have high-level interrupts. However, the driver is required to check the interrupt level. If the interrupt priority is greater than or equal to the highest system priority, the interrupt handler runs in high-level interrupt context. In this case, the driver can fail to attach, or the driver can use a two-level scheme to handle interrupts. For more information, see Handling High-Level Interrupts. legacy interruptsusing interruptsusing legacy The only information that the system has about a device interrupt is the priority level of the bus interrupt and the interrupt request number. An example of the priority level for a bus interrupt is the IPL on an SBus in a SPARC machine. An example of an interrupt request number is the IRQ on an ISA bus in an x86 machine.When an interrupt handler is registered, the system adds the handler to a list of potential interrupt handlers for each IPL or IRQ. When the interrupt occurs, the system must determine which device actually caused the interrupt, among all devices that are associated with a given IPL or IRQ. The system calls all the interrupt handlers for the designated IPL or IRQ until one handler claims the interrupt.The following buses are capable of supporting polled interrupts:SBus ISA PCI Both standard (MSI) and extended (MSI-X) message-signaled interrupts are implemented as in-band messages. A message-signaled interrupt is posted as a write with an address and value that are specified by the software.interruptsMSI implementationMSI interruptsimplementationConventional PCI specifications include optional support for Message Signaled Interrupts (MSI). An MSI is an in-band message that is implemented as a posted write. The address and the data for the MSI are specified by software and are specific to the host bridge. Because the messages are in-band, the receipt of the message can be used to “push” data that is associated with the interrupt. By definition, MSI interrupts are unshared. Each MSI message that is assigned to a device is guaranteed to be a unique message in the system. PCI functions can request 1, 2, 4, 8, 16, or 32 MSI messages. Note that the system software can allocate fewer MSI messages to a function than the function requested. The host bridge can be limited in the number of unique MSI messages that are allocated for devices. interruptsMSI-X implementationMSI-X interruptsimplementationMSI-X interrupts are enhanced versions of MSI interrupts that have the same features as MSI interrupts with the following key differences:A maximum of 2048 MSI-X interrupt vectors are supported per device. Address and data entries are unique per interrupt vector. MSI-X supports per function masking and per vector masking. ddi_intr_dup_handler functioninterrupt handlingddi_intr_dup_handler functionddi_intr_add_handler functioninterrupt handlingddi_intr_add_handler functionddi_intr_enable functioninterrupt handlingddi_intr_enable functionddi_intr_disable functioninterrupt handlingddi_intr_disable functionddi_intr_alloc functioninterrupt handlingddi_intr_alloc functionddi_intr_free functioninterrupt handlingddi_intr_free functionddi_intr_remove_handler functioninterrupt handlingddi_intr_remove_handler functionWith MSI-X interrupts, an unallocated interrupt vector of a device can use a previously added or initialized MSI-X interrupt vector to share the same vector address, vector data, interrupt handler, and handler arguments. Use the ddi_intr_dup_handler9F function to alias the resources provided by the Solaris OS to the unallocated interrupt vectors on an associated device. For example, if 2 MSI-X interrupts are allocated to a driver and 32 interrupts are supported on the device, then the driver can use ddi_intr_dup_handler to alias the 2 interrupts it received to the 30 additional interrupts on the device.The ddi_intr_dup_handler function can duplicate interrupts that were added with ddi_intr_add_handler9F or initialized with ddi_intr_enable9F.A duplicated interrupt is disabled initially. Use ddi_intr_enable to enable the duplicated interrupt. You cannot remove the original MSI-X interrupt handler until all duplicated interrupt handlers that are associated with this original interrupt handler are removed. To remove a duplicated interrupt handler, first call ddi_intr_disable9F, and then call ddi_intr_free9F. When all duplicated interrupt handlers that are associated with this original interrupt handler are removed, then you can use ddi_intr_remove_handler9F to remove the original MSI-X interrupt handler. See the ddi_intr_dup_handler9F man page for examples. soft interruptsinterrupt handlingsoftware interruptsThe Solaris DDI/DKI supports software interrupts, also known as soft interrupts. Soft interrupts are initiated by software rather than by a hardware device. Handlers for these interrupts must also be added to and removed from the system. Soft interrupt handlers run in interrupt context and therefore can be used to do many of the tasks that belong to an interrupt handler.Hardware interrupt handlers must perform their tasks quickly, because the handlers might have to suspend other system activity while doing these tasks. This requirement is particularly true for high-level interrupt handlers, which operate at priority levels greater than the priority level of the system scheduler. High-level interrupt handlers mask the operations of all lower-priority interrupts, including the interrupt operations of the system clock. Consequently, the interrupt handler must avoid involvement in activities that might cause it to sleep, such as acquiring a mutex.interrupt handlinghigh-level interruptsIf the handler sleeps, then the system might hang because the clock is masked and incapable of scheduling the sleeping thread. For this reason, high-level interrupt handlers normally perform a minimum amount of work at high-priority levels and delegate other tasks to software interrupts, which run below the priority level of the high-level interrupt handler. Because software interrupt handlers run below the priority level of the system scheduler, software interrupt handlers can do the work that the high-level interrupt handler was incapable of doing. The Solaris OS provides a framework for registering and unregistering interrupts and provides support for Message Signaled Interrupts (MSIs). Interrupt management interfaces enable you to manipulate priorities, capabilities, and interrupt masking, and to obtain pending information.interruptscapability functionsddi_intr_get_navail functioninterrupt handlingddi_intr_get_navail functionddi_intr_get_nintrs functioninterrupt handlingddi_intr_get_nintrs functionddi_intr_get_supported_types functioninterrupt handlingddi_intr_get_supported_types functionddi_intr_get_cap functioninterrupt handlingddi_intr_get_cap functionUse the following functions to obtain interrupt information:ddi_intr_get_navail9F Returns the number of interrupts available for a specified hardware device and interrupt type. ddi_intr_get_nintrs9F Returns the number of interrupts that the device supports for the specified interrupt type. ddi_intr_get_supported_types9F Returns the hardware interrupt types that are supported by both the device and the host. ddi_intr_get_cap9F Returns interrupt capability flags for the specified interrupt. interruptsinitialization and destruction functionsddi_intr_alloc functioninterrupt handlingddi_intr_alloc functionddi_intr_free functioninterrupt handlingddi_intr_free functionddi_intr_set_cap functioninterrupt handlingddi_intr_set_cap functionddi_intr_add_handler functioninterrupt handlingddi_intr_add_handler functionddi_intr_dup_handler functioninterrupt handlingddi_intr_dup_handler functionddi_intr_remove_handler functioninterrupt handlingddi_intr_remove_handler functionddi_intr_enable functioninterrupt handlingddi_intr_enable functionddi_intr_disable functioninterrupt handlingddi_intr_disable functionddi_intr_block_enable functioninterrupt handlingddi_intr_block_enable functionddi_intr_block_disable functioninterrupt handlingddi_intr_block_disable functionddi_intr_set_mask functioninterrupt handlingddi_intr_set_mask functionddi_intr_clr_mask functioninterrupt handlingddi_intr_clr_mask functionddi_intr_get_pending functioninterrupt handlingddi_intr_get_pending functionUse the following functions to create and remove interrupts:ddi_intr_alloc9F Allocates system resources and interrupt vectors for the specified type of interrupt. ddi_intr_free9F Releases the system resources and interrupt vectors for a specified interrupt handle. ddi_intr_set_cap9F Sets the capability of the specified interrupt through the use of the DDI_INTR_FLAG_LEVEL and DDI_INTR_FLAG_EDGE flags. ddi_intr_add_handler9F Adds an interrupt handler. ddi_intr_dup_handler9F Use with MSI-X only. Copies an address and data pair for an allocated interrupt vector to an unused interrupt vector on the same device. ddi_intr_remove_handler9F Removes the specified interrupt handler. ddi_intr_enable9F Enables the specified interrupt. ddi_intr_disable9F Disables the specified interrupt. ddi_intr_block_enable9F Use with MSI only. Enables the specified range of interrupts. ddi_intr_block_disable9F Use with MSI only. Disables the specified range of interrupts. ddi_intr_set_mask9F Sets an interrupt mask if the specified interrupt is enabled. ddi_intr_clr_mask9F Clears an interrupt mask if the specified interrupt is enabled. ddi_intr_get_pending9F Reads the interrupt pending bit if such a bit is supported by either the host bridge or the device. interruptspriority management functionsddi_intr_get_pri functioninterrupt handlingddi_intr_get_pri functionddi_intr_set_pri functioninterrupt handlingddi_intr_set_pri functionddi_intr_get_hilevel_pri functioninterrupt handlingddi_intr_get_hilevel_pri functionUse the following functions to obtain and set priority information:ddi_intr_get_pri9F Returns the current software priority setting for the specified interrupt. ddi_intr_set_pri9F Sets the interrupt priority level for the specified interrupt. ddi_intr_get_hilevel_pri9F Returns the minimum priority level for a high-level interrupt. interruptssoft interrupt functionsddi_intr_add_softint functioninterrupt handlingddi_intr_add_softint functionddi_intr_trigger_softint functioninterrupt handlingddi_intr_trigger_softint functionddi_intr_remove_softint functioninterrupt handlingddi_intr_remove_softint functionddi_intr_get_softint_pri functioninterrupt handlingddi_intr_get_softint_pri functionddi_intr_set_softint_pri functioninterrupt handlingddi_intr_set_softint_pri functionUse the following functions to manipulate soft interrupts and soft interrupt handlers:ddi_intr_add_softint9F Adds a soft interrupt handler. ddi_intr_trigger_softint9F Triggers the specified soft interrupt. ddi_intr_remove_softint9F Removes the specified soft interrupt handler. ddi_intr_get_softint_pri9F Returns the soft interrupt priority for the specified interrupt. ddi_intr_set_softint_pri9F Changes the relative soft interrupt priority for the specified soft interrupt. interruptschanging soft interrupt priority exampleinterruptschecking pending interrupts exampleinterruptssetting interrupt masks exampleinterruptsclearing interrupt masks exampleThis section provides examples for performing the following tasks:Changing soft interrupt priority Checking for pending interrupts Setting interrupt masks Clearing interrupt masks ddi_intr_set_softint_pri function interrupt handlingddi_intr_set_softint_pri function interrupt handlingsoftware interrupts software interruptschanging priority Use the ddi_intr_set_softint_pri9F function to change the soft interrupt priority to 9.if (ddi_intr_set_softint_pri(mydev->mydev_softint_hdl, 9) != DDI_SUCCESS) cmn_err (CE_WARN, "ddi_intr_set_softint_pri failed"); ddi_intr_get_pending function interrupt handlingddi_intr_get_pending function interrupt handlingpending interrupts Use the ddi_intr_get_pending9F function to check whether an interrupt is pending.if (ddi_intr_get_pending(mydevp->htable[0], &pending) != DDI_SUCCESS) cmn_err(CE_WARN, "ddi_intr_get_pending() failed"); else if (pending) cmn_err(CE_NOTE, "ddi_intr_get_pending(): Interrupt pending"); ddi_intr_set_mask function interrupt handlingddi_intr_set_mask function interrupt handlingsetting masks Use the ddi_intr_set_mask9F function to set interrupt masking to prevent the device from receiving interrupts.if ((ddi_intr_set_mask(mydevp->htable[0]) != DDI_SUCCESS)) cmn_err(CE_WARN, "ddi_intr_set_mask() failed"); ddi_intr_clr_mask function interrupt handlingddi_intr_clr_mask function interrupt handlingclearing masks Use the ddi_intr_clr_mask9F function to clear interrupt masking. The ddi_intr_clr_mask9F function fails if the specified interrupt is not enabled. If the ddi_intr_clr_mask9F function succeeds, the device starts generating interrupts.if (ddi_intr_clr_mask(mydevp->htable[0]) != DDI_SUCCESS) cmn_err(CE_WARN, "ddi_intr_clr_mask() failed"); interrupt handlersregisteringddi_intr_add_handler functioninterrupt handlingddi_intr_add_handler functionBefore a device driver can receive and service interrupts, the driver must call ddi_intr_add_handler9F to register an interrupt handler with the system. Registering interrupt handlers provides the system with a way to associate an interrupt handler with an interrupt specification. The interrupt handler is called when the device might have been responsible for the interrupt. The handler has the responsibility of determining whether it should handle the interrupt and, if so, of claiming that interrupt.Use the ::interrupts command in the mdb or kmdb debugger to retrieve the registered interrupt information of a device on supported SPARC and x86 systems. interruptsregistering legacy interrupts To register a driver's interrupt handler, the driver typically performs the following steps in its attach9E entry point:Use ddi_intr_get_supported_types9F to determine which types of interrupts are supported. Use ddi_intr_get_nintrs9F to determine the number of supported interrupt types. Use kmem_zalloc9F to allocate memory for DDI interrupt handles. For each interrupt type that you allocate, take the following steps:Use ddi_intr_get_pri9F to get the priority for the interrupt. If you need to set a new priority for the interrupt, use ddi_intr_set_pri9F. Use mutex_init9F to initialize the lock. Use ddi_intr_add_handler9F to register the handler for the interrupt. Use ddi_intr_enable9F to enable the interrupt. Take the following steps to free each interrupt:Disable each interrupt using ddi_intr_disable9F. Remove the interrupt handler using ddi_intr_remove_handler9F. Remove the lock using mutex_destroy9F. Free the interrupt using ddi_intr_free9F and kmem_free9F to free memory that was allocated for DDI interrupt handles. interruptsregistering legacy interrupt example The following example shows how to install an interrupt handler for a device called mydev. This example assumes that mydev supports one interrupt only./* Determine which types of interrupts supported */ ret = ddi_intr_get_supported_types(mydevp->mydev_dip, &type); if ((ret != DDI_SUCCESS) || (!(type & DDI_INTR_TYPE_FIXED))) { cmn_err(CE_WARN, "Fixed type interrupt is not supported"); return (DDI_FAILURE); } /* Determine number of supported interrupts */ ret = ddi_intr_get_nintrs(mydevp->mydev_dip, DDI_INTR_TYPE_FIXED, &count); /* * Fixed interrupts can only have one interrupt. Check to make * sure that number of supported interrupts and number of * available interrupts are both equal to 1. */ if ((ret != DDI_SUCCESS) || (count != 1)) { cmn_err(CE_WARN, "No fixed interrupts"); return (DDI_FAILURE); } /* Allocate memory for DDI interrupt handles */ mydevp->mydev_htable = kmem_zalloc(sizeof (ddi_intr_handle_t), KM_SLEEP); ret = ddi_intr_alloc(mydevp->mydev_dip, mydevp->mydev_htable, DDI_INTR_TYPE_FIXED, 0, count, &actual, 0); if ((ret != DDI_SUCCESS) || (actual != 1)) { cmn_err(CE_WARN, "ddi_intr_alloc() failed 0x%x", ret); kmem_free(mydevp->mydev_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } /* Sanity check that count and available are the same. */ ASSERT(count == actual); /* Get the priority of the interrupt */ if (ddi_intr_get_pri(mydevp->mydev_htable[0], &mydevp->mydev_intr_pri)) { cmn_err(CE_WARN, "ddi_intr_alloc() failed 0x%x", ret); (void) ddi_intr_free(mydevp->mydev_htable[0]); kmem_free(mydevp->mydev_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } cmn_err(CE_NOTE, "Supported Interrupt pri = 0x%x", mydevp->mydev_intr_pri); /* Test for high level mutex */ if (mydevp->mydev_intr_pri >= ddi_intr_get_hilevel_pri()) { cmn_err(CE_WARN, "Hi level interrupt not supported"); (void) ddi_intr_free(mydevp->mydev_htable[0]); kmem_free(mydevp->mydev_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } /* Initialize the mutex */ mutex_init(&mydevp->mydev_int_mutex, NULL, MUTEX_DRIVER, DDI_INTR_PRI(mydevp->mydev_intr_pri)); /* Register the interrupt handler */ if (ddi_intr_add_handler(mydevp->mydev_htable[0], mydev_intr, (caddr_t)mydevp, NULL) !=DDI_SUCCESS) { cmn_err(CE_WARN, "ddi_intr_add_handler() failed"); mutex_destroy(&mydevp->mydev_int_mutex); (void) ddi_intr_free(mydevp->mydev_htable[0]); kmem_free(mydevp->mydev_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } /* Enable the interrupt */ if (ddi_intr_enable(mydevp->mydev_htable[0]) != DDI_SUCCESS) { cmn_err(CE_WARN, "ddi_intr_enable() failed"); (void) ddi_intr_remove_handler(mydevp->mydev_htable[0]); mutex_destroy(&mydevp->mydev_int_mutex); (void) ddi_intr_free(mydevp->mydev_htable[0]); kmem_free(mydevp->mydev_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } return (DDI_SUCCESS); } interruptsremoving legacy interrupt example The following example shows how legacy interrupts are removed./* disable interrupt */ (void) ddi_intr_disable(mydevp->mydev_htable[0]); /* Remove interrupt handler */ (void) ddi_intr_remove_handler(mydevp->mydev_htable[0]); /* free interrupt handle */ (void) ddi_intr_free(mydevp->mydev_htable[0]); /* free memory */ kmem_free(mydevp->mydev_htable, sizeof (ddi_intr_handle_t)); interruptsregistering MSI interrupts To register a driver's interrupt handler, the driver typically performs the following steps in its attach9E entry point:Use ddi_intr_get_supported_types9F to determine which types of interrupts are supported. Use ddi_intr_get_nintrs9F to determine the number of supported MSI interrupt types. Use ddi_intr_alloc9F to allocate memory for the MSI interrupts. For each interrupt type that you allocate, take the following steps:Use ddi_intr_get_pri9F to get the priority for the interrupt. If you need to set a new priority for the interrupt, use ddi_intr_set_pri9F. Use mutex_init9F to initialize the lock. Use ddi_intr_add_handler9F to register the handler for the interrupt. Use one of the following functions to enable all the interrupts:Use ddi_intr_block_enable9F to enable all the interrupts in a block. Use ddi_intr_enable9F in a loop to enable each interrupt individually. interruptsregistering MSI interrupts example The following example illustrates how to register an MSI interrupt for a device called mydev./* Get supported interrupt types */ if (ddi_intr_get_supported_types(devinfo, &intr_types) != DDI_SUCCESS) { cmn_err(CE_WARN, "ddi_intr_get_supported_types failed"); goto attach_fail; } if (intr_types & DDI_INTR_TYPE_MSI) mydev_add_msi_intrs(mydevp); /* Check count, available and actual interrupts */ static int mydev_add_msi_intrs(mydev_t *mydevp) { dev_info_t *devinfo = mydevp->devinfo; int count, avail, actual; int x, y, rc, inum = 0; /* Get number of interrupts */ rc = ddi_intr_get_nintrs(devinfo, DDI_INTR_TYPE_MSI, &count); if ((rc != DDI_SUCCESS) || (count == 0)) { cmn_err(CE_WARN, "ddi_intr_get_nintrs() failure, rc: %d, " "count: %d", rc, count); return (DDI_FAILURE); } /* Get number of available interrupts */ rc = ddi_intr_get_navail(devinfo, DDI_INTR_TYPE_MSI, &avail); if ((rc != DDI_SUCCESS) || (avail == 0)) { cmn_err(CE_WARN, "ddi_intr_get_navail() failure, " "rc: %d, avail: %d\n", rc, avail); return (DDI_FAILURE); } if (avail < count) { cmn_err(CE_NOTE, "nitrs() returned %d, navail returned %d", count, avail); } /* Allocate memory for MSI interrupts */ mydevp->intr_size = count * sizeof (ddi_intr_handle_t); mydevp->htable = kmem_alloc(mydevp->intr_size, KM_SLEEP); rc = ddi_intr_alloc(devinfo, mydevp->htable, DDI_INTR_TYPE_MSI, inum, count, &actual, DDI_INTR_ALLOC_NORMAL); if ((rc != DDI_SUCCESS) || (actual == 0)) { cmn_err(CE_WARN, "ddi_intr_alloc() failed: %d", rc); kmem_free(mydevp->htable, mydevp->intr_size); return (DDI_FAILURE); } if (actual < count) { cmn_err(CE_NOTE, "Requested: %d, Received: %d", count, actual); } mydevp->intr_cnt = actual; /* * Get priority for first msi, assume remaining are all the same */ if (ddi_intr_get_pri(mydevp->htable[0], &mydev->intr_pri) != DDI_SUCCESS) { cmn_err(CE_WARN, "ddi_intr_get_pri() failed"); /* Free already allocated intr */ for (y = 0; y < actual; y++) { (void) ddi_intr_free(mydevp->htable[y]); } kmem_free(mydevp->htable, mydevp->intr_size); return (DDI_FAILURE); } /* Call ddi_intr_add_handler() */ for (x = 0; x < actual; x++) { if (ddi_intr_add_handler(mydevp->htable[x], mydev_intr, (caddr_t)mydevp, NULL) != DDI_SUCCESS) { cmn_err(CE_WARN, "ddi_intr_add_handler() failed"); /* Free already allocated intr */ for (y = 0; y < actual; y++) { (void) ddi_intr_free(mydevp->htable[y]); } kmem_free(mydevp->htable, mydevp->intr_size); return (DDI_FAILURE); } } (void) ddi_intr_get_cap(mydevp->htable[0], &mydevp->intr_cap); if (mydev->m_intr_cap & DDI_INTR_FLAG_BLOCK) { /* Call ddi_intr_block_enable() for MSI */ (void) ddi_intr_block_enable(mydev->m_htable, mydev->m_intr_cnt); } else { /* Call ddi_intr_enable() for MSI non block enable */ for (x = 0; x < mydev->m_intr_cnt; x++) { (void) ddi_intr_enable(mydev->m_htable[x]); } } return (DDI_SUCCESS); } interruptsremoving MSI interrupts example The following example shows how to remove MSI interrupts.static void mydev_rem_intrs(mydev_t *mydev) { int x; /* Disable all interrupts */ if (mydev->m_intr_cap & DDI_INTR_FLAG_BLOCK) { /* Call ddi_intr_block_disable() */ (void) ddi_intr_block_disable(mydev->m_htable, mydev->m_intr_cnt); } else { for (x = 0; x < mydev->m_intr_cnt; x++) { (void) ddi_intr_disable(mydev->m_htable[x]); } } /* Call ddi_intr_remove_handler() */ for (x = 0; x < mydev->m_intr_cnt; x++) { (void) ddi_intr_remove_handler(mydev->m_htable[x]); (void) ddi_intr_free(mydev->m_htable[x]); } kmem_free(mydev->m_htable, mydev->m_intr_size); } interrupt handlersfunctionality The driver framework and the device each place demands on the interrupt handler. All interrupt handlers are required to do the following tasks:device pollingDDI_INTR_UNCLAIMEDDetermine whether the device is interrupting and possibly reject the interrupt.The interrupt handler first examines the device to determine whether this device issued the interrupt. If this device did not issue the interrupt, the handler must return DDI_INTR_UNCLAIMED. This step enables the implementation of device polling. Any device at the given interrupt priority level might have issued the interrupt. Device polling tells the system whether this device issued the interrupt. Inform the device that the device is being serviced.Informing a device about servicing is a device-specific operation that is required for the majority of devices. For example, SBus devices are required to interrupt until the driver tells the SBus devices to stop. This approach guarantees that all SBus devices that interrupt at the same priority level are serviced. Perform any I/O request-related processing.Devices interrupt for different reasons, such as transfer done or transfer error. This step can involve using data access functions to read the device's data buffer, examine the device's error register, and set the status field in a data structure accordingly. Interrupt dispatching and processing are relatively time consuming. Do any additional processing that could prevent another interrupt.For example, read the next item of data from the device. DDI_INTR_CLAIMEDReturn DDI_INTR_CLAIMED. MSI interrupts must always be claimed.Claiming an interrupt is optional for MSI-X interrupts. In either case, the ownership of the interrupt need not be checked, because MSI and MSI-X interrupts are not shared with other devices. ISR (interrupt service routine)Drivers that support hotplugging and multiple MSI or MSI-X interrupts should retain a separate interrupt for hotplug events and register a separate ISR (interrupt service routine) for that interrupt. interruptsinterrupt handling exampleThe following example shows an interrupt routine for a device called mydev.static uint_t mydev_intr(caddr_t arg1, caddr_t arg2) { struct mydevstate *xsp = (struct mydevstate *)arg1; uint8_t status; volatile uint8_t temp; /* * Claim or reject the interrupt.This example assumes * that the device's CSR includes this information. */ mutex_enter(&xsp->high_mu); /* use data access routines to read status */ status = ddi_get8(xsp->data_access_handle, &xsp->regp->csr); if (!(status & INTERRUPTING)) { mutex_exit(&xsp->high_mu); return (DDI_INTR_UNCLAIMED); /* dev not interrupting */ } /* * Inform the device that it is being serviced, and re-enable * interrupts. The example assumes that writing to the * CSR accomplishes this. The driver must ensure that this data * access operation makes it to the device before the interrupt * service routine returns. For example, using the data access * functions to read the CSR, if it does not result in unwanted * effects, can ensure this. */ ddi_put8(xsp->data_access_handle, &xsp->regp->csr, CLEAR_INTERRUPT | ENABLE_INTERRUPTS); /* flush store buffers */ temp = ddi_get8(xsp->data_access_handle, &xsp->regp->csr); mutex_exit(&xsp->mu); return (DDI_INTR_CLAIMED); } Most of the steps performed by the interrupt routine depend on the specifics of the device itself. Consult the hardware manual for the device to determine the cause of the interrupt, detect error conditions, and access the device data registers. interrupt handlinghigh-level interruptsddi_intr_get_pri functioninterrupt handlingddi_intr_get_pri functionddi_intr_get_hilevel_pri functioninterrupt handlingddi_intr_get_hilevel_pri functionHigh-level interrupts are those interrupts that interrupt at the level of the scheduler and above. This level does not allow the scheduler to run. Therefore, high-level interrupt handlers cannot be preempted by the scheduler. High-level interrupts cannot block because of the scheduler. High-level interrupts can only use mutual exclusion locks for locking.interrupt handlingsoftware interruptsinterruptssoftware interruptsThe driver must determine whether the device is using high-level interrupts. Do this test in the driver's attach9E entry point when you register interrupts. See High-Level Interrupt Handling Example.If the interrupt priority returned from ddi_intr_get_pri9F is greater than or equal to the priority returned from ddi_intr_get_hilevel_pri9F, the driver can fail to attach, or the driver can implement a high-level interrupt handler. The high-level interrupt handler uses a lower-priority software interrupt to handle the device. To allow more concurrency, use a separate mutex to protect data from the high-level handler. If the interrupt priority returned from ddi_intr_get_pri9F is less than the priority returned from ddi_intr_get_hilevel_pri9F, the attach9E entry point falls through to regular interrupt registration. In this case, a soft interrupt is not necessary. interruptshigh-level mutexeshigh-level mutexesinterruptsA mutex initialized with an interrupt priority that represents a high-level interrupt is known as a high-level mutex. While holding a high-level mutex, the driver is subject to the same restrictions as a high-level interrupt handler. interruptshandling high-level interrupts examples In the following example, the high-level mutex (xsp->high_mu) is used only to protect data shared between the high-level interrupt handler and the soft interrupt handler. The protected data includes a queue used by both the high-level interrupt handler and the low-level handler, and a flag that indicates that the low-level handler is running. A separate low-level mutex (xsp->low_mu) protects the rest of the driver from the soft interrupt handler.static int mydevattach(dev_info_t *dip, ddi_attach_cmd_t cmd) { struct mydevstate *xsp; /* ... */ ret = ddi_intr_get_supported_types(dip, &type); if ((ret != DDI_SUCCESS) || (!(type & DDI_INTR_TYPE_FIXED))) { cmn_err(CE_WARN, "ddi_intr_get_supported_types() failed"); return (DDI_FAILURE); } ret = ddi_intr_get_nintrs(dip, DDI_INTR_TYPE_FIXED, &count); /* * Fixed interrupts can only have one interrupt. Check to make * sure that number of supported interrupts and number of * available interrupts are both equal to 1. */ if ((ret != DDI_SUCCESS) || (count != 1)) { cmn_err(CE_WARN, "No fixed interrupts found"); return (DDI_FAILURE); } xsp->xs_htable = kmem_zalloc(count * sizeof (ddi_intr_handle_t), KM_SLEEP); ret = ddi_intr_alloc(dip, xsp->xs_htable, DDI_INTR_TYPE_FIXED, 0, count, &actual, 0); if ((ret != DDI_SUCCESS) || (actual != 1)) { cmn_err(CE_WARN, "ddi_intr_alloc failed 0x%x", ret"); kmem_free(xsp->xs_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } ret = ddi_intr_get_pri(xsp->xs_htable[0], &intr_pri); if (ret != DDI_SUCCESS) { cmn_err(CE_WARN, "ddi_intr_get_pri failed 0x%x", ret"); (void) ddi_intr_free(xsp->xs_htable[0]); kmem_free(xsp->xs_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } if (intr_pri >= ddi_intr_get_hilevel_pri()) { mutex_init(&xsp->high_mu, NULL, MUTEX_DRIVER, DDI_INTR_PRI(intr_pri)); ret = ddi_intr_add_handler(xsp->xs_htable[0], mydevhigh_intr, (caddr_t)xsp, NULL); if (ret != DDI_SUCCESS) { cmn_err(CE_WARN, "ddi_intr_add_handler failed 0x%x", ret"); mutex_destroy(&xsp>xs_int_mutex); (void) ddi_intr_free(xsp->xs_htable[0]); kmem_free(xsp->xs_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } /* add soft interrupt */ if (ddi_intr_add_softint(xsp->xs_dip, &xsp->xs_softint_hdl, DDI_INTR_SOFTPRI_MAX, xs_soft_intr, (caddr_t)xsp) != DDI_SUCCESS) { cmn_err(CE_WARN, "add soft interrupt failed"); mutex_destroy(&xsp->high_mu); (void) ddi_intr_remove_handler(xsp->xs_htable[0]); (void) ddi_intr_free(xsp->xs_htable[0]); kmem_free(xsp->xs_htable, sizeof (ddi_intr_handle_t)); return (DDI_FAILURE); } xsp->low_soft_pri = DDI_INTR_SOFTPRI_MAX; mutex_init(&xsp->low_mu, NULL, MUTEX_DRIVER, DDI_INTR_PRI(xsp->low_soft_pri)); } else { /* * regular interrupt registration continues from here * do not use a soft interrupt */ } return (DDI_SUCCESS); } The high-level interrupt routine services the device and queues the data. The high-level routine triggers a software interrupt if the low-level routine is not running, as the following example demonstrates.static uint_t mydevhigh_intr(caddr_t arg1, caddr_t arg2) { struct mydevstate *xsp = (struct mydevstate *)arg1; uint8_t status; volatile uint8_t temp; int need_softint; mutex_enter(&xsp->high_mu); /* read status */ status = ddi_get8(xsp->data_access_handle, &xsp->regp->csr); if (!(status & INTERRUPTING)) { mutex_exit(&xsp->high_mu); return (DDI_INTR_UNCLAIMED); /* dev not interrupting */ } ddi_put8(xsp->data_access_handle,&xsp->regp->csr, CLEAR_INTERRUPT | ENABLE_INTERRUPTS); /* flush store buffers */ temp = ddi_get8(xsp->data_access_handle, &xsp->regp->csr); /* read data from device, queue data for low-level interrupt handler */ if (xsp->softint_running) need_softint = 0; else { xsp->softint_count++; need_softint = 1; } mutex_exit(&xsp->high_mu); /* read-only access to xsp->id, no mutex needed */ if (need_softint) { ret = ddi_intr_trigger_softint(xsp->xs_softint_hdl, NULL); if (ret == DDI_EPENDING) { cmn_err(CE_WARN, "ddi_intr_trigger_softint() soft interrupt " "already pending for this handler"); } else if (ret != DDI_SUCCESS) { cmn_err(CE_WARN, "ddi_intr_trigger_softint() failed"); } } return (DDI_INTR_CLAIMED); } interruptshandling low-level interrupts exampleThe low-level interrupt routine is started by the high-level interrupt routine, which triggers a software interrupt. The low-level interrupt routine runs until there is nothing left to process, as the following example shows.static uint_t mydev_soft_intr(caddr_t arg1, caddr_t arg2) { struct mydevstate *mydevp = (struct mydevstate *)arg1; /* ... */ mutex_enter(&mydevp->low_mu); mutex_enter(&mydevp->high_mu); if (mydevp->softint_count > 1) { mydevp->softint_count--; mutex_exit(&mydevp->high_mu); mutex_exit(&mydevp->low_mu); return (DDI_INTR_CLAIMED); } if ( /* queue empty */ ) { mutex_exit(&mydevp->high_mu); mutex_exit(&mydevp->low_mu); return (DDI_INTR_UNCLAIMED); } mydevp->softint_running = 1; while (EMBEDDED COMMENT:data on queue) { ASSERT(mutex_owned(&mydevp->high_mu); /* Dequeue data from high-level queue. */ mutex_exit(&mydevp->high_mu); /* normal interrupt processing */ mutex_enter(&mydevp->high_mu); } mydevp->softint_running = 0; mydevp->softint_count = 0; mutex_exit(&mydevp->high_mu); mutex_exit(&mydevp->low_mu); return (DDI_INTR_CLAIMED); }