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 __IOFIREWIREROMCACHE_H__ 24#define __IOFIREWIREROMCACHE_H__ 25 26#include <libkern/c++/OSObject.h> 27#include <IOKit/system.h> 28 29#include <libkern/c++/OSData.h> 30#include <IOKit/IOLocks.h> 31 32class IOFireWireDevice; 33 34/*! 35 @class IOFireWireROMCache 36 @abstract A class to hold a cache of a device's config ROM. 37*/ 38 39class IOFireWireROMCache : public OSObject 40{ 41 OSDeclareDefaultStructors(IOFireWireROMCache) 42 43public: 44 45 enum ROMState 46 { 47 kROMStateSuspended, 48 kROMStateResumed, 49 kROMStateInvalid 50 }; 51 52protected: 53 54 IOFireWireDevice * fOwner; 55 IORecursiveLock * fLock; 56 57 OSData * fROM; 58 ROMState fState; 59 UInt32 fGeneration; 60 61 struct ExpansionData { }; 62 63 /*! @var reserved 64 Reserved for future use. (Internal use only) 65 */ 66 67 ExpansionData *reserved; 68 69public: 70 71 /*! 72 @function initWithOwnerAndBytes 73 @abstract A member function to initialize an instance of IOFireWireROMCache which references a block of data. 74 @param owner A reference to the owner of this ROM 75 @param bytes A reference to a block of data 76 @param inLength The length of the block of data. 77 @param generation The bus generation 78 @result Returns true if initialization was successful, false otherwise. 79 */ 80 81 virtual bool initWithOwnerAndBytes( IOFireWireDevice * owner, const void *bytes, unsigned int inLength, UInt32 generation ); 82 83 84 /*! 85 @function withOwnerAndBytes 86 @abstract A static constructor function to create and initialize an instance of IOFireWireROMCache and copies in the provided data. 87 @param owner A reference to the owner of this ROM 88 @param bytes A buffer of data. 89 @param inLength The size of the given buffer. 90 @param generation The bus generation 91 @result Returns an instance of IOFireWireROMCache or 0 if a failure occurs. 92 */ 93 94 static IOFireWireROMCache *withOwnerAndBytes( IOFireWireDevice * owner, const void *bytes, unsigned int inLength, UInt32 generation ); 95 96 /*! 97 @function free 98 @abstract A member function which releases all resources created or used by the IOFireWireROMCache object. 99 @discussion Do not call this function directly, use release() instead. 100 */ 101 102 virtual void free(); 103 104 /*! 105 @function getLength 106 @abstract A member function which returns the length of the internal data buffer. 107 @result Returns an integer value for the length of data in the object's internal data buffer. 108 */ 109 110 virtual unsigned int getLength(); 111 112 /*! 113 @function ensureCapacity 114 @abstract A member function which will expand the size of the collection to a given storage capacity. 115 @param newCapacity The new capacity for the data buffer. 116 @result Returns the new capacity of the data buffer or the previous capacity upon error. 117 */ 118 119 virtual unsigned int ensureCapacity(unsigned int newCapacity); 120 121 /*! 122 @function appendBytes 123 @abstract A member function which appends a buffer of data onto the end of the object's internal data buffer. 124 @param bytes A pointer to the block of data. 125 @param inLength The length of the data block. 126 @result Returns true if the object was able to append the new data, false otherwise. 127 */ 128 129 virtual bool appendBytes(const void *bytes, unsigned int inLength); 130 131 /*! 132 @function appendBytes 133 @abstract A member function which appends the data contained in an IOFireWireROMCache object to the receiver. 134 @param other An IOFireWireROMCache object. 135 @result Returns true if appending the new data was successful, false otherwise. 136 */ 137 138 virtual bool appendBytes(const OSData *other); 139 140 /*! 141 @function getBytesNoCopy 142 @abstract A member function to return a pointer to the IOFireWireROMCache object's internal data buffer. 143 @result Returns a reference to the IOFireWireROMCache object's internal data buffer. 144 */ 145 146 virtual const void *getBytesNoCopy(); 147 148 /*! 149 @function getBytesNoCopy 150 @abstract Returns a reference into the IOFireWireROMCache object's internal data buffer at particular offset and with a particular length. 151 @param start The offset from the base of the internal data buffer. 152 @param inLength The length of window. 153 @result Returns a pointer at a particular offset into the data buffer, or 0 if the starting offset or length are not valid. 154 */ 155 156 virtual const void *getBytesNoCopy(unsigned int start, 157 unsigned int inLength); 158 159 virtual void lock( void ); 160 virtual void unlock( void ); 161 162 virtual IOReturn updateROMCache( UInt32 offset, UInt32 length ); 163 164 virtual bool hasROMChanged( const UInt32 * newBIB, UInt32 newBIBSize ); 165 166 virtual void setROMState( ROMState state, UInt32 generation = 0 ); 167 virtual IOReturn checkROMState( UInt32 &generation ); 168 virtual IOReturn checkROMState( void ); 169 170 virtual bool serialize( OSSerialize * s ) const; 171 172private: 173 OSMetaClassDeclareReservedUnused(IOFireWireROMCache, 0); 174 OSMetaClassDeclareReservedUnused(IOFireWireROMCache, 1); 175 OSMetaClassDeclareReservedUnused(IOFireWireROMCache, 2); 176 OSMetaClassDeclareReservedUnused(IOFireWireROMCache, 3); 177 OSMetaClassDeclareReservedUnused(IOFireWireROMCache, 4); 178 OSMetaClassDeclareReservedUnused(IOFireWireROMCache, 5); 179 OSMetaClassDeclareReservedUnused(IOFireWireROMCache, 6); 180 OSMetaClassDeclareReservedUnused(IOFireWireROMCache, 7); 181}; 182 183#endif