Mac Developer Library

Developer

IOCatalogue Class Reference

Options
Deployment Target:

On This Page
Language:

IOCatalogue

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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 through OS X v10.5.
  • Adds an array of driver personalities to the database.

    Declaration

    C++

    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.

  • This is the primary entry point for IOService.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    void free( void );

  • Get the current generation count of the database.

    Declaration

    C++

    SInt32 getGenerationCount( void ) const;

  • Initializes the database object.

    Declaration

    C++

    bool init( OSArray *initArray );

    Parameters

    initArray

    The initial array of driver personalities to populate the database.

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

    Declaration

    C++

    static void initialize( void );

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

    Declaration

    C++

    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.

  • Reports if a kernel module has been loaded.

    Declaration

    C++

    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.

  • Reports if a kernel module has been loaded.

    Declaration

    C++

    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.

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

    Declaration

    C++

    void moduleHasLoaded( const char *name );

    Parameters

    name

    Name of the kernel module.

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

    Declaration

    C++

    void moduleHasLoaded( OSString *name );

    Parameters

    name

    Name of the kernel module.

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

    Declaration

    C++

    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.

  • Return the Catalogue to its initial state.

    Declaration

    C++

    void reset( void);

    Discussion

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

  • Replace personalities in IOCatalog with those provided.

    Declaration

    C++

    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.

  • Serializes the catalog for transport to the user.

    Declaration

    C++

    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.

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

    Declaration

    C++

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

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

    Declaration

    C++

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

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    IOReturn unloadModule( OSString *moduleName ) const;

    Parameters

    moduleName

    An OSString containing the name of the module to unload.