Loading...
--- xnu/xnu-12377.101.15/iokit/IOKit/IOCircularDataQueue.h
+++ /dev/null
@@ -1,420 +0,0 @@
-/*
- * Copyright (c) 2024 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 IOGCCircularDataQueue_h
-#define IOGCCircularDataQueue_h
-
-#if KERNEL
-#include <IOKit/IOLib.h>
-#else
-#include <IOKit/IOKitLib.h>
-#endif
-
-__BEGIN_DECLS
-
-struct IOCircularDataQueue;
-typedef struct IOCircularDataQueue IOCircularDataQueue;
-
-// IOCircularDataQueueCreate* options
-typedef enum __OS_ENUM_ATTR IOCircularDataQueueCreateOptions {
- kIOCircularDataQueueCreateConsumer = 0x00000001,
- kIOCircularDataQueueCreateProducer = 0x00000002
-} IOCircularDataQueueCreateOptions;
-
-#if KERNEL
-
-/*!
- * @function IOCircularDataQueueCreateWithEntries
- * @abstract Function that creates a new IOCircularDataQueue instance with the specified number of entries of the given
- * size.
- * @discussion This method will create a new IOCircularDataQueue instance with enough capacity for numEntries of
- * entrySize each. It does account for the IOCircularDataQueueEntryHeader overhead for each entry. Note that the
- * numEntries and entrySize are simply used to determine the data region size. They do not actually restrict the number
- * of enqueues to the queue since its a circular buffer and will eventually overwrite old data. At any time, the
- * allocated data region can hold a maximum of numEntries queue entries. <br> This method allocates a new
- * IOCircularDataQueue instance with the given numEntries and entrySize parameters.
- * @param options IOCircularDataQueueCreateOptions.
- * @param numEntries Number of entries to allocate space for.
- * @param entrySize Size of each entry.
- * @param pQueue Pointer to a queue handle. On return, this holds a handle to the newly allocated queue.
- * @return
- * - `kIOReturnSuccess` if the queue was succesfully intialized.
- * - `kIOReturnBadArgument` if the parameters passed were invalid.
- * - `kIOReturnNoMemory` if there was a memory allocation failure.
- */
-IOReturn IOCircularDataQueueCreateWithEntries(IOCircularDataQueueCreateOptions options, uint32_t numEntries, uint32_t entrySize, IOCircularDataQueue **pQueue);
-
-/*!
- * @function IOCircularDataQueueCopyMemoryDescriptor
- * @abstract Returns a reference to the IOMemoryDescriptor for the queue's memory.
- * @discussion Returns a reference to the IOMemoryDescriptor for the queue's memory.
- * @param queue Queue handle. On return, this holds a handle to the newly allocated queue.
- * @return IOMemoryDescriptor reference
- */
-IOMemoryDescriptor * IOCircularDataQueueCopyMemoryDescriptor(IOCircularDataQueue *queue);
-
-#else /* KERNEL */
-
-/*!
- * @function IOCircularDataQueueCreateWithConnection
- * @abstract Function that creates a new IOCircularDataQueue instance with an open IOUserClient connection.
- * @discussion This method will create a new IOCircularDataQueue instance with a queue owned by the IOUserClient
- * instance passed in. The memory and queue attributes are created from the IOMemoryDescriptor returned by the IOUC
- * returned by clientMemoryForType() with the memoryType parameter passed to this function. This memory descriptor must
- * be one returned by the kernel api IOCircularDataQueueCopyMemoryDescriptor().
- * @param options IOCircularDataQueueCreateOptions.
- * @param connect An open IOUserClient connection created by the caller with IOServiceOpen(). The connection must be
- * valid while the queue is in use.
- * @param memoryType memoryType argument that will passed to the IOUC clientMemoryForType() function to obtain the queue memory.
- * @param pQueue Pointer to a queue handle. On return, this holds a handle to the newly allocated queue.
- * @return
- * - `kIOReturnSuccess` if the queue was succesfully intialized.
- * - `kIOReturnBadArgument` if the parameters passed were invalid.
- * - `kIOReturnNoMemory` if there was a memory allocation failure.
- */
-IOReturn IOCircularDataQueueCreateWithConnection(IOCircularDataQueueCreateOptions options, io_connect_t connect, uint32_t memoryType, IOCircularDataQueue **pQueue);
-
-#endif /* !KERNEL */
-
-/*!
- * @function IOCircularDataQueueDestroy
- * @abstract Function that destroys a previously created IOCircularDataQueue instance (created with
- * IOCircularDataQueueCreateWithEntries).
- * @param pQueue Pointer to the queue handle.
- * @return
- * - `kIOReturnSuccess` if the queue was succesfully destroyed.
- * - `kIOReturnBadArgument` if an invalid queue was provided.
- */
-IOReturn IOCircularDataQueueDestroy(IOCircularDataQueue **pQueue);
-
-
-/*!
- * @function IOCircularDataQueueEnqueue
- * @abstract Enqueues a new entry on the queue.
- * @discussion This method adds a new data entry of dataSize to the queue. It sets the size parameter of the entry
- * pointed to by the write index and copies the memory pointed to by the data parameter in place in the queue. Once
- * that is done, it moves the write index to the next index.
- * @param queue Handle to the queue.
- * @param data Pointer to the data to be added to the queue.
- * @param dataSize Size of the data pointed to by data.
- * @return
- * - `kIOReturnSuccess` on success.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - `kIOReturnBadArgument` if an invalid queue was provided.
- * - `kIOReturnBusy` if another thread is enqueing concurrently
- * - `kIOReturnUnsupported` if the queue has not been configured to support fixed size entries. Variable size is
- * currently not supported
- * - Other values indicate an error.
- */
-IOReturn IOCircularDataQueueEnqueue(IOCircularDataQueue *queue, const void *data, size_t dataSize);
-
-/*!
- * @function IOCircularDataQueueGetLatest
- * Access the latest entry data, also update the cursor position to the latest. No copy is made of the data. <br> Caller
- * is supposed to call IOCircularDataQueueIsCurrentDataValid() to check data integrity after reading the data is
- * complete.
- * @param queue Handle to the queue.
- * @param data A pointer to the data memory region for the latest entry data in the queue.
- * @param size A pointer to the size of the data parameter. On return, this contains the actual size of the data
- * pointed to by data param.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated.
- * - `kIOReturnUnderrun` if nothing has ever been enqueued into the queue
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - `kIOReturnBadArgument` if an invalid queue was provided.
- * - `kIOReturnTimeout` if the reader timed out when trying to read. This is possible if the writer overwrites the
- * latest index a reader is about to read. The function times out if the read is unsuccessful after multiple retries.
- * - Other values indicate an error.
- */
-IOReturn IOCircularDataQueueGetLatest(IOCircularDataQueue *queue, void **data, size_t *size);
-
-/*!
- * @function IOCircularDataQueueCopyLatest
- * Access the latest entry data and copy into the provided buffer. Also update the cursor position to the latest. On a
- * successful return, the function gaurantees that the latest data was successfully copied. In this case there is no
- * need to call IOCircularDataQueueIsCurrentDataValid() after reading the data is complete, since the function returns a
- * copy which cannot be overwritten by the writer.
- * @param queue Handle to the queue.
- * @param data Pointer to memory into which the latest data from the queue is copied. Lifetime of this memory is
- * controlled by the caller.
- * @param size Size of the data buffer provided for copying. On return, this contains the actual size of the data
- * pointed to by data param.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to latest and the data was successfully copied.
- * - `kIOReturnUnderrun` if nothing has ever been enqueued into the queue
- * - `kIOReturnBadArgument` if the buffer provided to copy the data is NULL or if an invalid queue was provided..
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - `kIOReturnTimeout` if the reader timed out when trying to copy the latest data. This is possible if the writer
- * overwrites the latest index a reader is about to copy. The function times out if the copy is unsuccessful after
- * multiple retries.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueCopyLatest(IOCircularDataQueue *queue, void *data, size_t *size);
-
-/*!
- * @function IOCircularDataQueueGetNext
- * Access the data at the next cursor position and updates the cursor position to the next. No copy is made of the data.
- * <br> Caller is supposed to call IOCircularDataQueueIsCurrentDataValid() to check data integrity after reading the
- * data is complete.
- * @param queue Handle to the queue.
- * @param data A pointer to the data memory region for the next entry data in the queue.
- * @param size A pointer to the size of the data parameter. On return, this contains the actual size of the data
- * pointed to by data param.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to the latest.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnUnderrun` if the cursor has reached the latest available data.
- * - `kIOReturnOverrun` if the entry at the cursor position is no longer in
- * the queue's buffer. Call IOCircularDataQueueGetLatest to get the latest data and cursor position.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueGetNext(IOCircularDataQueue *queue, void **data, size_t *size);
-
-/*!
- * @function IOCircularDataQueueCopyNext
- * Access the data at the next cursor position and copy into the provided buffer. Also update the cursor position to the
- * next. On a successful return, the function gaurantees that the next entry data was successfully copied. In this case
- * there is no need to call IOCircularDataQueueIsCurrentDataValid() after reading the data is complete, since the
- * function returns a copy which cannot be overwritten by the writer.
- * @param queue Handle to the queue.
- * @param data Pointer to memory into which the next data from the queue is copied. Lifetime of this memory is
- * controlled by the caller.
- * @param size Size of the data buffer provided for copying. On return, this contains the actual size of the data
- * pointed to by data param.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to next and the data was successfully copied.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnUnderrun` if the cursor has reached the latest available data.
- * - `kIOReturnOverrun` if the entry at the cursor position is no longer in
- * the queue's buffer. Call IOCircularDataQueueCopyLatest to get the latest data and cursor position.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueCopyNext(IOCircularDataQueue *queue, void *data, size_t *size);
-
-/*!
- * @function IOCircularDataQueueGetPrevious
- * Access the data at the previous cursor position and updates the cursor position to the previous. No copy is made of
- * the data. <br> Caller is supposed to call IOCircularDataQueueIsCurrentDataValid() to check data integrity after
- * reading the data is complete.
- * @param queue Handle to the queue.
- * @param data A pointer to the data memory region for the previous entry data in the queue.
- * @param size A pointer to the size of the data parameter. On return, this contains the actual size of the data
- * pointed to by data param.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to the previous.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnOverrun` if the entry at the cursor position is no longer in
- * the queue's buffer. Call IOCircularDataQueueGetLatest to get the latest data and cursor position.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueGetPrevious(IOCircularDataQueue *queue, void **data, size_t *size);
-
-/*!
- * @function IOCircularDataQueueCopyPrevious
- * Access the data at the previous cursor position and copy into the provided buffer. Also update the cursor position to
- * the previous. On a successful return, the function gaurantees that the previous entry data was successfully copied.
- * In this case there is no need to call IOCircularDataQueueIsCurrentDataValid() after reading the data is complete,
- * since the function returns a copy which cannot be overwritten by the writer.
- * @param queue Handle to the queue.
- * @param data Pointer to memory into which the previous data is copied. Lifetime of this memory is controlled by the
- * caller.
- * @param size Size of the data buffer provided for copying. On return, this contains the actual size of the data
- * pointed to by data param.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to the previous and the data was successfully copied.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnOverrun` if the entry at the cursor position is no longer in
- * the queue's buffer. Call IOCircularDataQueueCopyLatest to get the latest data and cursor position.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueCopyPrevious(IOCircularDataQueue *queue, void *data, size_t *size);
-
-/*!
- * @function IOCircularDataQueueIsCurrentDataValid
- * Verify if the data at the current cursor position is the same as the data when the cursor was first updated to this
- * position. Call this function after having read the data at the current cursor position from the queue, since the
- * queue entry could potentially have been overwritten by the writer while being read by the caller. <br>
- * @param queue Handle to the queue.
- * @return
- * - `kIOReturnSuccess` if the data at the cursor position is unchanged.
- * - `kIOReturnOverrun` if the entry at the cursor position is no longer the same and is
- * potentially overwritten. Call IOCircularDataQueueGetLatest to get the latest data and cursor position.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnBadArgument` if an invalid param was passed.
- * - `kIOReturnBadMedia` if the queueMemory is corrupted.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueIsCurrentDataValid(IOCircularDataQueue *queue);
-
-/*!
- * @function IOCircularDataQueueSetCursorLatest
- * Set the current cursor position to the latest entry in the queue. This only updates the cursor and does not read the
- * data from the queue. If nothing has been enqueued into the queue yet, this returns an error.
- * @param queue Handle to the queue.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to the latest.
- * - `kIOReturnUnderrun` if nothing has ever been enqueued into the queue since there is no latest entry.
- * - `kIOReturnAborted` if the queue is in an irrecoverable state.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueSetCursorLatest(IOCircularDataQueue *queue);
-
-/*!
- * @function IOCircularDataQueueGetCurrent
- * Access the data at the current cursor position. The cursor position is unchanged. No copy is made of the data. <br>
- * Caller is supposed to call IOCircularDataQueueIsCurrentDataValid() to check data integrity after reading the data is
- * complete.
- * @param queue Handle to the queue.
- * @param data A pointer to the data memory region for the next entry data in the queue.
- * @param size A pointer to the size of the data parameter. On return, this contains the actual size of the data
- * pointed to by data param.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnUnderrun` if nothing has ever been enqueued into the queue hence there is no entry at the current
- * position..
- * - `kIOReturnOverrun` if the entry at the current cursor position is no longer in
- * the queue's buffer. Call IOCircularDataQueueGetLatest to get the latest data and cursor position.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueGetCurrent(IOCircularDataQueue *queue, void **data, size_t *size);
-
-/*!
- * @function IOCircularDataQueueCopyCurrent
- * Access the data at the current cursor position and copy into the provided buffer. The cursor position is unchanged.
- * If successful, function gaurantees that the data returned is always valid, hence no need to call
- * IOCircularDataQueueIsCurrentDataValid().
- * @param queue Handle to the queue.
- * @param data Pointer to memory into which the previous data is copied. Lifetime of this memory is controlled by the
- * caller.
- * @param size Size of the data buffer provided for copying. On return, this contains the actual size of the data
- * pointed to by data param.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnUnderrun` if nothing has ever been enqueued into the queue hence there is no entry at the current
- * position..
- * - `kIOReturnOverrun` if the entry at the current cursor position is no longer in
- * the queue's buffer. Call IOCircularDataQueueCopyLatest to get the latest data and cursor position.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueCopyCurrent(IOCircularDataQueue *queue, void *data, size_t *size);
-
-/*!
- * @function IOCircularDataQueueGetLatestWithBlock
- * Access the latest entry data, also update the cursor position to the latest. Calls the provided block with the data
- * at the cursor position. No copy is made of the data. <br> Optionally the caller can call
- * IOCircularDataQueueIsCurrentDataValid() to check data integrity after reading the data is complete in the block.
- * Additionally the function also returns an error if the data has been overwritten after the block completion
- * @param queue Handle to the queue.
- * @param handler Block to call
- * -param data Pointer to the latest data in the queue that the block is called with.
- * -param size Size of the data pointed to by data that the block is called with.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to the latest.
- * - `kIOReturnUnderrun` if nothing has ever been enqueued into the queue
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - `kIOReturnBadArgument` if an invalid queue was provided.
- * - `kIOReturnAborted` if the queue was reset.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueGetLatestWithBlock(IOCircularDataQueue * queue, void (^handler)(const void *data, size_t size));
-
-/*!
- * @function IOCircularDataQueueGetNextWithBlock
- * Access the data at the next cursor position and updates the cursor position to the next. Calls the provided block
- * with the data at the cursor position. No copy is made of the data. <br> Optionally the caller can call
- * IOCircularDataQueueIsCurrentDataValid() to check data integrity after reading the data is complete in the block.
- * Additionally the function also returns an error if the data has been overwritten after the block completion.
- * @param queue Handle to the queue.
- * @param handler Block to call
- * -param data A pointer to the data memory region for the next entry data in the queue that the block is called with.
- * -param size Size of the data pointed to by data that the block is called with.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to next.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnUnderrun` if the cursor has reached the latest available data.
- * - `kIOReturnOverrun` if the entry at the cursor position is no longer in
- * the queue's buffer. Call IOCircularDataQueueGetLatest to get the latest data and cursor position.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueGetNextWithBlock(IOCircularDataQueue * queue, void (^handler)(const void *data, size_t size));
-
-/*!
- * @function IOCircularDataQueueGetPreviousWithBlock
- * Access the data at the previous cursor position and updates the cursor position to the previous. Calls the provided
- * block with the data at the cursor position. No copy is made of the data. <br> Optionally the caller can call
- * IOCircularDataQueueIsCurrentDataValid() to check data integrity after reading the data is complete in the block.
- * Additionally the function also returns an error if the data has been overwritten after the block completion.
- * @param queue Handle to the queue.
- * @param handler Block to call
- * -param data A pointer to the data memory region for the previous entry data in the queue that the block is called
- * with.
- * -param size Size of the data pointed to by data that the block is called with.
- * @return
- * - `kIOReturnSuccess` if the cursor position was updated to previous.
- * - `kIOReturnAborted` if the cursor has become invalid, possibly due to a reset of the queue.
- * - `kIOReturnUnderrun` if the entry at the cursor position is no longer in
- * the queue's buffer. Call IOCircularDataQueueGetLatest to get the latest data and cursor position.
- * - `kIOReturnBadArgument` if an invalid argument is passsed.
- * - `kIOReturnBadMedia` if the queue shared memory has been compromised.
- * - Other values indicate an error.
- *
- */
-IOReturn IOCircularDataQueueGetPreviousWithBlock(IOCircularDataQueue * queue, void (^handler)(const void *data, size_t size));
-
-__END_DECLS
-
-#endif /* IOGCCircularDataQueue_h */