#include <IOKit/IOCircularDataQueueImplementation.h>
IOKit/IOCircularDataQueueImplementation.h
@header IOCircularDataQueueMemory
This header contains the memory layout for a circular data queue.
A circular data queue supports a single producer and zero or more consumers.
The producer does not wait for consumers to read the data. If a
consumer falls behind, it will miss data.
The queue can be configured to support either fixed or variable sized
entries.
Currently only fixed is supported.
macroHEADER_16BYTE_ALIGNED
#define HEADER_16BYTE_ALIGNED 1
do the entry and entry headers need to be 16 byte aligned for perf/correctness ?
macroIOCIRCULARDATAQUEUE_ENTRY_STATE_WRITE_SIZE
#define IOCIRCULARDATAQUEUE_ENTRY_STATE_WRITE_SIZE 1
macroIOCIRCULARDATAQUEUE_ENTRY_STATE_GENERATION_SIZE
#define IOCIRCULARDATAQUEUE_ENTRY_STATE_GENERATION_SIZE 30
macroIOCIRCULARDATAQUEUE_ENTRY_STATE_DATATSIZE_SIZE
#define IOCIRCULARDATAQUEUE_ENTRY_STATE_DATATSIZE_SIZE 32
macroIOCIRCULARDATAQUEUE_ENTRY_STATE_SEQNUM_SIZE
#define IOCIRCULARDATAQUEUE_ENTRY_STATE_SEQNUM_SIZE 64
macroIOCIRCULARDATAQUEUE_ENTRY_STATE_RESERVED_SIZE
#define IOCIRCULARDATAQUEUE_ENTRY_STATE_RESERVED_SIZE 1
#define IOCIRCULARDATAQUEUE_ENTRY_STATE_RESERVED_SIZE ((8 * sizeof(__uint128_t)) - IOCIRCULARDATAQUEUE_ENTRY_STATE_WRITE_SIZE - IOCIRCULARDATAQUEUE_ENTRY_STATE_GENERATION_SIZE - IOCIRCULARDATAQUEUE_ENTRY_STATE_DATATSIZE_SIZE - IOCIRCULARDATAQUEUE_ENTRY_STATE_SEQNUM_SIZE)
unionIOCircularDataQueueEntryHeaderInfo
| __uint128_t | val | ||||||||||||||||
| unnamed struct at Kernel/IOKit/IOCircularDataQueueImplementation.h:119:2 | fields | ||||||||||||||||
| |||||||||||||||||
typedefIOCircularDataQueueEntryHeaderInfo
typedef union IOCircularDataQueueEntryHeaderInfo IOCircularDataQueueEntryHeaderInfo;
macroIOCIRCULARDATAQUEUE_ENTRY_STATE_WRITE_INPROGRESS
#define IOCIRCULARDATAQUEUE_ENTRY_STATE_WRITE_INPROGRESS (1)
macroIOCIRCULARDATAQUEUE_ENTRY_STATE_WRITE_COMPLETE
#define IOCIRCULARDATAQUEUE_ENTRY_STATE_WRITE_COMPLETE (0)
structIOCircularDataQueueEntryHeader
@typedef IOCircularDataQueueEntryHeader
@abstract An entry in the circular data queue. The entry header is written at the beginning of each entry in the
queue.
@discussion The entry has the current state, sentinel, followed by the data at the enty.
@field info The info of the queue entry. This includes the size, sequence number, generation and write status of the
data at this entry.
@field sentinel unique value written to the queue entry. This is copied from the sentinel in the queue header memory
when an entry is written.
@field data Represents the beginning of the data region. The address of the data field is a pointer to the start of
the data region.
| volatile uint64_t | sentinel | |
| uint64_t | _pad | pad for 16 byte aligment of data that follows |
| uint8_t[16] | data | Entry data begins. Aligned to 16 bytes. |
typedefIOCircularDataQueueEntryHeader
typedef struct IOCircularDataQueueEntryHeader IOCircularDataQueueEntryHeader;
macroCIRCULAR_DATA_QUEUE_ENTRY_HEADER_SIZE
#define CIRCULAR_DATA_QUEUE_ENTRY_HEADER_SIZE (sizeof(IOCircularDataQueueEntryHeader) - 16)
macroIOCIRCULARDATAQUEUE_STATE_WRITE_SIZE
#define IOCIRCULARDATAQUEUE_STATE_WRITE_SIZE 1
macroIOCIRCULARDATAQUEUE_STATE_RESET_SIZE
#define IOCIRCULARDATAQUEUE_STATE_RESET_SIZE 1
macroIOCIRCULARDATAQUEUE_STATE_GENERATION_SIZE
#define IOCIRCULARDATAQUEUE_STATE_GENERATION_SIZE 30
macroIOCIRCULARDATAQUEUE_STATE_WRITEINDEX_SIZE
#define IOCIRCULARDATAQUEUE_STATE_WRITEINDEX_SIZE 32
macroIOCIRCULARDATAQUEUE_STATE_SEQNUM_SIZE
#define IOCIRCULARDATAQUEUE_STATE_SEQNUM_SIZE 64
unionIOCircularDataQueueState
| __uint128_t | val | ||||||||||||||||
| unnamed struct at Kernel/IOKit/IOCircularDataQueueImplementation.h:191:2 | fields | ||||||||||||||||
| |||||||||||||||||
typedefIOCircularDataQueueState
typedef union IOCircularDataQueueState IOCircularDataQueueState;
macroIOCIRCULARDATAQUEUE_STATE_WRITE_INPROGRESS
#define IOCIRCULARDATAQUEUE_STATE_WRITE_INPROGRESS (1)
macroIOCIRCULARDATAQUEUE_STATE_WRITE_COMPLETE
#define IOCIRCULARDATAQUEUE_STATE_WRITE_COMPLETE (0)
macroIOCIRCULARDATAQUEUE_STATE_RESET_INPROGRESS
#define IOCIRCULARDATAQUEUE_STATE_RESET_INPROGRESS (1)
macroIOCIRCULARDATAQUEUE_STATE_RESET_COMPLETE
#define IOCIRCULARDATAQUEUE_STATE_RESET_COMPLETE (0)
macroIOCIRCULARDATAQUEUE_STATE_GENERATION_MAX
#define IOCircularDataQueueStateGeneration (((uint32_t)1 << 30) - 1)
#define IOCIRCULARDATAQUEUE_STATE_GENERATION_MAX (((uint32_t)1 << 30))
structIOCircularDataQueueMemory
| uint64_t | sentinel | |
| uint64_t | _padding | since we want it to be 16 bytes aligned below this |
| IOCircularDataQueueEntryHeader[1] | entries | Entries begin. Aligned to 16 bytes. |
typedefIOCircularDataQueueMemory
typedef struct IOCircularDataQueueMemory IOCircularDataQueueMemory;
macroCIRCULAR_DATA_QUEUE_MEMORY_HEADER_SIZE
#define CIRCULAR_DATA_QUEUE_MEMORY_HEADER_SIZE (sizeof(IOCircularDataQueueMemory) - sizeof(IOCircularDataQueueEntryHeader))
structIOCircularDataQueueMemoryCursor
@typedef IOCircularDataQueueMemoryCursor
@abstract The circular data queue cursor struct.
@discussion This struct represents a readers reference to a position in the queue. Each client holds an instance of
this in its process indicating its current reading position in the queue. The cursor holds uniqely identifying
information for the queue entry.
@field generation the generation for the entry data at the position in the queue. This generation is only changed
when the queue is reset.
@field position the position in the queue the cursor is at
@field sequenceNum The unique number for the data at the cursor position. The sequence number is unique for each
entry in the queue.
| uint32_t | generation | uint32_t seems a little excessive right now, since we dont expect these many resets. but |
| uint32_t | position | lets leave it for now. |
| uint64_t | sequenceNum |
typedefIOCircularDataQueueMemoryCursor
typedef struct IOCircularDataQueueMemoryCursor IOCircularDataQueueMemoryCursor;
structIOCircularDataQueueDescription
@typedef IOCircularDataQueueDescription
@abstract The circular data queue header shadow struct.
@discussion This struct represents the queue header shadow. Each client has a copy of this struct in its process .
This is used to detect any memory corruption of the shared memory queue header. This struct needs to be shared from
the creator of the queue to the clients via an out of band mechanism.
@field sentinel unique value written to the queue header memory and each queue entry.
@field allocMemSize the allocated memory size of the queue including the queue header
@field entryDataSize size of each entry in the queue including the entry header. The size is a multiple of 8 bytes
@field memorySize the memory size of the queue excluding the queue header
@field numEntries the number of fixed entries in the queue
IOCircularDataQueueDescription
| uint64_t | sentinel | |
| uint32_t | allocMemSize | total allocated size of the queue including the queue header. |
| uint32_t | entryDataSize | size of each queue entry including the per entry header. |
| uint32_t | memorySize | memory size of the queue (excluding the queue header) |
| uint32_t | numEntries | |
| uint32_t | dataSize | the client provided data size excluding the per entry header. |
| uint32_t | padding |
typedefIOCircularDataQueueDescription
typedef struct IOCircularDataQueueDescription IOCircularDataQueueDescription;
macrokIOCircularQueueDescriptionKey
#define kIOCircularQueueDescriptionKey "IOCircularQueueDescription"
macroQUEUE_FORMAT
#define QUEUE_FORMAT "Queue(%" PRIu64 " gen:%" PRIu64 " pos:%" PRIu64 " next:%" PRIu64 ")"
macroQUEUE_ARGS
#define QUEUE_ARGS(q) q->guard, q->generation, q->fixed.latestIndex, q->fixed.writingIndex
macroCURSOR_FORMAT
#define CURSOR_FORMAT "Cursor(%p gen:%" PRIu64 " pos:%" PRIu64 ")"
macroCURSOR_ARGS
#define CURSOR_ARGS(c) c, c->generation, c->position
macroENTRY_FORMAT
#define ENTRY_FORMAT "Entry(%" PRIu64 " gen:%" PRIu64 " pos:%" PRIu64 ")"
macroENTRY_ARGS
#define ENTRY_ARGS(e) e->guard, e->generation, e->position
macroqueue_debug_error
#define queue_debug_error(fmt, ...)
macroqueue_debug_note
#define queue_debug_note(fmt, ...)
macroqueue_debug_trace
#define queue_debug_trace(fmt, ...)
structIOCircularDataQueue
@typedef IOCircularDataQueue
@abstract A fixed entry size circular queue that supports multiple concurrent readers and a single writer.
@discussion The queue currently supports fixed size entries. The queue memory size is configured at init when the
number of entries and size of each entry is specifiied and cannot be resized later. Since the queue is a circular
buffer, the writer can potentially overwrite an entry while a reader is still reading it. The queue provides facility
to check for data integrity after reading the entry is complete. There is no support for sending notifications to
readers when data is enqueued into an empty queue by the writer. The queue supports a "pull model" for reading data
from the queue. The queue can be used for passing data from user space to kernel and vice-versa.
@field queueHeaderShadow The queue header shadow
@field queueCursor The queue cursor
@field isQueueMemoryAllocated Represents if the queue memory is allocated or if the queue uses a previously
created queue memory region.
@field queueMemory Pointer to the queue shared memory region
| IOCircularDataQueueMemoryCursor | queueCursor | |
| IOCircularDataQueueMemory * | queueMemory | |
| IOCircularDataQueueDescription | queueHeaderShadow | |
| IOBufferMemoryDescriptor * | iomd |
typedefIOCircularDataQueue
typedef struct IOCircularDataQueue IOCircularDataQueue;
macroATTR_LSE2
#define ATTR_LSE2
function_isQueueMemoryCorrupted
static bool ATTR_LSE2 _isQueueMemoryCorrupted(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Compares the sentinel in the shared queue header against the per-client queue header shadow (IOCircularDataQueueDescription). Returns true if they differ, indicating the shared memory queue header has been corrupted or tampered with. Every queue operation performs this check before, and typically after, touching the shared region; callers map a failure to kIOReturnBadMedia.
function_isCursorPositionInvalid
inline static bool ATTR_LSE2 _isCursorPositionInvalid(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Returns true if the client cursor's position is greater than or equal to numEntries in the queue header shadow, i.e. the cursor does not reference a valid entry slot. A freshly initialized cursor (position UINT32_MAX, set by _initCursor) fails this check until setCursorLatestInQueueMem or a get-latest operation positions it; read paths map the failure to kIOReturnAborted or kIOReturnBadArgument.
function_isEntryOutOfBounds
inline __unused static bool ATTR_LSE2 _isEntryOutOfBounds( IOCircularDataQueue *queue, IOCircularDataQueueEntryHeader *entry )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Bounds check helper. Returns true if the entry pointer lies outside the range from the first to the last entry of the queue's entry array, computed from numEntries and entryDataSize in the queue header shadow. Declared __unused; the enqueue and read paths instead perform an equivalent range check inline against the allocated memory size.
functiondestroyQueueMem
static IOReturn ATTR_LSE2 destroyQueueMem(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Releases the queue's backing memory. In the kernel, releases the IOBufferMemoryDescriptor with OSSafeReleaseNULL; in user space, unmaps the shared region with IOConnectUnmapMemory and clears the queueMemory pointer. Returns kIOReturnBadArgument if queue is NULL, kIOReturnSuccess otherwise. Called from IOCircularDataQueueDestroy.
function_reset
static IOReturn ATTR_LSE2 _reset(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Resets the queue by atomically replacing the 128-bit queue state with a compare-exchange: the generation is incremented modulo IOCIRCULARDATAQUEUE_STATE_GENERATION_MAX, the write index is set to 0, and the sequence number to UINT64_MAX (the first enqueue increments it to 0). Returns kIOReturnBusy if a write is in progress or the exchange loses a race, kIOReturnBadMedia if the queue sentinel no longer matches the shadow, kIOReturnUnsupported if entryDataSize is 0, kIOReturnBadArgument for NULL queue memory. The generation change invalidates outstanding cursors; readers subsequently observe kIOReturnAborted.
function_enqueueInternal
static IOReturn ATTR_LSE2 _enqueueInternal( IOCircularDataQueue *queue, const void *data, size_t dataSize, int earlyExitForTesting )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Enqueue worker. Validates the arguments and queue sentinel, then atomically sets the queue-state write bit with a 128-bit compare-exchange; failure returns kIOReturnBusy (single-writer discipline). Writes the entry header at the current write index with write-in-progress status, next sequence number, current generation and dataSize, stores the sentinel, copies the data, marks the entry write-complete, then publishes the advanced write index and sequence number with a release store. Returns kIOReturnBadArgument for NULL or oversized data or an out-of-bounds entry pointer, kIOReturnBadMedia on sentinel mismatch, kIOReturnUnsupported if entryDataSize is 0, kIOReturnOverrun on sequence number exhaustion. earlyExitForTesting is a test-only hook.
functionenqueueQueueMem
static IOReturn ATTR_LSE2 enqueueQueueMem( IOCircularDataQueue *queue, const void *data, size_t dataSize )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Enqueues a new entry: calls _enqueueInternal with the testing flag clear. Copies dataSize bytes into the entry at the write index and advances the write index; see IOCircularDataQueueEnqueue for the return codes.
functionisDataEntryValidInQueueMem
static IOReturn ATTR_LSE2 isDataEntryValidInQueueMem(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Verifies that the entry at the reader's cursor position still holds the data observed when the cursor was set; call after reading in place, since the writer may overwrite an entry while it is being read. Returns kIOReturnSuccess if the entry's generation, sequence number and write status are unchanged; kIOReturnOverrun if the entry was or is being overwritten; kIOReturnAborted if the queue generation changed (queue reset); kIOReturnBusy while a reset is in progress; kIOReturnBadArgument for an invalid cursor position or queue; kIOReturnBadMedia if the queue or entry sentinel is corrupted. Backs IOCircularDataQueueIsCurrentDataValid.
functionsetCursorLatestInQueueMem
static IOReturn ATTR_LSE2 setCursorLatestInQueueMem(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Positions the reader cursor at the most recently written entry (write index minus one, wrapping) without reading data, recording the entry's index, generation and sequence number in the cursor. Returns kIOReturnUnderrun if the queue sequence number is still UINT64_MAX (nothing ever enqueued), kIOReturnAborted if the entry is out of bounds or its generation differs from the queue's, kIOReturnBadMedia on a sentinel mismatch, kIOReturnBusy while a reset is in progress, kIOReturnBadArgument for NULL queue memory. Backs IOCircularDataQueueSetCursorLatest.
function_getLatestInQueueMemInternal
static IOReturn ATTR_LSE2 _getLatestInQueueMemInternal( IOCircularDataQueue *queue, void **data, size_t *size, bool copyMem )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Common worker for getLatestInQueueMem and copyLatestInQueueMem. Locates the most recently written entry and either returns a pointer into the shared queue memory (copyMem false) or copies the data into the caller's buffer (copyMem true), re-reading the 128-bit entry header after the memcpy to confirm it did not change. Retries up to 5 times when the writer overwrites the entry mid-read, then returns kIOReturnTimeout. Updates the cursor to the entry read. Other returns: kIOReturnUnderrun (nothing enqueued), kIOReturnBusy (reset in progress), kIOReturnBadMedia (sentinel mismatch), kIOReturnOverrun (entry data larger than entryDataSize or than the caller's buffer), kIOReturnBadArgument (NULL parameters or out-of-bounds entry).
functiongetLatestInQueueMem
static IOReturn ATTR_LSE2 getLatestInQueueMem( IOCircularDataQueue *queue, void **data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Returns a pointer to the latest entry's data in shared queue memory and moves the cursor to that entry; wrapper for _getLatestInQueueMemInternal with copyMem false. Caller is expected to call isDataEntryValidInQueueMem after reading, since the writer may overwrite the entry in place.
functioncopyLatestInQueueMem
static IOReturn ATTR_LSE2 copyLatestInQueueMem( IOCircularDataQueue *queue, void *data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Copies the latest entry's data into the caller-provided buffer and moves the cursor to that entry; wrapper for _getLatestInQueueMemInternal with copyMem true. A successful return guarantees a consistent copy, so no isDataEntryValidInQueueMem call is needed.
function_getNextInQueueMemInternal
static IOReturn ATTR_LSE2 _getNextInQueueMemInternal( IOCircularDataQueue *queue, void **data, size_t *size, bool copyMem )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Common worker for getNextInQueueMem and copyNextInQueueMem. Advances the cursor to position plus one modulo numEntries and returns a pointer to, or copies, that entry's data. Returns kIOReturnAborted if the cursor generation no longer matches the queue generation (queue reset), the cursor position is invalid, or the next entry's generation differs; kIOReturnUnderrun if the cursor is already at the newest entry, or the only newer entry is still being written, or nothing was ever enqueued; kIOReturnOverrun if the next entry's sequence number is not cursor sequence plus one (reader fell behind and the slot was overwritten), the data exceeds bounds, or a copy is invalidated by a concurrent write during the memcpy; kIOReturnBusy during a reset; kIOReturnBadMedia on sentinel mismatch; kIOReturnBadArgument for NULL parameters or an out-of-bounds entry.
functiongetNextInQueueMem
static IOReturn ATTR_LSE2 getNextInQueueMem( IOCircularDataQueue *queue, void **data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Returns a pointer to the entry after the cursor and advances the cursor; wrapper for _getNextInQueueMemInternal with copyMem false. Caller is expected to call isDataEntryValidInQueueMem after reading the data in place.
functioncopyNextInQueueMem
static IOReturn ATTR_LSE2 copyNextInQueueMem( IOCircularDataQueue *queue, void *data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Copies the entry after the cursor into the caller-provided buffer and advances the cursor; wrapper for _getNextInQueueMemInternal with copyMem true. A successful return guarantees a consistent copy.
function_getPrevInQueueMemInternal
static IOReturn ATTR_LSE2 _getPrevInQueueMemInternal( IOCircularDataQueue *queue, void **data, size_t *size, bool copyMem )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Common worker for getPrevInQueueMem and copyPrevInQueueMem. Steps the cursor back one position (wrapping to numEntries minus one at position 0) and returns a pointer to, or copies, that entry's data. Returns kIOReturnOverrun if the previous entry is being written, carries a sequence number greater than the cursor's (already overwritten by newer data), belongs to a different generation, exceeds size bounds, or a copy is invalidated during the memcpy; kIOReturnAborted if the cursor is invalid or the queue was reset; kIOReturnUnderrun if nothing was ever enqueued; kIOReturnBusy during a reset; kIOReturnBadMedia on sentinel mismatch; kIOReturnBadArgument for NULL parameters or an out-of-bounds entry.
functiongetPrevInQueueMem
static IOReturn ATTR_LSE2 getPrevInQueueMem( IOCircularDataQueue *queue, void **data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Returns a pointer to the entry before the cursor and moves the cursor back; wrapper for _getPrevInQueueMemInternal with copyMem false. Caller is expected to call isDataEntryValidInQueueMem after reading the data in place.
functioncopyPrevInQueueMem
static IOReturn ATTR_LSE2 copyPrevInQueueMem( IOCircularDataQueue *queue, void *data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Copies the entry before the cursor into the caller-provided buffer and moves the cursor back; wrapper for _getPrevInQueueMemInternal with copyMem true. A successful return guarantees a consistent copy.
function_getCurrentInQueueMemInternal
static IOReturn ATTR_LSE2 _getCurrentInQueueMemInternal( IOCircularDataQueue *queue, void **data, size_t *size, bool copyMem )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Common worker for getCurrentInQueueMem and copyCurrentInQueueMem. Reads the entry at the cursor position without moving the cursor, returning a pointer or copying the data. The entry must still carry the cursor's exact sequence number; otherwise kIOReturnOverrun. Returns kIOReturnAborted if the cursor is invalid, the queue was reset, or the entry generation differs; kIOReturnUnderrun if nothing was ever enqueued; kIOReturnBusy during a reset or if a copy is invalidated by a concurrent write during the memcpy; kIOReturnBadMedia on sentinel mismatch; kIOReturnBadArgument for NULL parameters or an out-of-bounds entry.
functiongetCurrentInQueueMem
static IOReturn ATTR_LSE2 getCurrentInQueueMem( IOCircularDataQueue *queue, void **data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Returns a pointer to the entry at the current cursor position, leaving the cursor unchanged; wrapper for _getCurrentInQueueMemInternal with copyMem false. Caller is expected to call isDataEntryValidInQueueMem after reading the data in place.
functioncopyCurrentInQueueMem
static IOReturn ATTR_LSE2 copyCurrentInQueueMem( IOCircularDataQueue *queue, void *data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Copies the entry at the current cursor position into the caller-provided buffer, leaving the cursor unchanged; wrapper for _getCurrentInQueueMemInternal with copyMem true. A successful return guarantees a consistent copy.
function_initCursor
static void ATTR_LSE2 _initCursor(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h
Invalidates the client cursor by setting generation and position to UINT32_MAX and sequenceNum to UINT64_MAX. Called during queue creation; the cursor becomes valid on the first successful get-latest operation or IOCircularDataQueueSetCursorLatest.
functionIOCircularDataQueueCreateWithEntries
IOReturn ATTR_LSE2 IOCircularDataQueueCreateWithEntries( IOCircularDataQueueCreateOptions options, uint32_t numEntries, uint32_t entrySize, IOCircularDataQueue **pQueue )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Creates a circular data queue with capacity for numEntries fixed-size entries of entrySize bytes each (kernel side). Rounds each entry up to 16-byte alignment plus the per-entry header, allocates a page-aligned IOBufferMemoryDescriptor in the kernel task with kIOMemoryKernelUserShared so the region can be mapped into a user process, attaches the queue description under kIOCircularQueueDescriptionKey as the descriptor's sharing context, resets the queue state and invalidates the cursor. The counts only size the data region; being circular, the queue eventually overwrites old data rather than limiting enqueues. Supports a single producer and zero or more consumers; a lagging consumer misses data. Returns kIOReturnBadArgument for a NULL pQueue, zero counts, or uint32_t overflow of the computed sizes; kIOReturnNoMemory on allocation failure.
functionIOCircularDataQueueCopyMemoryDescriptor
IOMemoryDescriptor * ATTR_LSE2 IOCircularDataQueueCopyMemoryDescriptor( IOCircularDataQueue *queue )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Returns the queue's IOBufferMemoryDescriptor with an additional retain, suitable for return from an IOUserClient clientMemoryForType override so a user process can map the queue and attach with IOCircularDataQueueCreateWithConnection. Returns NULL if the queue holds no descriptor; the caller releases the reference.
functionIOCircularDataQueueDestroy
IOReturn ATTR_LSE2 IOCircularDataQueueDestroy(IOCircularDataQueue **pQueue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Destroys a queue created with IOCircularDataQueueCreateWithEntries (or, in user space, IOCircularDataQueueCreateWithConnection): releases or unmaps the queue memory via destroyQueueMem, frees the IOCircularDataQueue structure, and clears *pQueue. Returns kIOReturnBadArgument if pQueue is NULL; kIOReturnSuccess otherwise, including when *pQueue is already NULL.
functionIOCircularDataQueueEnqueue
IOReturn ATTR_LSE2 IOCircularDataQueueEnqueue( IOCircularDataQueue *queue, const void *data, size_t dataSize )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Enqueues a new entry: copies dataSize bytes into the entry at the write index, stamps the entry header with the next sequence number and current generation, then advances the write index, overwriting the oldest entry once the queue wraps. Returns kIOReturnSuccess; kIOReturnBusy if another thread is enqueuing concurrently (single writer); kIOReturnBadArgument for a NULL queue or data, zero dataSize, or dataSize larger than the configured entry size; kIOReturnBadMedia if the shared memory sentinel check fails; kIOReturnUnsupported if the queue is not configured for fixed-size entries.
functionIOCircularDataQueueGetLatest
IOReturn ATTR_LSE2 IOCircularDataQueueGetLatest( IOCircularDataQueue *queue, void **data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Returns a pointer to the latest entry's data in shared queue memory, without copying, and moves the cursor to that entry. Caller should call IOCircularDataQueueIsCurrentDataValid after reading, since the writer may overwrite the entry in place. Returns kIOReturnSuccess; kIOReturnUnderrun if nothing has ever been enqueued; kIOReturnTimeout if repeated retries lost races with the writer; kIOReturnBadMedia on sentinel corruption; kIOReturnBadArgument for invalid parameters.
functionIOCircularDataQueueCopyLatest
IOReturn ATTR_LSE2 IOCircularDataQueueCopyLatest( IOCircularDataQueue *queue, void *data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Copies the latest entry's data into the caller-provided buffer and moves the cursor to that entry. size gives the buffer capacity on input and the entry's data size on return. Success guarantees a consistent copy, so IOCircularDataQueueIsCurrentDataValid is not needed. Returns kIOReturnUnderrun if nothing has ever been enqueued, kIOReturnOverrun if the buffer is too small, kIOReturnTimeout after repeated races with the writer, kIOReturnBadMedia on sentinel corruption, kIOReturnBadArgument for NULL parameters.
functionIOCircularDataQueueGetNext
IOReturn ATTR_LSE2 IOCircularDataQueueGetNext( IOCircularDataQueue *queue, void **data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Returns a pointer to the entry after the current cursor position, without copying, and advances the cursor. Caller should call IOCircularDataQueueIsCurrentDataValid after reading. Returns kIOReturnUnderrun when the cursor is already at the newest entry; kIOReturnOverrun when the reader has fallen behind and the next entry was overwritten (use IOCircularDataQueueGetLatest to resynchronize); kIOReturnAborted if the queue was reset; kIOReturnBadMedia on sentinel corruption; kIOReturnBadArgument for invalid parameters.
functionIOCircularDataQueueCopyNext
IOReturn ATTR_LSE2 IOCircularDataQueueCopyNext( IOCircularDataQueue *queue, void *data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Copies the entry after the current cursor position into the caller-provided buffer and advances the cursor; success guarantees a consistent copy. size is buffer capacity on input, data size on return. Returns kIOReturnUnderrun at the newest entry, kIOReturnOverrun when the entry was overwritten or the buffer is too small (use IOCircularDataQueueCopyLatest to resynchronize), kIOReturnAborted after a queue reset, kIOReturnBadMedia on sentinel corruption, kIOReturnBadArgument for invalid parameters.
functionIOCircularDataQueueGetPrevious
IOReturn ATTR_LSE2 IOCircularDataQueueGetPrevious( IOCircularDataQueue *queue, void **data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Returns a pointer to the entry before the current cursor position, without copying, and moves the cursor back. Caller should call IOCircularDataQueueIsCurrentDataValid after reading. Returns kIOReturnOverrun when the previous entry is no longer in the queue's buffer (overwritten by newer data; use IOCircularDataQueueGetLatest to resynchronize); kIOReturnAborted if the cursor became invalid, e.g. after a queue reset; kIOReturnBadMedia on sentinel corruption; kIOReturnBadArgument for invalid parameters.
functionIOCircularDataQueueCopyPrevious
IOReturn ATTR_LSE2 IOCircularDataQueueCopyPrevious( IOCircularDataQueue *queue, void *data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Copies the entry before the current cursor position into the caller-provided buffer and moves the cursor back; success guarantees a consistent copy. size is buffer capacity on input, data size on return. Returns kIOReturnOverrun when the entry was overwritten or the buffer is too small (use IOCircularDataQueueCopyLatest to resynchronize), kIOReturnAborted if the cursor became invalid, kIOReturnBadMedia on sentinel corruption, kIOReturnBadArgument for invalid parameters.
functionIOCircularDataQueueIsCurrentDataValid
IOReturn ATTR_LSE2 IOCircularDataQueueIsCurrentDataValid(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Verifies that the entry at the current cursor position still holds the same data as when the cursor was set. Call after reading data in place via the Get variants, since the writer may overwrite an entry while it is being read. Returns kIOReturnSuccess if unchanged; kIOReturnOverrun if the entry was potentially overwritten (use IOCircularDataQueueGetLatest to resynchronize); kIOReturnAborted if the cursor became invalid, e.g. after a queue reset; kIOReturnBadMedia if the queue memory is corrupted; kIOReturnBadArgument for invalid parameters.
functionIOCircularDataQueueSetCursorLatest
IOReturn ATTR_LSE2 IOCircularDataQueueSetCursorLatest(IOCircularDataQueue *queue)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Sets the cursor to the latest entry in the queue without reading data. Returns kIOReturnUnderrun if nothing has ever been enqueued, kIOReturnAborted if the queue is in an irrecoverable state, kIOReturnBadMedia on sentinel corruption, kIOReturnBadArgument for invalid parameters.
functionIOCircularDataQueueGetCurrent
IOReturn ATTR_LSE2 IOCircularDataQueueGetCurrent( IOCircularDataQueue *queue, void **data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Returns a pointer to the entry at the current cursor position without copying; the cursor is unchanged. Caller should call IOCircularDataQueueIsCurrentDataValid after reading. Returns kIOReturnUnderrun if nothing has ever been enqueued; kIOReturnOverrun if the entry at the cursor was overwritten (use IOCircularDataQueueGetLatest to resynchronize); kIOReturnAborted if the cursor became invalid, e.g. after a queue reset; kIOReturnBadMedia on sentinel corruption; kIOReturnBadArgument for invalid parameters.
functionIOCircularDataQueueCopyCurrent
IOReturn ATTR_LSE2 IOCircularDataQueueCopyCurrent( IOCircularDataQueue *queue, void *data, size_t *size )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu iokit/IOKit/IOCircularDataQueueImplementation.h, iokit/IOKit/IOCircularDataQueue.h
Copies the entry at the current cursor position into the caller-provided buffer; the cursor is unchanged and success guarantees a consistent copy. size is buffer capacity on input, data size on return. Returns kIOReturnUnderrun if nothing has ever been enqueued, kIOReturnOverrun if the entry was overwritten or the buffer is too small, kIOReturnAborted if the cursor became invalid, kIOReturnBadMedia on sentinel corruption, kIOReturnBadArgument for invalid parameters.