/*
 * Copyright (c) 1998-2002 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
 
#ifndef _IOKIT_IOFWPSEUDOADDRESSSPACE_H
#define _IOKIT_IOFWPSEUDOADDRESSSPACE_H

#include <IOKit/firewire/IOFWAddressSpace.h>

/*
 * If installed, this callback is invoked for drivers which 
 * would like to coalesce incoming writes and do batch processing 
 * of incoming block write packets.
 * This callback can be installed by calling setARxReqIntCompleteHandler
 * method in IOFWPseudoAddressSpace object. 
 */
typedef void (*IOFWARxReqIntCompleteHandler)( void * refcon );

/*
 * Pseudo firewire addresses usually represent emulated registers of some kind.
 * Accesses to these addresses will result in the owner being notified.
 * 
 * Virtual addresses should not have zero as the top 16 bits of the 48 bit local address,
 * since that may look like a physical address to hardware (eg. OHCI).
 * if reader is NULL then reads will not be allowed.
 * if writer is NULL then writes will not be allowed.
 * if either is NULL then lock requests will not be allowed.
 * refcon is passed back as the first argument of read and write callbacks.
 */

class IOFWPseudoAddressSpace;

#pragma mark -

/*! 
	@class IOFWPseudoAddressSpaceAux
*/

class IOFWPseudoAddressSpaceAux : public IOFWAddressSpaceAux
{
    OSDeclareDefaultStructors(IOFWPseudoAddressSpaceAux)

	friend class IOFWAddressSpace;
	friend class IOFWPseudoAddressSpace;
	friend class IOFireWireController;
		
protected:
	
    struct MemberVariables 
	{ 		
		IOFWARxReqIntCompleteHandler		fARxReqIntCompleteHandler;
		void *	  							fARxReqIntCompleteHandlerRefcon;	
	};
	  
    MemberVariables * fMembers;

public:
     
	virtual bool init( IOFWAddressSpace * primary );
	virtual	void free();

protected:

	bool createMemberVariables( void );
	void destroyMemberVariables( void );
	
	virtual void handleARxReqIntComplete();
		
public:

/*!	@function setARxReqIntCompleteHandler
	@abstract Installs a callback to receive notification, when FWIM has completed
			  ARxReqInt processing and no incoming packets are left in the queue.
	@param refcon	Client's callback object.
	@param handler	Client callback to be invoked, at the end of interrupt processing.
	@result none.	*/	
	virtual void setARxReqIntCompleteHandler( void * refcon, IOFWARxReqIntCompleteHandler handler );

	virtual bool intersects( IOFWAddressSpace * space );
	
private:

    OSMetaClassDeclareReservedUsed(IOFWPseudoAddressSpaceAux, 0);
    OSMetaClassDeclareReservedUsed(IOFWPseudoAddressSpaceAux, 1);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 2);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 3);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 4);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 5);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 6);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 7);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 8);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpaceAux, 9);
	
};

/*! 
	@class IOFWPseudoAddressSpace
*/

class IOFWPseudoAddressSpace : public IOFWAddressSpace
{
    OSDeclareDefaultStructors(IOFWPseudoAddressSpace)

	friend class IOFWPseudoAddressSpaceAux;
	friend class IOFireWireController;
	
protected:

    IOMemoryDescriptor*	fDesc;
    void *				fRefCon;
    FWReadCallback		fReader;
    FWWriteCallback		fWriter;
    FWAddress			fBase;
    UInt32				fLen;

/*! @struct ExpansionData
    @discussion This structure will be used to expand the capablilties of the class in the future.
    */    
    struct ExpansionData { };

/*! @var reserved
    Reserved for future use.  (Internal use only)  */
    ExpansionData *reserved;

    static	OSData *	allocatedAddresses; // unused
    
