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 IOFireWireSBP2LUN
25  Contains the class definition for IOFireWireSBP2LUN.
26*/
27
28#ifndef _IOKIT_IOFIREWIRESBP2LUN_H
29#define _IOKIT_IOFIREWIRESBP2LUN_H
30
31#include <IOKit/IOService.h>
32#include <IOKit/IOCommandGate.h>
33
34#include <IOKit/firewire/IOFireWireUnit.h>
35
36#include <IOKit/sbp2/IOFireWireSBP2Login.h>
37#include <IOKit/sbp2/IOFireWireSBP2ManagementORB.h>
38
39class IOFireWireSBP2Target;
40
41/*!
42    @class IOFireWireSBP2LUN
43    @abstract Provider for most drivers.
44    @discussion IOFireWireSBP2LUN objects are created by IOFireWireSBP2Target objects.  Each target may have zero or more IOFireWireSBP2LUN children. The LUN object serves as the matching nub for most drivers and therefore will be the provider for most drivers.  It supplies the methods that control the operation of the LUN as a whole.  Methods that control the behavior and execution of an SBP2 login session are supplied in a separate IOFireWireSBP2Login object. The LUN can be used to create one of these login objects.
45    The LUN can also create IOFireWireSBP2ManagementORBs for configuring and appending non-login related management functions.  Login related management functions (ie. Login, Logout, Reconnect) are supplied by the IOFireWireSBP2Login.
46    Finally the LUN can supply a reference to the IOFireWireUnit.  This can be useful if a driver wishes to access the standard FireWire APIs.
47*/
48
49class IOFireWireSBP2LUN : public IOService
50{
51    OSDeclareDefaultStructors( IOFireWireSBP2LUN );
52
53	friend class IOFireWireSBP2ManagementORB;
54	friend class IOFireWireSBP2Login;
55	friend class IOFireWireSBP2UserClient;
56
57protected:
58
59    // reserved for future use
60    struct ExpansionData { };
61    ExpansionData *reserved;
62
63	////////////////////////////////////////////
64	// methods called by friend classes
65
66	// IOFireWireSBP2Login methods
67    virtual void removeLogin( IOFireWireSBP2Login * login );
68	virtual IOFireWireSBP2Target * getTarget( void );
69
70	// IOFireWireSBP2ManagementORB methods
71	virtual void clearAllTasksInSet( void );  // assumes caller is on workloop
72	virtual void removeManagementORB( IOFireWireSBP2ManagementORB * orb );
73
74	// IOFireWireSBP2UserClient methods
75	virtual void flushAllManagementORBs( void );
76
77public:
78
79	////////////////////////////////////////////
80	// IOService overrides
81
82    /*! @function attach
83        @abstract Attaches an IOService client to a provider in the registry.
84        @discussion See IOService for discussion.
85        @param provider The IOService object which will serve as this objects provider.
86        @result false if the provider is inactive or on a resource failure, otherwise true.
87    */
88
89    virtual bool attach( IOService *provider );
90
91	/*! @function handleOpen
92		@abstract Overrideable method to control the open / close behaviour of an IOService.
93		@discussion See IOService for discussion.
94		@param forClient Designates the client of the provider requesting the open.
95		@param options Options for the open, may be interpreted by the implementor of handleOpen.
96		@result Return true if the open was successful, false otherwise. */
97
98    virtual bool handleOpen(  IOService *	  forClient,
99                              IOOptionBits	  options,
100                              void *		  arg );
101	/*!
102		@function handleClose
103		@abstract Overrideable method to control the open / close behaviour of an IOService.
104		@discussion See IOService for discussion.
105		@param forClient Designates the client of the provider requesting the close.
106		@param options Options for the close, may be interpreted by the implementor of handleOpen.
107	*/
108
109    virtual void handleClose(   IOService *		forClient,
110                                IOOptionBits	options );
111
112 	/*!
113		@function matchPropertyTable
114		@abstract Implements SBP2 specific matching.
115		@discussion See IOService for discussion.
116	    @param table The dictionary of properties to be matched against.
117		@result Returns false if the family considers the matching dictionary does not match in properties it 			understands, true otherwise.
118	*/
119
120	virtual bool matchPropertyTable(OSDictionary * table);
121
122protected:
123
124	////////////////////////////////////////////
125	// private fields
126
127    IOFireWireSBP2Target * 	fProviderTarget;
128    UInt32					fLUNumber;
129    OSSet *					fLoginSet;
130    OSIterator *			fLoginSetIterator;
131	IOCommandGate * 		fGate;
132	OSSet *					fORBSet;
133    OSIterator *			fORBSetIterator;
134	OSObject * 				fDiagnostics;
135
136	////////////////////////////////////////////
137	// private methods
138
139	// IOService methods
140    virtual void free( void );
141    virtual IOReturn message( UInt32 type, IOService * provider, void * argument = 0 );
142
143	// create management orb internals
144	static IOReturn staticCreateManagementORBAction( OSObject *self,
145													 void * refCon,
146													 void * completion,
147													 void * orb,
148													 void * );
149	virtual IOReturn createManagementORBAction( void * refCon,
150												FWSBP2ManagementCallback completion,
151												IOFireWireSBP2ManagementORB ** orb );
152
153	// remove management orb internals
154	static IOReturn staticRemoveManagementORBAction( OSObject * self, void * orb,
155													void *, void *, void * );
156	virtual IOReturn removeManagementORBAction( IOFireWireSBP2ManagementORB * orb );
157
158	// flush all management orb internals
159	static IOReturn staticExecuteFlushAllMgmtORBs( OSObject * self, void *,
160													void *, void *, void * );
161	virtual IOReturn executeFlushAllMgmtORBs( void );
162
163	// IOFireWireSBP2ManagementORB friend class wrappers
164    virtual bool initMgmtORBWithLUN( IOFireWireSBP2ManagementORB * orb, IOFireWireSBP2LUN * lun,
165									 void * refCon,
166									 FWSBP2ManagementCallback completion );
167
168	// IOFireWireSBP2Login friend class wrappers
169    virtual bool initLoginWithLUN( IOFireWireSBP2Login * login, IOFireWireSBP2LUN * lun );
170	virtual void suspendedNotify( void );
171	virtual void resumeNotify( void );
172
173private:
174
175    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 0);
176
177public:
178
179	////////////////////////////////////////////
180    // client methods
181
182	// getters
183
184    /*!
185		@function getFireWireUnit
186		@abstract Returns an IOFireWireUnit object.
187		@discussion An IOFireWireUnit is the provider of an IOFireWireSBP2Target.  In order to
188        use the base FireWire services you will need a reference to the unit.  This method
189        returns that reference.
190		@result Returns a pointer to an IOFireWireUnit.
191	*/
192
193    virtual IOFireWireUnit * getFireWireUnit( void );
194
195    /*!
196		@function getLUNumber
197		@abstract Returns the LUNs number.
198		@discussion Each LUN has a number to uniquely identify it on a device.  This method returns
199        this value in a UInt32.
200        @result Returns a UInt32 containing the Logical Unit Number.
201	*/
202
203	virtual UInt32 getLUNumber( void );
204
205	// factory methods
206
207    /*!
208		@function createLogin
209		@abstract Creates a new IOFireWireSBP2Login object.
210		@discussion	Creates a new IOFireWireSBP2Login object for the LUN.  Login objects supply most
211        of the SBP2 APIs related to login maintenance and Normal Command ORB execution.
212        @result Returns a pointer to a new IOFireWireSBP2Login.
213	*/
214
215    virtual IOFireWireSBP2Login *createLogin( void );
216
217    /*!
218		@function createManagementORB
219		@abstract Creates a new IOFireWireSBP2ManagementORB object.
220		@discussion	Creates a new IOFireWireSBP2ManagementORB object.  Management objects let you
221        execute commands like QueryLogins, LogicalUnitReset, and AbortTask.  These commands are
222        configured after they are created here.  When they are done executing (after a call to submit)
223        the supplied completion routine will be called with the supplied refcon.  Usually this refCon
224        is the "this" pointer of completion method's object.
225        @param refCon The refcon passed to the completion routine.
226        @param completion The completion routine.  Called when the ORB finishes execution.
227        @result Returns a pointer to a new IOFireWireSBP2Login.
228	*/
229
230    virtual IOFireWireSBP2ManagementORB * createManagementORB( void * refCon, FWSBP2ManagementCallback completion );
231
232protected:
233
234    static IOReturn staticCreateLogin( OSObject *self, void * login, void *, void *, void * );
235    virtual IOReturn createLoginAction( IOFireWireSBP2Login ** login );
236
237    static IOReturn staticRemoveLoginAction( OSObject *self, void * login, void *, void *, void * );
238    virtual IOReturn removeLoginAction( IOFireWireSBP2Login * login );
239
240public:
241
242    /*!
243		@function getDiagnostics
244		@abstract Debug-only method.
245		@discussion	Returns a reference to the internal diagnostics object when the services are built
246        in debug mode. Should be a no-op in release builds.
247        @result Returns a pointer to the diagnostics object (if any).
248	*/
249
250	virtual OSObject * getDiagnostics( void );
251
252    virtual bool finalize( IOOptionBits options );
253
254protected:
255
256	void terminateNotify( void );
257
258private:
259    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 1);
260    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 2);
261    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 3);
262    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 4);
263    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 5);
264    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 6);
265    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 7);
266    OSMetaClassDeclareReservedUnused(IOFireWireSBP2LUN, 8);
267
268};
269
270#endif