Mac Developer Library

Developer

IOLib.h Reference

Options
Deployment Target:

On This Page

IOLib.h Reference

Included Headers

  • <stdarg.h>

  • <sys/cdefs.h>

  • <sys/appleapiopts.h>

  • <IOKit/system.h>

  • <IOKit/IOReturn.h>

  • <IOKit/IOTypes.h>

  • <IOKit/IOLocks.h>

  • <libkern/OSAtomic.h>

  • <kern/thread_call.h>

  • <kern/clock.h>

Functions

  • Returns the osfmk identifier for the currently running thread.

    Declaration

    Objective-C

    #define IOThreadSelf() (current_thread())

    Discussion

    This function returns the current thread (a pointer to the currently active osfmk thread_shuttle).

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Debugger Debugger (OS X v10.8)

    Enter the kernel debugger.

    Declaration

    Objective-C

    void Debugger ( void );

    Parameters

    reason

    A C-string to describe why the debugger is being entered.

    Discussion

    This function freezes the kernel and enters the builtin debugger. It may not be possible to exit the debugger without a second machine.

    Import Statement

    Objective-C

    #include <MacTypes.h>;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Deprecated function - use kernel_thread_start(). Create a kernel thread.

    Declaration

    Objective-C

    IOThread IOCreateThread ( IOThreadFunc function, void *argument );

    Parameters

    function

    A C-function pointer where the thread will begin execution.

    argument

    Caller specified data to be passed to the new thread.

    Return Value

    An IOThread identifier for the new thread, equivalent to an osfmk thread_t.

    Discussion

    This function creates a kernel thread, and passes the caller supplied argument to the new thread. Warning: the value returned by this function is not 100% reliable. There is a race condition where it is possible that the new thread has already terminated before this call returns. Under that circumstance the IOThread returned will be invalid. In general there is little that can be done with this value except compare it against 0. The thread itself can call IOThreadSelf() 100% reliably and that is the prefered mechanism to manipulate the IOThreads state.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Spin delay for a number of microseconds.

    Declaration

    Objective-C

    void IODelay ( unsigned int microseconds );

    Parameters

    microseconds

    The integer number of microseconds to spin wait.

    Discussion

    This function spins to delay for at least the number of specified microseconds. Since the CPU is busy spinning no time is made available to other processes; this method of delay should be used only for short periods. Also, the AbsoluteTime based APIs of kern/clock.h provide finer grained and lower cost delays.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • IOExitThread IOExitThread (OS X v10.6)

    Deprecated function - use thread_terminate(). Terminate execution of current thread.

    Declaration

    Objective-C

    void IOExitThread ( void );

    Discussion

    This function destroys the currently running thread, and does not return.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Flushes the processor cache for mapped memory.

    Declaration

    Objective-C

    IOReturn IOFlushProcessorCache ( task_t task, IOVirtualAddress address, IOByteCount length );

    Parameters

    task

    Task the memory is mapped into.

    address

    Virtual address of the memory.

    length

    Length of the range to set.

    Return Value

    An IOReturn code.

    Discussion

    This function flushes the processor cache of an already mapped memory range. Note in most cases it is preferable to use IOMemoryDescriptor::prepare and complete to manage cache coherency since they are aware of the architecture's requirements. Flushing the processor cache is not required for coherency in most situations.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Frees memory allocated with IOMalloc.

    Declaration

    Objective-C

    void IOFree ( void *address, vm_size_t size );

    Parameters

    address

    Pointer to the allocated memory. Must be identical to result @of a prior IOMalloc.

    size

    Size of the memory allocated. Must be identical to size of @the corresponding IOMalloc

    Discussion

    This function frees memory allocated with IOMalloc, it may block and so should not be called from interrupt level or while a simple lock is held.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Frees memory allocated with IOMallocAligned.

    Declaration

    Objective-C

    void IOFreeAligned ( void *address, vm_size_t size );

    Parameters

    address

    Pointer to the allocated memory.

    size

    Size of the memory allocated.

    Discussion

    This function frees memory allocated with IOMallocAligned, it may block and so should not be called from interrupt level or while a simple lock is held.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Deprecated - use IOBufferMemoryDescriptor. Frees memory allocated with IOMallocContiguous.

    Declaration

    Objective-C

    void IOFreeContiguous ( void *address, vm_size_t size );

    Parameters

    address

    Virtual address of the allocated memory.

    size

    Size of the memory allocated.

    Discussion

    This function frees memory allocated with IOMallocContiguous, it may block and so should not be called from interrupt level or while a simple lock is held.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Frees memory allocated with IOMallocPageable.

    Declaration

    Objective-C

    void IOFreePageable ( void *address, vm_size_t size );

    Parameters

    address

    Virtual address of the allocated memory.

    size

    Size of the memory allocated.

    Discussion

    This function frees memory allocated with IOMallocPageable, it may block and so should not be called from interrupt level or while a simple lock is held.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Log a message to console in text mode, and /var/log/system.log.

    Declaration

    Objective-C

    void IOLog ( const char *format, ... );

    Parameters

    format

    A printf() style format string (see printf(3) documentation).

    other

    arguments described by the format string.

    Discussion

    This function allows a driver to log diagnostic information to the screen during verbose boots, and to a log file found at /var/log/system.log. IOLog should not be called from interrupt context.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Log a message to console in text mode, and /var/log/system.log.

    Declaration

    Objective-C

    void IOLogv ( const char *format, va_list ap );

    Parameters

    format

    A printf() style format string (see printf(3) documentation).

    ap

    stdarg(3) style variable arguments.

    Discussion

    This function allows a driver to log diagnostic information to the screen during verbose boots, and to a log file found at /var/log/system.log. IOLogv should not be called from interrupt context.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.6 and later.

  • Allocates general purpose, wired memory in the kernel map.

    Declaration

    Objective-C

    void * IOMalloc ( vm_size_t size );

    Parameters

    size

    Size of the memory requested.

    Return Value

    Pointer to the allocated memory, or zero on failure.

    Discussion

    This is a general purpose utility to allocate memory in the kernel. There are no alignment guarantees given on the returned memory, and alignment may vary depending on the kernel configuration. This function may block and so should not be called from interrupt level or while a simple lock is held.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Allocates wired memory in the kernel map, with an alignment restriction.

    Declaration

    Objective-C

    void * IOMallocAligned ( vm_size_t size, vm_offset_t alignment );

    Parameters

    size

    Size of the memory requested.

    alignment

    Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bit 0-7 zero.

    Return Value

    Pointer to the allocated memory, or zero on failure.

    Discussion

    This is a utility to allocate memory in the kernel, with an alignment restriction which is specified as a byte count. This function may block and so should not be called from interrupt level or while a simple lock is held.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Deprecated - use IOBufferMemoryDescriptor. Allocates wired memory in the kernel map, with an alignment restriction and physically contiguous.

    Declaration

    Objective-C

    void * IOMallocContiguous ( vm_size_t size, vm_size_t alignment, IOPhysicalAddress *physicalAddress );

    Parameters

    size

    Size of the memory requested.

    alignment

    Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bits 0-7 zero.

    physicalAddress

    IOMallocContiguous returns the physical address of the allocated memory here, if physicalAddress is a non-zero pointer. The physicalAddress argument is deprecated and should be passed as NULL. To obtain the physical address for a memory buffer, use the IODMACommand class in conjunction with the IOMemoryDescriptor or IOBufferMemoryDescriptor classes.

    Return Value

    Virtual address of the allocated memory, or zero on failure.

    Discussion

    This is a utility to allocate memory in the kernel, with an alignment restriction which is specified as a byte count, and will allocate only physically contiguous memory. The request may fail if memory is fragmented, and may cause large amounts of paging activity. This function may block and so should not be called from interrupt level or while a simple lock is held.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Allocates pageable memory in the kernel map.

    Declaration

    Objective-C

    void * IOMallocPageable ( vm_size_t size, vm_size_t alignment );

    Parameters

    size

    Size of the memory requested.

    alignment

    Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bits 0-7 zero.

    Return Value

    Pointer to the allocated memory, or zero on failure.

    Discussion

    This is a utility to allocate pageable memory in the kernel. This function may block and so should not be called from interrupt level or while a simple lock is held.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Read two bytes from the desired "Physical" IOSpace address.

    Declaration

    Objective-C

    UInt16 IOMappedRead16 ( IOPhysicalAddress address );

    Parameters

    address

    The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.

    Return Value

    Data contained at that location

    Discussion

    Read two bytes from the desired "Physical" IOSpace address. This function allows the developer to read an address returned from any memory descriptor's getPhysicalSegment routine. It can then be used by segmenting a physical page slightly to tag the physical page with its kernel space virtual address.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.2 and later.

  • Read four bytes from the desired "Physical" IOSpace address.

    Declaration

    Objective-C

    UInt32 IOMappedRead32 ( IOPhysicalAddress address );

    Parameters

    address

    The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.

    Return Value

    Data contained at that location

    Discussion

    Read four bytes from the desired "Physical" IOSpace address. This function allows the developer to read an address returned from any memory descriptor's getPhysicalSegment routine. It can then be used by segmenting a physical page slightly to tag the physical page with its kernel space virtual address.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.2 and later.

  • Read eight bytes from the desired "Physical" IOSpace address.

    Declaration

    Objective-C

    UInt64 IOMappedRead64 ( IOPhysicalAddress address );

    Parameters

    address

    The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.

    Return Value

    Data contained at that location

    Discussion

    Read eight bytes from the desired "Physical" IOSpace address. This function allows the developer to read an address returned from any memory descriptor's getPhysicalSegment routine. It can then be used by segmenting a physical page slightly to tag the physical page with its kernel space virtual address.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.2 and later.

  • Read one byte from the desired "Physical" IOSpace address.

    Declaration

    Objective-C

    UInt8 IOMappedRead8 ( IOPhysicalAddress address );

    Parameters

    address

    The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.

    Return Value

    Data contained at that location

    Discussion

    Read one byte from the desired "Physical" IOSpace address. This function allows the developer to read an address returned from any memory descriptor's getPhysicalSegment routine. It can then be used by segmenting a physical page slightly to tag the physical page with its kernel space virtual address.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.2 and later.

  • Write two bytes to the desired "Physical" IOSpace address.

    Declaration

    Objective-C

    void IOMappedWrite16 ( IOPhysicalAddress address, UInt16 value );

    Parameters

    address

    The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.

    value

    Data to be writen to the desired location

    Discussion

    Write two bytes to the desired "Physical" IOSpace address. This function allows the developer to write to an address returned from any memory descriptor's getPhysicalSegment routine.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.2 and later.

  • Write four bytes to the desired "Physical" IOSpace address.

    Declaration

    Objective-C

    void IOMappedWrite32 ( IOPhysicalAddress address, UInt32 value );

    Parameters

    address

    The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.

    value

    Data to be writen to the desired location

    Discussion

    Write four bytes to the desired "Physical" IOSpace address. This function allows the developer to write to an address returned from any memory descriptor's getPhysicalSegment routine.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.2 and later.

  • Write eight bytes to the desired "Physical" IOSpace address.

    Declaration

    Objective-C

    void IOMappedWrite64 ( IOPhysicalAddress address, UInt64 value );

    Parameters

    address

    The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.

    value

    Data to be writen to the desired location

    Discussion

    Write eight bytes to the desired "Physical" IOSpace address. This function allows the developer to write to an address returned from any memory descriptor's getPhysicalSegment routine.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.2 and later.

  • Write one byte to the desired "Physical" IOSpace address.

    Declaration

    Objective-C

    void IOMappedWrite8 ( IOPhysicalAddress address, UInt8 value );

    Parameters

    address

    The desired address, as returned by IOMemoryDescriptor::getPhysicalSegment.

    value

    Data to be writen to the desired location

    Discussion

    Write one byte to the desired "Physical" IOSpace address. This function allows the developer to write to an address returned from any memory descriptor's getPhysicalSegment routine.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.2 and later.

  • Spin delay for a number of nanoseconds.

    Declaration

    Objective-C

    void IOPause ( unsigned int nanoseconds );

    Parameters

    microseconds

    The integer number of nanoseconds to spin wait.

    Discussion

    This function spins to delay for at least the number of specified nanoseconds. Since the CPU is busy spinning no time is made available to other processes; this method of delay should be used only for short periods.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.5 and later.

  • Sleep the calling thread for a number of milliseconds.

    Declaration

    Objective-C

    void IOSleep ( unsigned int milliseconds );

    Parameters

    milliseconds

    The integer number of milliseconds to wait.

    Discussion

    This function blocks the calling thread for at least the number of specified milliseconds, giving time to other processes.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.