    virtual	void 					free();
	
public:

/*!	@function	simpleReader
	@abstract	A method for processing an address space read request
	@param		refcon		Client's callback object.
	@param		nodeID		FireWire Read from nodeID.
	@param		speed		at this 'speed'.
	@param		addr		with FireWire address 'addr'.
	@param		len			read 'len' bytes from nodeID.
	@param		buf			points to a memory descriptor containing the packet data.
	@param		offset		start from this 'offset' in 'buf'.
	@param		reqrefcon	Can be queried for extra info about the request.
	@result		UIn32		returns kFWResponseComplete on success */
    static 	UInt32 					simpleReader(
											void*					refcon,
											UInt16 					nodeID,
											IOFWSpeed &				speed,
											FWAddress 				addr,
											UInt32 					len,
											IOMemoryDescriptor**	buf,
											IOByteCount* 			offset,
                                            IOFWRequestRefCon		reqrefcon);

/*!	@function	simpleWriter
	@abstract	A method for processing an address space write request
	@param		refcon		Client's callback object.
	@param		nodeID		FireWire Write to nodeID.
	@param		speed		at this 'speed'.
	@param		addr		with FireWire address 'addr'.
	@param		len			write 'len' bytes to nodeID.
	@param		buf			obtain bytes from location given by 'buf'.
	@param		reqrefcon	Can be queried for extra info about the request.
	@result		UIn32		returns kFWResponseComplete on success */
    static 	UInt32 					simpleWriter(
											void*					refcon,
											UInt16 					nodeID,
											IOFWSpeed&				speed,
											FWAddress 				addr,
											UInt32 					len,
											const void*				buf,
                                            IOFWRequestRefCon		reqrefcon);
protected:

    // Get a unique address range
    IOReturn						allocateAddress(
											FWAddress*				addr,
											UInt32 					len);
    // free address
    void							freeAddress(
											FWAddress 				addr,
											UInt32 					len);

public:

