[apple/xnu.git] / iokit / IOKit / IOCatalogue.h

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
/*
 * Copyright (c) 1998 Apple Computer, Inc.  All rights reserved. 
 *
 * HISTORY
 *
 */


#ifndef _IOKIT_IOCATALOGUE_H
#define _IOKIT_IOCATALOGUE_H

#include <libkern/c++/OSObject.h>
#include <libkern/c++/OSCollectionIterator.h>
#include <libkern/c++/OSArray.h>
#include <libkern/c++/OSDictionary.h>
#include <IOKit/IOLocks.h>
#include <sys/cdefs.h>

#include <IOKit/IOKitServer.h>

class IOService;

/*!
    @class IOCatalogue
    @abstract In-kernel database for IOKit driver personalities.
    @discussion The IOCatalogue is a database which contains all IOKit driver personalities.  IOService uses this resource when matching devices to their associated drivers.
*/
class IOCatalogue : public OSObject
{
    OSDeclareDefaultStructors(IOCatalogue)
    
private:
    OSCollectionIterator   * kernelTables;
    OSArray                * array;
    IOLock *                 lock;
    SInt32                   generation;

    IOLock *                 kld_lock;

public:
    /*!
        @function initialize
        @abstract Creates and initializes the database object and poputates it with in-kernel driver personalities.
    */
    static void initialize( void );
    
    /*!
        @function init
        @abstract Initializes the database object.
        @param initArray  The initial array of driver personalities to populate the database.
    */
    bool init( OSArray * initArray );
    
    /*!
        @function free
        @abstract Cleans up the database and deallocates memory allocated at initialization.  This is never called in normal operation of the system.
    */
    void free( void );
    
    /*!
        @function findDrivers
        @abstract This is the primary entry point for IOService.
        @param service
        @param 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.
        @result Returns an ordered set of driver personalities ranked on probe-scores.  The ordered set must be released by the receiver.
    */
    OSOrderedSet * findDrivers( IOService * service, SInt32 * generationCount );
    
    /*!
        @function findDrivers
        @abstract 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.
        @param 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.
        @param 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.
        @result Returns an ordered set of driver personalities ranked on probe-scores. The ordered set must be released by the receiver.
    */
    OSOrderedSet * findDrivers( OSDictionary * matching, SInt32 * generationCount );
    
    /*!
        @function addDrivers
        @abstract Adds an array of driver personalities to the database.
        @param array Array of driver personalities to be added to the database.
        @param doNubMatchng Start matching process after personalities have been added.
        @result Returns true if driver personality was added to the database successfully. Failure is due to a memory allocation failure.
    */
    bool addDrivers( OSArray * array, bool doNubMatching = true );
    
    /*!
        @function removeDrivers
        @abstract Remove driver personalities from the database based on matching information provided.
        @param 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'.
        @param 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. 
        @result Returns true if personality was removed successfully. Failure is due to a memory allocation failure.
    */
    bool removeDrivers( OSDictionary * matching, bool doNubMatching = true );
    
    /*!
        @function getGenerationCount
        @abstract Get the current generation count of the database.
    */
    SInt32 getGenerationCount( void ) const;

    /*!
        @function isModuleLoaded
        @abstract Reports if a kernel module has been loaded.
        @param moduleName  Name of the module.
        @result Returns true if the associated kernel module has been loaded into the kernel.
    */
    bool isModuleLoaded( OSString * moduleName ) const;

    /*!
        @function isModuleLoaded
        @abstract Reports if a kernel module has been loaded.
        @param moduleName  Name of the module.
        @result Returns true if the associated kernel module has been loaded into the kernel.
    */
    bool isModuleLoaded( const char * moduleName ) const;
    
    /*!
        @function isModuleLoaded
        @abstract Reports if a kernel module has been loaded for a particular personality.
        @param driver  A driver personality's property list.
        @result Returns true if the associated kernel module has been loaded into the kernel for a particular driver personality on which it depends.
    */
    bool isModuleLoaded( OSDictionary * driver ) const;
    
    /*!
        @function moduleHasLoaded
        @abstract Callback function called after a IOKit dependent kernel module is loaded.
        @param name  Name of the kernel module.
    */
    void moduleHasLoaded( OSString * name );
    
    /*!
        @function moduleHasLoaded
        @abstract Callback function called after a IOKit dependent kernel module is loaded.
        @param name  Name of the kernel module.
    */
    void moduleHasLoaded( const char * name );

