xnu-3789.1.32.tar.gz

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

diff --git a/iokit/IOKit/IORegistryEntry.h b/iokit/IOKit/IORegistryEntry.h
index 315945052671c5d9531b1733fdb6220a29a83b0f..97f66e612fae0c7932cac359061744152cc02421 100644 (file)
--- a/iokit/IOKit/IORegistryEntry.h
+++ b/iokit/IOKit/IORegistryEntry.h
@@ -1,23 +1,29 @@
 /*
 /*

- * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 1998-2016 Apple Inc. All rights reserved.

  *
  *

- * @APPLE_LICENSE_HEADER_START@
+ * @APPLE_OSREFERENCE_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 file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. The rights granted to you under the License
+ * may not be used to create, or enable the creation or redistribution of,
+ * unlawful or unlicensed copies of an Apple operating system, or to
+ * circumvent, violate, or enable the circumvention or violation of, any
+ * terms of an Apple operating system software license agreement.

  * 
  * 

- * This Original Code and all software distributed under the License are
- * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this file.
+ * 
+ * The 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,
  * 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.
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.

  * 
  * 

- * @APPLE_LICENSE_HEADER_END@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@

  */
 /*
  * Copyright (c) 1998 Apple Computer, Inc.  All rights reserved. 
  */
 /*
  * Copyright (c) 1998 Apple Computer, Inc.  All rights reserved. 


@@ -36,6 +42,8 @@
 
 extern const OSSymbol * gIONameKey;
 extern const OSSymbol * gIOLocationKey;
 
 extern const OSSymbol * gIONameKey;
 extern const OSSymbol * gIOLocationKey;

+extern const OSSymbol * gIORegistryEntryIDKey;
+extern const OSSymbol * gIORegistryEntryPropertyKeysKey;

 
 class IORegistryEntry;
 class IORegistryPlane;
 
 class IORegistryEntry;
 class IORegistryPlane;


@@ -45,8 +53,8 @@ typedef void (*IORegistryEntryApplierFunction)(IORegistryEntry * entry,
                                                void * context);
 
 enum {
                                                void * context);
 
 enum {

-    kIORegistryIterateRecursively      = 0x00000001,
-    kIORegistryIterateParents          = 0x00000002
+    kIORegistryIterateRecursively   = 0x00000001,
+    kIORegistryIterateParents       = 0x00000002,

 };
 
 /*! @class IORegistryEntry : public OSObject
 };
 
 /*! @class IORegistryEntry : public OSObject


@@ -64,7 +72,7 @@ protected:
 /*! @struct ExpansionData
     @discussion This structure will be used to expand the capablilties of this class in the future.
     */    
 /*! @struct ExpansionData
     @discussion This structure will be used to expand the capablilties of this class in the future.
     */    

-    struct ExpansionData { };
+    struct ExpansionData;

 
 /*! @var reserved
     Reserved for future use.  (Internal use only)  */
 
 /*! @var reserved
     Reserved for future use.  (Internal use only)  */


@@ -91,6 +99,7 @@ public:
                                      IOOptionBits            options =
                                         kIORegistryIterateRecursively |
                                         kIORegistryIterateParents) const;
                                      IOOptionBits            options =
                                         kIORegistryIterateRecursively |
                                         kIORegistryIterateParents) const;

