IOATADevConfig.h   [plain text]

 * Copyright (c) 2000-2008 Apple Inc. All rights reserved.
 * 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
 * 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
 * License for the specific language governing rights and limitations
 * under the License.


#include <libkern/c++/OSObject.h>
#include <IOKit/IOTypes.h>
#include "IOATATypes.h"
#include "IOATABusInfo.h"

	@class IOATADevConfig 
	@abstract used for configuring and communicating the desired transfer modes of a device.
	 A disk driver would typically use this object in conjunction with the 512-bytes of identification 
	 data from the drive and the IOATABusInfo object for the bus it is connected to.
	 This object will determine the best matching transfer speeds available.
	 the device driver will then send a series of Set Features commands to configure the drive
	 and this object to the bus through the IOATADevice nub in order to configure the optimum transfer mode.
	 The driver for the disk drive may choose to populate this object with whatever transfer mode 
	 desired, in the event that a different mode is required.
	@discussion usually use the initWithBestSelection to make a best mode match.
	The Mode accessors use bit significance to indicate a selected mode or supported modes(s)
	ie, 00000001b indicates Mode-0, 00000010b indicates mode 1, etc.
	Selected mode is indicated by a single set bit. No bit set indicates no mode in that class is selected.
	ie, a bus will support multiple possible modes, but will only have one mode selected at that time.


class IOATADevConfig : public OSObject {