    /*!
        @function terminateDrivers
        @abstract Terminates all instances of a driver which match the contents of the matching dictionary. Does not unload module.
        @param 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'.
     */
    IOReturn terminateDrivers( OSDictionary * matching );

    /*!
        @function terminateDriversForModule
        @abstract Terminates all instances of a driver which depends on a particular module and unloads the module.
        @param moduleName Name of the module which is used to determine which driver instances to terminate and unload.
        @param unload Flag to cause the actual unloading of the module.
     */
    IOReturn terminateDriversForModule( OSString * moduleName, bool unload = true);

    /*!
        @function terminateDriversForModule
        @abstract Terminates all instances of a driver which depends on a particular module and unloads the module.
        @param moduleName Name of the module which is used to determine which driver instances to terminate and unload.
        @param unload Flag to cause the actual unloading of the module.
     */
    IOReturn terminateDriversForModule( const char * moduleName, bool unload = true);

    /*!
        @function startMatching
        @abstract Starts an IOService matching thread where matching keys and values are provided by the matching dictionary.
        @param 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'.
     */
    bool startMatching( OSDictionary * matching );

    /*!
        @function reset
        @abstract Return the Catalogue to its initial state.
    */
    void reset(void);

    /*!
        @function serialize
        @abstract Serializes the catalog for transport to the user.
        @param s The serializer object.
        @result Returns false if unable to serialize database, most likely due to memory shortage.
     */
    virtual bool serialize(OSSerialize * s) const;


    /*!
        @function recordStartupExtensions
        @abstract Records extensions made available by the primary booter.
            <p>
            This function is for internal use by the kernel startup linker.
            Kernel extensions should never call it.
        @result Returns true if startup extensions were successfully recorded,
            false if not.
    */
    virtual bool recordStartupExtensions(void);

    /*!
        @function addExtensionsFromArchive()
        @abstract Records an archive of extensions, as from device ROM.
            <p>
            This function is currently for internal use.
            Kernel extensions should never call it.
        @param mkext An OSData object containing a multikext archive.
        @result Returns true if mkext was properly unserialized and its
                contents recorded, false if not.
    */
    virtual bool addExtensionsFromArchive(OSData * mkext);


    /*!
        @function removeKernelLinker
        @abstract Removes from memory all code and data related to
            boot-time loading of kernel extensions. kextd triggers
            this when it first starts in order to pass responsibility
            for loading extensions from the kernel itself to kextd.
        @result Returns KERN_SUCCESS if the kernel linker is successfully
            removed or wasn't present, KERN_FAILURE otherwise.
    */
    virtual kern_return_t removeKernelLinker(void);

private:

    /*!
        @function unloadModule
        @abstract Unloads the reqested module if no driver instances are currently depending on it.
        @param moduleName An OSString containing the name of the module to unload.
     */
    IOReturn unloadModule( OSString * moduleName ) const;


};

__BEGIN_DECLS
/*!
    @function IOKitRelocStart
    @abstract Deprecated API.
*/
kmod_start_func_t IOKitRelocStart;
/*!
    @function IOKitRelocStop
    @abstract Deprecated API.
*/
kmod_stop_func_t IOKitRelocStop;
__END_DECLS

extern const OSSymbol *		gIOClassKey;
extern const OSSymbol *		gIOProbeScoreKey;
extern IOCatalogue *            gIOCatalogue;

#endif /* ! _IOKIT_IOCATALOGUE_H */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
de355530 A	6	* The contents of this file constitute Original Code as defined in and
	7	* are subject to the Apple Public Source License Version 1.1 (the
	8	* "License"). You may not use this file except in compliance with the
	9	* License. Please obtain a copy of the License at
	10	* http://www.apple.com/publicsource and read it before using this file.
1c79356b	11	*
de355530 A	12	* This Original Code and all software distributed under the License are
de355530 A	13	* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
1c79356b A	14	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1c79356b A	15	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
de355530 A	16	* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	17	* License for the specific language governing rights and limitations
	18	* under the License.
