ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IOLib.h

Includes:

Overview

Functions

Debugger: Enter the kernel debugger.
IOCreateThread: Create a kernel thread.
IODelay: Spin delay for a number of microseconds.
IOExitThread: Terminate exceution of current thread.
IOFlushProcessorCache: Flushes the processor cache for mapped memory.
IOFree: Frees memory allocated with IOMalloc.
IOFreeAligned: Frees memory allocated with IOMallocAligned.
IOFreeContiguous: Frees memory allocated with IOMallocContiguous.
IOFreePageable: Frees memory allocated with IOMallocPageable.
IOLog: Log a message to console in text mode, and /var/log/system.log.
IOMalloc: Allocates general purpose, wired memory in the kernel map.
IOMallocAligned: Allocates wired memory in the kernel map, with an alignment restriction.
IOMallocContiguous: Allocates wired memory in the kernel map, with an alignment restriction and physically contiguous.
IOMallocPageable: Allocates pageable memory in the kernel map.
IOMappedRead16: Read two bytes from the desired "Physical" IOSpace address.
IOMappedRead32: Read four bytes from the desired "Physical" IOSpace address.
IOMappedRead64: Read eight bytes from the desired "Physical" IOSpace address.
IOMappedRead8: Read one byte from the desired "Physical" IOSpace address.
IOMappedWrite16: Write two bytes to the desired "Physical" IOSpace address.
IOMappedWrite32: Write four bytes to the desired "Physical" IOSpace address.
IOMappedWrite64: Write eight bytes to the desired "Physical" IOSpace address.
IOMappedWrite8: Write one byte to the desired "Physical" IOSpace address.
IOPause: Spin delay for a number of nanoseconds.
IOSetProcessorCacheMode: Sets the processor cache mode for mapped memory.
IOSleep: Sleep the calling thread for a number of milliseconds.

Debugger

Enter the kernel debugger.

void Debugger(
    const char * reason);

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.

IOCreateThread

Create a kernel thread.

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.

IODelay

Spin delay for a number of microseconds.

void IODelay(
    unsigned 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.

IOExitThread

Terminate exceution of current thread.

void IOExitThread(
    void) __dead2;

Discussion

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

IOFlushProcessorCache

Flushes the processor cache for mapped memory.

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.

IOFree

Frees memory allocated with IOMalloc.

void IOFree(
    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 IOMalloc, it may block and so should not be called from interrupt level or while a simple lock is held.

IOFreeAligned

Frees memory allocated with IOMallocAligned.

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.

IOFreeContiguous

Frees memory allocated with IOMallocContiguous.

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.

IOFreePageable

Frees memory allocated with IOMallocPageable.

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.

IOLog

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

void IOLog(
    const char *format,
    ...) __attribute__((format(printf, 1, 2)));

Parameters

format: A printf() style format string (see printf() 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.

IOMalloc

Allocates general purpose, wired memory in the kernel map.

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.

IOMallocAligned

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

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.

IOMallocContiguous

Allocates wired memory in the kernel map, with an alignment restriction and physically contiguous.

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.

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.

IOMallocPageable

Allocates pageable memory in the kernel map.

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.

IOMappedRead16

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

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.

IOMappedRead32

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

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.

IOMappedRead64

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

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.

IOMappedRead8

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

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.

IOMappedWrite16

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

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.

IOMappedWrite32

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

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.

IOMappedWrite64

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

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.

IOMappedWrite8

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

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.

IOPause

Spin delay for a number of nanoseconds.

void IOPause(
    unsigned 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.

IOSetProcessorCacheMode

Sets the processor cache mode for mapped memory.

IOReturn IOSetProcessorCacheMode(
    task_t task,
    IOVirtualAddress address, 
    IOByteCount length,
    IOOptionBits cacheMode );

Parameters

task: Task the memory is mapped into.
address: Virtual address of the memory.
length: Length of the range to set.
cacheMode: A constant from IOTypes.h,
kIOMapDefaultCache to inhibit the cache in I/O areas, kIOMapCopybackCache in general purpose RAM.
kIOMapInhibitCache, kIOMapWriteThruCache, kIOMapCopybackCache to set the appropriate caching.

Return Value

An IOReturn code.

Discussion

This function sets the cache mode of an already mapped & wired memory range. Note this may not be supported on I/O mappings or shared memory - it is far preferable to set the cache mode as mappings are created with the IOMemoryDescriptor::map method.

IOSleep

Sleep the calling thread for a number of milliseconds.

void IOSleep(
    unsigned 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.

#defines

IOThreadSelf

Returns the osfmk identifier for the currently running thread.

#define IOThreadSelf()

Discussion

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

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19