iokit/IOKit/IOCatalogue.h

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