xnu-201.42.3.tar.gz

[apple/xnu.git] / iokit / IOKit / ata / IOATADevice_Reference.h

/*
 * Copyright (c) 1998-2000 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@
 */
 
/*! 
@header IOATADevice_Reference.h

This header defines the IOATADevice class.

The ATA/ATAPI framework creates instances of this class to
represent each valid ATA/ATAPI device detected during
ATA bus scanning. When an instance of this class is registered with
IOKit, the instance will be presented to clients which
'match' the IOATADevice class.
*/

/*!
@enum ATADeviceType
Defines ATA/ATAPI Device types.
@constant kATADeviceNone
Indicates no device installed. 
@constant kATADeviceATA
Indicates ATA type device, i.e. packet protocols not supported.
@constant kATADeviceATAPI
Indicates ATAPI type device, i.e. packet protocols supported.
*/
enum ATADeviceType {

    kATADeviceNone,
    kATADeviceATA,
    kATADeviceATAPI,
    
};

/*!
@enum ATATimingProtocol
Defines supported transport timing. See getTimingsSupported(), selectTiming().
@constant kATATimingPIO
Indicates transport timing is for Programmed I/O.
@constant kATATimingDMA
Indicates transport timing is for DMA.
@constant kATATimingDMA33
Indicates transport timing is for Ultra DMA/33.
@constant kATATimingDMA66
Indicates transport timing is for Ultra DMA/66.
@constant kATAMaxTimings
Indicates number of timing protocols defined.
*/        
enum ATATimingProtocol
{
    kATATimingPIO		= (1 << 0),
    kATATimingDMA     		= (1 << 1),
    kATATimingUltraDMA33	= (1 << 2),
    kATATimingUltraDMA66	= (1 << 3),
    kATAMaxTimings		= 4,

};

/*!
@enum ATAProtocol
Defines supported transport protocols. See getProtocolsSupported().
@constant kATAProtocolNone
Indicates no transport protocol defined.
@constant kATAProtocolSetRegs
Indicates the transport driver should do a Set ATA Registers operation. For this 
protocol, the transport driver sets the requested taskfile registers as indicated 
in the ATATaskfile structure and then reads back the taskfile registers requested.
The transport presumes the device will not generate an interrupt as a result
of this operation.
@constant kATAProtocolPIO
Indicates the transport driver should do a Programmed I/O operation. For this 
protocol, the transport driver sets the requested taskfile registers, and transfers
data to/from the IOATADevice via Programmed I/O operations. The IOATADevice client
can control the direction/amount data transferred by using setPointers() function.
The client can indicate a zero data transfer length to implement non-data transfer
commands such as power-management and set features.
@constant kATAProtocolDMA
Indicates the transport driver should do a DMA I/O operation to the device. For this 
protocol, the transport driver sets the requested taskfile registers, and transfers
data to/from the IOATADevice via DMA operations.
@constant kATAProtocolDMAQueued
Indicates the transport driver should do DMA Queued I/O operations. In this case,
the driver will queue multiple I/O operations at the IOATADevice. Both the device
and the transport driver must support this protocol.
@constant kATAProtocolDMAQueueRelease
Indicates the transport driver should do DMA Queued I/O operations with bus release. 
In this case, the driver will queue multiple I/O operations at the IOATADevice. In
addition this protocol allows Overlap between both devices on the ATA Bus.
@constant kATAProtocolATAPIPIO
Indicates the transport driver should send an use ATAPI packet protocol and transfer
data to/from the device via PIO cycles.
@constant kATAProtocolATAPIDMA
Indicates the transport driver should send an use ATAPI packet protocol and transfer
data to/from the device via DMA cycles.
*/
enum ATAProtocol {

   kATAProtocolNone		= 0,
   kATAProtocolSetRegs		= (1 << 0),
   kATAProtocolPIO		= (1 << 1),
   kATAProtocolDMA		= (1 << 2),
   kATAProtocolDMAQueued	= (1 << 3),
   kATAProtocolDMAQueuedRelease	= (1 << 4),

   kATAProtocolATAPIPIO		= (1 << 16),
   kATAProtocolATAPIDMA		= (1 << 17),
   
};

