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