/* * Copyright (c) 1998-2008 Apple 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 _IOATACONTROLLER_H #define _IOATACONTROLLER_H #include #include #include #include #include #include "ATATimerEventSource.h" class IOATADevice; class IOATABusCommand; class IOATABusInfo; class IOATADevConfig; /*! @class IOATAController @abstract The base class for ata controller family. Provides the interface common to all ata bus controllers. @discussion Subclasses of IOATAController implement drivers for specific bus hardware. Disk devices are clients of IOATAController and communicate via the IOATABusNub instantiated for each device discovered by the specific IOATAController subclass when it probes hardware. Via the nub, the ATA Controller provides standard information about bus capability, accepts requests for transfer mode configuration (timing), accepts requests for IO and bus operations, notifies the device driver about bus events which may affect the device, such as soft-resets or device removal (ie, media-bay and PC-card) and removal of queued IO requests which have not been dispatched into the hardware. @discussion The header doc for this class is incomplete. The source however is heavily commented and should be consulted until such time as complete header doc is available. */ class IOATAController : public IOService { OSDeclareDefaultStructors(IOATAController); public: /*--- Common ATA Controller Interface ---*/ // find out bus capability virtual IOReturn provideBusInfo( IOATABusInfo* infoOut); // set and get bus timing configuration for a specific unit virtual IOReturn selectConfig( IOATADevConfig* configRequest, UInt32 unitNumber); virtual IOReturn getConfig( IOATADevConfig* configRequest, UInt32 unitNumber); // The main call puts something on the work loop virtual IOReturn executeCommand( IOATADevice* nub, IOATABusCommand* cmd); /*-- Power Management ---*/ // TBD /*--- Overrides from IOService ---*/ virtual bool init(OSDictionary * properties); virtual IOService* probe( IOService* provider, SInt32* score ); virtual bool start( IOService* provider ); protected: enum { kBusFree = 'free', // bus is available kBusBusy = 'busy', // bus is busy with request kQueueOpen = '!lck', // queue is not locked kQueueLocked = 'LOCK', // queue is frozen and not kImmediateLocked = '!Imd', // immediate commands may not be processed kImmediateOK = 'Immd' // immediate commands allowed. }; /* Transaction State indicator definition - indicates what action is next*/ enum transState { kATAInitial = 0x00, // in queue kATAStarted = 0x01, // issue taskfile kATAPICmd = 0x02, // issue packet kATADataTx = 0x03, // data transfer phase kATAStatus = 0x04, // read status kATAComplete = 0x05, // io complete kATADone = 0x06 // completion callout called }; struct ataDevInfo { ataDeviceType type; // ata, atapi, unknown atapiConfig packetSend; // slow DRQ, IRQ, or fast DRQ for packet }; struct ataDoubleBuffer { IOPhysicalAddress physicalBuffer; IOLogicalAddress logicalBuffer; IOByteCount bufferSize; }; IOService* _provider; IOWorkLoop* _workLoop; IOCommandGate* _cmdGate; ATATimerEventSource* _timer; queue_head_t _commandQueue; IOATABusCommand* _currentCommand; UInt32 _busState; UInt32 _queueState; UInt32 _immediateGate; ataUnitID _selectedUnit; ataDevInfo _devInfo[2]; IOATADevice* _nub[2]; ataDoubleBuffer _doubleBuffer; IOATARegPtr8 _tfFeatureReg; IOATARegPtr8 _tfSCountReg; IOATARegPtr8 _tfSectorNReg; IOATARegPtr8 _tfCylLoReg; IOATARegPtr8 _tfCylHiReg; IOATARegPtr8 _tfSDHReg; IOATARegPtr8 _tfStatusCmdReg; IOATARegPtr16 _tfDataReg; IOATARegPtr8 _tfAltSDevCReg; // false if couldn't allocate the per-bus double buffer. // controllers should provide implementation where needed // for DMA hardware compatibility. The default method provides // a 4K buffer for PIO since MemoryDescriptors do not by default have // logical addresses in the kernel space. virtual bool allocateDoubleBuffer( void ); // perform 2-byte endian swap. Only useful on PIO transfers and identify data virtual void swapBytes16( UInt8* dataBuffer, IOByteCount length); /*! @function handleCommand @abstract Called by executeCommand() to handle the client command from the workloop context. @param command The command code. @param param1 Command parameter. @param param2 Command parameter. @param param3 Command parameter. @result kIOReturnSuccess on success, or an error code otherwise. */ virtual IOReturn handleCommand( void * command, void * param1 = 0, void * param2 = 0, void * param3 = 0); /*! @function busCanDispatch @abstract answers whether the bus is in state such that the next command can be dispatched. @result true - bus is free to issue commands. false - bus cannot issue commands at this time. */ virtual bool busCanDispatch( void ); /*! @function dispatchNext @abstract Causes the command at the front of the queue to dequeue, made the current command and begin execution. @result noErr indicates successful dispatch. */ virtual IOReturn dispatchNext( void ); // sets the result code, free's the bus state, dispatch next command and execute completion virtual void completeIO( IOReturn commandResult ); // Command queue handlers. virtual IOReturn enqueueCommand( IOATABusCommand* command); virtual IOATABusCommand* dequeueFirstCommand( void ); // event notifier for clients virtual void executeEventCallouts( ataEventCode event, ataUnitID unit); // default handler for device interrupts. virtual IOReturn handleDeviceInterrupt( void ); // timer functions // starts the timeout on the current command virtual IOReturn startTimer( UInt32 inMS); //disable and clear a running timer. virtual void stopTimer( void ); // called when a timeout occurs. virtual void handleTimeout( void ); // true if the timer has expired virtual bool checkTimeout( void ); // handle IO opcodes virtual IOReturn handleExecIO( void ); virtual IOReturn handleRegAccess( void ); virtual IOReturn handleBusReset(void); virtual IOReturn handleQueueFlush( void ); // various protocol phases virtual IOReturn asyncData(void); virtual IOReturn asyncStatus(void); virtual IOReturn asyncIO(void); virtual IOReturn asyncCommand(void); virtual IOReturn synchronousIO(void); // hardware access virtual IOReturn selectDevice( ataUnitID unit ); virtual IOReturn issueCommand( void ); virtual IOReturn writePacket( void ); virtual IOReturn softResetBus( bool doATAPI = false ); virtual IOReturn startDMA( void ); virtual IOReturn stopDMA( void ); virtual bool ATAPISlaveExists( void ); virtual UInt32 scanForDrives( void ); virtual bool waitForU8Status (UInt8 mask, UInt8 value); virtual IOByteCount readATAPIByteCount( void ); virtual void handleOverrun( IOByteCount length); virtual IOReturn registerAccess(bool isWrite); // PIO data transfers virtual IOReturn txDataIn (IOLogicalAddress buf, IOByteCount length); virtual IOReturn txDataOut (IOLogicalAddress buf, IOByteCount length); virtual IOATAController::transState determineATAPIState(void); // device should set the controller to the config for this device virtual void selectIOTiming( ataUnitID unit ); // subclasses MUST implement this function in order to initialize // the pointers to the ATA task file registers during start() time. virtual bool configureTFPointers(void); // convert a bit-significant indicator to a numeric value. virtual UInt16 bitSigToNumeric( UInt16 binary); // for 48 bit register reading and writing UInt16 readExtRegister( IOATARegPtr8 inRegister ); void writeExtRegister( IOATARegPtr8 inRegister, UInt16 inValue ); // overrides virtual void free(); private: // used called by the commandgate in executeCommand. static void executeCommandAction(OSObject * owner, void * arg0, void * arg1, void * arg2, void * arg3); // callout used by the timer to indicate the timeout failure. static void timeoutOccured( OSObject *owner, IOTimerEventSource *sender); protected: /*! @struct ExpansionData @discussion This structure will be used to expand the capablilties of the IOATAController in the future. */ typedef struct ExpansionData { IOBufferMemoryDescriptor* _doubleBufferDesc; } ExpansionData; /*! @var reserved Reserved for future use. (Internal use only) */ ExpansionData *reserved; private: OSMetaClassDeclareReservedUnused(IOATAController, 0); OSMetaClassDeclareReservedUnused(IOATAController, 1); OSMetaClassDeclareReservedUnused(IOATAController, 2); OSMetaClassDeclareReservedUnused(IOATAController, 3); OSMetaClassDeclareReservedUnused(IOATAController, 4); OSMetaClassDeclareReservedUnused(IOATAController, 5); OSMetaClassDeclareReservedUnused(IOATAController, 6); OSMetaClassDeclareReservedUnused(IOATAController, 7); OSMetaClassDeclareReservedUnused(IOATAController, 8); OSMetaClassDeclareReservedUnused(IOATAController, 9); OSMetaClassDeclareReservedUnused(IOATAController, 10); OSMetaClassDeclareReservedUnused(IOATAController, 11); OSMetaClassDeclareReservedUnused(IOATAController, 12); OSMetaClassDeclareReservedUnused(IOATAController, 13); OSMetaClassDeclareReservedUnused(IOATAController, 14); OSMetaClassDeclareReservedUnused(IOATAController, 15); OSMetaClassDeclareReservedUnused(IOATAController, 16); OSMetaClassDeclareReservedUnused(IOATAController, 17); OSMetaClassDeclareReservedUnused(IOATAController, 18); OSMetaClassDeclareReservedUnused(IOATAController, 19); OSMetaClassDeclareReservedUnused(IOATAController, 20); }; #endif /* !_IOATACONTROLLER_H */