IOCatalogue

Inherits from
OSObject
Availability
Available in OS X v10.0 through OS X v10.5.
Declared in
IOCatalogue.h

Overview

In-kernel database for IOKit driver personalities.

The IOCatalogue is a database which contains all IOKit driver personalities. IOService uses this resource when matching devices to their associated drivers.

Tasks

Miscellaneous

Instance Methods

addDrivers

Adds an array of driver personalities to the database.

bool addDrivers( OSArray *array, bool doNubMatching = true );
Parameters
array

Array of driver personalities to be added to the database.

doNubMatchng

Start matching process after personalities have been added.

Return Value

Returns true if driver personality was added to the database successfully. Failure is due to a memory allocation failure.

findDrivers(IOService *, SInt32 *)

This is the primary entry point for IOService.

OSOrderedSet * findDrivers( IOService *service, SInt32 *generationCount );
Parameters
service
generationCount

Returns a reference to the generation count of the database. The generation count increases only when personalities are added to the database *and* IOService matching has been initiated.

Return Value

Returns an ordered set of driver personalities ranked on probe-scores. The ordered set must be released by the receiver.

findDrivers(OSDictionary *, SInt32 *)

A more general purpose interface which allows one to retreive driver personalities based the intersection of the 'matching' dictionary and the personality's own property list.

OSOrderedSet * findDrivers( OSDictionary *matching, SInt32 *generationCount );
Parameters
matching

A dictionary containing only keys and values which are to be used for matching. For example, a matching dictionary containing 'IOProviderClass'='IOPCIDevice' will return all personalities with an IOProviderClass key and a value of IOPCIDevice.

generationCount

Returns a reference to the current generation of the database. The generation count increases only when personalities are added to the database *and* IOService matching has been initiated.

Return Value

Returns an ordered set of driver personalities ranked on probe-scores. The ordered set must be released by the receiver.

free

Cleans up the database and deallocates memory allocated at initialization. This is never called in normal operation of the system.

void free( void );

getGenerationCount

Get the current generation count of the database.

SInt32 getGenerationCount( void ) const;

init

Initializes the database object.

bool init( OSArray *initArray );
Parameters
initArray

The initial array of driver personalities to populate the database.

initialize

Creates and initializes the database object and poputates it with in-kernel driver personalities.

static void initialize( void );

isModuleLoaded

Reports if a kernel module has been loaded for a particular personality.

bool isModuleLoaded( OSDictionary *driver ) const;
Parameters
driver

A driver personality's property list.

Return Value

Returns true if the associated kernel module has been loaded into the kernel for a particular driver personality on which it depends.

isModuleLoaded(const char *)

Reports if a kernel module has been loaded.

bool isModuleLoaded( const char *moduleName ) const;
Parameters
moduleName

Name of the module.

Return Value

Returns true if the associated kernel module has been loaded into the kernel.

isModuleLoaded(OSString *)

Reports if a kernel module has been loaded.

bool isModuleLoaded( OSString *moduleName ) const;
Parameters
moduleName

Name of the module.

Return Value

Returns true if the associated kernel module has been loaded into the kernel.

moduleHasLoaded(const char *)

Callback function called after a IOKit dependent kernel module is loaded.

void moduleHasLoaded( const char *name );
Parameters
name

Name of the kernel module.

moduleHasLoaded(OSString *)

Callback function called after a IOKit dependent kernel module is loaded.

void moduleHasLoaded( OSString *name );
Parameters
name

Name of the kernel module.

removeDrivers

Remove driver personalities from the database based on matching information provided.

bool removeDrivers( OSDictionary *matching, bool doNubMatching = true );
Parameters
matching

A dictionary whose keys and values are used for matching personalities in the database. For example, a matching dictionary containing a 'IOProviderClass' key with the value 'IOPCIDevice' will remove all personalities which have the key 'IOProviderClass' equal to 'IOPCIDevice'.

doNubMatchng

Start matching process after personalities have been removed. Matching criteria is based on IOProviderClass of those personalities which were removed. This is to allow drivers which haven't been matched to match against NUB's which were blocked by the previous personalities.

Return Value

Returns true if personality was removed successfully. Failure is due to a memory allocation failure.

reset

Return the Catalogue to its initial state.

void reset( void);
Discussion

Should only be used by kextd just before it sends all kext personalities down during a rescan.

resetAndAddDrivers

Replace personalities in IOCatalog with those provided.

bool resetAndAddDrivers( OSArray *drivers, bool doNubMatching = true);
Discussion

Resets the catalogue with a new set of drivers, preserving matching originals to keep wired memory usage down.

serialize

Serializes the catalog for transport to the user.

virtual bool serialize( OSSerialize *s) const;
Parameters
s

The serializer object.

Return Value

Returns false if unable to serialize database, most likely due to memory shortage.

startMatching

Starts an IOService matching thread where matching keys and values are provided by the matching dictionary.

bool startMatching( OSDictionary *matching );
Parameters
matching

A dictionary whose keys and values are used for matching personalities in the database. For example, a matching dictionary containing a 'IOProviderClass' key with the value 'IOPCIDevice' will start matching for all personalities which have the key 'IOProviderClass' equal to 'IOPCIDevice'.

terminateDrivers

Terminates all instances of a driver which match the contents of the matching dictionary. Does not unload module.

IOReturn terminateDrivers( OSDictionary *matching );
Parameters
matching

A dictionary whose keys and values are used for matching personalities in the database. For example, a matching dictionary containing a 'IOProviderClass' key with the value 'IOPCIDevice' will cause termination for all instances whose personalities have the key 'IOProviderClass' equal to 'IOPCIDevice'.

terminateDriversForModule(const char *, bool)

Terminates all instances of a driver which depends on a particular module and unloads the module.

IOReturn terminateDriversForModule( const char *moduleName, bool unload = true);
Parameters
moduleName

Name of the module which is used to determine which driver instances to terminate and unload.

unload

Flag to cause the actual unloading of the module.

terminateDriversForModule(OSString *, bool)

Terminates all instances of a driver which depends on a particular module and unloads the module.

IOReturn terminateDriversForModule( OSString *moduleName, bool unload = true);
Parameters
moduleName

Name of the module which is used to determine which driver instances to terminate and unload.

unload

Flag to cause the actual unloading of the module.

unloadModule

Unloads the reqested module if no driver instances are currently depending on it.

IOReturn unloadModule( OSString *moduleName ) const;
Parameters
moduleName

An OSString containing the name of the module to unload.