1/*
2 * Copyright (c) 1998-2000 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  @header IOFireWireSBP2ManagementORB
25  Contains the class definition for IOFireWireSBP2ManagementORB.
26*/
27
28#ifndef _IOKIT_IOFIREWIRESBP2MANAGEMENTORB_H
29#define _IOKIT_IOFIREWIRESBP2MANAGEMENTORB_H
30
31#include <IOKit/firewire/IOFWCommand.h>
32#include <IOKit/firewire/IOFireWireUnit.h>
33
34#include <IOKit/IOUserClient.h>
35
36class IOFireWireSBP2LUN;
37class IOFireWireSBP2ManagementORB;
38class IOFireWireSBP2ORB;
39
40enum
41{
42    kFWSBP2QueryLogins			= 1,
43    kFWSBP2AbortTask			= 0xb,
44    kFWSBP2AbortTaskSet			= 0xc,
45    kFWSBP2LogicalUnitReset		= 0xe,
46    kFWSBP2TargetReset			= 0xf
47};
48
49// Callback when management command completes asynchronously
50
51/*!
52    @typedef FWSBP2ManagementCallback
53    @param refCon Reference constant supplied when the notification was registered.
54    @param status Indicates success or failure of operation.
55    @param orb Indicates current orb status is for.
56*/
57
58typedef void (*FWSBP2ManagementCallback)(void * refCon, IOReturn status, IOFireWireSBP2ManagementORB * orb);
59
60/*!
61    @class IOFireWireSBP2ManagementORB
62    @abstract Supplies non login related management ORBs.  Management ORBs can be executed independent
63    of a login, if necessary.  Management ORBs are created using the IOFireWireSBP2LUN interface.
64*/
65
66class IOFireWireSBP2ManagementORB : public IOFWCommand
67{
68    OSDeclareDefaultStructors( IOFireWireSBP2ManagementORB )
69
70	friend class IOFireWireSBP2LUN;
71	friend class IOFireWireSBP2UserClient;
72
73protected:
74
75	////////////////////////////////////////
76    // rom keys
77
78    enum
79    {
80        kUnitCharacteristicsKey 	= 0x3A,
81        kManagementAgentOffsetKey	= 0x54
82    };
83
84	////////////////////////////////////////
85	// structs
86
87    typedef struct
88    {
89        UInt32		orbOffsetHi;
90        UInt32		orbOffsetLo;
91        UInt32		reserved1[2];
92        UInt16		options;
93        UInt16		loginID;
94        UInt32		reserved2;
95        UInt32		statusFIFOAddressHi;
96        UInt32		statusFIFOAddressLo;
97    } FWSBP2TaskManagementORB;
98
99    typedef struct
100    {
101        UInt32		reserved1[2];
102        UInt32		queryResponseAddressHi;
103        UInt32		queryResponseAddressLo;
104        UInt16		options;
105        UInt16		lun;
106        UInt16		reserved2;
107        UInt16		queryResponseLength;
108        UInt32		statusFIFOAddressHi;
109        UInt32		statusFIFOAddressLo;
110    } FWSBP2QueryLoginsORB;
111
112    typedef struct
113    {
114        UInt8		details;
115        UInt8		sbpStatus;
116        UInt16		orbOffsetHi;
117        UInt32		orbOffsetLo;
118        UInt32		status[6];
119    } FWSBP2StatusBlock;
120
121protected:
122
123	////////////////////////////////////////
124	// friend methods
125
126    // IOFireWireSBP2LUN methods
127    virtual bool initWithLUN( 	IOFireWireSBP2LUN * lun,
128								void * refCon,
129								FWSBP2ManagementCallback completion  );
130
131	// IOFireWireSBP2UserClient methods
132    virtual void setAsyncCallbackReference( void * asyncRef );
133    virtual void getAsyncCallbackReference( void * asyncRef );
134
135protected:
136
137    // reserved for future use
138    struct ExpansionData
139	{
140		bool fInCriticalSection;
141	};
142    ExpansionData * fExpansionData;
143
144    IOFireWireSBP2LUN * 		fLUN;
145    IOFireWireUnit *			fUnit;
146
147    UInt32						fManagementOffset;
148    UInt32						fManagementTimeout;
149    UInt32						fFunction;
150    OSObject * 					fManageeCommand;
151
152	// our orb
153    FWSBP2TaskManagementORB		fManagementORB;
154    IOFWAddressSpace *			fManagementORBAddressSpace;
155    FWAddress					fManagementORBAddress;
156
157	// command to write management agent
158    IOFWWriteCommand *			fWriteCommand;
159    IOMemoryDescriptor *		fWriteCommandMemory;
160
161	// timeout
162    IOFWCommand *				fTimeoutCommand;
163    bool						fTimeoutTimerSet;
164
165	// status block
166    FWSBP2StatusBlock			fStatusBlock;
167    IOFWAddressSpace *			fStatusBlockAddressSpace;
168    FWAddress					fStatusBlockAddress;
169
170	// response buffer
171    void *						fResponseBuf;
172    UInt32						fResponseLen;
173    IOFWAddressSpace *			fResponseAddressSpace;
174    FWAddress					fResponseAddress;
175
176	// competion routine
177	FWSBP2ManagementCallback	fCompletionCallback;
178    void * 						fCompletionRefCon;
179
180    // for user client
181    OSAsyncReference64			fCallbackAsyncRef;
182
183	IOMemoryMap *				fResponseMap;
184
185	bool						fCompleting;
186
187	////////////////////////////////////////
188
189    // init / destroy
190    virtual IOReturn getUnitInformation( void );
191    virtual IOReturn allocateResources( void );
192    virtual void free( void );
193
194    // command execution
195    virtual IOReturn execute( void );
196    virtual IOReturn complete( IOReturn state );
197
198    // write complete handler
199    static void writeCompleteStatic( 	void *refcon,
200										IOReturn status,
201										IOFireWireNub *device,
202										IOFWCommand *fwCmd );
203    virtual void writeComplete( IOReturn status,
204								IOFireWireNub *device,
205								IOFWCommand *fwCmd );
206
207    // timeout handler
208    static void handleTimeoutStatic( 	void *refcon,
209										IOReturn status,
210										IOFireWireBus *bus,
211										IOFWBusCommand *fwCmd );
212    virtual void handleTimeout( IOReturn status, IOFireWireBus *bus, IOFWBusCommand *fwCmd );
213
214    // status block write handler
215    static UInt32 statusBlockWriteStatic( 	void *refcon,
216											UInt16 nodeID,
217											IOFWSpeed &speed,
218											FWAddress addr,
219											UInt32 len,
220											const void *buf,
221											IOFWRequestRefCon lockRead );
222    virtual UInt32 statusBlockWrite( 	UInt16 nodeID,
223										FWAddress addr,
224										UInt32 len,
225										const void *buf,
226										IOFWRequestRefCon lockRead );
227
228	// IOFireWireSBP2LUN friend class wrappers
229	virtual void clearAllTasksInSet( void );
230	virtual void removeManagementORB( IOFireWireSBP2ManagementORB * orb );
231
232public:
233
234	////////////////////////////////////////
235    // client methods
236
237    /*!
238		@function setCommandFunction
239		@abstract Sets the function of the management ORB.
240		@discussion Sets the the function of the management ORB.  Legal values are kFWSBP2QueryLogins,
241        kFWSBP2AbortTask, kFWSBP2AbortTaskSet,  kFWSBP2LogicalUnitReset, and kFWSBP2TargetReset.
242        @param function a value indicating the desired management function.
243        @result Returns kIOReturnSuccess if function was a legal function.
244	*/
245
246    virtual IOReturn setCommandFunction( UInt32 function );
247
248    /*!
249		@function getCommandFunction
250		@abstract Returns the current function of the management ORB.
251		@discussion Returns the function of the management ORB.  This is the same value that was
252        set with setCommandFunction.
253        @result Returns the function of the management ORB.
254	*/
255
256    virtual UInt32 getCommandFunction( void );
257
258    /*!
259		@function setManageeCommand
260		@abstract Sets the command to be managed by the management ORB.
261		@discussion All management functions except kFWSBP2QueryLogins require a reference to an ORB of
262        some sort.  kFWSBP2AbortTaskSet,  kFWSBP2LogicalUnitReset, and kFWSBP2TargetReset require a
263        reference to the login ORB.  kFWSBP2AbortTask requires a reference to the ORB to be aborted.
264        This method allows you to set the ORB to be managed.
265        @param command a reference to an IOFireWireSBP2Login or an IOFireWireSBP2ORB.
266 	*/
267
268    virtual void setManageeCommand( OSObject * command );
269
270    /*!
271		@function getCommandFunction
272		@abstract Returns the current managee command of the management ORB.
273		@discussion Returns the current managee command of the management ORB.  This is the same value that was
274        set with setManageeCommand.
275        @result  Returns the current managee command of the management ORB.
276	*/
277
278    virtual OSObject* getManageeCommand( void );
279
280    /*!
281		@function setResponseBuffer
282		@abstract Sets the response buffer for the management ORB.
283		@discussion Sets the response buffer for the management ORB.  kFWSBP2QueryLogins returns
284        a response to its query and needs to write it somewhere.  This routine allows you to
285        specify the location.
286        @param desc memory descriptor for buffer.
287        @result Returns kIOReturnSuccess on a success.
288	*/
289
290	virtual IOReturn setResponseBuffer( IOMemoryDescriptor * desc );
291
292    /*!
293		@function setResponseBuffer
294		@abstract Sets the response buffer for the management ORB.
295		@discussion Sets the response buffer for the management ORB.  kFWSBP2QueryLogins returns
296        a response to its query and needs to write it somewhere.  This routine allows you to
297        specify the location.
298        @param buf backing store for buffer
299        @param len length of buffer.
300        @result Returns kIOReturnSuccess on a success.
301	*/
302
303    virtual IOReturn setResponseBuffer( void * buf, UInt32 len );
304
305    /*!
306		@function getResponseBuffer
307		@abstract Returns the response buffer for the management ORB.
308		@discussion Returns the response buffer set in setResponseBuffer above
309        @param desc memory descriptor for buffer.
310        @param buf output parameter for backing store for buffer
311        @param len output parameter for length of buffer.
312	*/
313
314    virtual void getResponseBuffer( void ** buf, UInt32 * len );
315
316    /*!
317        @function release
318        @abstract Primary implementation of the release mechanism.
319        @discussion See OSObject.h for more information.
320        @param when When retainCount == when then call free().
321    */
322
323	virtual void release() const;
324
325protected:
326
327	virtual void setORBToDummy( IOFireWireSBP2ORB * orb );
328
329	virtual void suspendedNotify();
330
331private:
332
333    OSMetaClassDeclareReservedUsed(IOFireWireSBP2ManagementORB, 0);
334    OSMetaClassDeclareReservedUnused(IOFireWireSBP2ManagementORB, 1);
335    OSMetaClassDeclareReservedUnused(IOFireWireSBP2ManagementORB, 2);
336    OSMetaClassDeclareReservedUnused(IOFireWireSBP2ManagementORB, 3);
337    OSMetaClassDeclareReservedUnused(IOFireWireSBP2ManagementORB, 4);
338    OSMetaClassDeclareReservedUnused(IOFireWireSBP2ManagementORB, 5);
339    OSMetaClassDeclareReservedUnused(IOFireWireSBP2ManagementORB, 6);
340    OSMetaClassDeclareReservedUnused(IOFireWireSBP2ManagementORB, 7);
341    OSMetaClassDeclareReservedUnused(IOFireWireSBP2ManagementORB, 8);
342
343};
344
345#endif