    static IOFWPseudoAddressSpace*	readWrite(
											FWAddress 				addr,
											UInt32 					len, 
											FWReadCallback 			reader,
											FWWriteCallback 		writer,
											void*					refcon);

/*!	@function	simpleRead
	@abstract	Create an address space object to handle read-only memory (eg. the local ROM)
				handles everything itself
	@param		bus		Points to IOFireWireBus object.
	@param		addr	Points to starting address for the Pseudo Address Space.
	@param		len		Length of the Pseudo Address Space.
	@param		data	The virtual address of the first byte in the memory.
	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
    static IOFWPseudoAddressSpace*	simpleRead(
                                            IOFireWireBus*			bus,
			                                FWAddress*				addr,
											UInt32 					len,
											const void*				data);

/*!	@function	simpleReadFixed
	@abstract	Create an address space object to handle fixed read-only memory (eg. the local ROM)
				handles everything itself
	@param		bus		Points to IOFireWireBus object.
	@param		addr	Points to starting address for the Pseudo Address Space.
	@param		len		Length of the Pseudo Address Space.
	@param		data	The virtual address of the first byte in the memory.
	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
    static IOFWPseudoAddressSpace*	simpleReadFixed(
                                            IOFireWireBus*			bus,
			                                FWAddress 				addr,
											UInt32 					len,
											const void*				data);

/*!	@function	simpleRW
	@abstract	Create an address space object to handle r/w memory
				handles everything itself
	@param		bus		Points to IOFireWireBus object.
	@param		addr	Points to starting address for the Pseudo Address Space.
	@param		len		Length of the Pseudo Address Space.
	@param		data	The virtual address of the first byte in the memory.
	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
    static IOFWPseudoAddressSpace*	simpleRW(
                                            IOFireWireBus*			bus,
                                			FWAddress*				addr,
											UInt32 					len,
											void *					data);
											
/*!	@function	simpleRW
	@abstract	Create an address space object to handle r/w memory
				handles everything itself
	@param		bus		Points to IOFireWireBus object.
	@param		addr	Points to starting address for the Pseudo Address Space.
	@param		data	The virtual address of the first byte in the memory.
	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
    static IOFWPseudoAddressSpace*	simpleRW(
                                            IOFireWireBus*			bus,
                                			FWAddress*				addr,
											IOMemoryDescriptor *	data);
											
/*!	@function	initAll
	@abstract	Initialize an address space object to handle r/w memory
	@param		bus		Points to IOFireWireBus object.
	@param		addr	Points to starting address for the Pseudo Address Space.
	@param		len		Length of the Pseudo Address Space.
	@param		reader	Callback handler for incoming Read.
	@param		writer	Callback handler for incoming Write.
	@param		refcon	Client's callback object.
	@result		returns true on success, false on failure */
    virtual bool 					initAll(
                                            IOFireWireBus*			bus,
                							FWAddress*				addr,
											UInt32 					len, 
											FWReadCallback 			reader,
											FWWriteCallback 		writer,
											void*					refcon);
											
/*!	@function	initFixed
	@abstract	Initialize a fixed address space at top of kCSRRegisterSpaceBaseAddressHi
	@param		bus		Points to IOFireWireBus object.
	@param		addr	Points to starting address for the Pseudo Address Space.
	@param		reader	Callback handler for incoming Read.
	@param		writer	Callback handler for incoming Write.
	@param		refcon	Client's callback object.
	@result		returns true on success, false on failure */
    virtual bool 					initFixed(
                                            IOFireWireBus*			bus,
							                FWAddress 				addr,
											UInt32 					len,
                							FWReadCallback 			reader,
											FWWriteCallback 		writer,
											void*					refcon);

/*!	@function	doRead
	@abstract	A method for processing an address space read request
	@param		nodeID	FireWire Read from nodeID.
	@param		speed	at this 'speed'.
	@param		addr	with FireWire address 'addr'.
	@param		len		read 'len' bytes from nodeID.
	@param		buf		points to a memory descriptor containing the packet data.
	@param		offset	start from this 'offset' in 'buf'.
	@param		reqrefcon  Can be queried for extra info about the request.
	@result		UIn32	returns kFWResponseComplete on success */
    virtual UInt32 					doRead(
											UInt16 					nodeID, 
											IOFWSpeed &				speed, 
											FWAddress 				addr, 
											UInt32 					len,
                               				IOMemoryDescriptor **	buf, 
											IOByteCount * 			offset,
                                            IOFWRequestRefCon		reqrefcon);
/*!	@function	doWrite
	@abstract	A method for processing an address space write request
	@param		nodeID	FireWire Write to nodeID.
	@param		speed	at this 'speed'.
	@param		addr	with FireWire address 'addr'.
	@param		len		write 'len' bytes to nodeID.
	@param		buf		obtain bytes from location given by 'buf'.
	@param		reqrefcon  Can be queried for extra info about the request.
	@result		UIn32	returns kFWResponseComplete on success */
    virtual UInt32 					doWrite(
											UInt16 					nodeID,
											IOFWSpeed&				speed,
											FWAddress 				addr,
											UInt32 					len, 
											const void*				buf,
                                            IOFWRequestRefCon		reqrefcon);

/*!	@function	contains
	@abstract	returns number of bytes starting at addr in this space
	@result		0 if it doesn't contain the address
	*/
    virtual UInt32					contains(FWAddress addr);

/*!	@function	simpleRWFixed
	@abstract	Create a Read/Write fixed address space at top of kCSRRegisterSpaceBaseAddressHi.
	@param		control	Points to IOFireWireBus object.
	@param		addr	Points to starting address for the Pseudo Address Space.
	@param		len		Length of the address range.
	@param		data	The virtual address of the first byte in the memory.
	@result		returns valid IOFWPseudoAddressSpace on success, null on failure */
	static IOFWPseudoAddressSpace * simpleRWFixed( IOFireWireBus *control, FWAddress addr, UInt32 len, const void *data );

protected:
	
	virtual IOFWAddressSpaceAux * createAuxiliary( void );

protected:
	inline void handleARxReqIntComplete( void )
		{ ((IOFWPseudoAddressSpaceAux*)fIOFWAddressSpaceExpansion->fAuxiliary)->handleARxReqIntComplete(); }
	
public:
/*!	@function setARxReqIntCompleteHandler
	@abstract Installs a callback to receive notification, when FWIM has completed
			  ARxReqInt processing and no incoming packets are left in the queue.
	@param refcon	Client's callback object.
	@param handler	Client callback to be invoked, at the end of interrupt processing.
	@result none.	*/	
	inline void setARxReqIntCompleteHandler( void * refcon, IOFWARxReqIntCompleteHandler handler )
		{ ((IOFWPseudoAddressSpaceAux*)fIOFWAddressSpaceExpansion->fAuxiliary)->setARxReqIntCompleteHandler( refcon, handler ); }
			
private:

    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpace, 0);
    OSMetaClassDeclareReservedUnused(IOFWPseudoAddressSpace, 1);
    
};

#endif