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 *
24 *	IOFireWireNub.h
25 *
26 *
27 * 	Note: IOFWCommand(s) are allocated by methods in this class.
28 *            The remaining methods to setup and submit IOFWCommands are defined in
29 *            IOFWCommand.h
30 */
31#ifndef _IOKIT_IOFIREWIRENUB_H
32#define _IOKIT_IOFIREWIRENUB_H
33
34// public
35#include <IOKit/IOService.h>
36#include <IOKit/firewire/IOFWCommand.h>
37#include <IOKit/firewire/IOFWAddressSpace.h>
38
39class IOFireWireController;
40class IOFireWireBus;
41class IOConfigDirectory;
42class IOFireWireNub;
43class IOFireWireDevice;
44class IOFireWireUnit;
45class IOFWSimplePhysicalAddressSpace;
46class IOFWSimpleContiguousPhysicalAddressSpace;
47
48enum TerminationState
49{
50	kNotTerminated = 0,
51	kNeedsTermination,
52	kTerminated
53};
54
55#pragma mark -
56
57/*!
58	@class IOFireWireNubAux
59*/
60
61class IOFireWireNubAux : public OSObject
62{
63    OSDeclareDefaultStructors(IOFireWireNubAux)
64
65	friend class IOFireWireNub;
66
67protected:
68
69	IOFireWireNub * 		fPrimary;
70	TerminationState		fTerminationState;
71
72	/*!
73		@struct ExpansionData
74		@discussion This structure will be used to expand the capablilties of the class in the future.
75    */
76
77    struct ExpansionData { };
78
79	/*!
80		@var reserved
81		Reserved for future use.  (Internal use only)
82	*/
83
84	ExpansionData * reserved;
85
86    virtual bool init( IOFireWireNub * primary );
87	virtual	void free();
88
89	virtual UInt32 hopCount( IOFireWireNub * nub );
90	virtual UInt32 hopCount( void );
91
92	virtual TerminationState getTerminationState( void );
93	virtual void setTerminationState( TerminationState state );
94
95	virtual bool isPhysicalAccessEnabled( void );
96
97	virtual IOFWSimpleContiguousPhysicalAddressSpace * createSimpleContiguousPhysicalAddressSpace( vm_size_t size, IODirection direction );
98
99    virtual IOFWSimplePhysicalAddressSpace * createSimplePhysicalAddressSpace( vm_size_t size, IODirection direction );
100
101private:
102    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 0);
103    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 1);
104    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 2);
105    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 3);
106    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 4);
107    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 5);
108    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 6);
109    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 7);
110    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 8);
111    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 9);
112    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 10);
113    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 11);
114    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 12);
115    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 13);
116    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 14);
117    OSMetaClassDeclareReservedUnused(IOFireWireNubAux, 15);
118
119};
120
121#pragma mark -
122
123/*! @class IOFireWireNub
124*/
125class IOFireWireNub : public IOService
126{
127    OSDeclareAbstractStructors(IOFireWireNub)
128
129    friend class IOFireWireController;
130    friend class IOFireWireNubAux;
131	friend class IOFireWireDeviceAux;
132	friend class IOFireWireUnitAux;
133	friend class IOFireWireDevice;
134	friend class IOFireWireUnit;
135
136/*------------------Useful info about device (also available in the registry)--------*/
137protected:
138    int			fDeviceSpeed;	// Max supported by device
139    int			fCommsSpeed;	// Max speed this node can communicate with device
140    UInt16		fNodeID;	// Current node ID (could change after bus reset!)
141    UInt16		fLocalNodeID;	// ID of the local node (could change after bus reset!)
142    UInt32		fGeneration;	// ID Of bus topology that fNodeID is valid for.
143    CSRNodeUniqueID	fUniqueID;	// Device's globally unique ID (never changes)
144    mach_timespec_t	fAsyncTimeout;	// Guesstimate of how long to wait for response
145					// from device when making async requests
146					// Different values for quad/block transfers?
147					// OS8 FW has 40/100 mSec.
148
149    int			fMaxReadPackLog;
150    int			fMaxWritePackLog;
151    int			fMaxReadROMPackLog;
152
153    IOFireWireController *fControl;
154    IOConfigDirectory	*fDirectory;
155
156    UInt32		fNodeFlags;
157
158	OSSet *	 fConfigDirectorySet;
159
160	IOFireWireNubAux * fAuxiliary;
161
162/*! @struct ExpansionData
163    @discussion This structure will be used to expand the capablilties of the class in the future.
164    */
165    struct ExpansionData { };
166
167/*! @var reserved
168    Reserved for future use.  (Internal use only)  */
169    ExpansionData *reserved;
170
171    virtual void free();
172
173/*------------------Methods provided to FireWire device clients-----------------------*/
174public:
175
176    // Get nodeID and bus generation info
177    IOReturn getNodeIDGeneration(UInt32 &generation, UInt16 &nodeID, UInt16 &localID) const;
178    IOReturn getNodeIDGeneration(UInt32 &generation, UInt16 &nodeID) const;
179
180    // How fast can this system talk to the node?
181    virtual IOFWSpeed FWSpeed() const;
182
183    // How fast can this node talk to another node?
184    virtual IOFWSpeed FWSpeed(const IOFireWireNub *dst) const;
185
186    // How big (as a power of two) can packets sent to/received from the node be?
187    virtual int maxPackLog(bool forSend) const;
188
189    // How big (as a power of two) can packets sent to/received from a specified address in the node be?
190    virtual int maxPackLog(bool forSend, FWAddress address) const;
191
192    // How big (as a power of two) can packets sent from this node to dst node/received from dst be?
193    virtual int maxPackLog(bool forSend, const IOFireWireNub *dst) const;
194
195    // Set maximum packet size nub can handle
196    virtual void setMaxPackLog(bool forSend, bool forROM, int maxPackLog);
197
198    /*
199     * Create various FireWire commands to send to the device
200     */
201    virtual IOFWReadCommand 	*createReadCommand(FWAddress devAddress, IOMemoryDescriptor *hostMem,
202				FWDeviceCallback completion=NULL, void *refcon=NULL,
203 				bool failOnReset=false);
204    virtual IOFWReadQuadCommand *createReadQuadCommand(FWAddress devAddress, UInt32 *quads, int numQuads,
205				FWDeviceCallback completion=NULL, void *refcon=NULL,
206 				bool failOnReset=false);
207
208    virtual IOFWWriteCommand 	*createWriteCommand(FWAddress devAddress, IOMemoryDescriptor *hostMem,
209				FWDeviceCallback completion=NULL, void *refcon=NULL,
210 				bool failOnReset=false);
211    virtual IOFWWriteQuadCommand *createWriteQuadCommand(FWAddress devAddress, UInt32 *quads, int numQuads,
212				FWDeviceCallback completion=NULL, void *refcon=NULL,
213 				bool failOnReset=false);
214
215    // size is 1 for 32 bit compare, 2 for 64 bit.
216    virtual IOFWCompareAndSwapCommand 	*createCompareAndSwapCommand(FWAddress devAddress,
217				const UInt32 *cmpVal, const UInt32 *newVal, int size,
218				FWDeviceCallback completion=NULL, void *refcon=NULL,
219 				bool failOnReset=false);
220    /*
221     * Create local FireWire address spaces for the device to access
222     */
223    virtual IOFWPhysicalAddressSpace *createPhysicalAddressSpace(IOMemoryDescriptor *mem);
224    virtual IOFWPseudoAddressSpace *createPseudoAddressSpace(FWAddress *addr, UInt32 len,
225                    FWReadCallback reader, FWWriteCallback writer, void *refcon);
226
227    /*
228     * Get Config directory for nub
229     * Device nub directory is root directory, Unit nub directory is Unit directory.
230	 *
231	 * Depricated use getConfigDirectoryRef
232     *
233	 */
234
235	virtual IOReturn getConfigDirectory(IOConfigDirectory *&dir);
236
237    /*
238     * Get bus for nub
239     */
240    IOFireWireBus * getBus() const;
241
242    IOFireWireController * getController() const;
243
244    const CSRNodeUniqueID &getUniqueID() const;
245
246    /*
247     * Standard nub initialization
248     */
249    virtual bool init(OSDictionary * propTable);
250
251    virtual void setNodeFlags( UInt32 flags );
252    virtual UInt32 getNodeFlags( void );
253	virtual void clearNodeFlags( UInt32 flags );
254
255	virtual IOReturn setConfigDirectory( IOConfigDirectory *directory );
256
257    virtual IOReturn getConfigDirectoryRef( IOConfigDirectory *&dir );
258
259	inline UInt32 hopCount( IOFireWireNub * nub )
260		{ return fAuxiliary->hopCount( nub ); }
261
262	inline UInt32 hopCount( void )
263		{ return fAuxiliary->hopCount(); }
264
265	inline TerminationState getTerminationState( void )
266		{ return fAuxiliary->getTerminationState(); }
267
268protected:
269	inline void setTerminationState( TerminationState state )
270		{ fAuxiliary->setTerminationState( state ); }
271
272	virtual IOFireWireNubAux * createAuxiliary( void );
273
274public:
275
276	inline bool isPhysicalAccessEnabled( void )
277		{ return fAuxiliary->isPhysicalAccessEnabled(); }
278
279	inline IOFWSimpleContiguousPhysicalAddressSpace * createSimpleContiguousPhysicalAddressSpace( vm_size_t size, IODirection direction )
280		{ return fAuxiliary->createSimpleContiguousPhysicalAddressSpace( size, direction ); }
281
282    inline IOFWSimplePhysicalAddressSpace * createSimplePhysicalAddressSpace( vm_size_t size, IODirection direction )
283		{ return fAuxiliary->createSimplePhysicalAddressSpace( size, direction ); }
284
285private:
286    OSMetaClassDeclareReservedUsed(IOFireWireNub, 0);
287	OSMetaClassDeclareReservedUsed(IOFireWireNub, 1);
288    OSMetaClassDeclareReservedUnused(IOFireWireNub, 2);
289    OSMetaClassDeclareReservedUnused(IOFireWireNub, 3);
290
291};
292
293#endif /* ! _IOKIT_IOFIREWIRENUB_H */
294