IOLib.h Reference

Declared in
IOLib.h

Overview

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

See the Overview section above for header-level documentation.

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

IOCreateThread

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

IOThread IOCreateThread(
   IOThreadFunc function,
   void *argument) __attribute__((deprecated));
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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

IOExitThread

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

void IOExitThread(
   void) __attribute__((deprecated));
Discussion

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

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

IOFree

Frees memory allocated with IOMalloc.

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

IOFreeContiguous

Deprecated - use IOBufferMemoryDescriptor. Frees memory allocated with IOMallocContiguous.

void IOFreeContiguous(
   void *address,
   vm_size_t size) __attribute__((deprecated));
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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

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(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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

IOLogv

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

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

IOMallocContiguous

Deprecated - use IOBufferMemoryDescriptor. 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) __attribute__((deprecated));
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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
IOLib.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h

IOThreadSelf

Returns the osfmk identifier for the currently running thread.

#define IOThreadSelf() (current_thread())
Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLib.h