+

 /*! @function copyProperty
     @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. Available in Mac OS X 10.1 or later.
     @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s).
 /*! @function copyProperty
     @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. Available in Mac OS X 10.1 or later.
     @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s).


@@ -135,15 +144,55 @@ public:
 
     virtual IORegistryEntry * copyChildEntry( const IORegistryPlane * plane ) const;
 
 
     virtual IORegistryEntry * copyChildEntry( const IORegistryPlane * plane ) const;
 

-private:
+    /* method available in Mac OS X 10.4 or later */
+/*!
+    @typedef Action
+    @discussion Type and arguments of callout C function that is used when
+a runCommand is executed by a client.  Cast to this type when you want a C++
+member function to be used.  Note the arg1 - arg3 parameters are passed straight pass through to the action callout.
+    @param target
+       Target of the function, can be used as a refcon.  Note if a C++ function
+was specified, this parameter is implicitly the first parameter in the target
+member function's parameter list.
+    @param arg0 Argument to action from run operation.
+    @param arg1 Argument to action from run operation.
+    @param arg2 Argument to action from run operation.
+    @param arg3 Argument to action from run operation.
+*/
+    typedef IOReturn (*Action)(OSObject *target,
+                              void *arg0, void *arg1,
+                              void *arg2, void *arg3);
+
+/*! @function runPropertyAction
+    @abstract Single thread a call to an action w.r.t. the property lock
+    @discussion Client function that causes the given action to be called in a manner that syncrhonises with the registry iterators and serialisers.  This functin can be used to synchronously manipulate the property table of this nub
+    @param action Pointer to function to be executed in work-loop context.
+    @param arg0 Parameter for action parameter, defaults to 0.
+    @param arg1 Parameter for action parameter, defaults to 0.
+    @param arg2 Parameter for action parameter, defaults to 0.
+    @param arg3 Parameter for action parameter, defaults to 0.
+    @result Returns the value of the Action callout.
+*/
+    virtual IOReturn runPropertyAction(Action action, OSObject *target,
+                              void *arg0 = 0, void *arg1 = 0,
+                              void *arg2 = 0, void *arg3 = 0);

 
 

+private:
+#if __LP64__
+    OSMetaClassDeclareReservedUnused(IORegistryEntry, 0);
+    OSMetaClassDeclareReservedUnused(IORegistryEntry, 1);
+    OSMetaClassDeclareReservedUnused(IORegistryEntry, 2);
+    OSMetaClassDeclareReservedUnused(IORegistryEntry, 3);
+    OSMetaClassDeclareReservedUnused(IORegistryEntry, 4);
+    OSMetaClassDeclareReservedUnused(IORegistryEntry, 5);
+#else

     OSMetaClassDeclareReservedUsed(IORegistryEntry, 0);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 1);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 2);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 3);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 4);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 0);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 1);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 2);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 3);
     OSMetaClassDeclareReservedUsed(IORegistryEntry, 4);

-
-    OSMetaClassDeclareReservedUnused(IORegistryEntry, 5);
+    OSMetaClassDeclareReservedUsed(IORegistryEntry, 5);
+#endif

     OSMetaClassDeclareReservedUnused(IORegistryEntry, 6);
     OSMetaClassDeclareReservedUnused(IORegistryEntry, 7);
     OSMetaClassDeclareReservedUnused(IORegistryEntry, 8);
     OSMetaClassDeclareReservedUnused(IORegistryEntry, 6);
     OSMetaClassDeclareReservedUnused(IORegistryEntry, 7);
     OSMetaClassDeclareReservedUnused(IORegistryEntry, 8);


@@ -201,7 +250,7 @@ public:
 /*! @function init
     @abstract Standard init method for all IORegistryEntry subclasses.
     @discussion A registry entry must be initialized with this method before it can be used. A property dictionary may passed and will be retained by this method for use as the registry entry's property table, or an empty one will be created.
 /*! @function init
     @abstract Standard init method for all IORegistryEntry subclasses.
     @discussion A registry entry must be initialized with this method before it can be used. A property dictionary may passed and will be retained by this method for use as the registry entry's property table, or an empty one will be created.

-    @param A dictionary that will become the registry entry's property table (retaining it), or zero which will cause an empty property table to be created.
+    @param dictionary A dictionary that will become the registry entry's property table (retaining it), or zero which will cause an empty property table to be created.

     @result true on success, or false on a resource failure. */
 
     virtual bool init( OSDictionary * dictionary = 0 );
     @result true on success, or false on a resource failure. */
 
     virtual bool init( OSDictionary * dictionary = 0 );