	OSDeclareDefaultStructors( IOATADevConfig );
	/*!@function atadevconfig
	@abstract static creator function.
    static	IOATADevConfig* atadevconfig(void);
   /*!@function initWithBestSelection
	@abstract Handy initializer: pass the 512-byte result of the Identify Device or 
    Identify Packet Device in endian-order for your platform (byte-swapped on PPC) 
    and the IOATABusInfo object for the bus. The object will initialize all fields 
    and select the best transfer modes that match on bus and device. 
    If the return value was 0 (success or noErr), then a matching mode is supported.
    Examine the PIO and UDMA/DMA fields and to generate the apropriate SET FEATURES 
    parameters for your drive and send this initialised object to the IOATAController 
    when requesting a speed configuration.
    failure means no supported transfer modes matched between bus and device info.
	@param identifyData 512 bytes of data obtained from the device via IDENTIFY DEVICE or IDENTIFY PACKET DEVICE command.
	@param busInfo pointer to an IOATAbusInfo object obtained from a previous atanub->provideBusInfo() call.
	@result kIOSuccess (0) when a matching transfer mode is available between the device and controller.
	IOReturn	initWithBestSelection( const UInt16* identifyData, IOATABusInfo* busInfo);
    // intitialize with the 512 byte data from an ATA device identify command
	IOReturn assignFromData( const UInt16* identifyData );

	/*!@function setPacketConfig
	@param packetConfig
	@abstract 	For ATAPI devices, if the device asserts interrupt after the Packet Command when it is ready to accept the packet, set this value to true (mostly older devices). If the device accepts the packet only by asserting DRQ bit in status, then set this value false. Tells the bus controller whether to wait for packet acceptance or set pending interrupt.
	void setPacketConfig ( atapiConfig packetConfig);

	/*!@function getPacketConfig
	@result atapiConfig as defined in IOATATypes.h 
	atapiConfig getPacketConfig( void );	

	// The following Mode accessors use bit significance to indicate a selected mode or supported modes(s)
	// ie, 00000001b indicates Mode-0, 00000010b indicates mode 1, etc.
	// Selected mode is indicated by a single set bit. No bit set indicates no mode in that class is selected.
	// ie, a bus will support multiple possible modes, but will only have one mode selected at that time.

	/*!@function setPIOMode
	@param inModeBitMap bit-significant map of PIO mode
	void setPIOMode( UInt8 inModeBitMap);		// bit-significant map of PIO mode(s)
	/*!@function getPIOMode
	@result bit-significant map of PIO mode
	UInt8 getPIOMode( void );
	/*!@function setDMAMode
	@param inModeBitMap bit-significant map of DMA mode
	void setDMAMode( UInt8 inModeBitMap );	// bit-significant map of DMA mode(s)
	/*!@function getDMAMode
	@result bit-significant map of DMA mode
	UInt8 getDMAMode( void );
	/*!@function setUltraMode
	@param inModeBitMap bit-significant map of Ultra mode
	void setUltraMode( UInt8 inModeBitMap );	// bit-significant map of Ultra mode(s)

	/*!@function getUltraMode
	@result  bit-significant map of Ultra mode
	UInt8 getUltraMode( void );
	// The following cycle time accessors report cycle times in nanoseconds.
	// A device requesting a mode should also request a cycle time as reported in the device's identification page.
	// A bus controller will configure the bus not to exceed (go faster than) the minimum time requested.
	// When a bus controller reports a mode configuration, the cycle time indicates the busses contract not to go 
	// faster than. However an actual cycle time may be slower than the indicated time.	
	/*!@function setPIOCycleTime
	@param inNS PIO cycle time in nanoseconds. 
	void setPIOCycleTime( UInt16 inNS );
	/*!@function getPIOCycleTime
	@result reported PIO CycleTime in nanoseconds. 
	UInt16 getPIOCycleTime( void );

	/*!@function setDMACycleTime
	@param inNS reported multiword DMA Cycle time in nanoseconds.
	void setDMACycleTime( UInt16 inNS );
	/*!@function getDMACycleTime
	@result Reported multiword DMA cycle time in nanoseconds. 
	UInt16 getDMACycleTime( void );
	// Ultra ATA defines cycle times a device must meet to comply with standards.
	// No cycle time field is needed.

	// convert bit-significant to numeric value
	/*!@function bitSigToNumeric
	@abstract converts a bit-significant field to a numerical value. Note that a bit field of 0x00 has no defined result.
	@param binary the bit significant field.
	@result the numerical value of the highest bit set in the field.
	virtual UInt8 bitSigToNumeric( UInt16 binary);

	atapiConfig 					_atapiIRQForPacket;			// enum for bits 5 and 6 of word zero of 
																// the identify packet device info data for PACKET devices ONLY.
																// shift word-0 5-bits left, mask 0x03 and these enums apply.
																// values are:
																//	kATAPIDRQSlow 	= 0x00   - wait up to 3MS for packet on DRQ
																//	kATAPIIRQPacket = 0x01,  - device asserts IRQ for packet
																//	kATAPIDRQFast	= 0x10,  - packet on DRQ within 50us
																//	kATAPIUnknown   = 0x11   - reserved as of ATA/ATAPI-5

	UInt8 							_ataPIOMode;					/* <->: PIO Mode Timing class bit-significant */
	UInt16 							_ataPIOCycleTime;			/* <->: Cycle time in ns for PIO mode */
	UInt8 							_ataMultiDMAMode;			/* <->: Multiple Word DMA Timing Class bit-significant*/
	UInt16 							_ataMultiCycleTime;			/* <->: Cycle time in ns for Multiword DMA mode */
	UInt8 							_ataUltraDMAMode;			/* <->: Ultra DMA timing class bit-significant */

	IOReturn						_AssignPIOData( const UInt16* identifyData);
	IOReturn						_AssignDMAData(const UInt16* identifyData);
	IOReturn						_AssignUltraData(const UInt16* identifyData);
	UInt8							_MostSignificantBit( UInt8 inByte);

    virtual bool init();  
/*! @struct ExpansionData
    @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
    struct ExpansionData { };

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

    OSMetaClassDeclareReservedUnused(IOATADevConfig, 0);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 1);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 2);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 3);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 4);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 5);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 6);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 7);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 8);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 9);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 10);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 11);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 12);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 13);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 14);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 15);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 16);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 17);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 18);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 19);
    OSMetaClassDeclareReservedUnused(IOATADevConfig, 20);

//some static utility functions to parse the identify data for feature support

  static bool sDriveSupports48BitLBA( const UInt16* identifyData );
  static UInt32 sDriveExtendedLBASize( UInt32* lbaHi, UInt32* lbaLo, const UInt16* identifyData); // result returned is same as lbaLo. 

// header doc info goes here. I find putting it within the delcarations more confusing than putting it all in the bottom of the header.

#endif /* !_IOATADEVCONFIG_H */