1c79356b A	19	*
	20	* @APPLE_LICENSE_HEADER_END@
	21	*/
	22	/*
	23	* Copyright (c) 1998 Apple Computer, Inc. All rights reserved.
	24	*
	25	* HISTORY
	26	*
	27	*/
	28
	29
	30	#ifndef _IOKIT_IOCATALOGUE_H
	31	#define _IOKIT_IOCATALOGUE_H
	32
	33	#include <libkern/c++/OSObject.h>
	34	#include <libkern/c++/OSCollectionIterator.h>
	35	#include <libkern/c++/OSArray.h>
	36	#include <libkern/c++/OSDictionary.h>
	37	#include <IOKit/IOLocks.h>
	38	#include <sys/cdefs.h>
	39
	40	#include <IOKit/IOKitServer.h>
	41
	42	class IOService;
	43
	44	/*!
	45	@class IOCatalogue
	46	@abstract In-kernel database for IOKit driver personalities.
	47	@discussion The IOCatalogue is a database which contains all IOKit driver personalities. IOService uses this resource when matching devices to their associated drivers.
	48	*/
	49	class IOCatalogue : public OSObject
	50	{
	51	OSDeclareDefaultStructors(IOCatalogue)
	52
	53	private:
	54	OSCollectionIterator * kernelTables;
	55	OSArray * array;
	56	IOLock * lock;
	57	SInt32 generation;
	58
0b4e3aa0 A	59	IOLock * kld_lock;
0b4e3aa0 A	60
1c79356b A	61	public:
	62	/*!
	63	@function initialize
	64	@abstract Creates and initializes the database object and poputates it with in-kernel driver personalities.
	65	*/
	66	static void initialize( void );
	67
	68	/*!
	69	@function init
	70	@abstract Initializes the database object.
	71	@param initArray The initial array of driver personalities to populate the database.
	72	*/
	73	bool init( OSArray * initArray );
	74
	75	/*!
	76	@function free
	77	@abstract Cleans up the database and deallocates memory allocated at initialization. This is never called in normal operation of the system.
	78	*/
	79	void free( void );
	80
	81	/*!
	82	@function findDrivers
	83	@abstract This is the primary entry point for IOService.
	84	@param service
	85	@param 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.
	86	@result Returns an ordered set of driver personalities ranked on probe-scores. The ordered set must be released by the receiver.
	87	*/
	88	OSOrderedSet * findDrivers( IOService * service, SInt32 * generationCount );
	89
	90	/*!
	91	@function findDrivers
	92	@abstract 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.
	93	@param 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.
	94	@param 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.
	95	@result Returns an ordered set of driver personalities ranked on probe-scores. The ordered set must be released by the receiver.
	96	*/
	97	OSOrderedSet * findDrivers( OSDictionary * matching, SInt32 * generationCount );
	98
	99	/*!
	100	@function addDrivers
	101	@abstract Adds an array of driver personalities to the database.
	102	@param array Array of driver personalities to be added to the database.
	103	@param doNubMatchng Start matching process after personalities have been added.
	104	@result Returns true if driver personality was added to the database successfully. Failure is due to a memory allocation failure.
	105	*/
	106	bool addDrivers( OSArray * array, bool doNubMatching = true );
	107
	108	/*!
	109	@function removeDrivers
	110	@abstract Remove driver personalities from the database based on matching information provided.
	111	@param 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'.
	112	@param 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.
	113	@result Returns true if personality was removed successfully. Failure is due to a memory allocation failure.
	114	*/
	115	bool removeDrivers( OSDictionary * matching, bool doNubMatching = true );
	116
	117	/*!
	118	@function getGenerationCount
	119	@abstract Get the current generation count of the database.
	120	*/
	121	SInt32 getGenerationCount( void ) const;
	122
	123	/*!
	124	@function isModuleLoaded
125	@abstract Reports if a kernel module has been loaded.
126	@param moduleName Name of the module.
127	@result Returns true if the associated kernel module has been loaded into the kernel.
128	*/
129	bool isModuleLoaded( OSString * moduleName ) const;
130
131	/*!
132	@function isModuleLoaded
133	@abstract Reports if a kernel module has been loaded.
134	@param moduleName Name of the module.
135	@result Returns true if the associated kernel module has been loaded into the kernel.
136	*/
137	bool isModuleLoaded( const char * moduleName ) const;
138
139	/*!
140	@function isModuleLoaded
141	@abstract Reports if a kernel module has been loaded for a particular personality.
142	@param driver A driver personality's property list.
143	@result Returns true if the associated kernel module has been loaded into the kernel for a particular driver personality on which it depends.
144	*/
145	bool isModuleLoaded( OSDictionary * driver ) const;
146
147	/*!
148	@function moduleHasLoaded
149	@abstract Callback function called after a IOKit dependent kernel module is loaded.
150	@param name Name of the kernel module.
151	*/
152	void moduleHasLoaded( OSString * name );
153
154	/*!
155	@function moduleHasLoaded
156	@abstract Callback function called after a IOKit dependent kernel module is loaded.
157	@param name Name of the kernel module.
158	*/
159	void moduleHasLoaded( const char * name );
160
161	/*!
162	@function terminateDrivers
163	@abstract Terminates all instances of a driver which match the contents of the matching dictionary. Does not unload module.
9bccf70c	164	@param 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'.
1c79356b A	165	*/
	166	IOReturn terminateDrivers( OSDictionary * matching );
	167
	168	/*!
	169	@function terminateDriversForModule
	170	@abstract Terminates all instances of a driver which depends on a particular module and unloads the module.
	171	@param moduleName Name of the module which is used to determine which driver instances to terminate and unload.
	172	@param unload Flag to cause the actual unloading of the module.
	173	*/
	174	IOReturn terminateDriversForModule( OSString * moduleName, bool unload = true);
	175
	176	/*!
	177	@function terminateDriversForModule
	178	@abstract Terminates all instances of a driver which depends on a particular module and unloads the module.
	179	@param moduleName Name of the module which is used to determine which driver instances to terminate and unload.
	180	@param unload Flag to cause the actual unloading of the module.
	181	*/
	182	IOReturn terminateDriversForModule( const char * moduleName, bool unload = true);
	183
	184	/*!
	185	@function startMatching
	186	@abstract Starts an IOService matching thread where matching keys and values are provided by the matching dictionary.
9bccf70c	187	@param 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'.
1c79356b A	188	*/
	189	bool startMatching( OSDictionary * matching );
	190
	191	/*!
	192	@function reset
	193	@abstract Return the Catalogue to its initial state.
	194	*/
	195	void reset(void);
	196
	197	/*!
	198	@function serialize
	199	@abstract Serializes the catalog for transport to the user.
	200	@param s The serializer object.
	201	@result Returns false if unable to serialize database, most likely due to memory shortage.
	202	*/
	203	virtual bool serialize(OSSerialize * s) const;
	204
	205
	206	/*!
	207	@function recordStartupExtensions
	208	@abstract Records extensions made available by the primary booter.
	209	<p>
	210	This function is for internal use by the kernel startup linker.
	211	Kernel extensions should never call it.
	212	@result Returns true if startup extensions were successfully recorded,
	213	false if not.
	214	*/
	215	virtual bool recordStartupExtensions(void);
	216
	217	/*!
	218	@function addExtensionsFromArchive()
	219	@abstract Records an archive of extensions, as from device ROM.
	220	<p>
	221	This function is currently for internal use.
	222	Kernel extensions should never call it.
	223	@param mkext An OSData object containing a multikext archive.
	224	@result Returns true if mkext was properly unserialized and its
	225	contents recorded, false if not.
	226	*/
	227	virtual bool addExtensionsFromArchive(OSData * mkext);
	228
	229
	230	/*!
	231	@function removeKernelLinker
	232	@abstract Removes from memory all code and data related to
	233	boot-time loading of kernel extensions. kextd triggers
	234	this when it first starts in order to pass responsibility
	235	for loading extensions from the kernel itself to kextd.
	236	@result Returns KERN_SUCCESS if the kernel linker is successfully
	237	removed or wasn't present, KERN_FAILURE otherwise.
	238	*/
	239	virtual kern_return_t removeKernelLinker(void);
	240
	241	private:
	242
	243	/*!
	244	@function unloadModule
	245	@abstract Unloads the reqested module if no driver instances are currently depending on it.
	246	@param moduleName An OSString containing the name of the module to unload.
	247	*/
	248	IOReturn unloadModule( OSString * moduleName ) const;
	249
	250
	251	};
252
253	__BEGIN_DECLS
254	/*!
255	@function IOKitRelocStart
256	@abstract Deprecated API.
257	*/
258	kmod_start_func_t IOKitRelocStart;
259	/*!
260	@function IOKitRelocStop
261	@abstract Deprecated API.
262	*/
263	kmod_stop_func_t IOKitRelocStop;
264	__END_DECLS
265
266	extern const OSSymbol * gIOClassKey;
267	extern const OSSymbol * gIOProbeScoreKey;
268	extern IOCatalogue * gIOCatalogue;
269
270	#endif /* ! _IOKIT_IOCATALOGUE_H */