xnu-7195.50.7.100.1.tar.gz

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

diff --git a/iokit/DriverKit/OSAction.iig b/iokit/DriverKit/OSAction.iig
index 999205c4ed34d2ad6df53f953037e7706def8875..2627ef0b0bbfb71c3bac3042bd6a5f1272197cb6 100644 (file)
--- a/iokit/DriverKit/OSAction.iig
+++ b/iokit/DriverKit/OSAction.iig
@@ -33,6 +33,8 @@
 
 typedef void (^OSActionCancelHandler)(void);
 typedef void (^OSActionAbortedHandler)(void);
+struct OSActionWaitToken;
+class OSString;
 
 /*!
  * @class OSAction
@@ -44,13 +46,22 @@ typedef void (^OSActionAbortedHandler)(void);
  * The callback is specified as a method and object pair.
  * State associated with the callback may be allocated and stored for the creator of the object.
  * Methods to allocate an OSAction instance are generated for each method defined in a class with
- * a TYPE attribute, so there should not be any need to directly call OSAction::Create().
+ * a TYPE attribute. The generated methods are named CreateAction{name of method with type attribute}
+ * and have the following declaration:
+ *
+ * kern_return_t CreateActionNameOfMethod(size_t referenceSize, OSAction **action);
+ *
+ * referenceSize refers to the size of additional state structure available to the creator of the OSAction
+ * with GetReference. If successful, the generated method returns kIOReturnSuccess and a created OSAction
+ * through the 'action' parameter with a +1 retain count to be released by the caller. See IOReturn.h for
+ * error codes.
  */
 
 class NATIVE KERNEL OSAction : public OSObject
 {
 public:
 
+#if DRIVERKIT_PRIVATE
     /*!
      * @brief       Create an instance of OSAction.
         * @discussion  Methods to allocate an OSAction instance are generated for each method defined in a class with
@@ -73,6 +84,16 @@ public:
                size_t          referenceSize,
                OSAction     ** action) LOCAL;
 
+     static kern_return_t
+     CreateWithTypeName(
+          OSObject      * target,
+          uint64_t        targetmsgid,
+          uint64_t        msgid,
+          size_t          referenceSize,
+          OSString      * typeName,
+          OSAction     ** action) LOCAL;
+#endif
+
        virtual void
        free() override;
 
@@ -105,6 +126,46 @@ public:
        kern_return_t
        SetAbortedHandler(OSActionAbortedHandler handler) LOCALONLY;
 
+    /*!
+     * @brief       Mark this OSAction to be waited for later with Wait().
+     * @discussion  This call should be made before any possible invocation of the action.
+     *              An OSAction instance only supports one waiter and WillWait() will return an error if already called.
+     * @param       token Opaque value to be passed to a later call to Wait() and EndWait().
+     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
+     */
+       kern_return_t
+       WillWait(OSActionWaitToken ** token) LOCALONLY;
+
+    /*!
+     * @brief       Discard the OSActionWaitToken for the action.
+     * @discussion  Free any resources needed to wait for the action allocated by WillWait().
+     *              There should be no outstanding invocations of the action when EndWait is called,
+     *              if necessary the action should be canceled before calling EndWait().
+     * @param       token Opaque value to be passed from an earlier call to WillWait().
+     * @return      kIOReturnSuccess on success. kIOReturnAborted if aborted or canceled.
+                                       kIOReturnTimeout if the deadline was passed. See IOReturn.h for error codes.
+     */
+       kern_return_t
+       EndWait(
+               OSActionWaitToken * token) LOCALONLY;
+
+    /*!
+     * @brief       Wait for the action to be invoked.
+     * @discussion  The current thread is blocked until the action invocation has completed, the action canceled
+                                       or aborted, or the deadline passed.
+     * @param       token Opaque value to be passed from an earlier call to WillWait().
+     * @param       options Pass one of the kIOTimerClock* options to specify the timebase for the
+     *              deadline.
+     * @param       deadline Pass the time the wait should timeout, or zero for no timeout.
+     * @return      kIOReturnSuccess on success. kIOReturnAborted if aborted or canceled.
+                                       kIOReturnTimeout if the deadline was passed. See IOReturn.h for error codes.
+     */
+       kern_return_t
+       Wait(
+               OSActionWaitToken * token,
+               uint64_t options,
+               uint64_t deadline) LOCALONLY;
+
        virtual void
        Aborted(void) LOCAL;
 };