1/*
2 * Copyright (c) 1998-2002 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#ifndef __IOCONFIGDIRECTORY_H__
24#define __IOCONFIGDIRECTORY_H__
25
26#include <libkern/c++/OSObject.h>
27#include <IOKit/IOReturn.h>
28
29#include <IOKit/firewire/IOFireWireFamilyCommon.h>
30
31class OSData;
32class OSString;
33class OSIterator;
34class IOFireWireDevice;
35
36/*! @class IOConfigDirectory
37*/
38class IOConfigDirectory : public OSObject
39{
40    OSDeclareAbstractStructors(IOConfigDirectory);
41
42protected:
43    int fStart;			// Offset into ROM of start of this dir
44    int fType;			// Directory type
45    int fNumEntries;		// In directory
46
47/*! @struct ExpansionData
48    @discussion This structure will be used to expand the capablilties of the class in the future.
49    */
50    struct ExpansionData { };
51
52/*! @var reserved
53    Reserved for future use.  (Internal use only)  */
54    ExpansionData *reserved;
55
56    virtual bool initWithOffset(int start, int type);
57
58    virtual const UInt32 *getBase() = 0;
59    virtual IOReturn createIterator(UInt32 testVal, UInt32 testMask,
60                                    OSIterator *&iterator);
61    virtual IOConfigDirectory *getSubDir(int start, int type) = 0;
62
63public:
64    /*!
65        @function update
66        makes sure that the ROM has at least the specified capacity,
67        and that the ROM is uptodate from its start to at least the
68        specified quadlet offset.
69        @result kIOReturnSuccess if the specified offset is now
70        accessable at romBase[offset].
71    */
72    virtual IOReturn update(UInt32 offset, const UInt32 *&romBase) = 0;
73
74    /*!
75        @function getKeyType
76        Gets the data type for the specified key
77        @param type on return, set to the data type
78        @result kIOReturnSuccess if the key exists in the dictionary
79    */
80    virtual IOReturn getKeyType(int key, IOConfigKeyType &type);
81    /*!
82        @function getKeyValue
83        Gets the value for the specified key, in a variety of forms.
84        @param value on return, set to the data type
85        @param text if non-zero, on return points to the
86        string description of the field, or NULL if no text found.
87        @result kIOReturnSuccess if the key exists in the dictionary
88        and is of a type appropriate for the value parameter
89        @param value reference to variable to store the entry's value
90    */
91    virtual IOReturn getKeyValue(int key, UInt32 &value, OSString** text = NULL);
92    virtual IOReturn getKeyValue(int key, OSData *&value,
93                                 OSString** text = NULL);
94    virtual IOReturn getKeyValue(int key, IOConfigDirectory *&value,
95                                 OSString** text = NULL);
96    virtual IOReturn getKeyOffset(int key, FWAddress &value,
97                                  OSString** text = NULL);
98
99
100    /*!
101        @function getIndexType
102        Gets the data type for entry at the specified index
103        @param type on return, set to the data type
104        @result kIOReturnSuccess if the index exists in the dictionary
105    */
106    virtual IOReturn getIndexType(int index, IOConfigKeyType &type);
107    /*!
108        @function getIndexKey
109        Gets the key for entry at the specified index
110        @param key on return, set to the key
111        @result kIOReturnSuccess if the index exists in the dictionary
112    */
113    virtual IOReturn getIndexKey(int index, int &key);
114
115    /*!
116        @function getIndexValue
117        Gets the value at the specified index of the directory,
118        in a variety of forms.
119        @param type on return, set to the data type
120        @result kIOReturnSuccess if the index exists in the dictionary
121        and is of a type appropriate for the value parameter
122        @param value reference to variable to store the entry's value
123    */
124    virtual IOReturn getIndexValue(int index, UInt32 &value);
125    virtual IOReturn getIndexValue(int index, OSData *&value);
126    virtual IOReturn getIndexValue(int index, OSString *&value);
127    virtual IOReturn getIndexValue(int index, IOConfigDirectory *&value);
128    virtual IOReturn getIndexOffset(int index, FWAddress &value);
129    virtual IOReturn getIndexOffset(int index, UInt32 &value);
130
131    /*!
132        @function getIndexEntry
133        Gets the entry at the specified index of the directory,
134        as a raw UInt32.
135        @param entry on return, set to the entry value
136        @result kIOReturnSuccess if the index exists in the dictionary
137        @param value reference to variable to store the entry's value
138    */
139    virtual IOReturn getIndexEntry(int index, UInt32 &value);
140
141    /*!
142        @function getSubdirectories
143        Creates an iterator over the subdirectories of the directory.
144        @param iterator on return, set to point to an OSIterator
145        @result kIOReturnSuccess if the iterator could be created
146    */
147    virtual IOReturn getSubdirectories(OSIterator *&iterator);
148
149    /*!
150        @function getKeySubdirectories
151        Creates an iterator over subdirectories of a given type of the directory.
152        @param key type of subdirectory to iterate over
153        @param iterator on return, set to point to an OSIterator
154        @result kIOReturnSuccess if the iterator could be created
155    */
156    virtual IOReturn getKeySubdirectories(int key, OSIterator *&iterator);
157
158    int getType() const;
159
160    int getNumEntries() const;
161
162protected:
163
164	virtual const UInt32 * lockData( void ) = 0;
165	virtual void unlockData( void ) = 0;
166	virtual IOReturn updateROMCache( UInt32 offset, UInt32 length ) = 0;
167	virtual IOReturn checkROMState( void ) = 0;
168
169private:
170    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 0);
171    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 1);
172    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 2);
173    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 3);
174    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 4);
175    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 5);
176    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 6);
177    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 7);
178    OSMetaClassDeclareReservedUnused(IOConfigDirectory, 8);
179
180};
181
182#endif /* __IOCONFIGDIRECTORY_H__ */
183