@@ -210,7 +259,7 @@ public:
     @abstract Standard free method for all IORegistryEntry subclasses.
     @discussion This method will release any resources of the entry, in particular its property table. Note that the registry entry must always be detached from the registry before free may be called, and subclasses (namely IOService) will have additional protocols for removing registry entries. free should never need be called directly. */
 
     @abstract Standard free method for all IORegistryEntry subclasses.
     @discussion This method will release any resources of the entry, in particular its property table. Note that the registry entry must always be detached from the registry before free may be called, and subclasses (namely IOService) will have additional protocols for removing registry entries. free should never need be called directly. */
 

-    virtual void free( void );
+    virtual void free( void ) APPLE_KEXT_OVERRIDE;

 
 /*! @function setPropertyTable
     @abstract Replace a registry entry's property table.
 
 /*! @function setPropertyTable
     @abstract Replace a registry entry's property table.


@@ -281,7 +330,7 @@ public:
 
 /*! @function setProperty
     @abstract Synchronized method to construct and add an OSData property to a registry entry's property table.
 
 /*! @function setProperty
     @abstract Synchronized method to construct and add an OSData property to a registry entry's property table.

-    @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSData copied from the supplied date and length, set in the property table with the given name, and released.
+    @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSData copied from the supplied data and length, set in the property table with the given name, and released.

     @param aKey The property's name as a C-string.
     @param bytes The property's value as a pointer. OSData will copy this data.
     @param length The property's size in bytes, for OSData.
     @param aKey The property's name as a C-string.
     @param bytes The property's value as a pointer. OSData will copy this data.
     @param length The property's size in bytes, for OSData.


@@ -467,6 +516,11 @@ public:
     virtual OSIterator * getChildIterator( const IORegistryPlane * plane )
                                                                        const;
 
     virtual OSIterator * getChildIterator( const IORegistryPlane * plane )
                                                                        const;
 

+#if XNU_KERNEL_PRIVATE
+    uint32_t getChildCount( const IORegistryPlane * plane ) const;
+    OSArray * copyPropertyKeys(void) const;
+#endif
+

     virtual void applyToChildren( IORegistryEntryApplierFunction applier,
                                   void * context,
                                   const IORegistryPlane * plane ) const;
     virtual void applyToChildren( IORegistryEntryApplierFunction applier,
                                   void * context,
                                   const IORegistryPlane * plane ) const;


@@ -505,11 +559,11 @@ public:
 
 /*! @function inPlane
     @abstract Determines whether a registry entry is attached in a plane.
 
 /*! @function inPlane
     @abstract Determines whether a registry entry is attached in a plane.

-    @discussion This method determines if the entry is attached in a plane to any other entry.
-    @param plane The plane object.
-    @result If the entry has a parent in the plane, true is returned, otherwise false is returned. */
+    @discussion This method determines if the entry is attached in a plane to any other entry.  It can also be used to determine if the entry is a member of any plane.
+    @param plane The plane object, 0 indicates any plane.
+    @result If the entry has a parent in the given plane or if plane = 0 then if entry has any parent; return true, otherwise false. */

 
 

