/*
* Copyright (c) 2019-2019 Apple Inc. All rights reserved.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
* This file contains Original Code and/or Modifications of Original Code
* as defined in and that are subject to the Apple Public Source License
* Version 2.0 (the 'License'). You may not use this file except in
* compliance with the License. The rights granted to you under the License
* may not be used to create, or enable the creation or redistribution of,
* unlawful or unlicensed copies of an Apple operating system, or to
* circumvent, violate, or enable the circumvention or violation of, any
* terms of an Apple operating system software license agreement.
*
* Please obtain a copy of the License at
* http://www.opensource.apple.com/apsl/ and read it before using this file.
*
* The Original Code and all software distributed under the License are
* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
* Please see the License for the specific language governing rights and
* limitations under the License.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
#ifndef _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H
#define _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H
#include <DriverKit/IODispatchQueue.iig>
#include <DriverKit/IOService.iig>
struct IOInterruptDispatchSourcePayload {
uint64_t time;
uint64_t count;
};
enum {
kIOInterruptDispatchSourceTypeEdge = 0x00000000,
kIOInterruptDispatchSourceTypeLevel = 0x00000001
};
enum {
kIOInterruptSourceIndexMask = 0x0000FFFF,
kIOInterruptSourceAbsoluteTime = 0x00000000,
kIOInterruptSourceContinuousTime = 0x00010000
};
/*!
* @class IOInterruptDispatchSource
*
* @abstract
* IOInterruptDispatchSource delivers interrupts to a handler block on a dispatch queue.
*
* @discussion
* A driver can run code in response to an interrupt from a device, specified as an IOService
* and index. The code runs at normal thread level, but is notified with the mach_absolute_time
* the primary interrupt fired. For IOPCIDevices, only MSI interrupt sources are supported.
*/
class NATIVE KERNEL IOInterruptDispatchSource : public IODispatchSource
{
public:
/*!
* @brief Create an IOInterruptDispatchSource for an interrupt by index from an IOService provider.
* @param provider The IOService object representing the HW device producing the interrupt.
* @param index Index for the interrupt, optionally or'ed with one of the following constants:
kIOInterruptSourceContinuousTime time values sent to the InterruptOccurred() method will be in mach_continuous_time() units.
* @param queue Target queue to run the handler block.
* @param source Created source with +1 retain count to be released by the caller.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
static kern_return_t
Create(IOService * provider,
uint32_t index,
IODispatchQueue * queue,
IOInterruptDispatchSource ** source) LOCAL;
/*!
* @brief Returns the type of interrupt used for a device supplying hardware interrupts, by index from an IOService provider.
* @param provider The IOService object representing the HW device producing the interrupt.
* @param index Index for the interrupt.
* @param interruptType The interrupt type for the interrupt source will be stored here.
* kIOInterruptTypeEdge will be returned for edge-trigggered sources.
* kIOInterruptTypeLevel will be returned for level-trigggered sources.
* Other flags may be returned depending on the provider, for example PCI flags for messaged interrupts.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
static kern_return_t
GetInterruptType(IOService * provider,
uint32_t index,
uint64_t * interruptType);
virtual bool
init() override;
virtual void
free() override;
/*!
* @brief Set the handler block to run when the interupt fires.
* @param action OSAction instance specifying the callback method. The OSAction object will be retained
* until SetHandler is called again or the event source is cancelled.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
virtual kern_return_t
SetHandler(
OSAction * action TYPE(InterruptOccurred)) LOCAL;
/*!
* @brief Control the enable state of the interrupt source.
* @param enable Pass true to enable the source or false to disable.
* @param handler Optional block to be executed after the interrupt has been disabled and any pending
* interrupt handlers completed.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
virtual kern_return_t
SetEnableWithCompletion(
bool enable,
IODispatchSourceCancelHandler handler) override LOCAL;
/*!
* @brief Cancel all callbacks from the event source.
* @discussion After cancellation, the source can only be freed. It cannot be reactivated.
* @param handler Handler block to be invoked after any callbacks have completed.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
virtual kern_return_t
Cancel(IODispatchSourceCancelHandler handler) override LOCAL;
/*!
* @brief Get the count and time of the last interrupt received by the kernel
primary interrupt handler.
* @param count Interrupt count.
* @param time Interrupt time.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
virtual kern_return_t
GetLastInterrupt(
uint64_t * count,
uint64_t * time);
private:
virtual kern_return_t
CheckForWork(bool synchronous) override LOCAL;
virtual void
InterruptOccurred(
OSAction * action TARGET,
uint64_t count,
uint64_t time) REPLY LOCAL;
};
#endif /* ! _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H */