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 ffb9d684488b9db570d1768810d4893017b36a16..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,7 +99,6 @@ public:
                                      IOOptionBits            options =
                                         kIORegistryIterateRecursively |
                                         kIORegistryIterateParents) const;
                                      IOOptionBits            options =
                                         kIORegistryIterateRecursively |
                                         kIORegistryIterateParents) const;

-    OSMetaClassDeclareReservedUsed(IORegistryEntry, 0);

 
 /*! @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.
 
 /*! @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.


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

-    OSMetaClassDeclareReservedUsed(IORegistryEntry, 1);

 
 /*! @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.
 
 /*! @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.


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

-    OSMetaClassDeclareReservedUsed(IORegistryEntry, 2);

 
 /*! @function copyParentEntry
     @abstract Returns an registry entry's first parent entry in a plane. Available in Mac OS X 10.1 or later.
 
 /*! @function copyParentEntry
     @abstract Returns an registry entry's first parent entry in a plane. Available in Mac OS X 10.1 or later.


@@ -130,7 +135,6 @@ public:
     @result Returns the first parent of the registry entry, or zero if the entry is not attached into the registry in that plane. A reference on the entry is returned to caller, which should be released. */
 
     virtual IORegistryEntry * copyParentEntry( const IORegistryPlane * plane ) const;
     @result Returns the first parent of the registry entry, or zero if the entry is not attached into the registry in that plane. A reference on the entry is returned to caller, which should be released. */
 
     virtual IORegistryEntry * copyParentEntry( const IORegistryPlane * plane ) const;

-    OSMetaClassDeclareReservedUsed(IORegistryEntry, 3);

 
 /*! @function copyChildEntry
     @abstract Returns an registry entry's first child entry in a plane. Available in Mac OS X 10.1 or later.
 
 /*! @function copyChildEntry
     @abstract Returns an registry entry's first child entry in a plane. Available in Mac OS X 10.1 or later.


@@ -139,7 +143,6 @@ public:
     @result Returns the first child of the registry entry, or zero if the entry is not attached into the registry in that plane. A reference on the entry is returned to caller, which should be released. */
 
     virtual IORegistryEntry * copyChildEntry( const IORegistryPlane * plane ) const;
     @result Returns the first child of the registry entry, or zero if the entry is not attached into the registry in that plane. A reference on the entry is returned to caller, which should be released. */
 
     virtual IORegistryEntry * copyChildEntry( const IORegistryPlane * plane ) const;

-    OSMetaClassDeclareReservedUsed(IORegistryEntry, 4);

 
     /* method available in Mac OS X 10.4 or later */
 /*!
 
     /* method available in Mac OS X 10.4 or later */
 /*!


@@ -173,10 +176,23 @@ member function's parameter list.
     virtual IOReturn runPropertyAction(Action action, OSObject *target,
                               void *arg0 = 0, void *arg1 = 0,
                               void *arg2 = 0, void *arg3 = 0);
     virtual IOReturn runPropertyAction(Action action, OSObject *target,
                               void *arg0 = 0, void *arg1 = 0,
                               void *arg2 = 0, void *arg3 = 0);

-    OSMetaClassDeclareReservedUsed(IORegistryEntry, 5);

 
 private:
 
 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, 5);
+#endif

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


@@ -234,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 );


@@ -243,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.


@@ -314,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.


@@ -500,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;


@@ -586,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,


@@ -751,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,


@@ -773,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 );
 
 };


@@ -810,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


@@ -840,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.


@@ -887,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 );