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