-    virtual bool inPlane( const IORegistryPlane * plane ) const;
+    virtual bool inPlane( const IORegistryPlane * plane = 0) const;

 
 /*! @function getDepth
     @abstract Counts the maximum number of entries between an entry and the registry root, in a plane.
 
 /*! @function getDepth
     @abstract Counts the maximum number of entries between an entry and the registry root, in a plane.


@@ -553,7 +607,7 @@ public:
 /*! @function detachFromChild
     @abstract Detaches a child entry from its parent in a plane.
     @discussion This method is called in the parent entry when a child detaches, to make overrides possible. It is a no-op if the entry is not a child of the parent. Detaching the entry will release both the child and parent. This method will call detachFromParent in the child entry if it is not being called from detachFromParent.
 /*! @function detachFromChild
     @abstract Detaches a child entry from its parent in a plane.
     @discussion This method is called in the parent entry when a child detaches, to make overrides possible. It is a no-op if the entry is not a child of the parent. Detaching the entry will release both the child and parent. This method will call detachFromParent in the child entry if it is not being called from detachFromParent.

-    @param parent The registry entry to detach.
+    @param child The registry entry to detach.

     @param plane The plane object. */
 
     virtual void detachFromChild( IORegistryEntry * child,
     @param plane The plane object. */
 
     virtual void detachFromChild( IORegistryEntry * child,


@@ -718,16 +772,38 @@ public:
     static const char * dealiasPath( const char ** opath,
                                     const IORegistryPlane * plane );
 
     static const char * dealiasPath( const char ** opath,
                                     const IORegistryPlane * plane );
 

+/*! @function makePlane
+    @abstract Constructs an IORegistryPlane object.
+    @discussion Most planes in IOKit are created by the OS, although other planes may be created.
+    @param name A C-string name for the new plane, to be copied.
+    @result A new instance of an IORegistryPlane, or zero on failure. */
+
+    static const IORegistryPlane * makePlane( const char * name );
+
+/*!    @abstract Returns an ID for the registry entry that is global to all tasks.
+    @discussion The entry ID returned by getRegistryEntryID can be used to identify a registry entry across all tasks. A registry entry may be looked up by its entry ID by creating a matching dictionary with IORegistryEntryIDMatching() in user space, or <code>IOService::registryEntryIDMatching()</code> in the kernel, to be used with the IOKit matching functions. The ID is valid only until the machine reboots.
+    @result An ID for the registry entry, assigned when the entry is first attached in the registry. */
+
+    uint64_t getRegistryEntryID( void );
+

     /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
     /* * * * * * * * * * * * internals * * * * * * * * * * * */
     /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
     /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
     /* * * * * * * * * * * * internals * * * * * * * * * * * */
     /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 

-public:
-    static IORegistryEntry * initialize( void );
-    static const IORegistryPlane * makePlane( const char * name );
-    // don't even think about using this

     virtual bool init( IORegistryEntry * from,
                                const IORegistryPlane * inPlane );
     virtual bool init( IORegistryEntry * from,
                                const IORegistryPlane * inPlane );

+
+#ifdef XNU_KERNEL_PRIVATE
+public:
+#else
+private:
+#endif
+    static IORegistryEntry * initialize( void );
+
+#ifdef XNU_KERNEL_PRIVATE
+    SInt32 getRegistryEntryGenerationCount( void ) const;
+#endif
+

 private:
     inline bool arrayMember( OSArray * set,
                             const IORegistryEntry * member,
 private:
     inline bool arrayMember( OSArray * set,
                             const IORegistryEntry * member,


@@ -740,16 +816,24 @@ private:
                     unsigned int relation,
                     const IORegistryPlane * plane ) const;
 
                     unsigned int relation,
                     const IORegistryPlane * plane ) const;
 

-    virtual OSArray * getParentSetReference( const IORegistryPlane * plane )
+    APPLE_KEXT_COMPATIBILITY_VIRTUAL
+       OSArray * getParentSetReference( const IORegistryPlane * plane )

                                                                        const;
                                                                        const;

-    virtual OSArray * getChildSetReference( const IORegistryPlane * plane )
+
+    APPLE_KEXT_COMPATIBILITY_VIRTUAL
+    OSArray * getChildSetReference( const IORegistryPlane * plane )

                                                                        const;
                                                                        const;

-    virtual IORegistryEntry * getChildFromComponent( const char ** path,
+
+    APPLE_KEXT_COMPATIBILITY_VIRTUAL
+    IORegistryEntry * getChildFromComponent( const char ** path,

                                const IORegistryPlane * plane );
 
                                const IORegistryPlane * plane );
 

-    virtual const OSSymbol * hasAlias(  const IORegistryPlane * plane,
+    APPLE_KEXT_COMPATIBILITY_VIRTUAL
+    const OSSymbol * hasAlias(  const IORegistryPlane * plane,

                                     char * opath = 0, int * length = 0 ) const;
                                     char * opath = 0, int * length = 0 ) const;

-    virtual const char * matchPathLocation( const char * cmp,
+
+    APPLE_KEXT_COMPATIBILITY_VIRTUAL
+    const char * matchPathLocation( const char * cmp,

                                const IORegistryPlane * plane );
 
 };
                                const IORegistryPlane * plane );
 
 };


