[apple/xnu.git] / iokit / DriverKit / IOInterruptDispatchSource.iig

/*
 * 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
};

/*!
 * @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.
     * @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;

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 */
Commit	Line	Data
cb323159 A	1	/*
	2	* Copyright (c) 2019-2019 Apple Inc. All rights reserved.
	3	*
	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
	5	*
	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. The rights granted to you under the License
	10	* may not be used to create, or enable the creation or redistribution of,
	11	* unlawful or unlicensed copies of an Apple operating system, or to
	12	* circumvent, violate, or enable the circumvention or violation of, any
	13	* terms of an Apple operating system software license agreement.
	14	*
	15	* Please obtain a copy of the License at
	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	*
	18	* The Original Code and all software distributed under the License are
	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
	25	*
	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
	27	*/
	28
	29	#ifndef _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H
	30	#define _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H
	31
	32	#include <DriverKit/IODispatchQueue.iig>
	33	#include <DriverKit/IOService.iig>
	34
	35	struct IOInterruptDispatchSourcePayload {
	36	uint64_t time;
	37	uint64_t count;
	38	};
	39
eb6b6ca3 A	40	enum {
	41	kIOInterruptDispatchSourceTypeEdge = 0x00000000,
	42	kIOInterruptDispatchSourceTypeLevel = 0x00000001
	43	};
	44
cb323159 A	45	/*!
	46	* @class IOInterruptDispatchSource
	47	*
	48	* @abstract
	49	* IOInterruptDispatchSource delivers interrupts to a handler block on a dispatch queue.
	50	*
	51	* @discussion
	52	* A driver can run code in response to an interrupt from a device, specified as an IOService
	53	* and index. The code runs at normal thread level, but is notified with the mach_absolute_time
	54	* the primary interrupt fired. For IOPCIDevices, only MSI interrupt sources are supported.
	55	*/
	56
	57	class NATIVE KERNEL IOInterruptDispatchSource : public IODispatchSource
	58	{
	59	public:
	60
	61	/*!
	62	* @brief Create an IOInterruptDispatchSource for an interrupt by index from an IOService provider.
	63	* @param provider The IOService object representing the HW device producing the interrupt.
	64	* @param index Index for the interrupt.
	65	* @param queue Target queue to run the handler block.
	66	* @param source Created source with +1 retain count to be released by the caller.
	67	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	68	*/
	69	static kern_return_t
	70	Create(IOService * provider,
	71	uint32_t index,
	72	IODispatchQueue * queue,
	73	IOInterruptDispatchSource ** source) LOCAL;
	74
eb6b6ca3 A	75	/*!
	76	* @brief Returns the type of interrupt used for a device supplying hardware interrupts, by index from an IOService provider.
	77	* @param provider The IOService object representing the HW device producing the interrupt.
	78	* @param index Index for the interrupt.
	79	* @param interruptType The interrupt type for the interrupt source will be stored here.
	80	* kIOInterruptTypeEdge will be returned for edge-trigggered sources.
	81	* kIOInterruptTypeLevel will be returned for level-trigggered sources.
	82	* Other flags may be returned depending on the provider, for example PCI flags for messaged interrupts.
	83	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	84	*/
	85
	86	static kern_return_t
	87	GetInterruptType(IOService * provider,
	88	uint32_t index,
	89	uint64_t * interruptType);
	90
cb323159 A	91	virtual bool
	92	init() override;
	93
	94	virtual void
	95	free() override;
	96
	97	/*!
	98	* @brief Set the handler block to run when the interupt fires.
	99	* @param action OSAction instance specifying the callback method. The OSAction object will be retained
	100	* until SetHandler is called again or the event source is cancelled.
	101	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	102	*/
	103	virtual kern_return_t
	104	SetHandler(
	105	OSAction * action TYPE(InterruptOccurred)) LOCAL;
	106
	107	/*!
	108	* @brief Control the enable state of the interrupt source.
	109	* @param enable Pass true to enable the source or false to disable.
	110	* @param handler Optional block to be executed after the interrupt has been disabled and any pending
	111	* interrupt handlers completed.
	112	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	113	*/
	114	virtual kern_return_t
	115	SetEnableWithCompletion(
	116	bool enable,
	117	IODispatchSourceCancelHandler handler) override LOCAL;
	118
	119	/*!
	120	* @brief Cancel all callbacks from the event source.
	121	* @discussion After cancellation, the source can only be freed. It cannot be reactivated.
	122	* @param handler Handler block to be invoked after any callbacks have completed.
	123	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	124	*/
	125	virtual kern_return_t
	126	Cancel(IODispatchSourceCancelHandler handler) override LOCAL;
	127
	128	private:
	129	virtual kern_return_t
	130	CheckForWork(bool synchronous) override LOCAL;
	131
	132	virtual void
	133	InterruptOccurred(
	134	OSAction * action TARGET,
	135	uint64_t count,
	136	uint64_t time) REPLY LOCAL;
	137	};
	138
	139	#endif /* ! _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H */