/*!
@typedef ATATiming
@abstract
Provides the low-level cycle times for the transport timing indicated.
@discussion
See enum ATATimingProtocols for a list of transport timing protocols.
@field timingProtocol
Indicates transport timing the structure refers to. See enum ATATimingProtocol
for a list of transport timings.
@field mode
Indicates the ATA DMA/PIO mode supported. The mode is a number indicating preset
timings for a particular set of timings as defined by the ATA specification.
@field minDataAccess
The minimum time (in nS) that IOW-/IOR- indicates that the data is valid for 16-bit
data transfers. This field does not apply for Ultra/33 and Ultra/66 timings.
@field minDataCycle
The minimum time (in nS) that a full 16-bit data transfer will take, i.e. the time
between consecutive assertions of IOW-/IOR-. For Ultra/33 and Ultra/66 timings
this field indicates the average single cycle time.
@field minCmdAccess
The minimum time (in nS) that IOW-/IOR- indicates that the data is valid for 8-bit
pio command transfers.
@field minCmdCycle
The minimum time (in nS) that a full 8-bit pio data transfer will take, i.e. the time
between consecutive assertions of IOW-/IOR-.
*/
typedef struct ATATiming {

    ATATimingProtocol	timingProtocol;

    UInt32		featureSetting;

    UInt32		mode;
    UInt32		minDataAccess;
    UInt32		minDataCycle;
    UInt32		minCmdAccess;
    UInt32		minCmdCycle;
    UInt32		reserved_3[9];
    
} ATATiming;
 
