IOLib.h



Functions

Debugger

Abstract: Enter the kernel debugger.
void Debugger(const char * reason);

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

Parameters

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

IOCreateThread

Abstract: Create a kernel thread.
IOThread IOCreateThread(IOThreadFunc function, void *argument);

This function creates a kernel thread, and passes the caller supplied argument to the new thread.

Parameters

NameDescription
functionA C-function pointer where the thread will begin execution.
argumentCaller specified data to be passed to the new thread.
Result: An IOThread identifier for the new thread, equivalent to an osfmk thread_t.

IODelay

Abstract: Spin delay for a number of microseconds.
void IODelay(unsigned microseconds);

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.

Parameters

NameDescription
microsecondsThe integer number of microseconds to spin wait.

IOExitThread

Abstract: Terminate exceution of current thread.
volatile void IOExitThread();

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


IOFlushProcessorCache

Abstract: Flushes the processor cache for mapped memory.
IOReturn IOFlushProcessorCache( task_t task, IOVirtualAddress address,
 IOByteCount length );

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.

Parameters

NameDescription
taskTask the memory is mapped into.
addressVirtual address of the memory.
lengthLength of the range to set.
Result: An IOReturn code.

IOFree

Abstract: Frees memory allocated with IOMalloc.
void IOFree(void * address, vm_size_t size);

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.

Parameters

NameDescription
addressPointer to the allocated memory.
sizeSize of the memory allocated.

IOFreeAligned

Abstract: Frees memory allocated with IOMallocAligned.
void IOFreeAligned(void * address, vm_size_t size);

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.

Parameters

NameDescription
addressPointer to the allocated memory.
sizeSize of the memory allocated.

IOFreeContiguous

Abstract: Frees memory allocated with IOMallocContiguous.
void IOFreeContiguous(void * address, vm_size_t size);

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.

Parameters

NameDescription
addressVirtual address of the allocated memory.
sizeSize of the memory allocated.

IOLog

Abstract: Log a message to console in text mode, and /var/log/system.log.
void IOLog(const char *format, ...)
__attribute__((format(printf, 1, 2)));

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.

Parameters

NameDescription
formatA printf() style format string (see printf() documentation).
otherarguments described by the format string.

IOMalloc

Abstract: Allocates general purpose, wired memory in the kernel map.
void * IOMalloc(vm_size_t size);

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.

Parameters

NameDescription
sizeSize of the memory requested.
Result: Pointer to the allocated memory, or zero on failure.

IOMallocAligned

Abstract: Allocates wired memory in the kernel map, with an alignment restriction.
void * IOMallocAligned(vm_size_t size, vm_offset_t alignment);

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.

Parameters

NameDescription
sizeSize of the memory requested.
alignmentByte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bit 0-7 zero.
Result: Pointer to the allocated memory, or zero on failure.

IOMallocContiguous

Abstract: 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);

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.

Parameters

NameDescription
sizeSize of the memory requested.
alignmentByte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bits 0-7 zero.
physicalAddressIOMallocContiguous returns the physical address of the allocated memory here, if physicalAddress is a non-zero pointer.
Result: Virtual address of the allocated memory, or zero on failure.

IOSetProcessorCacheMode

Abstract: Sets the processor cache mode for mapped memory.
IOReturn IOSetProcessorCacheMode( task_t task, IOVirtualAddress address,
 IOByteCount length, IOOptionBits cacheMode );

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.

Parameters

NameDescription
taskTask the memory is mapped into.
addressVirtual address of the memory.
lengthLength of the range to set.
cacheModeA 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.
Result: An IOReturn code.

IOSleep

Abstract: Sleep the calling thread for a number of milliseconds.
void IOSleep(unsigned milliseconds);

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

Parameters

NameDescription
millisecondsThe integer number of milliseconds to wait.

IOThreadSelf

Abstract: Returns the osfmk identifier for the currently running thread.

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


© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)