iokit/DriverKit/OSAction.iig

   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_OSACTION_H
  30 #define _IOKIT_OSACTION_H
  31
  32 #include <DriverKit/OSObject.iig>
  33
  34 typedef void (^OSActionCancelHandler)(void);
  35 typedef void (^OSActionAbortedHandler)(void);
  36 struct OSActionWaitToken;
  37 class OSString;
  38
  39 /*!
  40  * @class OSAction
  41  *
  42  * @abstract
  43  * OSAction is an object that represents a callback to be be invoked.
  44  *
  45  * @discussion
  46  * The callback is specified as a method and object pair.
  47  * State associated with the callback may be allocated and stored for the creator of the object.
  48  * Methods to allocate an OSAction instance are generated for each method defined in a class with
  49  * a TYPE attribute. The generated methods are named CreateAction{name of method with type attribute}
  50  * and have the following declaration:
  51  *
  52  * kern_return_t CreateActionNameOfMethod(size_t referenceSize, OSAction **action);
  53  *
  54  * referenceSize refers to the size of additional state structure available to the creator of the OSAction
  55  * with GetReference. If successful, the generated method returns kIOReturnSuccess and a created OSAction
  56  * through the 'action' parameter with a +1 retain count to be released by the caller. See IOReturn.h for
  57  * error codes.
  58  */
  59
  60 class NATIVE KERNEL OSAction : public OSObject
  61 {
  62 public:
  63
  64 #if DRIVERKIT_PRIVATE
  65     /*!
  66      * @brief       Create an instance of OSAction.
  67          * @discussion  Methods to allocate an OSAction instance are generated for each method defined in a class with
  68      *              a TYPE attribute, so there should not be any need to directly call OSAction::Create().
  69      * @param       target OSObject to receive the callback. This object will be retained until the OSAction is
  70      *              canceled or freed.
  71      * @param       targetmsgid Generated message ID for the target method.
  72      * @param       msgid Generated message ID for the method invoked by the receiver of the OSAction
  73      *              to generate the callback.
  74      * @param       referenceSize Size of additional state structure available to the creator of the OSAction
  75      *              with GetReference.
  76      * @param       action Created OSAction with +1 retain count to be released by the caller.
  77      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  78      */
  79         static kern_return_t
  80         Create(
  81                 OSObject      * target,
  82                 uint64_t        targetmsgid,
  83                 uint64_t        msgid,
  84                 size_t          referenceSize,
  85                 OSAction     ** action) LOCAL;
  86
  87      static kern_return_t
  88      CreateWithTypeName(
  89           OSObject      * target,
  90           uint64_t        targetmsgid,
  91           uint64_t        msgid,
  92           size_t          referenceSize,
  93           OSString      * typeName,
  94           OSAction     ** action) LOCAL;
  95 #endif
  96
  97         virtual void
  98         free() override;
  99
 100     /*!
 101      * @brief       Return a pointer to any state allocated by the OSAction creator.
 102      * @discussion  Reference data is allocated with zero initialized content. It may be set and retrieved later
 103      *              with this method.
 104      * @return      A pointer to storage for the owner. It will be NULL if referenceSize was zero, and NULL
 105      *              when called in a process other than the owner that is receiving the OSAction as a parameter.
 106      */
 107         void *
 108         GetReference() LOCALONLY;
 109
 110     /*!
 111      * @brief       Cancel all callbacks from the action.
 112      * @discussion  After cancellation, the action can only be freed. It cannot be reactivated.
 113      * @param       handler Handler block to be invoked after any callbacks have completed.
 114      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 115      */
 116         kern_return_t
 117         Cancel(OSActionCancelHandler handler) LOCALONLY;
 118
 119     /*!
 120      * @brief       Install a handler to be invoked when no other processes reference the action.
 121      * @discussion  When all tasks other than the creator release their references to the action,
 122      *              invoke the handler in the owner. A task exiting will always remove its references.
 123      * @param       handler Handler block to be invoked on no more references.
 124      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 125      */
 126         kern_return_t
 127         SetAbortedHandler(OSActionAbortedHandler handler) LOCALONLY;
 128
 129     /*!
 130      * @brief       Mark this OSAction to be waited for later with Wait().
 131      * @discussion  This call should be made before any possible invocation of the action.
 132      *              An OSAction instance only supports one waiter and WillWait() will return an error if already called.
 133      * @param       token Opaque value to be passed to a later call to Wait() and EndWait().
 134      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 135      */
 136         kern_return_t
 137         WillWait(OSActionWaitToken ** token) LOCALONLY;
 138
 139     /*!
 140      * @brief       Discard the OSActionWaitToken for the action.
 141      * @discussion  Free any resources needed to wait for the action allocated by WillWait().
 142      *              There should be no outstanding invocations of the action when EndWait is called,
 143      *              if necessary the action should be canceled before calling EndWait().
 144      * @param       token Opaque value to be passed from an earlier call to WillWait().
 145      * @return      kIOReturnSuccess on success. kIOReturnAborted if aborted or canceled.
 146                                         kIOReturnTimeout if the deadline was passed. See IOReturn.h for error codes.
 147      */
 148         kern_return_t
 149         EndWait(
 150                 OSActionWaitToken * token) LOCALONLY;
 151
 152     /*!
 153      * @brief       Wait for the action to be invoked.
 154      * @discussion  The current thread is blocked until the action invocation has completed, the action canceled
 155                                         or aborted, or the deadline passed.
 156      * @param       token Opaque value to be passed from an earlier call to WillWait().
 157      * @param       options Pass one of the kIOTimerClock* options to specify the timebase for the
 158      *              deadline.
 159      * @param       deadline Pass the time the wait should timeout, or zero for no timeout.
 160      * @return      kIOReturnSuccess on success. kIOReturnAborted if aborted or canceled.
 161                                         kIOReturnTimeout if the deadline was passed. See IOReturn.h for error codes.
 162      */
 163         kern_return_t
 164         Wait(
 165                 OSActionWaitToken * token,
 166                 uint64_t options,
 167                 uint64_t deadline) LOCALONLY;
 168
 169         virtual void
 170         Aborted(void) LOCAL;
 171 };
 172
 173 #endif /* ! _IOKIT_OSACTION_H */