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 _IOKIT_IOFWPSEUDOADDRESSSPACE_H
24#define _IOKIT_IOFWPSEUDOADDRESSSPACE_H
25
26#include <IOKit/firewire/IOFWAddressSpace.h>
27
28/*
29 * If installed, this callback is invoked for drivers which
30 * would like to coalesce incoming writes and do batch processing
31 * of incoming block write packets.
32 * This callback can be installed by calling setARxReqIntCompleteHandler
33 * method in IOFWPseudoAddressSpace object.
34 */
35typedef void (*IOFWARxReqIntCompleteHandler)( void * refcon );
36
37/*
38 * Pseudo firewire addresses usually represent emulated registers of some kind.
39 * Accesses to these addresses will result in the owner being notified.
40 *
41 * Virtual addresses should not have zero as the top 16 bits of the 48 bit local address,
42 * since that may look like a physical address to hardware (eg. OHCI).
43 * if reader is NULL then reads will not be allowed.
44 * if writer is NULL then writes will not be allowed.
45 * if either is NULL then lock requests will not be allowed.
46 * refcon is passed back as the first argument of read and write callbacks.
47 */
48
49class IOFWPseudoAddressSpace;
50
51#pragma mark -
52
53/*!
54	@class IOFWPseudoAddressSpaceAux
55*/
56
57class IOFWPseudoAddressSpaceAux : public IOFWAddressSpaceAux
58{
59    OSDeclareDefaultStructors(IOFWPseudoAddressSpaceAux)
60
61	friend class IOFWAddressSpace;
62	friend class IOFWPseudoAddressSpace;
63	friend class IOFireWireController;
64
65protected:
66
67    struct MemberVariables
68	{
69		IOFWARxReqIntCompleteHandler		fARxReqIntCompleteHandler;
70		void *	  							fARxReqIntCompleteHandlerRefcon;
71	};
72
73    MemberVariables * fMembers;
74
75public:
76
77	virtual bool init( IOFWAddressSpace * primary );
78	virtual	void free();
79
80protected:
81
82	bool createMemberVariables( void );
83	void destroyMemberVariables( void );
84
85	virtual void handleARxReqIntComplete();
86
87public:
88
89/*!	@function setARxReqIntCompleteHandler
90	@abstract Installs a callback to receive notification, when FWIM has completed
91			  ARxReqInt processing and no incoming packets are left in the queue.
92	@param refcon	Client's callback object.
93	@param handler	Client callback to be invoked, at the end of interrupt processing.
94	@result none.	*/
95	virtual void setARxReqIntCompleteHandler( void * refcon, IOFWARxReqIntCompleteHandler handler );
96
97	virtual bool intersects( IOFWAddressSpace * space );
98
99private:
100
101    OSMetaClassDeclareReservedUsed(IOFWPseudoAddressSpaceAux, 0);
102    OSMetaClassDeclareReservedUsed(IOFWPseudoAddressSpaceAux, 1);
103    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 2);
104    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 3);
105    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 4);
106    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 5);
107    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 6);
108    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 7);
109    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 8);
110    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 9);
111
112};
113
114/*!
115	@class IOFWPseudoAddressSpace
116*/
117
118class IOFWPseudoAddressSpace : public IOFWAddressSpace
119{
120    OSDeclareDefaultStructors(IOFWPseudoAddressSpace)
121
122	friend class IOFWPseudoAddressSpaceAux;
123	friend class IOFireWireController;
124
125protected:
126
127    IOMemoryDescriptor*	fDesc;
128    void *				fRefCon;
129    FWReadCallback		fReader;
130    FWWriteCallback		fWriter;
131    FWAddress			fBase;
132    UInt32				fLen;
133
134/*! @struct ExpansionData
135    @discussion This structure will be used to expand the capablilties of the class in the future.
136    */
137    struct ExpansionData { };
138
139/*! @var reserved
140    Reserved for future use.  (Internal use only)  */
141    ExpansionData *reserved;
142
143    static	OSData *	allocatedAddresses; // unused
144
145    virtual	void 					free();
146
147public:
148
149/*!	@function	simpleReader
150	@abstract	A method for processing an address space read request
151	@param		refcon		Client's callback object.
152	@param		nodeID		FireWire Read from nodeID.
153	@param		speed		at this 'speed'.
154	@param		addr		with FireWire address 'addr'.
155	@param		len			read 'len' bytes from nodeID.
156	@param		buf			points to a memory descriptor containing the packet data.
157	@param		offset		start from this 'offset' in 'buf'.
158	@param		reqrefcon	Can be queried for extra info about the request.
159	@result		UIn32		returns kFWResponseComplete on success */
160    static 	UInt32 					simpleReader(
161											void*					refcon,
162											UInt16 					nodeID,
163											IOFWSpeed &				speed,
164											FWAddress 				addr,
165											UInt32 					len,
166											IOMemoryDescriptor**	buf,
167											IOByteCount* 			offset,
168                                            IOFWRequestRefCon		reqrefcon);
169
170/*!	@function	simpleWriter
171	@abstract	A method for processing an address space write request
172	@param		refcon		Client's callback object.
173	@param		nodeID		FireWire Write to nodeID.
174	@param		speed		at this 'speed'.
175	@param		addr		with FireWire address 'addr'.
176	@param		len			write 'len' bytes to nodeID.
177	@param		buf			obtain bytes from location given by 'buf'.
178	@param		reqrefcon	Can be queried for extra info about the request.
179	@result		UIn32		returns kFWResponseComplete on success */
180    static 	UInt32 					simpleWriter(
181											void*					refcon,
182											UInt16 					nodeID,
183											IOFWSpeed&				speed,
184											FWAddress 				addr,
185											UInt32 					len,
186											const void*				buf,
187                                            IOFWRequestRefCon		reqrefcon);
188protected:
189
190    // Get a unique address range
191    IOReturn						allocateAddress(
192											FWAddress*				addr,
193											UInt32 					len);
194    // free address
195    void							freeAddress(
196											FWAddress 				addr,
197											UInt32 					len);
198
199public:
200
201    static IOFWPseudoAddressSpace*	readWrite(
202											FWAddress 				addr,
203											UInt32 					len,
204											FWReadCallback 			reader,
205											FWWriteCallback 		writer,
206											void*					refcon);
207
208/*!	@function	simpleRead
209	@abstract	Create an address space object to handle read-only memory (eg. the local ROM)
210				handles everything itself
211	@param		bus		Points to IOFireWireBus object.
212	@param		addr	Points to starting address for the Pseudo Address Space.
213	@param		len		Length of the Pseudo Address Space.
214	@param		data	The virtual address of the first byte in the memory.
215	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
216    static IOFWPseudoAddressSpace*	simpleRead(
217                                            IOFireWireBus*			bus,
218			                                FWAddress*				addr,
219											UInt32 					len,
220											const void*				data);
221
222/*!	@function	simpleReadFixed
223	@abstract	Create an address space object to handle fixed read-only memory (eg. the local ROM)
224				handles everything itself
225	@param		bus		Points to IOFireWireBus object.
226	@param		addr	Points to starting address for the Pseudo Address Space.
227	@param		len		Length of the Pseudo Address Space.
228	@param		data	The virtual address of the first byte in the memory.
229	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
230    static IOFWPseudoAddressSpace*	simpleReadFixed(
231                                            IOFireWireBus*			bus,
232			                                FWAddress 				addr,
233											UInt32 					len,
234											const void*				data);
235
236/*!	@function	simpleRW
237	@abstract	Create an address space object to handle r/w memory
238				handles everything itself
239	@param		bus		Points to IOFireWireBus object.
240	@param		addr	Points to starting address for the Pseudo Address Space.
241	@param		len		Length of the Pseudo Address Space.
242	@param		data	The virtual address of the first byte in the memory.
243	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
244    static IOFWPseudoAddressSpace*	simpleRW(
245                                            IOFireWireBus*			bus,
246                                			FWAddress*				addr,
247											UInt32 					len,
248											void *					data);
249
250/*!	@function	simpleRW
251	@abstract	Create an address space object to handle r/w memory
252				handles everything itself
253	@param		bus		Points to IOFireWireBus object.
254	@param		addr	Points to starting address for the Pseudo Address Space.
255	@param		data	The virtual address of the first byte in the memory.
256	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
257    static IOFWPseudoAddressSpace*	simpleRW(
258                                            IOFireWireBus*			bus,
259                                			FWAddress*				addr,
260											IOMemoryDescriptor *	data);
261
262/*!	@function	initAll
263	@abstract	Initialize an address space object to handle r/w memory
264	@param		bus		Points to IOFireWireBus object.
265	@param		addr	Points to starting address for the Pseudo Address Space.
266	@param		len		Length of the Pseudo Address Space.
267	@param		reader	Callback handler for incoming Read.
268	@param		writer	Callback handler for incoming Write.
269	@param		refcon	Client's callback object.
270	@result		returns true on success, false on failure */
271    virtual bool 					initAll(
272                                            IOFireWireBus*			bus,
273                							FWAddress*				addr,
274											UInt32 					len,
275											FWReadCallback 			reader,
276											FWWriteCallback 		writer,
277											void*					refcon);
278
279/*!	@function	initFixed
280	@abstract	Initialize a fixed address space at top of kCSRRegisterSpaceBaseAddressHi
281	@param		bus		Points to IOFireWireBus object.
282	@param		addr	Points to starting address for the Pseudo Address Space.
283	@param		reader	Callback handler for incoming Read.
284	@param		writer	Callback handler for incoming Write.
285	@param		refcon	Client's callback object.
286	@result		returns true on success, false on failure */
287    virtual bool 					initFixed(
288                                            IOFireWireBus*			bus,
289							                FWAddress 				addr,
290											UInt32 					len,
291                							FWReadCallback 			reader,
292											FWWriteCallback 		writer,
293											void*					refcon);
294
295/*!	@function	doRead
296	@abstract	A method for processing an address space read request
297	@param		nodeID	FireWire Read from nodeID.
298	@param		speed	at this 'speed'.
299	@param		addr	with FireWire address 'addr'.
300	@param		len		read 'len' bytes from nodeID.
301	@param		buf		points to a memory descriptor containing the packet data.
302	@param		offset	start from this 'offset' in 'buf'.
303	@param		reqrefcon  Can be queried for extra info about the request.
304	@result		UIn32	returns kFWResponseComplete on success */
305    virtual UInt32 					doRead(
306											UInt16 					nodeID,
307											IOFWSpeed &				speed,
308											FWAddress 				addr,
309											UInt32 					len,
310                               				IOMemoryDescriptor **	buf,
311											IOByteCount * 			offset,
312                                            IOFWRequestRefCon		reqrefcon);
313/*!	@function	doWrite
314	@abstract	A method for processing an address space write request
315	@param		nodeID	FireWire Write to nodeID.
316	@param		speed	at this 'speed'.
317	@param		addr	with FireWire address 'addr'.
318	@param		len		write 'len' bytes to nodeID.
319	@param		buf		obtain bytes from location given by 'buf'.
320	@param		reqrefcon  Can be queried for extra info about the request.
321	@result		UIn32	returns kFWResponseComplete on success */
322    virtual UInt32 					doWrite(
323											UInt16 					nodeID,
324											IOFWSpeed&				speed,
325											FWAddress 				addr,
326											UInt32 					len,
327											const void*				buf,
328                                            IOFWRequestRefCon		reqrefcon);
329
330/*!	@function	contains
331	@abstract	returns number of bytes starting at addr in this space
332	@result		0 if it doesn't contain the address
333	*/
334    virtual UInt32					contains(FWAddress addr);
335
336/*!	@function	simpleRWFixed
337	@abstract	Create a Read/Write fixed address space at top of kCSRRegisterSpaceBaseAddressHi.
338	@param		control	Points to IOFireWireBus object.
339	@param		addr	Points to starting address for the Pseudo Address Space.
340	@param		len		Length of the address range.
341	@param		data	The virtual address of the first byte in the memory.
342	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
343	static IOFWPseudoAddressSpace * simpleRWFixed( IOFireWireBus *control, FWAddress addr, UInt32 len, const void *data );
344
345protected:
346
347	virtual IOFWAddressSpaceAux * createAuxiliary( void );
348
349protected:
350	inline void handleARxReqIntComplete( void )
351		{ ((IOFWPseudoAddressSpaceAux*)fIOFWAddressSpaceExpansion->fAuxiliary)->handleARxReqIntComplete(); }
352
353public:
354/*!	@function setARxReqIntCompleteHandler
355	@abstract Installs a callback to receive notification, when FWIM has completed
356			  ARxReqInt processing and no incoming packets are left in the queue.
357	@param refcon	Client's callback object.
358	@param handler	Client callback to be invoked, at the end of interrupt processing.
359	@result none.	*/
360	inline void setARxReqIntCompleteHandler( void * refcon, IOFWARxReqIntCompleteHandler handler )
361		{ ((IOFWPseudoAddressSpaceAux*)fIOFWAddressSpaceExpansion->fAuxiliary)->setARxReqIntCompleteHandler( refcon, handler ); }
362
363private:
364
365    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpace, 0);
366    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpace, 1);
367
368};
369
370#endif
371