@@ -777,7 +861,7 @@ private:
     const IORegistryPlane *    plane;
     IOOptionBits               options;
 
     const IORegistryPlane *    plane;
     IOOptionBits               options;
 

-    virtual void free( void );
+    virtual void free( void ) APPLE_KEXT_OVERRIDE;

 
 public:
 /*! @function iterateOver
 
 public:
 /*! @function iterateOver


@@ -807,7 +891,7 @@ public:
     @discussion This method calls either getNextObjectFlat or getNextObjectRecursive depending on the options the iterator was created with. This implements the OSIterator defined getNextObject method. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it.
     @result The next registry entry in the iteration (the current entry), or zero if the iteration has finished at this level of recursion. The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */
 
     @discussion This method calls either getNextObjectFlat or getNextObjectRecursive depending on the options the iterator was created with. This implements the OSIterator defined getNextObject method. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it.
     @result The next registry entry in the iteration (the current entry), or zero if the iteration has finished at this level of recursion. The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */
 

-    virtual IORegistryEntry * getNextObject( void );
+    virtual IORegistryEntry * getNextObject( void ) APPLE_KEXT_OVERRIDE;

 
 /*! @function getNextObjectFlat
     @abstract Return the next object in the registry iteration, ignoring the kIORegistryIterateRecursively option.
 
 /*! @function getNextObjectFlat
     @abstract Return the next object in the registry iteration, ignoring the kIORegistryIterateRecursively option.


@@ -854,18 +938,18 @@ public:
     @abstract Exits all levels of recursion, restoring the iterator to its state at creation.
     @discussion This method exits all levels of recursion, and restores the iterator to its state at creation. */
 
     @abstract Exits all levels of recursion, restoring the iterator to its state at creation.
     @discussion This method exits all levels of recursion, and restores the iterator to its state at creation. */
 

-    virtual void reset( void );
+    virtual void reset( void ) APPLE_KEXT_OVERRIDE;

 
 /*! @function isValid
     @abstract Checks that no registry changes have invalidated the iteration.
     @discussion If a registry iteration is invalidated by changes to the registry, it will be made invalid, the currentEntry will be considered zero, and further calls to getNextObject et al. will return zero. The iterator should be reset to restart the iteration when this happens.
     @result false if the iterator has been invalidated by changes to the registry, true otherwise. */
 
 
 /*! @function isValid
     @abstract Checks that no registry changes have invalidated the iteration.
     @discussion If a registry iteration is invalidated by changes to the registry, it will be made invalid, the currentEntry will be considered zero, and further calls to getNextObject et al. will return zero. The iterator should be reset to restart the iteration when this happens.
     @result false if the iterator has been invalidated by changes to the registry, true otherwise. */
 

-    virtual bool isValid( void );
+    virtual bool isValid( void ) APPLE_KEXT_OVERRIDE;

 
 /*! @function iterateAll
     @abstract Iterates all entries (with getNextObject) and returns a set of all returned entries.
 
 /*! @function iterateAll
     @abstract Iterates all entries (with getNextObject) and returns a set of all returned entries.

-    @discussion This method will reset, then iterate all entries in the iteration (with getNextObject) until successful (ie. the iterator is valid at the end of the iteration).
+    @discussion This method will reset, then iterate all entries in the iteration (with getNextObject).

     @result A set of entries returned by the iteration. The caller should release the set when it has finished with it. Zero is returned on a resource failure. */
 
     virtual OSOrderedSet * iterateAll( void );
     @result A set of entries returned by the iteration. The caller should release the set when it has finished with it. Zero is returned on a resource failure. */
 
     virtual OSOrderedSet * iterateAll( void );