iokit/IOKit/IOCatalogue.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   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.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  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.
  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
  59     IOLock *                 kld_lock;
  60
  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.
 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'.
 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.
 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'.
 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     bool serializeData(IOOptionBits kind, OSSerialize * s) const;
 206
 207     /*!
 208         @function recordStartupExtensions
 209         @abstract Records extensions made available by the primary booter.
 210             <p>
 211             This function is for internal use by the kernel startup linker.
 212             Kernel extensions should never call it.
 213         @result Returns true if startup extensions were successfully recorded,
 214             false if not.
 215     */
 216     virtual bool recordStartupExtensions(void);
 217
 218     /*!
 219         @function addExtensionsFromArchive()
 220         @abstract Records an archive of extensions, as from device ROM.
 221             <p>
 222             This function is currently for internal use.
 223             Kernel extensions should never call it.
 224         @param mkext An OSData object containing a multikext archive.
 225         @result Returns true if mkext was properly unserialized and its
 226                 contents recorded, false if not.
 227     */
 228     virtual bool addExtensionsFromArchive(OSData * mkext);
 229
 230
 231     /*!
 232         @function removeKernelLinker
 233         @abstract Removes from memory all code and data related to
 234             boot-time loading of kernel extensions. kextd triggers
 235             this when it first starts in order to pass responsibility
 236             for loading extensions from the kernel itself to kextd.
 237         @result Returns KERN_SUCCESS if the kernel linker is successfully
 238             removed or wasn't present, KERN_FAILURE otherwise.
 239     */
 240     virtual kern_return_t removeKernelLinker(void);
 241
 242     static void disableExternalLinker(void);
 243
 244 private:
 245
 246     /*!
 247         @function unloadModule
 248         @abstract Unloads the reqested module if no driver instances are currently depending on it.
 249         @param moduleName An OSString containing the name of the module to unload.
 250      */
 251     IOReturn unloadModule( OSString * moduleName ) const;
 252 };
 253
 254 __BEGIN_DECLS
 255 /*!
 256     @function IOKitRelocStart
 257     @abstract Deprecated API.
 258 */
 259 kmod_start_func_t IOKitRelocStart;
 260 /*!
 261     @function IOKitRelocStop
 262     @abstract Deprecated API.
 263 */
 264 kmod_stop_func_t IOKitRelocStop;
 265 __END_DECLS
 266
 267 extern const OSSymbol *         gIOClassKey;
 268 extern const OSSymbol *         gIOProbeScoreKey;
 269 extern IOCatalogue *            gIOCatalogue;
 270
 271 #endif /* ! _IOKIT_IOCATALOGUE_H */