class IOATAStandardDevice : public IOATADevice
{
public:

/*!
@function allocCommand
@abstract 
Allocates an IOATACommand object for this device.
@discussion 
The client uses the allocCommand() member function to allocate IOATACommand(s)
for an IOATADevice. The client then uses the member functions of 
the IOATACommand to initialize it and send it to the device. A completed IOATACommand
may be reused for subsequent I/O requests or returned to the ATA/ATAPI Family.
@param deviceType
Always specify kIOATADevice.
@param clientDataSize
The client may indicate the size of a per-command data area for its own
use.
*/
     IOATACommand	*allocCommand( IOATADevice *deviceType, UInt32 clientDataSize = 0 );

/*!
@function getUnit
@abstract
Returns the ATA unit number corresponding to this device.
*/
    ATAUnit			getUnit();
    
/*!
@function getDeviceType
@abstract
Returns the type of the corresponding ATA/ATAPI device.
@discussion 
See enum ATADeviceType for return values for this function. 
*/   
    ATADeviceType		getDeviceType();
    
/*!
@function getIdentifyData
@abstract 
Returns the ATA/ATAPI Identify data for the IOATADevice
@discussion
Identify data is from the results of the last ATA bus probe.
@param identifyBuffer
Pointer to a 512-byte data buffer to receive the ATA/ATAPI Identify data.
*/  
    bool			getIdentifyData( ATAIdentify *identifyBuffer );
    
/*!
@function getInquiryData
@abstract 
Returns ATAPI Inquiry data for the IOATADevice. 
@discussion
Inquiry data returned is from the results of the last ATA bus probe.
@param inquiryBufSize
Size of the buffer supplied.
@param inquiryBuffer
Pointer to a buffer to receive the Inquiry data.
*/
    bool			getInquiryData( UInt32 inquiryBufSize, ATAPIInquiry *inquiryBuffer );
    
/*!
@function getDeviceCapacity
@abstract 
Returns the block count and block size of the ATA/ATAPI device. 
@discussion
This function returns the capacity as returned by the ATA Identify command for ATA devices,
and the Read Device Capacity for ATAPI devices. The client should use caution in interpreting
the results of this function since the results are based on the last ATA bus scan.
@param blockMax
Pointer to a (UInt32) to receive the maximum addressable block on the device. Note: The device
block count is one greater than the maximum addressable block number.
@param blockSize
Pointer to a (UInt32) to receive the block size of the device in bytes.
*/    
    bool 			getDeviceCapacity( UInt32 *blockMax, UInt32 *blockSize );
    
    
/*!
@function getProtocolSupported
@abstract 
Returns a bit mask of transport protocols this IOATADevice supports.
@discussion
There is no guarantee that a particular device/driver combination will support
all transport protocols defined. The IOATADevice client must use this function
to determine which ATAProtocol values are valid for this device.
@param protocolsSupported
Pointer to a (UInt32) to receive a bit mask of transport protocols supported. See enum
ATAProtocol of a list of transport protocols.
*/
    bool			getProtocolsSupported( ATAProtocol *protocolsSupported );
    
/*!
@function getTimingsSupported
@abstract
Returns a bit mask of transport timings this IOATADevice supports
@discussion
There is no guarantee that a particular device/driver combination will support
all transport timings defined. The IOATADevice client must use this function
to determine which ATATimingProtocol values are valid for this device.
@param protocolsSupported
Pointer to a (UInt32) to receive a bit mask of transport timings supported. See enum
ATATimingProtocol of a list of transport timings.
*/
    bool 			getTimingsSupported( ATATimingProtocol *timingsSupported );
    
/*!
@function getTimingSelected
@abstract
Returns the last transport timing selected for the device
@param timingProtocol
Pointer to a (UInt32) to receive the current timing protocol selected. See enum ATATimingProtocol
for a list of transport timing protocols.
*/    
    bool			getTimingSelected( ATATimingProtocol *timingProtocol );
    
/*!
@function getTiming
@abstract
Returns the parameters for the transport timing indicated.
@discussion
If the transport/device combination does not support the transport timing
indicated, then this function will return false. See getTimingsSupported()
to obtain a bit mask of supported timings.
@param timingProtocol
Pointer to a (UInt32) which the client has set to the timing protocol whose parameters are
to be obtained.
@param timing
Pointer to a (struct ATATiming) to receive the parameters (cycle timings) for the requested
timing.
*/    
    bool			getTiming( ATATimingProtocol *timingProtocol, ATATiming *timing );
    
/*!    
@function getATAPIPktInt
@abstract
Returns whether the an ATAPI device will generate an Interrupt prior to signal it is ready
to request a command packet.
@discussion
A return value of (true) will indicates the device will generate a packet transfer interrupt. 
This function would not normally need to be used by the IOATADevice client. It is for use
by the transport driver.
*/
    bool			getATAPIPktInt();

/*!
@function selectTiming
@abstract
Selects the transport timing to be used for this IOATADevice.
@discussion
The IOATADevice client must issue the selectTiming() function when initializing an IOATADevice and
after an ATA Bus Reset event. 
@param timingProtocol
The transport timing to be selected for the device. See getTimingsSupported() for transport timings
supported by the transport/device combination.
@param fNotifyMsg
If fNotifyMsg is set to false, selectTiming() operates a synchronous call, i.e. it blocks the
client until it completes. If the client needs to call this function during an event such as
an ATA Bus Reset, it must use the asynchronous version of this function by setting fNotifyMsg
to true. In this case the client will be notified via a message when this function has
completed.
*/
    bool 			selectTiming( ATATimingProtocol timingProtocol, bool fNotifyMsg = false );
    
/*!
@function holdQueue
@abstract 
Suspends sending additional IOATACommand to this device.
@discussion
holdQueue() may only be called from the IOATADevice workloop. The client
is guaranteed to be running in this context during a message() notification.

holdQueue() has no effect on commands already passed to the host adapter. One
or more commands may complete after the queue is held. See notifyIdle()
@param queueType
Perform action on the indicated queue. See enum ATAQueueType in IOATACommand.
*/
    void			holdQueue( UInt32 queueType );
    
/*!
@function releaseQueue
@abstract
Resumes sending IOATACommands to the IOATADevice. 
@discussion
If the device queue was not held, releaseQueue() has no effect.

releaseQueue() may only be called from the IOATADevice workloop. This is guaranteed
to be the case after a IOATACommand completion of after a message() notification.
@param queueType
Perform action on the indicated queue. See enum ATAQueueType in IOATACommand.
*/    
    void			releaseQueue( UInt32 queueType );
    
/*!
@function flushQueue
@abstract 
Returns any commands on the IOATADevice's pending work queue.
@discussion
flushQueue() may only be called from the IOATADevice workloop. This is 
guaranteed to be the case after a IOATACommand completion of after a 
message() notification.

All pending command are completed prior to flushQueue() returning to the caller.

flushQueue() has no effect on commands already passed to the host adapter. One
or more commands may complete after the queue is flushed. See notifyIdle().
@param queueType
Perform action on the indicated queue. See enum ATAQueueType in IOATACommand.
@param rc
The return code of any flushed commands is set to (rc).
*/    
    void			flushQueue( UInt32 queueType, IOReturn rc );
    
/*!
@function notifyIdle
@abstract
Notifies the client when all active commands on an ATA device have completed.
@discussion
notifyIdle() may only be called from the IOATADevice workloop. This is guaranteed
to be the case after a IOATACommand completion of after a message() notification.

Only one notifyIdle() call may be active. Any outstanding notifyIdle() calls may
be cancelled by calling notifyIdle() with no parameters.
@param target
Object to receive the notification. Normally the client's (this) pointer.
@param callback
Pointer to a callback routine of type CallbackFn.
@param refcon
Pointer to client's private data.
*/   
    void			notifyIdle(  void *target = 0, CallbackFn callback = 0, void *refcon = 0 );

/*!
@function getWorkLoop
@abstract
Returns the IOWorkLoop object that services this IOATADevice.
*/
IOWorkloop *getWorkLoop();

};