SW Driver User Manual For Marvell Serial ATA Host Adapters
SW Driver User Manual For Marvell Serial ATA Host Adapters
SW Driver User Manual For Marvell Serial ATA Host Adapters
Doc. No. MV-S800188-00, Rev. A July 26, 2005 Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
Document Conventions
Note Provides related information or information of special importance. Caution Indicates potential damage to hardware or software, or loss of data. Warning Indicates a risk of personal injury.
Document Status
Doc Status: Preliminary Technical Publication: 0.x For further infromation about Marvell products, see the Marvell website: http://www.marvell.com
For further information about Marvell products, see the Marvell website: http://www.marvell.com
Disclaimer No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose, without the express written permission of Marvell. Marvell retains the right to make changes to this document at any time, without notice. Marvell makes no warranty of any kind, expressed or implied, with regard to any information contained in this document, including, but not limited to, the implied warranties of merchantability or fitness for any particular purpose. Further, Marvell does not warrant the accuracy or completeness of the information, text, graphics, or other items contained within this document. Marvell products are not designed for use in life-support equipment or applications that would cause a life-threatening situation if any such products failed. Do not use Marvell products in these types of equipment or applications. With respect to the products described herein, the user or recipient, in the absence of appropriate U.S. government authorization, agrees: 1) Not to re-export or release any such information consisting of technology, software or source code controlled for national security reasons by the U.S. Export Control Regulations ("EAR"), to a national of EAR Country Groups D:1 or E:2; 2) Not to export the direct product of such technology or such software, to EAR Country Groups D:1 or E:2, if such technology or software and direct products thereof are controlled for national security reasons by the EAR; and, 3) In the case of technology controlled for national security reasons under the EAR where the direct product of the technology is a complete plant or component of a plant, not to export to EAR Country Groups D:1 or E:2 the direct product of the plant or major component thereof, if such direct product is controlled for national security reasons by the EAR, or is subject to controls under the U.S. Munitions List ("USML"). At all times hereunder, the recipient of any such information agrees that they shall be deemed to have manually signed this document in connection with their receipt of any such information. Copyright 2005. Marvell International Ltd. All rights reserved. Marvell, the Marvell logo, Moving Forward Faster, Alaska, Fastwriter, GalNet, Libertas, Link Street, NetGX, PHYAdvantage, Prestera, Virtual Cable Tester, and Yukon are registered trademarks of Marvell. AnyVoltage, Discovery, DSP Switcher, Feroceon, GalTis, Horizon, RADLAN, Raising The Technology Bar, The Technology Within, UniMAC, and VCT are trademarks of Marvell. All other trademarks are the property of their respective owners.
CONFIDENTIAL
Document Classification: Proprietary Information
Table of Contents
Section 1.
1.1 1.2 1.3 1.4 1.5 1.6 1.7
Introduction .................................................................................................................................. 7 CORE Driver................................................................................................................................ 9 System-Dependent Header File (mvOs.h)................................................................................... 9 SCSI to ATA Translation Layer (SAL) .........................................................................................9 Common Intermediate Application Layer Tasks (Common IAL)................................................ 10 Intermediate Application Layer (IAL) ......................................................................................... 10 Application Layers ..................................................................................................................... 11
Section 2.
2.1 2.2 2.3 2.4 2.5
System Integration............................................................................ 12
Introduction ................................................................................................................................ 12 System Integration Using Only CORE Driver ............................................................................ 12 System Integration Using CORE Driver, SCSI to ATA Translation Layer, and Common IAL Layers.................................................................................................................................. 20 System Integration by Example ................................................................................................. 21 Miscellaneous Issues................................................................................................................. 23
Section 3.
3.1 3.2 3.3 3.4 3.5
Introduction ................................................................................................................................ 29 Linux IAL SMART (Self-Monitoring, Analysis, and Reporting Technology) Support ................. 30 Building and Running the Project ..............................................................................................32 Linux IAL SCSI Host Template Driver API................................................................................. 36 Linux IAL Extension Library ...................................................................................................... 36
Section 4.
4.1 4.2
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
Section 5.
5.1 5.2
Section 6.
6.1 6.2 6.3 6.4 6.5 6.6
Core Driver......................................................................................... 44
Introduction ............................................................................................................................... 44 CORE Driver API and Data Structures Summary ..................................................................... 45 Compile-Time CORE Driver Configuration ............................................................................... 49 CORE Driver API User Implementation Requirements and Restrictions .................................. 51 Detailed CORE Driver Implemented API and Data Structures ................................................. 52 System-Dependent Header File (mvOs.h) ................................................................................ 80
Section 7.
7.1 7.2 7.3 7.4 7.5 7.6 7.7 7.8 7.9
Introduction ............................................................................................................................... 88 Architecture ............................................................................................................................... 88 SAL API Summary .................................................................................................................... 88 SAL SCSI Characteristics ......................................................................................................... 88 Internal Implementation............................................................................................................. 90 SCSI to ATA Commands Translation Table.............................................................................. 91 ATA to SCSI Error Translation .................................................................................................. 91 SAL Integration ......................................................................................................................... 93 SAL API..................................................................................................................................... 94
Section 8.
8.1 8.2 8.3 8.4 8.5
Introduction ............................................................................................................................... 99 Common IAL Basic Design and Integration Guidelines ............................................................ 99 Common IAL Function API and Data Structures Summary .................................................... 100 Common IAL Internal State Diagrams .................................................................................... 103 Detailed IAL Function API and Data Structures ...................................................................... 106
Section 9.
CONFIDENTIAL
Document Classification: Proprietary Information
List of Tables
Table 1: Table 2: Table 3: Table 4: Table 5: Table 6: Table 7: Table 8: SMART Command Input Buffer..........................................................................................................31 Supported SCSI Commands ..............................................................................................................89 SCSI to ATA Commands Translation.................................................................................................91 ATA to SCSI Error Translation ...........................................................................................................92 Enumerators.......................................................................................................................................94 Enumerator Values.............................................................................................................................95 State Table Description ....................................................................................................................103 Revision History ...............................................................................................................................115
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
List of Figures
Figure 1: Figure 2: Figure 3: Figure 4: Figure 5: Figure 6: Serial ATA Host Adapter Software Driver Architecture ....................................................................... 8 Channel-to-Channel Communication Driver Support in the Core Driver ........................................... 25 Linux IAL Driver Architecture ............................................................................................................ 29 BIOS IAL Driver Architecture............................................................................................................. 41 CORE Driver API and Data Structures Block Diagrams.................................................................... 45 Common IAL API and Data Structures Block Diagram ................................................................... 101
CONFIDENTIAL
Document Classification: Proprietary Information
Architectural Specification
Introduction
1.1 Introduction
The Serial ATA Host Adapter is a PCI/PCI-X to 4/8 port Serial ATA (SATA) adapter that provides connectivity to SATA storage devices. This document describes the software driver architecture of the Serial ATA Host Adapter. This architecture provides the system integrator (referred to in the driver documentation as the "user") to ramp up a system better and faster, using the Serial ATA Host Adapter, without the need for thorough knowledge of the adapter itself. The Serial ATA Host Adapter software driver architecture consists of the following components: (from bottom to top): CORE driver System dependent header file (mvOs.h) SCSI to ATA translation layer (SAL) Common Intermediate Application Layer Tasks (Common IAL) Intermediate Application Layer (IAL) Application Layers
1.1.1
Relevant Devices
This document is relevant for the following devices: 88SX5040, 88SX5041, 88SX5080, and 88SX5081, which are referred to as 88SX50xx. 88SX6081 and 88SX6041, which are referred to as 88SX60x1 88SX6042 and 88SX7042 Note The 88SX60x1 devices are the third generation of Marvell PCI to SATA host controllers. Note that the software described in this document uses the enumerator MV_SATA_GEN_II to refer to these devices. The 88SX6042 and 88SX7042 are the fourth generation of Marvell PCI to SATA host controllers. Note that the software described in this document uses the enumerator MV_SATA_GEN_IIE to refer to these devices.
1.1.2
Relevant Documents
For further information regarding the Serial ATA Host Adapter, see the following datasheets: 88SX5040, 88SX5041, 88SX5080, and 88SX5081 PCI/PCI-X to 8-Port/4-Port Serial ATA Host Controller (Document Control number MV-S101357-00). 88SX6081 and 88SX6041 PCI/PCI-X to 8-Port/4-Port Serial-ATA II Storage Controllers (Document Control Number MV-S101495-00). 88SX6042 and 88SX7042 PCI/PCI-X and PCI-E to 4-Port Serial-ATA STorage Controller (Document Control Number MV-S102305-00).
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
Figure 1:
Application Layers
Hardware
CONFIDENTIAL
Document Classification: Proprietary Information
Architectural Specification
CORE Driver
Note The Serial ATA Host Adapter CORE driver is completely ANSI-C compliant source code.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
The SCSI to ATA translation layer provides the following functionality: Translation of certain SCSI commands with immediate completion (without queuing to CORE driver). Translation of certain SCSI commands to ATA and then further queuing to CORE driver. Error reporting of failing SCSI commands through SCSI sense code. Note The SCSI to ATA translation layer is tested with external tools that cover all cases and options of the supported SCSI commands.
CONFIDENTIAL
Document Classification: Proprietary Information
Architectural Specification
Application Layers
IAL connects to ATA subsystem: In this case, the IAL functions as glue software for delivering the ATA commands received from the ATA subsystem to the CORE driver. IAL does not connect to application layers: This case can be used for verification of a single or multiple Serial ATA Host Adapters in a newly integrated system.
The IAL provides the following functionality: From the Application layers point of view: Representation of Serial ATA Host Adapters and their channels and storage devices to the Application layers. Proper command and request reception from the Application layers and proper completion of them. Proper error propagation of events to the Application layers From the CORE driver APIs point of view: Trigger Serial ATA Host Adapter initialization sequences through the CORE driver API. Management of Serial ATA Host Adapter SATA channels and the storage devices connected to them, through the CORE driver API. Translation/Delivery/Generation of ATA commands and their delivery to hardware, through the CORE driver API. Proper scheduling of commands and requests to hardware, through the CORE driver API. Error handling and reporting, through the CORE driver API call-back functions. Calls CORE driver ISR function. From the SAL APIs point of view: Forwarding SCSI commands to SAL for execution by the Serial ATA Host Adapter. From the Common IAL APIs point of view: Trigger of storage device discovery and initialization sequences. Parsing of IDENTIFY DEVICE ATA buffer response.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
2.1 Introduction
This section describes methods of integrating the OS-independent components of the Marvell Serial ATA host bus adapter software layers into a user-specific software driver. It is divided into two main sections: System integration using only CORE driver (described in Section 2.2). System integration using CORE driver, SCSI to ATA translation layer, and Common IAL layer (described in Section 2.3). An example of system integrationMarvell Windows SCSI-port (described in Section 2.4)is provided. This example is based on the system integration method described in Section 2.3). Section 2.5 "Miscellaneous Issues" has miscellaneous issues involving system integration issues. The OS-independent components discussed in this section are: CORE driver: Provides low-level access to hardware with queuing interface and interrupt service routine (see Section 6. "Core Driver" on page 44). SCSI to ATA translation layer: Provides functionality for translating SCSI commands to ATA commands and queuing capability to hardware using the CORE driver (see Section 7. "SCSI to ATA Translation Layer" on page 88). This functionality is usually required when IAL connects to SCSI subsystems. Common IAL layer: Provides functionality usually required by IALs. The code is written in OS-independent coding style (see Section 8. "IAL Common Layer" on page 99). Note This document refers to the software layers that control all the OS-independent components as "high" layers or "higher" layers. These software layers consist of the IAL and additional higher layers.
CONFIDENTIAL
Document Classification: Proprietary Information
System Integration
System Integration Using Only CORE Driver
2.2.1
This file includes macros and possibly function calls that provide the CORE driver with the capability to access system resources. This file is user-supplied. For details see Section 6.6 "System-Dependent Header File (mvOs.h)" on page 80.
2.2.2
Higher layers scan the PCI bus/buses for detection of Serial ATA Host Adapters. For each adapter found the following steps must be performed by higher layers: 1. Initializes the Base Addresses registers (BARs) found in each adapters PCI configuration space (BAR). 2. The system integrator must decide if register access to Serial ATA Host Adapter is performed through I/O-BAR or Memory-BAR (and accordingly define the register access in the mvOs.h file). 3. Enable memory and I/O accesses to adapter and enable adapters master capability (bits 0, 1, and 2 in Command register in PCI configuration space). 4. Allocate and initialize (assign zero to all fields) the MV_SATA_ADAPTER data structure and 4/8 MV_SATA_CHANNEL data structures (depending on the amount of serial ATA channels the adapter supports). 5. Allocate 4/8 request and response queues (1 KByte for each request queue and 256 bytes for each response queue. If the 128 EDMA entries mode is selected for the 88SX6042/88SX7042, the request queue size is 4 KByte and the response queue size is 1 KByte). See the Serial ATA Host Adapter datasheets regarding alignment restrictions that each request/response queue must have. Note The request and response queues must be cache-coherent. For systems that have hardware cache coherency assist, the allocation for request and response queues is a simple memory allocation that is reachable by the adapter from PCI address space. For systems that dont have cache coherency hardware assist, allocate request and response queues that have non-cacheable attributes when being accessed. 6. Set the MV_SATA_ADAPTER data structure variables: a) Set the adapterId field for a value unique to that specific Serial ATA Host Adapter. (In debug mode this field is used by the CORE driver for log messages.) b) Set the adapter pciConfigDeviceId to the PCI device ID of the adapter, as reported on the adapters PCI configuration space. c) Set the adapter pciConfigRevisionId to the PCI revision ID of the adapter, as reported on the adapters PCI configuration space. d) Set the adapterIoBaseAddress field to the CPU address that enables access from the CPU to the specific Serial ATA Host Adapter adapter being initialized. The address can be mapped into either memoryBAR or IO-BAR. e) Set intCoalThre and intTimeThre threshold fields to the required values for using the interrupt coalescing mechanism. Setting them both to zero indicates that interrupt coalescing thresholds are set to minimum, which achieves the same results as disabling them. f) Set the mvSataEvetNotify field to point to the user-implemented function used by the CORE driver as a callback function for event notification. g) Set the sataChannel pointer to zero.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
h) Set pciCommand, pciSerrMask and pciInterruptMask to the required values. (See the Serial ATA Host Adapter datasheet for further information about these fields.) 7. Call the mvSataInitAdapter() function to start initialization of the adapter. See Section 6.5.3.1 "CORE Driver Adapter Management" on page 57) for an explanation of the functionality of mvSataInitAdapter().
8.
Set up the adapters interrupt line to trigger a higher layers interrupt service routine wrapper upon interrupt generation. 9. If the adapter supports staggered spinup, start an OOB sequence by calling either mvSataEnableStaggeredSpinUp() per serial ATA channel for performing an OOB sequence on the serial ATA channels one by one, or alternatively call the mvSataEnableStaggeredSpinupAll() function to perform an OOB sequence of all serial ATA channels in parallel. 10. Call the mvSataUnmaskAdapterInterrupt() function to enable interrupt assertion by the adapter.
2.2.3
After the hardware detection and initialization described above has been completed, there are two possible states per SATA channelconnected or disconnected. If a specific SATA channel is not connected, then there is no need for further initialization of the specific SATA channel.
Note To determine whether the SATA channel is connected to/disconnected from a storage device, use the mvSataIsStorageDeviceConnected()CORE driver function. If a SATA channel is connected, then higher layers must perform the following algorithms to detect and initialize the storage device connected to the specific SATA channel: 1. 2. 3. 4. Storage device discovery algorithm: Checks whether the SATA channel is directly connected to a hard drive or to a port multiplier. Initialization of hard drive algorithm: Reads the hard drives IDENTIFY DEVICE data, parses the data, and accordingly issues SET FEATURES ATA commands. Initialization of port multiplier: This algorithm is a preparation algorithm to perform the "Initialization of hard drive algorithm" for each hard drive connected to the device SATA ports of the port multiplier. Configuring EDMA mode.
2.2.3.1
1.
This is the first algorithm to be executed when a Serial ATA channel is connected. From the MV_SATA_CHANNEL data structures allocated in Section 2.2.2 "Hardware Detection, Adapter, and CORE Driver Initialization" initialize the MV_SATA_CHANNEL data structure corresponding to the SATA channel being initialized as follows: a) Set corresponding sataChannel pointers in MV_SATA_ADAPTER channel to point to the MV_SATA_CHANNEL chosen. b) Set channelNumber to the index number of the SATA channel. c) Set the requestQueue, requestQueuePciHiAddress, and requestQueuePciLowAddress fields to point to the request queue allocated in Section 2.2.2 "Hardware Detection, Adapter, and CORE Driver Initialization" . The requestQueue parameter is the CPU address to the request queue and
CONFIDENTIAL
Document Classification: Proprietary Information
System Integration
System Integration Using Only CORE Driver
4.
5. 6.
2.2.3.2
The algorithm described in this section is intended for port multiplier initialization. This is a preparation algorithm, which detects the number of SATA channels the port multiplier has, and for each SATA channel, initializes the hard drive connected to it (if any). The higher layers must perform the following steps: 1. Query the port multiplier regarding its vendor, features and capabilities. As a result of the query the higher layers know how many device ports are connected to the port multiplier. See the mvGetPMDeviceInfo() function in the Common IAL layer (Section 8.5.2.1 "Common IAL Helper Functions" on page 108) for reference on how to perform the query. 2. For all device ports on the port multiplier, perform the following: a) Trigger an OOB sequence on the device port of the port multiplier. This can be achieved by calling mvPMDevEnableStaggeredSpinUp(), or alternatively calling mvPMDevEnableStaggeredSpinUpAll(), which triggers an OOB sequence on all device ports of the port multiplier. b) Read the Status register of the port multipliers device port (using the mvPMDevReadReg() CORE driver function). If a hard drive is connected to the port multipliers device port, perform the following steps. Otherwise skip to the next port multipliers device port.
Clear the SError register of the port multipliers device port (using the mvPMDevWriteReg() CORE driver function). This enables the hard drive to send FISes to the adapters host port. Perform the algorithm described in Section 2.2.3.3 "Initialization of Hard Drive Algorithm" for the specific port multipliers device port. Continue initialization of the next hard drives connected to the other port multipliers device ports.
2.2.3.3
The algorithm described in this section initializes a hard drive. The algorithm can be executed when the hard drive is either connected directly to the adapters SATA channel or through the port multipliers device port. For the first option, when the hard drive is connected directly to the adapter, perform the algorithm described in this section, then perform the steps described in Section 2.2.3.4 "Configuring EDMA Mode" .
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
For the second option, every function call to the CORE drivers functions must have the port multipliers device port as an input to the function. The higher layers must perform the following steps: 1. Initiate the software reset protocol using the mvStorageDevATAStartSoftResetDevice() CORE driver function. If the adapter supports port multiplier, then the destination port multiplier port must be port 15 (0xF), otherwise the destination port must be 0 (default). Note that after software reset protocol has been completed, the ATA Status register equals 0x80, which indicates disk busy. 2. Poll and wait for signature FIS to arrive (aka register device to host FIS or FIS 34). The polling can be achieved by calling mvStorageIsDeviceBsyBitOff(), which reads the ATA Status register and returns MV_TRUE if the BSY bit switched from 1 to 0. Note Steps #1 and #2 above can be automated by calling the mvStorageDevATASoftResetDevice() CORE driver function, which initiates a software reset protocol and polls until FIS 34 is received. The problematic issue is that a hard drive may be in its mechanics initialization state, thus it may take a few seconds until it has been completed. Due to this, the higher layer developer is encouraged to have a timerbased polling mechanism that as its first step initiates a software reset protocol, but the polling for reception of FIS 34 can be used with timer based polling methods that releases the CPU for performing other tasks. 3. 4. Execute the IDENTIFY DEVICE ATA command (using the mvStorageDevATAIdentifyDevice() CORE driver function). Parse the IDENTIFY DEVICE data buffer and accordingly set the hard drives parameters such as UDMA speed, write cache, read ahead, etc.
2.2.3.4
Configure each SATA channels EDMA mode using the information collected from the IDENTIFY DEVICE data buffers (see Section 2.2.3.3 "Initialization of Hard Drive Algorithm" ). This can be achieved by calling the mvSataConfigEdmaMode() CORE driver function.
2.2.4
After adapter detection and initialization, when the storage devices detection and initialization phases have been completed, the adapter and hard drives connected to it are ready for command queuing and execution.
2.2.4.1
The command queuing is performed using the mvSataQueueCommand() CORE driver function. If the command is UDMA read/write then the IAL must provide as input to the mvSataQueueCommand() function, a PRD table which is a scatter-gather table (see Section 6. "Core Driver" ). The UDMA commands are executed solely by the adapters EDMA engine, from the point of view of queuing to hardware, data transfer, and completion. The PIO commands are performed by the CORE driver. When the outstanding commands issued to the CORE driver have mixed PIO and UDMA commands, the CORE driver identifies the command and automatically switches between EDMA enabled mode for UDMA commands execution, and EDMA disabled mode for PIO commands execution.
CONFIDENTIAL
Document Classification: Proprietary Information
System Integration
System Integration Using Only CORE Driver
Note Higher layers can optionally call the mvSataNumOfDmaCommands() CORE driver function, which returns the number of outstanding commands on the specific SATA channel. Using the return value, the higher layers can be signalled as to whether the SATA channel has empty slots for further command queuing.
2.2.4.2
Command Completion
Command completion is done using a callback function called by the CORE driver, which is a higher layers function, to indicate completion of a specific command. The completion can have different status indication successful completion and erroneous completion. Usually the command completion scheme is triggered by the adapters interrupt notifying higher layers of a specific event. The higher layers call the CORE driver mvSataInterruptServiceRoutine() function, which interrogates the adapter and response queues, and upon recognition of completion the CORE driver calls a callback function with the statuses. The callback function is per command and it is defined in the command, when issued to the CORE driver using the mvSataQueueCommand() function. The CORE driver supports three types of command completion schemes. At any time a single scheme is valid. The higher layers are allowed to change the command completion scheme, but when they do scheme switching, higher layers must make sure that no outstanding commands are queued to the adapter.
Note To enable this scheme, the higher layers must call the mvSataSetInterruptScheme() function after
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
4. 5. 6. 7. 8.
If the return value is MV_TRUE, then higher layers schedules a task in which the actual interrupt handling will be done. Note that if the return value is MV_TRUE, then the mvSataCheckPendingInterrupt() function has already masked the adapters interrupts. Higher layers ISR exits. Scheduled task is executed after the higher layers ISR exits. Task calls the mvSataInterruptServiceRoutine() CORE driver function. The mvSataInterruptServiceRoutine() function interrogates the adapter and response queues and accordingly calls the callback function for completion. The mvSataInterruptServiceRoutine() function unmasks the adapters interrupts before exiting.
Notes To enable this scheme, the higher layers must call the mvSataSetInterruptScheme() function after mvSataInitAdapter() has been called. When this scheme is enabled, higher layers must make sure that mvSataUnmaskAdapterInterrupts()has not been called, or if it has been called previously, then mvSataMaskAdapterInterrupts() is called before enabling this scheme.
The following scenario is typical for such a scheme: 1. Higher layers queue command(s) using the mvSataQueueCommand() CORE driver function. 2. Higher layers call the mvSataInterruptServiceRoutine()CORE driver function. 3. The mvSataInterruptServiceRoutine() function interrogates the adapter and response queues and accordingly calls the callback function for completion.
Note Higher layers must not queue new commands in the context of completion callback functions. Higher layers must wait until mvSataInterruptServiceRoutine() exits.Afterwards it is permissible to queue new commands.
2.2.5
Error Handling
When using the CORE driver, the following hardware and software errors may occur: PCI bus error SATA bus errors Hard drives errors Command timeout Software errors
The following section details how the CORE driver handles such errors, using its API.
CONFIDENTIAL
Document Classification: Proprietary Information
System Integration
System Integration Using Only CORE Driver
2.2.5.1
When a PCI bus error occurs and it is detected by the adapter, a PCI interrupt is generated (depending on the pciSerrMask and pciInterruptMask settings defined in Section 2.2.2 "Hardware Detection, Adapter, and CORE Driver Initialization" ). Higher layers must call the mvSataInterruptServiceRoutine() function as part of the interrupt service. Upon PCI bus error the mvSataInterruptServiceRoutine() function calls the mvSataEventNotify() callback function with corresponding parameters, indicating that a PCI bus error was detected. It is recommended that upon detection of a PCI bus error, higher layers abort all outstanding commands, re-initialize the adapter and its storage devices, and then retry the aborted commands.
2.2.5.2
Depending on the adapter, a SATA bus error can be identified using different methods. For example, for a 88SX50XX device, if an UDMA command was completed with the ERR bit equal to 1 in ATA status, and the ATA ERROR register equals 0x0C or 0x14, then this means that a SATA bus error occurred in the middle of execution of a command. (The command is completed via the completion callback function of the specific failed command). The higher layers can also periodically poll the SError registers on all the adapters SATA channels, to identify serial ATA bus errors. It is recommended that upon detection of a serial ATA bus error, all outstanding commands be aborted and retried.
2.2.5.3
Upon completion of a failed command due to a hard drive error (for example UNC error), the CORE driver calls the callback function with error indication. Depending on the type of failure, higher layers must decide which actions should be done next.
2.2.5.4
Command Timeout
When higher layers issue a command to the CORE driver, it is recommended to allocate a timeout period for each specific command. When a commands timer expires, it is recommended that the higher layers perform the following for the specific SATA channel on which the command timed out: 1. Call the mvSataDisableChannelDma()function. This disables the queuing mechanism. 2. Call mvSataFlushDmaQueue(). This triggers the CORE driver to empty its queue. When each entry is emptied, the CORE driver calls the relevant callback function with abort indication. 3. Call mvSataChannelHardReset(). This resets the adapters specific serial ATA bridge and re-issues an OOB sequence. 4. Trigger the Storage Devices Detection and Initialization algorithm for re-initialization of the SATA channel. (See Section 2.2.3 "Storage Devices Detection and Initialization" .) 5. After re-initialization has been completed, retry the abort commands.
2.2.5.5
Software Errors
The CORE driver has many sanity checks with regards to the parameters that are passed to the CORE driver functions. It is recommended that in the initial stages of system integration, all CORE driver logging messages be enabled. At more advanced stages the CORE driver provides the ability to filter only the error messages and disable all logging messages in the production driver, since they increase the CORE drivers footprint and decreases its performance.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
2.3 System Integration Using CORE Driver, SCSI to ATA Translation Layer, and Common IAL Layers
This system integration method is typical for systems that have SCSI subsystems that initiate SCSI commands. The CORE, SAL, and Common IAL layers can be integrated with the users IAL, thus providing an interface for executing SCSI commands as if the SATA hard drives were SCSI targets. This is done by different functionality provided by the different layers: SAL provides the functionality of translating SCSI commands into ATA commands and an interface for queuing to the CORE driver. CORE driver provides hardware access and ATA command queuing. Common IAL provides the functionality for initializing SATA hard drives. This type of system integration has the following components and tasks that must be fulfilled: Coding of a system-dependent header file (mvOs.h) that enables the CORE driver accessing system resources (described in Section 6.6 "System-Dependent Header File (mvOs.h)" on page 80). Hardware detection; initialization of adapter, CORE, SAL, and Common IAL drivers. Command queuing, execution, and completion. Error handling.
2.3.1
2.3.2
Hardware Detection; Initialization of Adapter, CORE, SAL, and Common IAL Drivers
See Section 2.2.2 "Hardware Detection, Adapter, and CORE Driver Initialization" up to and including calling the mvSataInitAdapter() CORE driver function. Afterwards, higher layers must perform the following steps: 1. Call the mvSataScsiInitAdapterExt()SAL function to initialize the SAL layer. 2. Set up the adapters interrupt line to trigger a higher layers interrupt service routine wrapper upon interrupt generation. 3. Call the mvAdapterStartInitialization() Common IAL function, which starts the initialization process of storage devices connected to the adapters SATA channel. 4. Set up the timer function that is called every 0.5 seconds (or any other configurable variable in Common IAL). The timer function must call the mvIALTimerCallback() Common IAL function.
2.3.3
2.3.3.1
This section describes how SCSI commands are queued, executed, and completed.
When the IAL receives a SCSI command, the IAL checks if it is a SCSI read/write command. If this is the case, then the IAL must build a PRD table for the SCSI command. If the SCSI command is read/write or any other SCSI command, the IAL calls the mvExecuteScsiCommand() function, which handles all translation from SCSI commands to ATA commands, and queuing to the CORE driver.
CONFIDENTIAL
Document Classification: Proprietary Information
System Integration
System Integration by Example
2.3.3.2
Command Completion
When using the SAL, there are several types of command completion: Immediate command completion. In the mvExecuteScsiCommand() function, the SAL calls the callback function. This is indicated by the return value MV_SCSI_COMMAND_STATUS_COMPLETED from mvExecuteScsiCommand(). Command queued to CORE driver. This is indicated by the return value MV_SCSI_COMMAND_STATUS_QUEUED from mvExecuteScsiCommand(). Failure of command execution. Usually this is because the SAL does not support the command being queued. This is indicated by the value MV_SCSI_COMMAND_STATUS_FAILED from mvExecuteScsiCommand(). Queuing in initialization stages. This is usually command queuing due to SATA drives being initialized. When SATA drives initialization has been completed for a specific SATA channel, all SCSI commands that were previously queued with the MV_SCSI_COMMAND_STATUS_QUEUED_BY_IAL return value will be aborted and re-queued by the SCSI subsystem. The command completion status returned by the SAL is a SCSI-like status. Users must map the completion statuses to their specific SCSI subsystem completion statuses.
2.3.4
Error Handling
When using the CORE driver, SAL, and Common IAL, the following hardware and software errors may occur. PCU bus error SATA bus error or hard drives errors Command timeout Software errors
2.3.4.1 2.3.4.2
These errors are reported to the SAL. When such errors occur, the SAL translates the error codes to SCSI-like error codes. Depending on the type of the failure, higher layers must decide on the next actions to be done.
2.3.4.3
Command Timeout
See Section 2.3.4.3 "Command Timeout" . Instead of triggering the Storage Devices Detection and Initialization algorithm, (Section 2.2.3) call the mvRestartChannel() Common IAL function, which performs all the storage devices re-initialization.
2.3.4.4
Software Errors
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
The example is the Marvell Windows SCSI mini-port driver for the Serial ATA Host Adapters.
2.4.1
Hardware Detection
The Windows kernel performs hardware detection in the following manner: 1. Windows calls DriverEntry() function. 2. DriverEntry enables auto-flush mechanism (see Section 6. "Core Driver" for further information about autoflush). 3. DriverEntry initializes a template hwInitializationData data structure that contains all function pointers for hardware initialization, command execution, and interrupt service routine. 4. DriverEntry calls the ScsiPortInitialize() SCSI Port function, each time defining a new PCI device ID from the Serial ATA Host Adapters device list. According to this method, DriverEntry requests that the SCSI Port scan the PCI buses for adapters that have the relevant vendor ID and device ID, and accordingly calls mvFindAdapter().
2.4.2
Hardware Initialization
For each adapter found by the SCSI port driver (as requested by DriverEntry using the ScsiPortInitialize() function), the SCSI port driver calls the mvFindAdapter() function, which performs the following: 1. Initializes the HwDeviceExtension parameters (see Windows DDK). 2. Gets PCI BAR 0 mapping through ScsiPortValidateRange and ScsiPortGetDeviceBase. Note that the Windows kernel has already enabled memory and I/O access to the adapter and has also enabled the adapters capability to be a PCI master. 3. Reads adapters PCI device ID and revision ID. 4. Allocates request and response queues. 5. Initializes the MV_SATA_ADAPTER data structure (which is part of HwDeviceExtension as previously requested by DriverEntry). 6. Calls the mvSataInitAdapter() function. 7. Calls the mvSataScsiInitAdapterExt() function with a pointer to MV_SAL_ADAPTER_EXTENSION, which is also part of HwDeviceExtension, as previously requested by DriverEntry.
2.4.3
The SCSI port calls the mvHwInitialize() function, which triggers storage devices initialization by calling the mvAdapterStartInitialization() Common IAL function.
2.4.4
The SCSI port calls mvStartIO() for executing SCSI commands (and other tasks). If the request was I/O-Control, the IAL handles this request. If the request was executing SCSI command, the IAL checks if the command is a Read or Write SCSI command, in which case the IAL must build a PRD table. Afterwards, the IAL issues a command to the SAL via the mvExecuteScsiCommand() SAL function. The IAL checks the return value of mvExecuteScsiCommand() and accordingly decides wether to call ScsiPortNotification() with NextRequest or NextLuRequest.
CONFIDENTIAL
Document Classification: Proprietary Information
System Integration
Miscellaneous Issues
2.4.5
Upon PCI interrupt from the adapter (or from another adapter sharing the same PCI IRQ), the SCSI port calls the mvInterrupt() function, and mvInterrupt()calls mvSataInterruptServiceRoutine() for interrupt processing. Within mvSataInterruptServiceRoutine() the command completion callback is called for completing the SCSI commands. After mvSataInterruptServiceRoutine() has been completed and has returned MV_TRUE (indicating that the interrupt was generated by the adapter), mvInterrupt() calls the mvSataScsiPostIntService() SAL function. For every SCSI command completed, the IALCompletion() IAL function is called. (This is defined as a callback function for every SCSI command issued to the SAL. The IALCompletion() function maps the corresponding SAL completion status to SCSI port driver-specific status codes.
2.4.6
Upon timeout caused by a non-completed SCSI command (previously issued by the SCSI port driver) the mvResetBus() IAL function is called. The function performs the following: 1. Calls the mvSataDisableChannelDma() CORE driver function to disable queuing. 2. Calls the mvSataFlushDmaQueue() CORE driver function. As a result, all callback functions for the outstanding commands are called with abort indication. 3. Calls the mvSataChannelHardReset() CORE driver function, to reset the SATA bridge and restart an OOB sequence. 4. Calls the mvRestartChannel() Common IAL function, to restart storage device re-initialization.
Upon hotplug event on SATA channel (either connected directly to the adapter or indirectly, through the port multiplier) the user-implemented mvSataEventNotify() function is called with the corresponding event. The event indication can be one of the following: SATA channel connect event on Serial ATA Host Adapter (indicated by MV_SATA_CABLE_EVENT_CONNECT). SATA channel disconnect event on Serial ATA Host Adapter (indicated by MV_SATA_CABLE_EVENT_DISCONNECT) SATA channel connect or disconnect on port multipliers device side SATA channels Serial ATA Host Adapter (indicated by MV_SATA_CABLE_EVENT_PM_HOT_PLUG). The hotplug event on the SATA channel connected directly to the adapter is easier to handle than the indirectly connected channel (through port multiplier) for the following reasons: When the port multiplier sends SDB FIS with the N bit indicating a hotplug event on the port multiplier, there is no indication whether a device SATA channel was connected or disconnected, or on which device side
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
SATA channel it occurred. On the other hand, when the hard drive is directly connected to the adapter, the previous events are reported by the adapter. When the hard drive is disconnected from the port multiplier while it is in the middle of a transaction (either due to PIO command or UDMA command), the command will not be completed. If the hard drive is directly connected and a disconnect event occurs, then the software driver can simply abort the transactions.
Due to the above reasons, it is recommended that upon receipt of a hotplug event on the port multipliers device port, the software drive immediately aborts all outstanding commands and starts storage device re-initialization on the specific SATA channel. Thus at the end of the re-initialization process, the software can determine the reason for the hot plug event and on which device channel it occurred.
2.5.2
The Logger module is a generic debug messages logging mechanism. It is used by the CORE driver, SAL, and Common IAL independently of one another. It is recommended that the IAL also register its debug messages in this logging mechanism. The Logger module produces output messages for debugging, monitoring, and tracking the activity of the SATA adapter driver modules. It uses module identifiers with the required logging level to monitor driver activity. The logging level for each module determines the type of messages being printed for the module. Every driver module may be registered independently to the logger, with the desired logging level. When the logging filter associated with the module matches the level of the current log message, the logger keeps the module name and log filter. It only prints the messages from registered modules. The message output format is "<Module name> (<Debug Level>) <Message body>", i.e. "Core Driver (DEBUG) Issue SRST command" Note The Logger module is implemented as part of the CORE driver. See Section 6. "Core Driver" on page 44 for further information on the API of the Logger module.
2.5.3
The 88SX60x1 adapter supports a channel-to-channel communication feature (aka Target mode). In this mode, the Serial-ATA II ports are used for communication between two 88SX60x1 adapters. The communication channels are not symmetricone side is configured as an initiator while the other side is configured as a target. The communication is carried out based on sending either a message or a block of data (via DMA). An IAL callback function called by the CORE driver as part of the its interrupt service routine indicates that a message was received and/or the SATA channels DMA has been completed. sFigure 2 describes the channel-to-channel communication driver support in the CORE driver.
CONFIDENTIAL
Document Classification: Proprietary Information
System Integration
Miscellaneous Issues
Figure 2:
Initiator host
target host
1. mvSataC2CActivateBmDma
2. mvSataC2CSendRegisterDeviceToHostFIS
1. mvSataC2CSendRegisterDeviceToHostFIS
2. mvSataC2CActivateBmDma
activateBMDmaMode activateBMDmaMode Send Vendor Unique FIS 34h (Register Device to Host) Send Vendor Unique FIS 34h (Register Device to Host) interrupt Send Vendor Unique FIS 39h(DMA Activate) read write
interrupt
interrupt
interrupt
C2Ccallback (IAL)
interrupt
C2Ccallback (IAL)
interrupt
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
2.5.3.1
The channel-to-channel feature is initialized by calling the mvSataC2CInit() CORE driver function. The IAL calls the function with MV_SATA_C2C_MODE_INITIATOR for the adapter with the initiator SATA channel and MV_SATA_C2C_MODE_TARGET for the adapter with the target SATA channel. When calling the mvSataC2CInit() CORE driver function, the call-back function must be valid for both the initiator and the target. For disabling the channel-to-channel communication feature the IAL can call the mvSataC2CStop() CORE driver function.
2.5.3.2
Both initiator and target can send a message with a size of 10 bytes. The hardware sends this messages using FIS 34 SATA FIS. For sending a message the IAL calls the mvSataC2CSendRegisterDeviceToHostFIS() Core driver function. The receiving SATA channel issues an interrupt and the CORE driver calls the defined call-back function as part of the interrupt handling.
2.5.3.3
The IAL can initiate a block transfer using DMA transfer SATA protocol between the initiator and target SATA channels. The DMA transfer direction can be either from/to the target SATA channel, but the DMA initiation can be triggered only by the initiator SATA channel. The algorithm is as follows: 1. Initiators IAL calls themvSataC2CActivateBmDma() CORE driver function for the initiator SATA channel. This initializes the initiators DMA and waits for DMA Setup FIS from target SATA channel. 2. Initiators IAL calls the mvSataC2CSendRegisterDeviceToHostFIS() Core driver function to send a message to the target channel. The content of the message depends on the IALs implementation. It is recommended that message be unique, so that the driver handling the target SATA channel can recognize it and accordingly set the targets DMA. 3. Software driver that handles the target SATA channel (targets IAL) receives a unique message (triggered by the CORE driver calling the defined call-back function as part of the interrupt handling). 4. Targets IAL calls the mvSataC2CActivateBmDma() CORE driver function for the target SATA channel. The CORE driver sets up the targets SATA channel DMA and sends DMA ACTIVATE FIS to the initiator. 5. Initiator and target SATA channels perform DMA transfer. When the DMA transfer has been completed, both the initiators and targets IALs receive a call-back function call from the CORE driver indicating the completion. 6. Both the initiators and targets IALs call the mvSataC2CResetBmDma() CORE driver after receiving the DMA transfer completion indication.
2.5.3.4
CONFIDENTIAL
Document Classification: Proprietary Information
System Integration
Miscellaneous Issues
2.5.4
I/O-Granularity
The interrupt coalescing in I/O Granularity enables command completion interrupts to be coupled into a single interrupt. This feature can be used in RAID applications. In such applications a single RAID transaction is divided into EDMA transactions to multiple drives and the completion interrupt can be generated as a single interrupt for the entire RAID transaction.
Interrupt Coalescing in I/O Granularity Design Highlights For every I/O transaction, the related I/O transaction counter is updated with the number of SATA commands
related to this I/O transaction. The 88SX60x1 adapter issues a maskable interrupt, when the number of SATA commands executed with a specific I/O transaction number equals the number of SATA commands related to that specific I/O transaction number. The I/O Granularity driver support is capable of switching between two modes of operationswith and without interrupt coalescing in I/O granularity per SATA adapter. When interrupt coalescing in I/O granularity is enabled for the controller, all EDMA transactions for this adapter are executed with an interrupt coalescing I/O granularity interrupt scheme.
2.5.4.1
To enable I/O-Granularity CORE driver support, the IAL must call the mvSataEnableIoGranularity() CORE driver function after mvSataInitAdapter() has been called.
2.5.4.2
The following steps describe the modifications needed to be done for queuing a command when the I/O-Granularity feature is enabled. 1. For the first command in the chain of commands to be queued with I/O-Granularity, the IAL must set the iogCommandType to MV_IOG_COMMAND_TYPE_FIRST and then set the total number of commands in the transCount field. 2. Call the mvSataQueueCommand()function. Upon exit the CORE driver sets iogCurrentTransId. This is a unique code for the chain of command. 3. IAL saves the iogCurrentTransId returned by CORE driver. This field must be used for the next commands in the chain. 4. For the other commands in the chain of commands, the IAL must set the iogCommandType to MV_IOG_COMMAND_TYPE_NEXT and then set the transId to the saved value that was previously returned by CORE driver.
2.5.4.3
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
2.5.4.4
When the I/O-Granularity feature is enabled, error handling is the same as that described in Section 2.2.5 "Error Handling" with the following addition: When any error occurs, the I/O-Granularity feature is automatically disabled by the CORE driver, to enable the IAL to perform error handling and recovery. When the IAL has completed error handling and recovery, it must re-enable I/O-Granularity feature support by calling the mvSataEnableIoGranularity() CORE driver function.
Note See Section 6. "Core Driver" for further information about the I/O-Granularity functions API.
2.5.5
When using the CORE driver API, the following restrictions apply: When allocating a request queue, the PCI address should be 1 KByte aligned. When allocating a response queue the PCI address should be 256 bytes aligned. The request queue and response queue should be cache coherent or in non-cacheable memory regions. When the IAL builds a PRD table, each entry must not cross the 4 GByte addressing boundary (for further details, see the Serial ATA Host Adapter datasheet). When the IAL calls mvSataShutdownAdapter() for deactivating a specific SATA channel, it must make sure that no other task is using the CORE driver API. Depending on operating system implementation, the IAL must gracefully remove (or delete) the semaphore from the relevant MV_SATA_CHANNEL data structure after calling mvSataRemoveChannel().
CONFIDENTIAL
Document Classification: Proprietary Information
3.1 Introduction
The Serial ATA Host Adapter Linux Intermediate Application Layer (IAL) is a software layer positioned under the Linux SCSI subsystem and above the CORE driver, SAL, and Common IAL. The Linux IAL implements a Linux SCSI host template (Linux SCSI sub-system low level driver interface) that receives SCSI-3 commands and forwards them to the SAL for SCSI command translation to ATA, and later for queuing to hardware through the CORE driver API. The Linux IAL consists of the following parts: Linux IAL SCSI Host Template Driver Linux IAL Extension Library
Figure 3:
mv_sata.o driver
Linux Intermediate Application Layer
Hardware
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
3.1.1
The Linux IAL Host Template driver is the part of the Linux IAL that enables connectivity to the Linux SCSI subsystem. It presents the Serial ATA Host Adapter as a SCSI host adapter, by implementing a SCSI host template. The Linux IAL Host Template driver implements the following functionality: Registers a SCSI host adapter for each SATA channel to the Linux SCSI subsystem using a Linux SCSI host template data structure. Triggers the Serial ATA Host Adapter initialization sequence. Triggers a storage devices initialization process using the Common IAL API. These storage devices are connected to the Serial ATA Host Adapter SATA channels.
3.1.2
The Linux IAL Extension Library provides the Linux IAL SCSI Host Template driver with the ability to perform a set of tasks. The Extension Library is not implemented from within the SCSI Host Template driver. This is because the Extension Library is more Serial ATA Host Adapter-hardware-oriented than the SCSI Host Template Driver, which makes it easier for the user to differentiate between Linux-oriented source code and hardware-oriented source code. The Linux IAL Extension Library implements the following functionality: PRD table generation from SCSI scatter-gather buffers list. Sanity checking of vital Serial ATA Host Adapter configuration. SCSI commands completion notification, based on call-back function from the SCSI subsystem. Triggering of Common IAL storage device initialization sequence upon hot-plug event. CORE driver Interrupt Service Routine (ISR) Wrapper.
3.2 Linux IAL SMART (Self-Monitoring, Analysis, and Reporting Technology) Support
The Linux IAL supports SMART commands. The commands are standard SMART commands, but the interface is a Marvell proprietary interface through the SCSI_IOCTL_SEND_COMMAND interface. The structure of the SCSI command delivered via SCSI_IOCTL_SEND_COMMAND is a 6-byte command that is followed by the buffer containing the ATA register values. The driver uses the same buffer for input and output, thus the minimum buffer allocated by application must be 520 bytes (8 bytes for ATA registers + 512 bytes for the whole sector returned by some of SMART commands). For an explanation of ATA register values, see the ATA/ATAPI-6 specification. Marvell has ported a general Linux utility called SMARTMONTOOLS. This utility generally interfaces to ATA hard drives via /dev/hdX block devices. To communicate with the driver, the ported utility uses the SCSI_IOCTL_SEND_COMMAND IO control function with the vendor-specific command code 0xC as a transport for the SMART commands. For an explanation of the SMARTMONTOOLS package, see the Readme file and the SMARTMONTOOLS user manual.
CONFIDENTIAL
Document Classification: Proprietary Information
The following commands are supported by the Linux IAL as part of the support for SMART: IDENTIFY - ATA IDENTIFY (not a SMART command) ENABLE SMART DISABLE SMART ENABLE DISABLE AUTOSAVE EXECUTE OFFLINE DIAGS RETURN STATUS READ SMART THRESHOLDS ENABLE DISABLE AUTO OFFLINE READ SMART LOG
Table 1: Buffer Offs et 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xA 0xB 0xC 0xD
SMART Command Input Buffer Valu e 0xC 0 0 0 6 0 0xEC for the INDENTIFY 0xB0 for the SMART Depends on the command Depends on the command Depends on the command Depends on the command Depends on the command Depends on the command Depends on the command Des cription Vendor-specific SCSI command Reserved Reserved Reserved Command header length Reserved ATA command register input value ATA sector number register input value ATA features register input value ATA sector count register input value ATA LBA Mid register input value ATA LBA High input value ATA device register input value ATA error register input value
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
The requirements are: Linux machine with kernel 2.4 or 2.6 series Serial ATA Host Adapter software package Native GNU toolchain compilers (gcc, ld etc.) Kernel header files.
3.3.2
To build and run the project: 1. Log in as root. 2. Change the current directory to LinuxIAL. 3. Put the linux kernel header files under /usr/src/linux-2.x (where x is 4 for kernel based on 2.4 version and 6 for kernel based on 2.6 version) 4. Execute a make command on the shell. 5. Add a SCSI subsystem to the running kernel by executing /sbin/modprobe scsi_mod. 6. Run the kernel module by executing /sbin/insmod mv_sata.o. This detects storage devices connected to the SATA adapter and presents them as SCSI storage devices to the Linux kernel. To build a project with three different levels of log messaging: 1. 2. 3. 4. 5. Log in as root. Change the current directory to LinuxIAL. Put the linux kernel header files under /usr/src/linux-2.x (where x is 4 for kernel based on 2.4 version and 6 for kernel based on 2.6 version) Execute a sh build.sh command on the shell. The script creates target directory build/Linux in driver root. The target directory structure is: build/Linux/DebugError/mv_sata.o - Module prints log messages on error. build/Linux/DebugFull/mv_sata.o - Module prints all log messages. build/Linux/Free/lmv_sata.o - Module prints no messages. 6. 7. 8. Add a SCSI subsystem to the running kernel by executing /sbin/modprobe scsi_mod. Change the current directory to the desired target directory, e.g., cd ./../build/Linux/DebugFull. Run the kernel module by executing /sbin/insmod mv_sata.o. This detects storage devices connected to the SATA adapter and presents them as SCSI storage devices to the Linux kernel.
Notes If the kernel header files are not located in the /usr/src/linux-2.x directory, edit the Makefile in the LinuxIAL directory and change the value of the KERNEL_SRC parameter to the desired directory. If you need to cross-compile the project (and not compile it with native tools), edit the Makefile and modify the CROSS_COMPILE parameter so it has the prefix of the desired cross compiler toolchain
CONFIDENTIAL
Document Classification: Proprietary Information
(e.g., for PowerPC, CROSS_COMPILE is assigned the value powerpc-linux-). Also, modify the CFLAGS parameter to the correct values. (See the example in the Makefile.) To stop and remove the kernel module from the Linux kernel, execute rmmod linuxIAL.
3.3.2.1
This section describes how to build the project that makes it possible to install and boot Linux RedHat on an Serial ATA Host Adapter. 1. Log in as root. 2. For distributions based on kernel 2.4 download the Redhat kernels to a directory, e.g., /usr/src/kernels/. For RedHat 8 you must have a directory /usr/src/kernels/2.4.18-14 and for RedHat 9 you must have a directory /usr/src/kernels/2.4.20-8. 3. For distributions based on kernel 2.6 (e.g Fedora Core 3), create directory under /usr/src/kernels/ with the name of the kernel release, and under that directory create directory for each kernel configuration then put the kernel sources tree for that configuration. for example, to create drivers for Fedora Core 3 for x86 cpu: - mkdir /usr/src/kernels/2.6.9-1.667 - mkdir /usr/src/kernels/2.6.9-1.667/i586 - mkdir /usr/src/kernels/2.6.9-1.667/i686 - mkdir /usr/src/kernels/2.6.9-1.667/smp - download the kernel rpm for i586 (kernel-2.6.9-1.667.i586.rpm) 4. Change the current directory to RedHat (under LinuxIAL).- run rpm2cpio kernel-2.6.9-1.667.i586.rpm | cpio id 5. Run mv lib/modules/2.6.9-1.667/sources/* /usr/src/kernels/2.6.9-1.667/i586 6. Do the last 3 steps for i686 and smp kernels. 7. To make sure the files are in Unix format, run the following command: > dos2unix gen_module.sh files/* 8. Execute sh gen_module.sh /usr/src/kernels. This generates files in the Files directory. 9. Copy these files to a diskette. 10. Start the RedHat installation on the required computer which has the Serial ATA Host Adapter(s). 11. During installation, select Expert mode and follow the installation instructions. 12. When a driver disk is requested, insert the diskette in Drive A and continue with the installation.
Notes The gen_modules.sh script scans all directories under /usr/src/kernels and according to the directory names it generates four drivers per directory name. The four drivers are drivers for boot, single CPU, SMP, and bigmem. Due to the fact that gen_modules.sh scans directories under /usr/src/kernels, it needs the exact version of the kernel for which the drivers are being built. For example, for RedHat 9 kernel, the directory name must be 2.4.20-8, which is the exact kernel version RedHat 9 installation is shipped with.
3.3.2.2
After installing the Linux kernel module mv_sata.o, a new directory called mvSata is added to the /proc/scsi/ directory. This directory has one or more files in it. Each files name is a number (number of the registered Scsi Host). Each file indicates a sequence number of a single SATA channel of Serial ATA Host Adapter. For example if there is a single 88SX5041 adapter and there are no other SCSI adapters in the system, Four files named 0 up to 3 will be found. Two operations can be done on each of the /proc extension filesreading from them and writing to them.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
3.3.2.3
When reading from a /proc extension file (for example by executing cat /proc/scsi/mvSata/0) the output is as follows: Version_1_1
PCI location: Bus 10, Slot 9 DeviceID: 6042, Rev 1, adapterId 1, channel 1
Adapter
Channel
Id
LUN
TO
TS
Vendor
Mode
LBA48
- Total Outstanding commands accumulated - Total number of IOs accumulated - Total number of sectors transferred (both read/write) - EDMA mode (TCQ|NCQ|Normal) - Large Block Address 48 feature set enabled
The meaning of the output is: Version_1_1 is the output version of the /proc extension file. TimeStamp is the timestamp of the system. The first number is the tick count of the operating system and the second is the number of ticks the operating system counts per second (fixed number). Number of interrupts produced by the adapter: Note that even if the same interrupt line on the PCI is shared with other adapters, this number will still count the real number of interrupts generated by the adapter. Description of the channels attached to the adapter: Adapter, Channel, ID, LUN TO TSA TS SCSI ID Number of outstanding commands accumulated. Total number of IO operations. Total number of sectors transferred through the specific SATA channel.
CONFIDENTIAL
Document Classification: Proprietary Information
Model number of the storage device connected to the specific SATA channel. Indication of DMA mode. Indication that the storage device has the 48-bit LBA addressing feature set enabled (indicated by value 1).
3.3.2.4
It is possible to do three different things while writing to the /proc extension files: Change interrupt coalescing parameters: Executing a write to the /proc extension file (e.g., echo "int_coal 1 30 10000" > /proc/scsi/mvSata/0) changes the values of the interrupt coalescing parameters of the specific SATA unit (each quad SATA unit contains 4 SATA channels). The format is int_coal x y z, where x is the SATA unit (0 or 1), y is the number of completed commands needed to generate an interrupt, and z is the timeout in 150 MHz ticks, where the adapter starts counting after the first command is completed. Shut down a SATA physical interface: Execute echo "sata_phy_shutdown x" > /proc/scsi/mvSata/0 to shut down a SATA PHY x. Power up a SATA physical interface: Execute echo "sata_phy_powerup x" > /proc/scsi/mvSata/0 to power up a SATA PHY x. Notes All values indicated by x, y, and z above should be in decimal format. After power-up, the SATA physical interfaces are all powered up.
3.3.3
When adding or removing a storage device from an operating system, when the Serial ATA Host Adapters driver is already up and running, the SCSI subsystem must be informed of the changes made. This is done by executing Add or Remove requests to the SCSI subsystem.
3.3.3.1
To add a storage device to a specific SATA channel on a specific adapter (e.g., channel y on adapter x or device z on channel y on adapter x in the case of a port multiplier): 1. Poll on the /proc extension file relevant to adapter x and wait until channel y is valid (and the variable z if the hard drive is connected to a port multiplier) 2. For kernel 2.4 based systems execute echo "scsi add-single-device x y z 0" > /proc/scsi/scsi. For kernel 2.6 based systems, where scsi hot-pug is supported, there is no need for user intervention.
Note If the hard drive is connected directly to the adapters SATA channel and not through port multiplier, then z parameter equals 0
3.3.3.2
To remove a storage device that is connected on SATA channel y on adapter x (and z if the hard drive is connected through a port multiplier): 1. For kernel 2.4 based systems execute echo "scsi remove-single-device x y z 0" > /proc/scsi/scsi. For kernel 2.6 based systems, where scsi hot-plug is supported, there is no need for user intervention. 2. Remove the storage device connected to SATA channel x on a adapter y.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
Note If the hard drive is connected directly to the adapters SATA channel and not through the port multiplier, then z parameter equals 0
mv_ial_ht_proc_info mv_ial_ht_queuecommand
mv_ial_ht_hl_bus_reset mv_ial_ht_release
3.5
CONFIDENTIAL
Document Classification: Proprietary Information
4.1 Introduction
The Serial ATA Host Adapter Windows 2000/XP/2003 Intermediate Application Layer (IAL) is a software layer positioned under the Windows SCSI port driver and above the CORE driver, SAL, and Common IAL. The Windows 2000/XP/2003 IAL implements a SCSI Miniport driver that receives SCSI-3 commands and forwards them to SCSI to ATA translation layer for further queuing to hardware via CORE driver API.
.
mvSata.sys
Windows IAL
Hardware
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
4.1.1
The Windows IAL SCSI miniport driver implements the following functionality: Represents the Serial ATA Host Adapter as a SCSI host adapter. Triggers Serial ATA Host Adapter initialization sequence. Triggers storage devices connected to Serial ATA Host Adapter SATA channels via Common IAL functions. CORE driver Interrupt Service Routine (ISR) Wrapper. Error Handling: Performs mapping of SAL error status to SCSI port error status. Handles hot-plug events, and notifies the SCSI port layer about these events. Windows IAL SMART (Self-Monitoring, Analysis, and Reporting Technology) support The Windows IAL SCSI miniport driver fully supports the Windows drive failure prediction (SMART) IOCTL interface. The application can use the SMART IOCTL commands (all Windows versions, except of Windows.NET) or WMI predictive failure capabilities to execute SMART commands via the SATA SCSI miniport driver.
Notes For an explanation of WMI support for SMART drives see http://www.microsoft.com/whdc/hwdev/ driver/WMI/smartdrv.mspx For an explanation of SMART IOCTL interface support in Windows see the SMARTAPP example at http://support.microsoft.com/default.aspx?scid=kb;en-us;Q208048.
The following SMART commands are supported by the Windows IAL: IDENTIFY - ATA IDENTIFY (not a SMART command, but can be sent using this IOCTL interface) ENABLE SMART DISABLE SMART ENABLE DISABLE AUTOSAVE EXECUTE OFFLINE DIAGS RETURN STATUS READ SMART ATTRIBS READ SMART THRESHOLDS READ SMART LOG WRITE SMART LOG
The requirements are: Computer running Windows 2000/XP/2003. Serial ATA Host Adapter software package Microsoft Driver Development Kit build environment for Windows 2000/XP/2003.
CONFIDENTIAL
Document Classification: Proprietary Information
Note If you use Windows 2000 DDK (which doesnt include built-int toolchains as in Windows 2003 DDK), then you may also need Microsoft Visual C++ Enterprise edition.
4.2.2
Building
To build the driver: 1. Invoke the DDK Free Build Environment under the windows DDK program group. This starts a command prompt window and sets some environment variables). 2. Change the current directory to Windows IAL. 3. Run the batch file mvsata_build.bat from the current directory. The generated binary file (mvsata.sys) will be located under the directory install. To build a driver with three different levels of log messaging 1. Go to the command prompt window. 2. Change the current directory to Windows IAL 3. Run the batch build_all.bat with the parameter indicating the DDK directory, for example build_all.bat C:\winddk\3790. 4. The batch file creates the build/Windows target directory in driver root. The target directory structure is the following: - build/Windows/<Platform>/DebugError/mvSata.sys - Module prints log messages on error. - build/Windows/<Platform>/DebugFull/mvSata.sys - Module prints all log messages. - build/Windows/<Platform>/Free/mvSata.sys - Module prints no messages. 5. Where the <Platform> parameter can be either i386 (used in 32-bit Windows versions) or amd64 (used in Windows version for AMD 64-bit processor.)
Note For building to i386 and amd64 platforms, Windows 2003 DDK must be installed.
4.2.3
The installation of the driver can be done by using the Windows Device Manager. Note that the driver .inf and .sys files location depends on the build type chosen in Section 4.2.2 "Building" on page 39.
4.2.4
This section describes how to install and boot from a Serial ATA Host Adapter. 1. Copy the mvSata.inf, mvSata.sys and txtsetup.oem files to a diskette. 2. Start a Windows installation on a CD-ROM. 3. When prompted, press the F6 key (at the beginning of the installation). 4. When prompted, press the S key, then insert the diskette in Drive A and continue the installation, following the installation instructions.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
4.2.5
View the .reg files under the Install directory and follow the instructions to enter registry values that affect how the Windows 2000/XP/2003 SCSI manager interprets the generic configuration information of SCSI device drivers. These values can affect all the Serial ATA Host Adapters installed drivers or a specific driver. They will take effect the next time the driver is started. Following are the registry files supplied and a description of the values they set:
mv_256k.reg specifies the maximum I/O length of transactions issued by the Windows SCSI Port. mv_maxReqs specifies the number of outstanding SCSI requests per SCSI adapter.
4.2.6
This driver supports hard drive and port multiplier hot-swapping. The storage drive can be connected or disconnected on the fly. On a connect event the system may take a few seconds before it updates the device manager with regards to the new device added. This is due to the disk initialization sequence, which may be stalled due to hard drive initialization (e.g., when initializing the hard drives mechanics).
CONFIDENTIAL
Document Classification: Proprietary Information
5.1 Introduction
The main purpose of the Serial ATA Host Adapter BIOS Extension driver is to enable interrupt 13h extensions to hard drives connected to Serial ATA Host Adapter SATA channels. Figure 4 describes the connectivity of the different software layers.
Figure 4:
.
Applications
System BIOS
BIOS IAL
Hardware
5.1.1
The BIOS extension driver provides the following functionality: Support for PnP and non-PnP system BIOSes Initialization of Serial ATA Host Adapters Initialization of storage devices connected to Serial ATA Host Adapter SATA channels 0 and 1. If port multiplier is connected (to channel 0 or 1), only disk on port 0 is initialized and hooked.
CONFIDENTIAL
Document Classification: Proprietary Information
Initialization
Software Driver User Manual for Marvell Serial ATA Host Adapters
Each loaded extension image scans the adapters and takes control over up to four adapters. Each adapter:
Has at least one discovered disk. Servicing interrupt 13h calls Notes Interrupt 13h servicing is done via source code found in the BIOS IAL. The CORE driver interface for queuing and executing commands is not used for int13h servicing, due to the fact that in run-time the text and data sections of the driver are read-only, and only the callers stack is read-write. This makes it impossible to call CORE driver functions, which need to maintain data structures and pointers to the status of the queues. The BIOS extension driver does not provide hotplug functionality.
5.2.1
Requirements
The requirements are: PC running Windows 2000 or above Watcom C/C++ compiler. Serial ATA Host Adapter software package. DOS for flashing the BIOS extension driver into Serial ATA Host Adapter the adapters flash. Notes The project build was tested mainly on Watcom C/C++ compiler version 1.0 on a PC running Windows 2000. The compiler is an open-source compiler that can be downloaded and installed from http://www.openwatcom.org. The installation should be for DOS 16/32bit and Windows 16/32 bit targets.
5.2.2
Building
To build the driver: 1. Open a command line and change the directory to BiosIAL from the software package root tree. 2. Execute makeBiosDriver.bat.
CONFIDENTIAL
Document Classification: Proprietary Information
5.2.3
To install the BIOS extension driver: 1. Boot the system with DOS (MS-DOS, DR-DOS, or any other variant of DOS). 2. Copy mvFlshUp.com and the required BIOS extension driver image to a diskette. 3. Insert the diskette and run mvFlshUp.com <image name> (image name is the required BIOS extension driver image). The utility provides a list of available adapters to choose from.
5.2.4
To un- install the BIOS extension driver: 1. Boot the system with DOS (MS-DOS, DR-DOS or any other variant of DOS). 2. Copy mvFlshUp.com to a diskette. 3. Insert the diskette and run mvFlshUp.com /erase <adapter Device ID> (Adapter Device ID is the device ID of the required adapter. This can be 0x5080, 5081 ... 0x7042). The utility provides a list of available adapters to choose from.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
6.1 Introduction
The CORE driver is a software package which is operating system and architecture independent. When a system-dependent header file (mvOs.h file) is attached to the CORE driver, it can access and reserve system resources that it needs for proper functioning. The CORE driver API and data structures are divided into two main categories: CORE-driver-implemented API and data structures: Includes most of the functions and data structures being used. These functions are already implemented as part of the CORE driver software suite. User-implemented API and data structure: Includes several functions and a single data structure which must be implemented by the user in the system-dependent header file (mvOs.h). In Section 6.2 and Section 6.3 the data structure and functions which must be implemented are referred to as "user-implemented".
Note In this document, references to the "CORE driver API and data structure" mean the combination of COREdriver-implemented API and data structures plus the user-implemented API and data structure. The CORE driver provides the following functionality: Serial ATA Host Adapter management, initialization, diagnostics and status reporting. Execution of UDMA ATA commands. Execution Non-UDMA ATA commands. Management of software queue of ATA commands per SATA channel. Each queue depth is 31 commands (configurable). Management of command completion and events notification, based on call-back functions. Interrupt Service. I/O Granularity extension for generating a single interrupt on multiple I/Os. Channel to Channel communication (aka Target mode): API for communication between two 88SX60x1, 88SX6042, and 88SX7042 adapters. Debug messages logging module: Generic debug messages logging module that is used by the CORE driver and can be used by any other software layer. This section is divided into the following sub-sections: CORE Driver API and Data Structures Summary: A brief summary that categorizes the CORE driver API into groups of functions and a brief description of the data structure being used. The purpose of this section is to ramp up the users knowledge of the CORE drivers interface. Compile-Time CORE Driver Configuration: Describes the functions, data types and data structures the user must implement for proper integration of the CORE driver in the system. This section also deals with restrictions the user must be aware of when integrating the CORE driver in the system. CORE Driver API User Implementation Requirements and Restrictions: Shows how to use the CORE driver from the Intermediate Application Layer (IAL) point of view. It is separated into sub-sections, each describing a specific task the IAL must use.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
CORE Driver API and Data Structures Summary
Detailed CORE Driver Implemented API and Data Structures: A complete reference to the COREdriver-implemented API and data structures. System-Dependent Header File (mvOs.h): Details the API, data types, and data structures the user must implement for proper integration of the CORE driver in the system.
Figure 5:
CORE driver
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
6.2.1
mvSataConfigureChannel mvSataRemoveChannel mvSataIsStorageDeviceConnected mvSataChannelHardReset mvSataSetFBSMode mvSataConfigEdmaMode mvSataEnableChannelDma mvSataDisableChannelDma mvSataFlushDmaQueue mvSataNumOfDmaCommands mvSataGetNumOfPortQueuedCommands mvSataSetIntCoalParams
Configures Serial ATA Host Adapter-specific SATA channel. Removes Serial ATA Host Adapter-specific SATA channel. Checks if storage device is connected to specific SATA channel. Causes Serial ATA Host Adapter to reset a specific SATA channel. Enables FIS-based switching mode. Configures specific SATA channels EDMA mode. Enables specific SATA channels EDMA mode. Disables specific SATA channels EDMA mode. Flushes corresponding SATA channels request queue. Returns number of posted DMA commands on a specific SATA channel request queue. Gets the number of the outstanding commands for the given port. Sets interrupt coalescing for specific quad SATA channels Serial ATA Host Adapter (or octal SATA channels on 88SX60X1 adapters). Sets the AMP and PRE values of a specific SATA channel. Powers up the physical interface of a specific SATA channel. Shuts down the physical interface of a specific SATA channel. Performs an external loopback test of specific SATA channel. Enables SATA communication on a specific SATA channel. Enables SATA communication on all SATA channels.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
CORE Driver API and Data Structures Summary
Disables SATA communication on a specific SATA channel. Disables SATA communication on all SATA channels. Modifies SATA speed (Gen I/II) on a specific SATA channel. Returns SATA speed (Gen I/II) on a specific SATA channel. Sets the SATA interface power state of a specific SATA channel. Gets the SATA interface power state of a specific SATA channel.
Issues user-specific non-UDMA ATA command to specific storage device. Issues IDENTIFY DEVICE ATA command to specific storage device. Issues SET FEATURES ATA command to specific storage device. Issues IDLE IMMEDIATE ATA command to specific storage device Issues SRST sequence to specific storage device. Issues SRST sequence to specific storage device but does not poll for disk ready status. Returns MV_TRUE if storage device busy bit is off. Issues user-specific PIO ATA command to specific storage device (using ATA registers data structure as input and output for the function). Sets the storage device type connected to a specific SATA channel. Retrieves the storage device type connected to a specific SATA channel
mvStorageDevSetDeviceType mvStorageDevGetDeviceType
Po rt m ul t ip li er fu ncti o ns (Pol l in g dr iv en)
Reads a port multipliers internal register. Writes to a port multipliers internal register. Enables communication on a specific SATA channel on a port multipliers device ports. Enables communication on all SATA channels on a port multipliers device ports.
mvSataQueueCommand
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
mvSataCommandCompletionCallBack mvSataEventNotify
I nt errup t Se r v ic e R o ut ine
Callback function called upon specific command completion. Event notification, upon event (Interrupt) from Serial ATA Host Adapter.
Interrupt Service Routine Masks Serial ATA Host Adapter interrupts. Unmasks Serial ATA Host Adapter interrupts. Modifies CORE driver interrupt scheme. Used for checking whether an interrupt is pending only in the interrupt scheme, where interrupt handling is performed in a task and not in the ISR. Checks if the drive reported device errors. The 60X1 B2 may not issue an error interrupt when the device error is reported, after transferring part of the data.
mvSata60X1B2CheckDevError
Initializes semaphore. Takes ownership of a semaphore. Releases ownership of a semaphore. Saves CPU flags and masks its interrupts. Restore CPU flags. Delays function in micro-seconds resolution. User implemented function that enables logging of CORE driver messages.
Associate the module with the logger. Set log filter for the module Get log filter for the module Prints log message
mvLogSetModuleFilter
mvLogGetModuleFilter mvLogMsg
C h ann el to cha nn el c om m u n ica t io n ( aka Tar g et m od e) f un ct io ns mvSataC2CInit mvSataC2CStop Initializes channel to channel communication mode for a specific SATA channel. Disables channel to channel communication mode for a specific SATA channel.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Compile-Time CORE Driver Configuration
Sends Register Host to Device FIS. Activates Bus Master DMA for the channel. Resets Bus Master DMA for the channel.
6.2.2
Data structures modified by IAL and CORE driver. MV_SATA_ADAPTER MV_SATA_CHANNEL MV_STORAGE_DEVICE_REGISTERS
mvSataQueueCommand() function.
User-implemented data structure, used for locking/unlocking MV_SATA_ADAPTER and MV_SATA_CHANNEL.
6.3.1
For logging CORE driver debug messages, the following must be added to the user-specific mvOs.h file: #define MV_LOG_DEBUG - For logging all debug messages. #define MV_LOG_ERROR - For logging only error messages. It is recommended to disable all logging mechanisms on a released driver, to minimize the drivers footprint and maximize performance.
6.3.2
The default behavior of the CORE driver in compile time is that its queue size is 31 commands. It is possible to modify this behavior in compile by adding the following lines to the user-specific mvOs.h file: #define MV_SATA_OVERRIDE_SW_QUEUE_SIZE
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
#define MV_SATA_REQUESTED_SW_QUEUE_SIZE <queue size> where <queue size> is the requested queue size (between 1 and 31). The EDMA of the MVSX6042 and MVSX7042 devices supports the 128 entries mode, in addition to the legacy 32 entries mode. Adding the following line enables support of this feature: #define MV_SATA_SUPPORT_GEN2E_128_QUEUE_LEN. When it has been defined, the CORE driver allocates up to 127 commands for each channel. To override this default allocation length, add the following lines: #define MV_SATA_OVERRIDE_GEN2E_SW_QUEUE_SIZE #define MV_SATA_REQUESTED_GEN2E_SW_QUEUE_SIZE <queue size> where <queue size> is the requested queue size (between 1 and 127).
6.3.3
To enable single data region support, add the following line to the user-specific mvOs.h file: #define MV_SATA_SUPPORT_EDMA_SINGLE_DATA_REGION
6.3.4
Older versions of the CORE driver used static allocation for the commands info data structure (MV_QUEUE_COMMAND_INFO). In Version 3.6.0 this allocation may be removed. Instead the CORE Driver uses memory allocated by the IAL. To use this mode, the IAL must add the define MV_SATA_STORE_COMMANDS_INFO_ON_IAL_STACK, and must make sure that the memory pointed by pCommandInfo (part of the MV_QUEUED_COMMAND_ENTRY structure) is owned by the CORE driver as long as the command is not completed.
6.3.5
To enable channel-to-channel communication support, the following line must be added to the user-specific mvOs.h file: #define MV_SATA_C2C_COMM
6.3.6
To enable I/O-Granularity interrupt acceleration, the following line must be added to the user-specific mvOs.h file: #define MV_SATA_IO_GRANULARITY
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
CORE Driver API User Implementation Requirements and Restrictions
6.4.1
Requirements
For the CORE driver to work properly, user-implemented functions, data types and data structures must be implemented. In this document these requirements are marked as "User-implemented". For clarification purposes they are listed again in this section.
Note These functions, data types and data structures must all be implemented or declared in the systemdependent header file (mvOs.h).
6.4.1.1
mvSataCommandCompletionCallBack mvSataEventNotify
6.4.1.2
System Functions
mvOsSemInit mvOsSemTake mvOsSemRelease mvMicroSecondsDelay ###### ADD Logging mechanism functions ######
Note If a locking mechanism is performed in higher layers above the CORE driver, then the user may consider not using the CORE drivers locking mechanism, by defining the above functions in the user-specific mvOs.h file with a "while (0) {} " statement.
6.4.1.3
Data Types
The user must implement the following data types: MV_VOID MV_U32 MV_U16 MV_U8 MV_VOID_PTR MV_U32_PTR
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_SATA_GEN - Enumerator for either MV_SATA_GEN_I, MV_SATA_GEN_II or MV_SATA_GEN_IIE. MV_BOOLEAN - Enumerator for the value MV_TRUE and MV_FALSE MV_UDMA_TYPE - Enumerator for either MV_UDMA_TYPE_READ or MV_UDMA_TYPE_WRITE MV_COMPLETION_TYPE - Enumerator for either MV_COMPLETION_TYPE_NORMAL or MV_COMPLETION_TYPE_ERROR or MV_COMPLETION_TYPE_ABORT MV_EVENT_TYPE - Enumerator for either MV_EVENT_TYPE_ADAPTER_ERROR, MV_EVENT_TYPE_SATA_CABLE, or MV_EVENT_TYPE_SATA_ERROR. MV_SATA_CABLE_EVENT - Enumerator for either MV_SATA_CABLE_EVENT_DISCONNECTED, MV_SATA_CABLE_EVENT_CONNECTED, or MV_SATA_CABLE_EVENT_PM_HOT_PLUG. MV_SATA_ERROR_EVENT - Enumerator for either MV_SATA_RECOVERABLE_COMMUNICATION_ERROR, MV_SATA_UNRECOVERABLE_COMMUNICATION_ERROR, or MV_SATA_DEVICE_ERROR. MV_EDMA_MODE - Enumerator for either MV_EDMA_MODE_QUEUED, MV_EDMA_MODE_NOT_QUEUED, or MV_EDMA_MODE_NATIVE_QUEUING. MV_SATA_SWITCHING_MODE - Enumerator for either MV_SATA_SWITCHING_MODE_NONE, MV_SATA_SWITCHING_MODE_CBS, MV_SATA_SWITCHING_MODE_QCBS, or MV_SATA_SWITCHING_MODE_FBS. MV_QUEUE_COMMAND_RESULT - Enumerator for either MV_QUEUE_COMMAND_RESULT_OK, MV_QUEUE_COMMAND_RESULT_QUEUED_MODE_DISABLED, MV_QUEUE_COMMAND_RESULT_FULL, MV_QUEUE_COMMAND_RESULT_BAD_LBA_ADDRESS or MV_QUEUE_COMMAND_RESULT_BAD_PARAMS MV_NON_UDMA_PROTOCOL - Enumerator for either MV_NON_UDMA_PROTOCOL_NON_DATA, MV_NON_UDMA_PROTOCOL_PIO_DATA_IN, or MV_NON_UDMA_PROTOCOL_PIO_DATA_OUT. MV_QUEUED_COMMAND_TYPE - Enumerator for either MV_QUEUED_COMMAND_TYPE_UDMA, or MV_QUEUED_COMMAND_TYPE_NONE_UDMA. MV_SATA_C2C_MODE - Enumerator for channel-to-channel feature. It determines the channels role in the channel-to-channel communication mode of either MV_SATA_C2C_MODE_INITIATOR or MV_SATA_C2C_MODE_TARGET
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
MV_C2C_EVENT_TYPE - Enumerator for channel-to-channel feature. Can be either MV_C2C_REGISTER_DEVICE_TO_HOST_FIS_DONE, or MV_C2C_REGISTER_DEVICE_TO_HOST_FIS_ERROR, or MV_C2C_BM_DMA_DONE, or MV_C2C_BM_DMA_ERROR. MV_IOG_COMMAND_TYPE - Enumerator for I/O Granularity feature. Can be either MV_IOG_COMMAND_TYPE_FIRST or MV_IOG_COMMMAND_TYPE_NEXT. MV_SATA_INTERRUPT_SCHEME - Enumerator for either MV_SATA_INTERRUPT_HANDLING_IN_ISR, MV_SATA_INTERRUPT_HANDLING_IN_TASK, or MV_SATA_INTERRUPTS_DISABLED. MV_SATA_IF_SPEED - Enumerator for either MV_SATA_IF_SPEED_1_5_GBPS, MV_SATA_IF_SPEED_3_GBPS, MV_SATA_IF_SPEED_NO_LIMIT and MV_SATA_IF_SPEED_INVALID. MV_SATA_IF_POWER_STATE - Enumerator for either MV_SATA_IF_POWER_PHY_READY, MV_SATA_IF_POWER_PARTIAL, or MV_SATA_IF_POWER_SLUMBER. MV_SATA_DEVICE_TYPE - Enumerator for either MV_SATA_DEVICE_TYPE_UNKOWN, MV_SATA_DEVICE_TYPE_ATA_DISK, MV_SATA_DEVICE_TYPE_ATAPI_DISK, or MV_SATA_DEVICE_TYPE_PM.
6.5.1.2
Defines
MV_SATA_DEVICE_ID_5080,MV_SATA_DEVICE_ID_5081, MV_SATA_DEVICE_ID_5040, MV_SATA_DEVICE_ID_5041, MV_SATA_DEVICE_ID_6081, MV_SATA_DEVICE_ID_6041, MV_SATA_DEVICE_ID_6042, and MV_SATA_DEVICE_ID_7042 - The different device ID per Serial ATA Host Adapters PCI configuration space. MV_SATA_VENDOR_ID - The vendor ID for the Serial ATA Host Adapter PCI configuration space (equals 0x11AB). MV_SATA_CHANNELS_NUM - Maximum number of serial ATA channels in a single Serial ATA Host Adapter (equals 8). MV_SATA_UNITS_NUM - Maximum number of serial ATA units in a single Serial ATA Host Adapter (equals 2). MV_SATA_PM_MAX_PORTS - Maximum number of serial ATA ports of the Port Multiplier device. MV_SATA_PM_CONTROL_PORT - The device port number of the control port of the Port Multiplier device. MV_EDMA_QUEUE_LENGTH - Maximum number of outstanding UDMA ATA commands (equals 32). MV_EDMA_GEN2E_QUEUE_LENGTH - Maximum number of outstanding UDMA ATA commands for the MVSX6042 and MVSX7042 devices (equals 128). MV_EDMA_REQUEST_ENTRY_SIZE - Size of a single entry in a request queue (equals 32). MV_EDMA_RESPONSE_ENTRY_SIZE - Size of a single entry in a response queue (equals 8). MV_EDMA_REQUEST_QUEUE_SIZE - Size of an entire request queue (equals 32 * 32 = 1024 bytes). MV_EDMA_RESPONSE_QUEUE_SIZE - Size of an entire response queue (equals 32 * 8 = 256 bytes). MV_EDMA_PRD_ENTRY_SIZE - Size of a single entry in a PRD table (equals 16). MV_EDMA_PRD_SNOOP_FLAG - Flag indicating a snoop operation to be performed on the relevant PRD entry. MV_EDMA_PRD_EOT_FLAG - Flag indicating the end of a PRD table. MV_ATA_IDENTIFY_DEV_DATA_LENGTH - Number of fields in the data array returned from a storage device as a response for an IDENTIFY DEVICE ATA command (equals 256).
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_ATA_MODEL_NUMBER_LEN - Length of the model number, as extracted from the IDENTIFY DEVICE ATA command (equals 0x40). MV_C2C_MESSAGE_SIZE - Definition for channel-to-channel communication feature. The maximum size of user data transmitted with Register Device to Host FIS - equals to 10
Logger Defines
MV_LOG_DEBUG - The preprocessor variable. When one is set, all log debug messages are printed. MV_LOG_ERROR - The preprocessor variable. When one is set, all log error messages are printed.
6.5.2
Data Structures
MV_SATA_ADAPTER
Fields set by the Intermediate Application Layer MV_U32 adapterId - A unique number for each Serial ATA Host Adapter. This number is only used for indexing multiple Serial ATA Host Adapters for the purpose of log messages. MV_VOID_PTR IALData - is scratchpad data used only by IAL. MV_U8 pciConfigRevisionId - Device revision number of the adapter, as reported from the revision number in the adapters PCI configuration space. MV_U16 pciConfigDeviceId - Device Id number of the adapter, as reported from the revision number in the adapters PCI configuration space. MV_BUS_ADDR_T adapterIoBaseAddress - A CPU address for accessing an Serial ATA Host Adapter adapters function0, BAR0 base address. MV_U32 intCoalThre[MV_SATA_UNITS_NUM] - Array of two fields indicating the Interrupt Coalescing Threshold for each quad SATA channel. MV_U32 intTimeThre[MV_SATA_UNITS_NUM] - Array of two fields indicating the Interrupt Time Threshold in each quad SATA channel.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
mvSataEventNotify - Pointer to a call-back function, used by CORE driver to indicate error or status change in an Serial ATA Host Adapter. MV_SATA_CHANNEL *sataChannel [MV_SATA_CHANNEL_NUM] - Array of MV_SATA_CHANNEL_NUM count in fields (equals 8). Each is a pointer to MV_SATA_CHANNEL data structures. MV_U32 pciCommand - A 32-bit field describing the Serial ATA Host Adapter PCI command register. MV_U32 pciSerrMask - A 32-bit field describing the bit masking register of the SERR# signal in the Serial ATA Host Adapter. MV_U32 pciInterruptMask - A 32-bit field describing the bit masking register of the PCI unit Interrupt Cause register.
MV_SATA_CHANNEL
Fields set by the Intermediate Application Layer MV_U8 channelNumber - Logical number from 0.. MV_SATA_CHANNEL_NUM-1 (equals 7). MV_DMA_REQUEST_QUEUE_ENTRY *requestQueue - CPU address (pointer) to the request queue of the channel. MV_DMA_RESPONSE_QUEUE_ENTRY *responseQueue - CPU address (pointer) to the response queue of the channel. MV_U32 requestQueuePCIHiAddress - High 32-bit PCI address of the SATA channel request queue. MV_U32 requestQueuePCILowAddress - Low 32-bit PCI address of the SATA channel request queue. MV_U32 responseQueuePCIHiAddress - High 32-bit PCI address of the SATA channel response queue. MV_U32 responseQueuePCILowAddress - Low 32-bit PCI address of the SATA channel response queue.
MV_QUEUE_COMMAND_INFO
MV_QUEUED_COMMAND_TYPE type - Type of ATA commandUDMA or non-UDMA MV_U8 PMPort - Destination port multipliers port number. union { MV_UDMA_COMMAND_PARAMS udmaCommand; MV_NONE_UDMA_COMMAND_PARAMS NoneUdmaCommand; } commandParams - parameters of the ATA command.
MV_UDMA_COMMAND_PARAMS
MV_UDMA_TYPE readWrite - Whether the command is read or write. MV_BOOLEAN isEXT - Indicates if the command is LBA48 or legacy command. MV_BOOLEAN FUA - Indicates the value of the FUA field of FPDMA (aka NCQ) commands. MV_U32 MV_U16 MV_U16 MV_U32 MV_U32 lowLBAAddress -The LSB 32 bits of the LBA sector address. highLBAAddress - The MSB 16 bits of the sector LBA address. numOfSectors - Number of sectors to transfer. prdLowAddr - A low 32-bit PCI address to the PRD table of the command. prdHighAddr- A high 32-bit PCI address to the PRD table of the command.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_BOOLEAN singleDataRegion - MV_TRUE if the single data region is used for this command. In this case prdLowAdd and prdHighAdd point to the I/O buffer rather than the PRD table. This field exists only when the single data region feature is enabled. MV_U16 byteCount - Holds the byte count of the I/O buffer if the single data region is used for this command. This field exists only when the single data region feature is enabled. A value of "0" indicates 64KB. mvSataCommandCompletionCallBack_t callBack A callback function that is called when command execution has been completed. MV_VOID_PTR commandId - An arbitrary ID that uniquely identifies the command. If I/O Granularity is enabled, then the following fields are valid: MV_BOOLEAN ioGranularityEnabled - MV_TRUE if I/O Granularity feature is enabled. MV_IOG_COMMAND_TYPE iogCommandType - Equals MV_IOG_COMMAND_TYPE_FIRST if this is the first command in the I/O granularity command chain. Otherwise equals MV_IOG_COMMAND_TYPE_NEXT. union {MV_U8 transId; MV_U8 transCount} iogGranularityCommandParam - If iogCommandType indicates first command, then union refers to transCount, which indicates the number of I/Os the chain holds. Otherwise the union refers to transId, which refers to the transaction chain ID of which this command is part. MV_U8 iogCurrentTransId - If iogCommandType indicates first command, then iogCurrentTransId is output from the CORE driver and it indicates the transaction ID allocated to the chain of commands. Otherwise, iogCurrentTransId holds the transaction ID to which this command refers.
Notes Only in the case of a 48-bit LBA-feature-set-compliant storage device, numOfSectors can be more than 256 sectors and LBA address is 48-bit. Otherwise, numOfSectors can be a maximum of 256 sectors and LBA address consists of a 28-bit address. If numOfSectors is zero and the isEXT field is MV_FALSE (48-bit address feature set is not in use), then the UDMA command transfer size is 256 sectors. If numOfSectors is zero and the isEXT field is MV_TRUE (48-bit address feature set is in use), then the UDMA command transfer size is 65,536 sectors.
MV_NONE_UDMA_COMMAND_PARAMS
MV_NON_UDMA_PROTOCOL protocolType - Protocol of the requested ATA command to perform. MV_BOOLEAN isEXT- Equals MV_TRUE if the command is an LBA 48-bit extended command. MV_U16_PTR bufPtr - Pointer to a buffer that the PIO data-out/in ATA command transfers from/to (must be word (16-bit) byte aligned). MV_U32 count - Number of words to transfer from/to buffer. MV_U16 features- The value to be written to the FEATURES register. MV_U16 sectorCount - The value to be written to the SECTOR COUNT register. MV_U16 lbaLow - The value to be written to the LBA LOW register. MV_U16 lbaMid - The value to be written to the LBA MID register MV_U16 lbaHigh - The value to be written to the LBA HIGH register. MV_U8 device - The value to be written to the DEVICE register.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
MV_U8 command - The value to be written to the COMMAND register. mvSataCommandCompletionCallBack_t callBack - A callback function that is called when command execution has been completed MV_VOID_PTR commandId -An arbitrary ID that uniquely identifies the command.
MV_STORAGE_DEVICE_REGISTERS
Fields set either by the IAL or CORE driver (depending on the function used with this data structure). MV_U8 errorRegister - Storage devices error register. MV_U16 featuresRegister - Storage devices feature register. This field is set only by the CORE driver. MV_U8 commandRegister - Storage devices command register. This field is set only by the CORE driver. MV_U16 sectorCountRegister - Storage devices sector count register. MV_U16 lbaLowRegister - Storage devices low LBA register. MV_U16 lbaMidRegister - Storage devices mid LBA register. MV_U16 lbaHighRegister - Storage devices high LBA register. MV_U8 deviceRegister - Storage devices device register. MV_U8 statusRegister - Storage devices status register.
Note The 16-bit fields in the MV_STORAGE_DEVICE_REGISTERS data structure are all used only in 48-bit LBA storage devices. When using legacy 28-bit LBA addressing, only the 8-bit LSB of these fields are used.
MV_SATA_EDMA_PRD_ENTRY
Fields set by the Intermediate Application Layer: MV_U32 lowBaseAddr - Low 32-bit address of the buffer the IAL needs to read/write. MV_U16 byteCount - Length of the buffer (maximum 64 KByte). MV_U16 flags - Flags indicating how the Serial ATA Host Adapter must handle this buffer. MV_U32 highBaseAddr - High 32-bit address of the buffer the IAL needs to read/write. MV_U32 reserved - Reserved field that IAL must not use.
Note See the Serial ATA Host Adapter datasheet for further information about the fields described above.
6.5.3
6.5.3.1
The following CORE driver adapter management functions initializes and configures the Serial ATA Host Adapter and its SATA channels.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
3.
4.
5. 6.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the corresponding Serial ATA Host Adapter.
RETURN
MV_TRUE on success MV_FALSE on failure
Note The mvSataInitAdapter function does not initialize the SATA channels in the Serial ATA Host Adapter adapter.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the corresponding Serial ATA Host Adapter.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. regOffset - An offset to the register to read.
RETURN
32 bits that hold the value of the register.
Note Several Serial ATA Host Adapter internal registers are implemented as 8-bit or 16-bit registers. The above function can still be used for reading these registers. The read operation result in an 8-bit register will be in the first 8 least significant bits of the return value. The reading operating in a 16-bit register will be in the first 16 least significant bits of the return value.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. regOffset - An offset to the register to write. regValue - The value to write to the register.
RETURN
N/A
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
Note Several Serial ATA Host Adapter internal registers are implemented as 8-bit or 16-bit registers. The above function can still be used for writing to these registers. The write operation uses the 8 least significant bits in the regValue parameter for the 8-bit registers, and uses the 16 least significant bits in the regValue parameter for 16-bit registers.
6.5.3.2
INPUT
pAdapter - A pointer to an MV_SATA_ADAPTER data structure that holds information to access the Serial ATA Host Adapter device. channelIndex - An index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
Note Refer to the MV_SATA_CHANNEL data structure regarding parameters that must be filled in by the IAL before calling the mvSataConfigureChannel() function.
INPUT
pAdapter - A pointer to an MV_SATA_ADAPTER data structure that holds information to access the Serial ATA Host Adapter device. channelIndex - An index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE if a SATA storage device is connected MV_FALSE if a SATA storage device is not connected
Note This function is used to check if a storage device is connected directly to a Serial ATA Host Adapter. It cant be used for checking if a storage device is connected to a port multipliers device port.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
Note This function does not poll for disk ready status (ATA status BSY bit transits to 0) as in Release 3.1.2 and older releases. To do this, the IAL must use the mvSataChannelHardReset() function to perform the reset and OOB sequence, and afterwards use the mvStorageIsDeviceBsyBitOff() function for polling on disk ready status.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_BOOLEAN mvSataSetFBSMode (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_BOOLEAN enableFBS, MV_BOOLEAN useQueueLen128) DESCRIPTION
Configures a specific SATA channel EDMA to enable/disable the FIS Base Switching mode. If FBS mode is selected, it configures the EDMA queue depth mode of the SATA channel (32 entries mode or the 128 mode).
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. enableFBS - When true FBS mode is enabled. useQueueLen128 - When enableFBS is true, this field indicates whether or not to use the 128 entries mode of the EDMA.
RETURN
MV_TRUE on success MV_FALSE if:
The FBS feature is set to be enabled for an adapter that doesnt support this feature, or The function is called while the EDMA is enabled. useQueueLen128 is true and enableFBS is false. Note This function only sets the sw configuration, the hardware is configured accordingly by mvSataConfigEdmaMode()
MV_BOOLEAN mvSataConfigEdmaMode (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_EDMA_MODE dmaMode, MV_U8 queueDepth) DESCRIPTION
Configures a specific SATA channel EDMA mode (queued commands features set or non-queued commands feature set). If the queued commands features set is selected, it configures the queue depth the SATA channel may use. This function also sets EDMA burst sizes to maximum supported by the adapter.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. dmaMode - Can be either MV_EDMA_MODE_QUEUED, indicating queued commands feature set, or MV_EDMA_MODE_NOT_QUEUED, indicating non-queued feature set. queueDepth - Valid only if queued commands feature set is selected. This parameter indicates the queue depth the SATA channel may use.
RETURN
MV_TRUE on success
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. execCallBack - If this parameter equals MV_FLUSH_TYPE_CALLBACK, then all callback functions for all posted and not completed ATA commands are called. If it equals MV_FLUSH_TYPE_NONE then the queue is flushed without calling the callback functions.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel.
RETURN
In the case of success, the return value is number between 0.. MV_MAX_CMD - Number of UDMA ATA commands posted. In the case of failure, the return value is 0xFF.
MV_U8 mvSataGetNumOfPortQueuedCommands (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMport, MV_U8* pCommandsPerChannel) DESCRIPTION
Returns the number of posted ATA commands on the software ATA commands queue in a specific SATA channel and specific port multiplier device port.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. PMport - Device port number on the port multiplier. pCommandsPerChannel - if not a NULL, then will be set with the total number of the outstanding commands of the given channel.
RETURN
In the case of success, the return value is a number between 0.. MV_MAX_CMD and the Number of UDMA ATA commands posted. In the case of failure, the return value is 0xFF.
MV_BOOLEAN mvSataSetIntCoalParams (MV_SATA_ADAPTER *pAdapter, MV_U8 sataUnit, MV_U32 intCoalThre, MV_U32 intTimeThre) DESCRIPTION
Sets the interrupt coalescing for a specific SATA unit (each SATA unit contains quad SATA channels).
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
If the adapter supports all units interrupt coalescing (as in the case of the 88SX60X1 adapter) then sataUnit equals 0xFF, which signals the CORE driver to enable this feature.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. sataUnit - An index to a specific Serial ATA Host Adapter SATA unit. When sataUnit equals 0xFF, this is an indication for the CORE to enable the all units interrupt coalescing feature. intCoalThre - Parameter indicating the Interrupt Coalescing Threshold to be set. intTimeThre - Parameter indicating the Interrupt Time Threshold to be set.
RETURN
MV_TRUE on success MV_FALSE on failure
Notes For further information about the Interrupt Time Threshold and Interrupt Coalescing Threshold registers, see the Serial ATA Host Adapter datasheet. This function can be called in runtime without deactivating any SATA channel. When this function is called, intCoalThre and intTimeThre in the MV_SATA_ADAPTER data structure are automatically updated.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel. signalAmps - New value of the AMP (values can be from 07). pre - New value of the PRE (values can be from 03).
RETURN
MV_TRUE on success MV_FALSE on failure
Note CORE driver modifies the pre-emphasis and amplitude that were saved previously in the MV_SATA_ADAPTER data structure by mvSataInitAdapter(). This is done to preserve the new preemphasis and amplitude values after each SATA channel reset.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
Notes The physical interfaces of all SATA channels are powered on by default after reset.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
Note No disconnect interrupt will be asserted by the Serial ATA Host Adapter after the physical interface is shut down.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel.
RETURN
MV_TRUE on success of diagnostic MV_FALSE on failure of diagnostic
Note See the Serial ATA Host Adapter datasheet for an explanation of the external loopback diagnostics.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
Note The IAL can have a function loop calling mvSataEnableStaggeredSpinUp() for all SATA channels on the adapter; but the mvSataEnableStaggeredSpinUpAll() function will be faster, since it does the OOB sequence negotiation in parallel for all SATA channels.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel. ifSpeed - The required setting (or limitation) for the specific SATA channel.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
RETURN
MV_SATA_IF_SPEED_INVALID - If SATA channel staggered spinup is disabled or if an error occurred on the function parameters. MV_SATA_IF_SPEED_1_5_GBPS - If currently negotiated interface speed is Gen I. MV_SATA_IF_SPEED_3_GBPS - If currently negotiated interface speed is Gen II
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel. ifPowerState - SATA interface power state.
RETURN
MV_TRUE if the desired power state was entered successfully. MV_FALSE otherwise.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel. ifPowerState - Pointer to the variable that will be set with the SATA interface power state by this function.
RETURN
MV_TRUE on success. MV_FALSE on failure.
6.5.3.3
MV_BOOLEAN mvStorageDevATAExecuteNonUDMACommand (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMPort, MV_NON_UDMA_PROTOCOL protocolType, MV_BOOLEAN isEXT, MV_U16_PTR bufPtr, MV_U32 count, MV_U16 features, MV_U16 sectorCount, MV_U16 lbaLow, MV_U16 lbaMid, MV_U16 lbaHigh, MV_U8 device, MV_U8 command); DESCRIPTION
Performs a user-defined non-UDMA command. Possible commands must belong to a protocol of either non-data, PIO data-in or PIO data-out ATA command.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. PMPort - An index to the port multipliers destination port (equals 0 if no port multiplier available). protocolType - Protocol of the requested ATA command to perform. isEXT - MV_TRUE if the command is an LBA 48-bit extended command. bufPtr - Pointer to a buffer that the PIO data-out/in ATA command transfers from/to (must be word (16-bit) byte aligned). count - Number of words to transfer from/to buffer. features - The value to be written to the FEATURES register. sectorCount - The value to be written to the SECTOR COUNT register. lbaLow - The value to be written to the LBA LOW register. lbaMid - The value to be written to the LBA MID register. lbaHigh - The value to be written to the LBA HIGH register. device - The value to be written to the DEVICE register. command - The value to be written to the COMMAND register.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
RETURN
MV_TRUE on success MV_FALSE on failure
Note When isEXT is MV_TRUE (extended command) All the 16-bit fields of the MV_U16 parameters to the function are used. Otherwise only the 8 LSBs are used.
MV_BOOLEAN mvStorageDevATAIdentifyDevice (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMPort, MV_U16_PTR identifyDeviceResult) DESCRIPTION
Performs an IDENTIFY DEVICE ATA command to the storage device connected to the SATA channel indexed by channelIndex. The resulting commands data is stored in identifyDeviceResult.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. PMPort - An index to the port multipliers destination port (equals 0 if no port multiplier available). identifyDeviceResult - Holds a pointer to a 512 bytes data buffer that holds the IDENTIFY DEVICE ATA command result.
RETURN
MV_TRUE on success MV_FALSE on failure
MV_BOOLEAN mvStorageDevATASetFeatures (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMPort, MV_U8 subCommand, MV_U8 subCommandSpecific1, MV_U8 subCommandSpecific2, MV_U8 subCommandSpecific3, MV_U8 subCommandSpecific4) DESCRIPTION
Performs a SET FEATURES ATA command to the storage device connected to the SATA channel indexed by channelIndex.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. PMPort - An index to port multipliers destination port (equals 0 if no port multiplier available). subCommand - Sub-command for the SET FEATURES ATA command. subCommandSpecific1 - First parameter to the sub-command. subCommandSpecific2 - Second parameter to the sub-command. subCommandSpecific3 - Third parameter to the sub-command.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE on success MV_FALSE on failure
MV_BOOLEAN mvStorageDevATASoftResetDevice (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMPort, MV_STORAGE_DEVICE_REGISTERS *registerStruct) DESCRIPTION
Performs a software reset sequence on the storage device connected to the SATA channel indexed by channelIndex. The software reset sequence is performed according the software reset sequence defined in the ATA/ATAPI6 specification This function waits for the BSY bit to be 0, which occurs when FIS 34 is sent from the device to the host upon software reset completion status.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel. PMPort - An index to the port multipliers destination port (equals 0 if no port multiplier available). registerStruct - Holds a pointer to the ATA register data structure, which contains a dump of ATA registers upon completion of software reset protocol. If this parameter equals 0, ATA registers are not dumped.
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel. PMPort - An index to the port multipliers destination port (equals 0 if no port multiplier available).
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel. registerStruct - A pointer to the ATA registers data structure. If non-zero, then upon exit the function dumps the ATA registers to it.
RETURN
MV_TRUE when BSY bit is off MV_FALSE when BSY bit is on (or on failure)
MV_BOOLEAN mvStorageDevExecutePIO (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMPort, MV_NON_UDMA_PROTOCOL protocolType, MV_BOOLEAN isEXT, MV_U16_PTR bufPtr, MV_U32 count, MV_STORAGE_DEVICE_REGISTERS *pInATARegs, MV_STORAGE_DEVICE_REGISTERS *pOutATARegs) DESCRIPTION
Performs a user-defined non-UDMA command. Possible commands must belong to a protocol of either non-data, PIO data-in or PIO data-out ATA command.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. PMPort - An index to the port multipliers destination port (equals 0 if no port multiplier available). protocolType - Protocol of the requested ATA command to perform. isEXT - MV_TRUE if the command is an LBA 48-bit extended command. bufPtr - Pointer to a buffer that the PIO data-out/in ATA command transfers from/to (must be word (16-bit) byte aligned). count - Number of words to transfer from/to buffer. pInATARegs - ATA registers to be written (includes the command). pOutATARegs - Holds the result of the PIO command.
RETURN
MV_TRUE on success MV_FALSE on failure
Note When isEXT is MV_TRUE (extended command), then all the 16-bit fields of the ATA registers data structure are used. Otherwise only the 8 LSB bits are used.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel. deviceType - The deviceType connected.
RETURN
MV_TRUE on success MV_FALSE on failure
Note This function doesnt query the hardware for the type of storage device, but sets the deviceType field for the appropriate channels data structure.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel.
RETURN
MV_SATA_DEVICE_TYPE_UNKOWN if no storage device connected (or upon failure). MV_SATA_DEVICE_TYPE_ATA_DISK if a hard drive is connected. MV_SATA_DEVICE_TYPE_ATAPI_DISK if an ATAPI device connected. MV_SATA_DEVICE_TYPE_PM if a port multiplier is connected.
Note This function doesnt query the hardware for the type of storage device connected, but returns the value previously set by the mvStorageDevSetDeviceType() function.
6.5.3.4
MV_BOOLEAN mvPMDevReadReg (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMPort, MV_U32_PTR pValue, MV_STORAGE_DEVICE_REGISTERS *registerStruct) DESCRIPTION
Reads from a port multipliers internal register using PIO non-data protocol.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel. PMPort - Must be 0xF (indicated port multipliers control port). pValue - Holds the result of the read (32 bit). registerStruct - Holds a pointer to the ATA register data structure that contains a dump of ATA registers upon completion of register read. If this parameter equals 0, then ATA registers are not dumped.
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_BOOLEAN mvPMDevWriteReg (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMPort, MV_U32 value, MV_STORAGE_DEVICE_REGISTERS *registerStruct) DESCRIPTION
Writes a value to the port multipliers internal register using PIO non-data protocol.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel. PMPort - Must be 0xF (indicated port multipliers control port). value - Holds the value to be written to the register (32 bit). registerStruct - Holds a pointer to the ATA register data structure that contains a dump of ATA registers upon completion of register write. If this parameter equals 0, then ATA registers are not dumped.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel. PMPort - Holds the required port multipliers SATA channel number.
RETURN
MV_TRUE on success MV_FALSE on failure
MV_BOOLEAN mvPMDevEnableStaggeredSpinUpAll (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 PMNumOfPorts, MV_U16_PTR bitmask) DESCRIPTION
Enables SATA channel communication and triggers an OOB sequence on all port multipliers SATA channels.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
PMNumOfPorts - Holds the number of device side SATA channels that the port multiplier supports. bitmask - Pointer to 16-bit data container that holds a bitmask of 1 when the relevant port multipliers device port staggered spinup operation was successful.
RETURN
MV_TRUE on success MV_FALSE on failure
6.5.3.5
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter SATA channel. pCommandInfo - A pointer to an MV_QUEUE_COMMAND_INFO data structure that holds the parameters of the ATA command to add to the commands queue.
RETURN
MV_QUEUE_COMMAND_RESULT_OK - ATA command is queued successfully. MV_QUEUE_COMMAND_RESULT_QUEUED_MODE_DISABLED - ATA command queueing failed because queuing mode was not enabled. (the API function mvSataEnableChannelDma was not called successfully) or this mode was disabled due to an error.) MV_QUEUE_COMMAND_RESULT_FULL - Command queueing failed because the commands queue is full. MV_QUEUE_COMMAND_RESULT_BAD_LBA_ADDRESS - Command queueing failed because it tried to queue a 48-bit LBA-feature-set-compliant ATA command on a 28-bit LBA-feature-set-compliant storage device. MV_QUEUE_COMMAND_RESULT_BAD_PARAMS - UDMA command queueing failed due to bad parameters passed to function.
Note It is recommended that the IAL assign the value 0 on the MV_QUEUE_COMMAND_INFO data structure (memset operation) before filling in the required parameters.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
6.5.4
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter.
RETURN
MV_TRUE - If there was a real interrupt for the adapter. MV_FALSE - If there was no real interrupt for the adapter.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter.
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
Detailed CORE Driver Implemented API and Data Structures
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. interruptScheme - A parameter containing the required interrupt scheme.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter.
RETURN
MV_TRUE if there a pending interrupt MV_FALSE if there is no pending interrupt
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - Index to a specific Serial ATA Host Adapter channel.
RETURN
MV_TRUE if a device error is reported, and MV_FALSE otherwise.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_VOID - Void MV_U32 - Unsigned 32-bit MV_U16 - Unsigned 16-bit MV_U8 - Unsigned 8-bit MV_VOID_PTR - Pointer to void MV_U32_PTR - Pointer to unsigned 32-bit MV_U16_PTR - Pointer to unsigned 16-bit MV_U8_PTR - Pointer to unsigned 8-bit MV_CHAR_PTR - Pointer to string MV_BUS_ADDR_T - Type that makes it possible for CPU to access PCI addresses MV_CPU_FLAGS - Type that makes it possible for CORE driver to save and restore CPU flags
6.6.1.2
Defines (User-Implemented)
MV_CPU_WRITE_BUFFER_FLUSH() - Macro for flushing CPU write buffer. MV_CPU_TO_LE16 (x) - Macro for converting 16-bit from CPU endianess to Little Endian. MV_CPU_TO_LE32 (x) - Macro for converting 32-bit from CPU endianess to Little Endian. MV_LE16_TO_CPU (x) - Macro for converting 16-bit from Little Endian to CPU endianess. MV_LE32_TO_CPU (x) - Macro for converting 32-bit from Little Endian to CPU endianess. MV_REG_WRITE_BYTE (base, offset, value) - Macro for writing byte to Serial ATA Host Adapter internal register. MV_REG_WRITE_WORD (base, offset, value) - Macro for writing word (16-bit) to Serial ATA Host Adapter internal register. MV_REG_WRITE_DWORD (base, offset, value) - Macro for writing dword (32-bit) to Serial ATA Host Adapter internal register. MV_REG_READ_BYTE (base, offset) - Macro for reading a byte from Serial ATA Host Adapter internal register. MV_REG_READ_WORD (base, offset) - Macro for reading a word (16-bit) from Serial ATA Host Adapter internal register. MV_REG_READ_DWORD (base, offset) - Macro for reading a dword (32-bit) from Serial ATA Host Adapter internal register.
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
System-Dependent Header File (mvOs.h)
6.6.2
6.6.2.1 6.6.2.2
Data Structures
MV_OS_SEMAPHORE (User-Implemented) Command Completion and Event Notification (User-Implemented)
MV_BOOLEAN mvSataCommandCompletionCallBack (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_COMPLETION_TYPE completionType, MV_VOID_PTR *commandID, MV_U16 errorCause, MV_U32 timeStamp, MV_STORAGE_DEVICE_REGISTERS *registerStruct) DESCRIPTION
This callback function is used by the CORE driver to indicate a command completion event.
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. channelIndex - An index to a specific Serial ATA Host Adapter channel. completionType - Equals MV_COMPLETION_TYPE_NORMAL if completion is normal with no errors, MV_COMPLETION_TYPE_ERROR if completion is erroneous, or MV_COMPLETION_TYPE_ABORT if completion is due to an abort request (due to previously called mvSataFlushDmaQueue function with flushType equals FLUSH_TYPE_CALLBACK as a parameter to it). commandID - The command identifier as it is passed to the functions mvSataQueueUdmaCommand/
RETURN
MV_TRUE on success MV_FALSE on failure
Note See the Serial ATA Host Adapter datasheet for further information on a specific SATA channel Error Cause register.
MV_BOOLEAN mvSataEventNotify (MV_SATA_ADAPTER *pAdapter, MV_EVENT_TYPE eventType, MV_U32 param1, MV_U32 param2) DESCRIPTION
This callback function is called when the CORE driver needs to notify the IAL of a specific event.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
INPUT
pAdapter - A pointer to the MV_SATA_ADAPTER data structure, which holds all information for accessing the Serial ATA Host Adapter. eventType - Equals MV_EVENT_TYPE_ADAPTER_ERROR in the case of an error in the Serial ATA Host Adapter or equals MV_EVENT_TYPE_SATA_CABLE in the case of a disconnect/connect of a storage device to a SATA channel or MV_EVENT_TYPE_SATA_ERROR in case SATA link error or ATA device error. param1 - If eventType is MV_EVENT_TYPE_ADAPTER_ERROR, this parameter holds the PCI Cause register read from the Serial ATA Host Adapter. If eventType is MV_EVENT_TYPE_SATA_CABLE, this parameter equals 0 in the case of a disconnect event notification, or equals 1 in the case of a connect event notification. If the eventType is MV_EVENT_TYPE_SATA_ERROR, this parameter is MV_SATA_RECOVERABLE_COMMUNICATION_ERROR if the SATA link error is recoverable, MV_SATA_UNRECOVERABLE_COMMUNICATION_ERROR if the SATA link error is unrecoverable of MV_SATA_DEVICE_ERROR if ATA device error occurred. param2 - If eventType is MV_EVENT_TYPE_ADAPTER_ERROR, this parameter is not in use. If eventType equals MV_EVENT_TYPE_SATA_CABLE or MV_EVENT_TYPE_SATA_ERROR, this parameter holds the index of the SATA channel on which the connect/disconnect/error event.
RETURN
MV_TRUE on success MV_FALSE on failure
Note When this function is called with MV_EVENT_TYPE_SATA_ERROR, and param1 is MV_SATA_UNRECOVERBALE_ERROR, then the IAL is responsible for doing the error recovery. This recovery involves disabling the EDMA, flushing commands, doing hard reset, then restarting the channel. When MV_SATA_RECOVERABLE_ERROR or MV_SATA_DEVICE_ERROR events are received, the IAL shouldnt be involved in the error recovery process, since it is performed automatically by the hardware or by the CORE driver.
6.6.2.3
INPUT
semaphore - A pointer to an MV_OS_SEMAPHORE data structure that holds semaphore information to be initialized.
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
System-Dependent Header File (mvOs.h)
INPUT
semaphore - A pointer to an MV_OS_SEMAPHORE data structure.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
semaphore - A pointer to an MV_OS_SEMAPHORE data structure.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - A pointer to the adapters data structure. delay - Number of micro-seconds to delay.
RETURN
N/A
6.6.2.4
Logger API
INPUT
moduleId - The module identifier. filterMask - The filter mask for logging.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
name- Pointer to the module name. The module name string is not copied by the logger so the caller must not free the memory containing the string.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
moduleId - The module identifier. filterMask - The new filter mask for logging.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
moduleId - The module identifier.
RETURN
Module logging filter value. For unregistered module, this function returns 0.
INPUT
moduleId - The module identifier. type - Log message type format - Formatted string
RETURN
None
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
System-Dependent Header File (mvOs.h)
6.6.2.5
INPUT
pAdapter - Pointer to the adapter data structure. enable - MV_TRUE to enable interrupt coalescing in I/O granularity, MV_FALSE to disable interrupt coalescing in I/O granularity
RETURN
MV_TRUE on success MV_FALSE on failure
6.6.2.6
MV_BOOLEAN mvSataC2CInit(MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_SATA_C2C_MODE mvSataC2CMode, MV_VOID_PTR mvSataC2CCallBack) DESCRIPTION
Initializes SATA channel for Target Mode communication.
INPUT
pAdapter - pointer to the adapter data structure. - index of the specific SATA channel. channelIndex
mvSataC2CMode - the channel role in Target Mode communication: target or initiator. mvSataC2CCallBack - callback function to call on target mode communication event.
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - pointer to the adapter data structure. - the index of the specific SATA channel channelIndex
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_BOOLEAN mvSataC2CSendRegisterDeviceToHostFIS (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 pmPort, MV_BOOLEAN bInterrupt, MV_U8 msg[MV_C2C_MESSAGE_SIZE]) DESCRIPTION
Sends Register Device to Host FIS on specific SATA channel.
INPUT
pAdapter - pointer to the adapter data structure. channelIndex - the index of the specific SATA channel. pmPort - Port multiplier port number. bInterrupt - determines whether to generate the interrupt on the receiver side. msg - message containing 10 bytes of user data, which is reflected in ATA register on the receiver channel.
RETURN
MV_TRUE on success MV_FALSE on failure
MV_BOOLEAN mvSataC2CActivateBmDma (MV_SATA_ADAPTER *pAdapter, MV_U8 channelIndex, MV_U8 pmPort, MV_U32 prdTableHigh, MV_U32 prdTableLow, MV_UDMA_TYPE dmaType) DESCRIPTION
Activates Bus Master DMA for the specific SATA channel.
INPUT
pAdapter - pointer to the adapter data structure. - the index of the specific SATA channel. channelIndex
pmPort - Port Multiplier port number. prdTableHigh - the upper 32-bit of PRD table address. prdTableLow - the lower 32-bit of PRD table address. dmaType - DMA operation type (read or write).
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
pAdapter - pointer to the adapter data structure. - the index of the specific SATA channel. channelIndex
RETURN
MV_TRUE on success
CONFIDENTIAL
Document Classification: Proprietary Information
Core Driver
System-Dependent Header File (mvOs.h)
MV_FALSE on failure
typedef MV_BOOLEAN (*C2CCallBack_t)(struct mvSataAdapter * pAdapter, struct mvSataChannel * pChannel, MV_C2C_EVENT_TYPE event, MV_U32 msgSize, MV_U8* msg); DESCRIPTION
This is a user-implemented callback function, which is executed upon target mode Register device to host FIS reception, Bus Master DMA transfer completion, or communication error.
INPUT
pAdapter - pointer to the adapter data structure. pChannel - pointer to the SATA channel data structure. event - target mode communication event which could be one of the following: - MV_C2C_REGISTER_DEVICE_TO_HOST_FIS_DONE: Register device to host FIS has been successfully received. - MV_C2C_REGISTER_DEVICE_TO_HOST_FIS_ERROR: Register device to host FIS transfer error. - MV_C2C_BM_DMA_DONE: Bus Master DMA transaction succeeded. - MV_C2C_BM_DMA_ERROR: Bus Master DMA data transfer error succeeded. msgSize - message buffer size. If message buffer is unavailable, equals 0. msg - message buffer which contains either 10 bytes user data in the case of MV_C2C_REGISTER_DEVICE_TO_HOST_FIS, otherwise equal to NULL.
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
7.1 Introduction
The SCSI to ATA Translation Layer (SAL) driver is a software layer that is operating system and architecture independent. The functionality of this layer is to translate SCSI commands into ATA commands and vice versa. It can be used as a sub-component of an OS-specific driver that is layered under the OS SCSI sub-system.
7.2 Architecture
This layer is built on the CORE driver layer and the Common Intermediate Application layer. From the upper side, it provides an entry point that handles SCSI commands. The upper IAL components are responsible for the adapter management, which involves initializing the adapter, SATA channels, SATA drives, handling hot-plug events etc. Also, several OS services are needed by this layer mainly for messages logging. These services are provided by the OS layer that is integrated with the CORE driver.
The SAL complies with the following SCSI standards: 1. SCSI-3 Architecture Model (X3.270-199x) (SAM). 2. SCSI-3 Primary Commands (X3.301 - 199x) (SPC). 3. SCSI-3 Block Commands (ANSI NCITS 306-199X)(SBC).
7.4.2
Device Addressing
The following SCSI to ATA device addressing translation scheme holds: SATA channel translated to SCSI bus.
CONFIDENTIAL
Document Classification: Proprietary Information
Port multiplier device port translated to SCSI target. SATA drive contains one lun (lun 0).
7.4.3
7.4.3.1
SCSI Features
Unit Attention Condition Reporting
The following events reported separately in the following order: 1. Bus reset occurred - Additional sense 29h and additional sense qualifier 2h. 2. Parameters changed - Additional sense 2Ah and additional sense qualifier 1h. upon power-on or hardware reset the IAL notifies the SAL about unit attention condition, the SAL in turn report the first event for the first command it receives, and the second event is reported for the consecutive command (unless the command is INQUIRY or REQUEST SENSE, see SAM for details).
7.4.3.2
Auto-Sense
when command completes with CHECK CONDITION status the SAL reports the sense data automatically, actually this the only mode supported for reporting sense data, the SAL doesnt store this data for future reporting using the request sense command
7.4.3.3
The following mode pages are supported: Caching mode page Control mode page
7.4.3.4
Relative Addressing
7.4.4
Table 2:
Command READ(6) READ(10) WRITE(6) WRITE(10) INQUIRY TEST UNIT READY MODE SELECT(6)
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
Table 2:
Supported SCSI Commands (Continued) SCSI Operation Code 1Ah 25h 03h 13h 2fh 35h 2Bh 07h 3Fh
Command MODE SENSE(6) READ CAPACITY(10) REQUEST SENSE(6) VERIFY(6) VERIFY(10) SYNCHRONIZE CACHE(10) SEEK(10) REASSIGN BLOCKS WRITE LONG(10)
In some cases a SCSI command is translated into several ATA commands, e.g., when a VERIFY (10) command with 512 sectors is received for a drive that doesnt support the ATA command READ VERIFY SECTORS EXT, it is translated into READ VERIFY SECTORS. But this ATA command is limited to 256 sectors only, so the solution is to send two commands, each with 256 sectors. When command splitting is required, the SAL sends these ATA commands one by one in a serial manner, i.e., one command is sent, and when it has been completed by the CORE drive, the next command is sent.
7.5.2
Control Synchronization
The SAL doesnt implement any synchronization mechanism to protect its internal data. The IAL is responsible for doing this. The SAL API functions are not re-entrant and must not be called simultaneously unless they are called for different adapters.
7.5.3
Buffer Synchronization
A typical SCSI command involves two buffersdata buffer and sense data buffer. The sense data buffer is modified by the SAL for all SCSI commands. The data buffer is also modified by the SAL for all SCSI commands except the READ(6), READ(10), WRITE(6), and WRITE(10) SCSI commands. For these commands, data buffers are always accessed by the hardware DMA. The IAL must take this into consideration when synchronizing buffers between the CPUs cache and the system memory.
CONFIDENTIAL
Document Classification: Proprietary Information
WRITE(6) WRITE(10)
0Ah 2Ah
12h 00h
MODE SELECT(6) 15h MODE SENSE(6) READ CAPACITY(10) REQUEST SENSE(6) VERIFY(6) VERIFY(10) 1Ah 25h 03h 13h 3Fh
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
Table 4:
No Media
If the ATA command is READ VERIFY SECTORS(EXT) set the sense key to Unit Attention. Else if the ATA command is DMA command (READ/WRITE DMA [QUEUED][EXT]..) set the sense key to Unit Attention, and set the Additional Sense Code to 3Ah (No Media in Device). If the ATA command is READ VERIFY SECTORS(EXT) set the sense key to Unit Attention. Else if the ATA command is DMA command (READ/WRITE DMA [QUEUED][EXT]..) set the sense key to Unit Attention, and set the Additional Sense Code to 3Ah (No Media in Device). If the ATA command is READ VERIFY SECTORS(EXT) set the sense key to Unit Attention. Else if the ATA command is DMA command (READ/WRITE DMA [QUEUED][EXT]..) set the sense key to Unit Attention, and set the Additional Sense Code to 3Ah (No Media in Device). If the ATA command is READ VERIFY SECTORS(EXT) or SET FEATURES set the sense key to Aborted Command and set the Additional Sense Code to No Sense Code. Else if the ATA command is DMA command (READ/WRITE DMA [QUEUED][EXT]..) then check the IDNF. If IDNF is not set, then set the SCSI sense key to ILLEGAL REQUEST and set the Additional Sense Code to ILLEGAL BLOCK. If the IDNF is also set, then set the sense key to Aborted Command and set the Additional Sense Core to No Sense. If the ATA command is READ VERIFY SECTORS(EXT) set the sense key to Aborted Command and set the Additional Sense Code to No Sense Code. Else if the ATA command is DMA command (READ/WRITE DMA [QUEUED][EXT]..) then check the ABRT. If ABRT is not set, then set the SCSI sense key to ILLEGAL REQUEST and set the Additional Sense Code to ILLEGAL BLOCK. If the ABRT is also set, then set the sense key to Aborted Command and set the Additional Sense Core to No Sense. If the ATA command is READ VERIFY SECTORS(EXT) or READ DMA, set the sense key to Medium Error, set the Valid bit to 1, and set the Information bytes with the LBA Address in the Sense buffer of the relevant SCSI command. Else if the ATA command is Write DMA command (WRITE DMA [QUEUED][EXT]..), this error is called WP(Write Protect). Set the sense key to Data Protect and set the Additional Sense Code set to No Sense.
MC
Media Changed
MCR
ABRT
Command Aborted
IDNF
UNC
Uncorrectable data
CONFIDENTIAL
Document Classification: Proprietary Information
Table 4:
If the ATA command is DMA command (READ/WRITE DMA [QUEUED][EXT]..) set the sense key to Aborted Command and set the Additional Sense Code to No Sense Code.
Note If the ATA error received doesnt match the above-mentioned cases, set the sense key to Aborted Command and set the Additional Sense Code to No Sense Code.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_SCSI_COMPLETION_TYPE - This enumerator defines the values used to describe how the SCSI command is completed by the SAL. For some values the SAL also sets the SCSI command status.
Table 5:
Enumerators
D e s cr ip ti o n Initial value set by SAL. Should not be returned unless unexpected error occurred. Command completed successfully with no errors. Bad SCSI Command Block. Something is wrong with the parameters passed in this structure (e.g, the data length to transfer doesnt match the number of sectors). Bad parameter in the SCSI CDB. Translated ATA command completer with error. No place in the CORE drive commands queue for the translated command. CORE drive not ready for queuing ATA commands. Command was aborted by the CORE driver. Returned data less than the data buffer length. SCSI Sta tu s N/A GOOD N/A
CHECK CONDITION CHECK CONDITION CHECK CONDITION N/A N/A GOOD/ CHECK CONDITION GOOD/ CHECK CONDITION CHECK CONDITION N/A N/A N/A N/A N/A CHECK CONDITION CHECK CONDITION
UNDERRUN
Command failed due to parity error. Drive was disconnected while processing the command. Targeted device not available. SCSI bus ID not valid. Not Used. Not Used. Command failed with unit attention condition due to bus reset. Command failed with unit attention condition and parameters changed.
CONFIDENTIAL
Document Classification: Proprietary Information
MV_SCSI_COMMAND_STATUS_TYPE - Returned by mvSataExecuteScsiCommand() to describe the flow of the SCSI command. The values of this enumerator are: Table 6: Enumerator Values Desc ription SCSI command was completed when it was processed by mvSataExecuteScsiCommand(), and the completion callback function was called. Translated to ATA command(s) that are queued in the CORE drivers commands queue. mvSataExecuteScsiCommand() failed to handle this command due to unexpected error. Not used by SAL.
7.9.2
7.9.2.1
Data Structures
MV_SATA_SCSI_CMD_BLOCK
This structure contains the input/output and context information of SCS command to be processed by mvSataExecuteScsiCommand().
Description of Fields:
IN MV_U8* IN MV_U32 IN MV_U8 IN MV_U8 IN MV_U8 ScsiCdb - SCSI command data block buffer ScsiCdbLength - Length in bytes of the CDB (6,10,12,16) bus - SCSI bus target - Target device ID lun - SCSI lun number of the device
IN MV_BOOLEAN useSingleBuffer - True when the data located in the buffer pointed by pDataBuffer (virtual address). False when the command is READ/WRITE. In this case the dates located in a PRD table. IN MV_U8 IN MV_U32 IN MV_U32 IN MV_U32 IN MV_U32 OUT MV_U8 IN MV_U8* IN MV_U32 OUT MV_U32 OUT MV_U32 *pDataBuffer - Pointer to the command data buffer dataBufferLength - Length in bytes of the command data buffer PRDTableEntries - Number of entries in the PRD table PRDTableLowPhyAddress - Low 32 bits of the PRD table physical address PRDTableHighPhyAddress - High 32 bits of the PRD table physical address ScsiStatus - SCSI status will be written to this field pSenseBuffer - Pointer to the SCSI sense buffer senseBufferLength - Length in bytes of the SCSI sense buffer senseDataLength - Length in bytes of the generated sense data dataTransfered - Length in bytes of the data transferred to the data buffer/s
OUT MV_SCSI_COMPLETION_TYPE ScsiCommandCompletion - Translation layer status of the completed SCSI command callback function called by the translation layer when the SCSI completed.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
IN mvScsiCommandCompletionCallBack completionCallBack - Callback function to be invoked when the command is completed. IN struct mvSalAdapterExtension * pSalAdapterExtension - Pointer to the SAL extension of the adapter. IN struct mvIALCommonAdapterExtension* pIalAdapterExtension - Not used by SAL MV_VOID_PTR IALData - This field is for the IAL use only.
The following are fields for internal use by the translation layer: MV_UDMA_TYPE udmaType
MV_QUEUED_COMMAND_TYPE commandType - Used for sense buffer MV_U32 MV_BOOLEAN MV_U16 MV_U16 LowLbaAddress - Used for non-UDMA and for sense buffer isExtended splitCount sequenceNumber - Used to create a list for commands that need post interrupt service
7.9.2.2
MV_SATA_SCSI_CHANNEL_STATS
This structure is used for collecting statistics of the I/Os sent by the SAL. The fields of this structure are: MV_U32 MV_U32 MV_U32 totalIOs totalAccumulatedOutstanding totalSectorsTransferred
7.9.2.3
MV_SATA_SCSI_DRIVE_DATA
driveReady - Indicates that the drive is ready for receiving ATA commands
This structure contains the information used by the SAL per SATA drive fields: MV_BOOLEAN
ATA_IDENTIFY_INFO identifyInfo - This structure contains information based on the IDENTIFY DATA that should be set by the IAL MV_U16_PTR identifyBuffer - Pointer to the buffer to which to write IDENTIFY data
MV_SATA_SCSI_CHANNEL_STATS stats - I/Os statistics MV_BOOLEAN MV_U32 UAConditionPending - If Unit Attention Condition is pending
7.9.2.4
MV_SAL_ADAPTER_EXTENSION
This structure contains the information used by the SAL for a given adapter. The fields of this structure are: MV_SATA_ADAPTER *pSataAdapter - Pointer to the CORE driver data structure MV_SATA_SCSI_CMD_BLOCK *pHead - Head of a linked list of the commands that need service when mvSataScsiPostIntService() is invoked
CONFIDENTIAL
Document Classification: Proprietary Information
MV_SATA_SCSI_DRIVE_DATA ataDriveData [MV_SATA_CHANNELS_NUM][MV_SATA_PM_MAX_PORTS] - SATA drive information for each drive MV_U16 identifyBuffer[MV_SATA_CHANNELS_NUM][MV_ATA_IDENTIFY_DEV_DATA_LENGTH] - Data buffer for the IDENTIFY command. One buffer is used for each channel, so multiple devices on the same channel share this buffer.
7.9.3
API Functions
INPUT
pAdapterExt - Pointer to SAL structure extension allocated for a given adapter. pSataAdapter - Pointer to MV_SATA_ADAPTER data structure, which holds information to access the Serial ATA Host Adapter device.
MV_VOID
mvSataScsiPostIntService(MV_SAL_ADAPTER_EXTENSION *pAdapterExt)
DESCRIPTION
This function should be called after calling the CORE driver ISR. When the SCSI command is split into multiple ATA commands, this function sends the next ATA command when one has been completed.
INPUT
pAdapterExt - Pointer to SAL structure extension allocated for given adapter.
INPUT
pMvSataCmdBlockAdapterExt - Pointer to SCSI COMMAND BLOCK structure, which contains the information of the SCSI command to translate.
RETURN
MV_SCSI_COMMAND_STATUS_TYPE - How the command was processed
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_VOID mvSataScsiSetDriveReady(MV_SAL_ADAPTER_EXTENSION *pAdapterExt, MV_U8 channelIndex, MV_U8 PMPort, MV_BOOLEAN isReady) DESCRIPTION
Informs the SAL that SATA drive(s) are ready/not ready.
INPUT
pAdapterExt - Pointer to SAL structure extension allocated for a given adapter. channelIndex - Channel number where the drive is connected. PMPort - Port number where the drive is connected. When isReady is MV_FALSE a failure of FFh indicates that all the drives on the given channel are not ready. isReady - If equals MV_TRUE then the drive is ready. When MV_FALSE then drive(s) are not ready.
chan-
INPUT
pAdapterExt - Pointer to SAL structure extension allocated for a given adapter. channelIndex - Channel number where the drive is connected. PMPort - Port number where the drive is connected.
CONFIDENTIAL
Document Classification: Proprietary Information
8.1 Introduction
The Common IAL component is a software package which is operating system and architecture -independent. It has two main functionalitiesit provides the set of helper API functions to the system-dependent IAL layer and manages state machines of the adapter and SATA channel. The Common IAL component API and data structures are divided into three categories:
Common IAL implemented helper API and data structures: Includes the helper routines for the systemdependent IAL. Common IAL implemented state machine API and data structures: Includes the functions and data structures used in the adapter and channels state machine. Common IAL User-implemented API: Includes several functions and a single data structure which must be implemented by the user in the system-dependent IAL layer.
The Common IAL layer provides the following functionality: Triggers SATA adapter initialization sequence through the Core Driver API. Manages a state machine for the adapter and its channels to provide an asynchronous SATA adapter and SATA channels initialization process that is completely transparent to OS. Interacts with SAL to provide the representation of SATA connected equipment in SAL. Interacts with system-dependent IAL layer to represent the SATA adapters and SATA equipment connected to their channel to user application or OS SCSI subsystem. Notifies system-dependent IAL about changes in the status of SATA connected equipment and serves as a wrapper between system-dependent IAL and SAL component. Access to TWSI devices connected to the 88SX6041, 88SX6042, 88SX6081, and 88SX7042, adapter TWSI bus. This document is divided into the following sections: Common IAL basic design and integration guidelines: Describes the basic design guidelines for Common IAL. Common IAL state machine for adapter and channels: Describes a Common IAL state machine for the adapter and its channels. Common IAL API Summary: Categorizes the Common IAL data structure and API being used.
8.2.1
Serial ATA devices such as disk drives and Port Multipliers may not initialize immediately. Usually Port Multipliers initialize faster than disk drives, since they dont have any mechanical parts. It usually takes few seconds for a disk drive to initialize, until it reports about the devices malfunctions. On other hand, operating systems such as Linux
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
and Windows require the device driver to avoid any delays longer than ~10 milliseconds, since longer delays affect OS system performance and smoothness, and occasionally may cause certain management processes to timeout. To resolve this issue, the Common IAL component provides a mechanism of asynchronous SATA adapter and SATA channels initialization that is completely transparent to the OS. The initialization sequence is state-machinebased and timer-driven, so channels initialization is done in the background and enables the other OS components to continue running.
8.2.2
System Timer
The state machines of the adapter and channel are timer-driven, thus every adapter instance requires a single, periodic, low-resolution OS timer. The timer period default value must be set to 0.5 seconds, unless modified by the user. When a channel state requires a longer timeout period, timer events are accumulated until the timer expiration threshold is reached.
8.2.3
The Common IAL optionally maintains a SCSI command software queue, which contains the SCSI commands submitted by the OS before channel initialization has been completed. When channel initialization has been completed, all SCSI commands in the queue are returned to the OS with BUSY status, which causes the OS to retry the commands.
Note For Windows OS the command queue is not required. In this case when channel initialization sequence has not completed, the SCSI command is completed immediately and returned to OS with BUSY status.
CONFIDENTIAL
Document Classification: Proprietary Information
Figure 6:
Com m on IAL
Functions
Data Structures
SAL API
SAL
Core Driver
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
8.3.1
mvGetSataDeviceType
mvInitSataDisk mvGetPMDeviceInfo
mvStopChannel mvPMHotPlugDetected
mvIALTimerCallback
mvCommandCompletionErrorHandler
mvExecuteScsiCommand
8.3.2
CONFIDENTIAL
Document Classification: Proprietary Information
8.4.1
AD AP TE R _ IN IT IA LI Z IN G
In i ti a l a da p te r s ta t e
Staggered spin-up for SATA II adapter done SATA I adapter Error: Adapter data structure not initialized
ADAPTER_READY
Working adapter state. When the adapter changes its state from ADAPTER_INITIALIZING to ADAPTER_READY, all channels states are set to CHANNEL_DISCONNECTED and the channel initialization algorithm is triggered.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
8.4.2
CHANNEL_CONNECTED
Channel is connected to adapter. Start SRST for channel in Gen. II and set polling timer to 31 seconds. -> CHANNEL_NOT_CONNECTED
CHANNEL_IN_SRST 1. Device BSY bit is set and 31 sec. timeout has expired.
Check every 0.5 seconds if the device BSY bit is cleared. If so, start device detection. -> CHANNEL_NOT_CONNECTED
2. Device BSY bit is set but timeout -> CHANNEL_IN_SRST has not expired. 3. Device BSY bit is clear and Port -> CHANNEL_PM_STAGGERED_SPIN_UP Multiplier (PM) device detected. Configure PM. Proceed with PM staggered spin-up for all PM ports. 4. Device BSY bit is clear and SATA disk drive is detected. Initialize SATA disk drive. Enable channel EDMA. 5. Any failure in 3 or 4. -> CHANNEL_READY
-> CHANNEL_NOT_CONNECTED
CONFIDENTIAL
Document Classification: Proprietary Information
PM device is detected on channel. Initiate staggered spin-up for all PM ports CHANNEL_NOT_CONNECTED CHANNEL_PM_SRST_DEVICE
2. Staggered spin-up successfully com-> pleted. Detect PM ports on which the devices are present. Set index of first PM connected device being initialized. Start device SRST. Set channel timer to 31 sec.
CHANNEL_PM_SRST_DEVICE
PM device is detected and staggered spin-up is completed. The channel remains in this state until all devices connected to PM are initialized.
1. BSY bit is clear on PM con-> CHANNEL_PM_SRST_DEVICE nected device (disk drive) found in SRST. Initialize disk drive. There are more devices connected to PM. Start SRST on next device. Set channel timer to 31 sec. -> CHANNEL_READY 2. BSY bit is clear on PM connected device (disk drive) found in SRST. Initialize disk drive. There are no more devices connected to PM. Enable channel EDMA 3. Failed to communicate with PM device. -> CHANNEL_NOT_CONNECTED
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
CHANNEL_READY
Channel and all attached devices are initialized. Flush SCSI command queue for this channel if one is being maintained. All commands are returned with BUSY status and OS resubmits them later.
If the channel has a PM connected to it and asynchronous notification is not supported by PM, start polling the PM Error information GSCR[33] register every 0.5 sec.
1. Channel disconnect detected. 2. PM hot plug is detected, either by polling or by receiving the event from Core Driver.
CHANNEL_PM_HOT_PLUG
The channel remains in this state until the channels EDMA command queue on this channel is empty. If the queue is empty, restart the channel by setting its state to CHANNEL_CONNECTED. The channel is being restarted.
8.5.1
8.5.1.1
MV_ADAPTER_STATE: Adapter state enumerator for either ADAPTER_INITIALIZING, ADAPTER_READY, or ADAPTER_FATAL_ERROR MV_CHANNEL_STATE: Channel state enumerator for either CHANNEL_NOT_CONNECTED, CHANNEL_CONNECTED, CHANNEL_IN_SRST, CHANNEL_PM_STAGGERED_SPIN_UP, CHANNEL_PM_SRST_DEVICE, CHANNEL_READY, or CHANNEL_PM_HOT_PLUG. MV_IAL_ASYNC_TIMER_PERIOD: Timer period define in milliseconds (equals to 500).
CONFIDENTIAL
Document Classification: Proprietary Information
8.5.1.2
Data Structures
MV_IAL_COMMON_CHANNEL_EXTENSION
MV_U8 PMnumberOfPorts Number of ports in Port Multiplier if one is connected to current channel. MV_U16 PMdevsToInit Bit mask to enumerate the Port Multiplier connected devices that need further initialization: Bit value of 1 means that a device needs to be initialized. MV_U8 devInSRST Indicates a Port Multiplier connected device on which the software reset is in progress. MV_BOOLEAN completionError Indicates that SCSI command completion error has occurred on current channel. When the Port Multiplier is connected to the channel, completionError is equal to MV_TRUE and asynchronous notification is not supported by the Port Multiplier. The driver checks the change in status of Port Multiplier connected devices before submitting the next SCSI command. MV_U8 pmAccessType Used for Port Multiplier polling mechanism. Indicates the access type to the Port Multiplier registers: Equals either MV_ATA_COMMAND_PM_READ_REG or MV_ATA_COMMAND_PM_WRITE_REG. MV_U8 pmReg Used for Port Multiplier polling mechanism. Stores the Port Multiplier register number to access. MV_BOOLEAN pmRegAccessInProgress Indicates that a Port Multiplier register access is pending. This is used to prevent the polling routine from reentering the register access. Equal to MV_TRUE if the register access is in progress. MV_BOOLEAN pmAsyncNotifyEnabled Indicates that a asynchronous notification is supported by the Port Multiplier connected to this channel. MV_U32 SRSTTimerThreshold Stores the timer expiration value of the software reset timer. MV_U32 SRSTTimerValue Stores the current timer value of the software reset timer. MV_VOID_PTR IALChannelPendingCmdQueue Head of the command queue managed by the Common IAL.
MV_IAL_COMMON_ADAPTER_EXTENSION
MV_SATA_ADAPTER *pSataAdapter Pointer to the Core Driver adapter data structure. MV_ADAPTER_STATE adapterState Current state of the adapter. MV_CHANNEL_STATE channelState[MV_SATA_CHANNELS_NUM] Current state of adapters channels.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
8.5.2
8.5.2.1
INPUT
iden - pointer to the buffer returned by the ATA IDENTIFY command pIdentifyInfo- pointer to the ATA parameters structure
RETURN
MV_TRUE on success MV_FALSE on failure
INPUT
mvRegs - ATA registers structure
RETURN
MV_SATA_DEVICE_TYPE_UNKNOWN - unknown device type MV_SATA_DEVICE_TYPE_ATA_DISK - ATA disk drive MV_SATA_DEVICE_TYPE_ATAPI_DISK - ATAPI disk drive MV_SATA_DEVICE_TYPE_PM - Port Multiplier
MV_BOOLEAN mvInitSataDisk(MV_SATA_ADAPTER *pSataAdapter, MV_U8 channelIndex, MV_U8 PMPort, ATA_IDENTIFY_INFO *pIdentifyInfo, MV_U16_PTR identifyBuffer) DESCRIPTION
Retrieves drive information using ATA IDENTIFY command and initialized disk drive using SET FEATURES ATA command.
CONFIDENTIAL
Document Classification: Proprietary Information
OUTPUT
pIdentifyInfo - pointer to IDENTIFY information structure identifyBuffer - pointer to IDENTIFY buffer
RETURN
MV_TRUE on success MV_FALSE on failure
8.5.2.2
INPUT pSataAdapter - pointer to Core Driver adapter data structure ialExt - Common IAL adapter data structure allocated by system-dependent IAL scsiAdapterExt - pointer to SAL extension RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
void mvRestartChanne(MV_IAL_COMMON_ADAPTER_EXTENSION *ialExt, MV_U8 channelIndex, MV_SAL_ADAPTER_EXTENSION *scsiAdapterExt, MV_BOOLEAN bBusReset) DESCRIPTION
Restarts the initialization sequence for current channel. The channel state is changed to CHANNEL_CONNECTED, the OS is notified about the change in the bus and the channel initialization is started.
INPUT ialExt - Common IAL adapter data structure allocated by system-dependent IAL
channelIndex - channel number scsiAdapterExt - pointer to SAL extension bBusReset - Equals MV_TRUE if the function was called upon bus reset.
RETURN
None
INPUT ialExt - Common IAL adapter data structure allocated by system-dependent IAL
channelIndex - channel number
INPUT ialExt - Common IAL adapter data structure allocated by system-dependent IAL
channelIndex - channel number
CONFIDENTIAL
Document Classification: Proprietary Information
INPUT ialExt - Common IAL adapter data structure allocated by system-dependent IAL scsiAdapterExt - pointer to SAL extension RETURN
MV_TRUE on success MV_FALSE on failure
INPUT ialExt - Common IAL adapter data structure allocated by system-dependent IAL channelIndex - channel number RETURN
None
INPUT
pScb - SCSI command block structure canQueue - determines if the IAL can queue this command
RETURN
Return MV_SCSI_COMMAND_STATUS_COMPLETED if the command has been returned to the OS. Return MV_SCSI_COMMAND_STATUS_QUEUED_BY_IAL if the command has been queued to the channel software queue. Otherwise return the result of mvSataExecuteScsiCommand() function call.
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
8.5.3
The system-dependent IAL layer must supply the following functions to the Common IAL:
INPUT pSataAdapter - pointer to Core Driver adapter data structure channelIndex - channel number RETURN
MV_TRUE on success MV_FALSE on failure
INPUT pSataAdapter - pointer to Core Driver adapter data structure channelIndex - channel number RETURN
None
INPUT pSataAdapter - pointer to Core Driver adapter data structure channelIndex - channel number RETURN
MV_TRUE on success MV_FALSE on failure
MV_BOOLEAN IALConfigQueuingMode(MV_SATA_ADAPTER *pSataAdapter, MV_U8 channelIndex, MV_EDMA_MODE mode, MV_U8 queueDepth) DESCRIPTION
Performs all system-dependent IAL operations for queuing mode. Then it must call mvSataConfigEdmaMode().
CONFIDENTIAL
Document Classification: Proprietary Information
channelIndex - channel number mode - EDMA mode to configure for the channel. Can be either MV_EDMA_MODE_QUEUED, MV_EDMA_MODE_NOT_QUEUED or MV_EDMA_MODE_NATIVE_QUEUING queueDepth - maximum number of outstanding EDMA commands in queue RETURN
MV_TRUE on success MV_FALSE on failure
8.5.4
The following functions enable access to TWSI devices attached to the 88SX60X1 TWSI bus.
MV_BOOLEAN mvSataTWSIMasterReadByte(MV_SATA_ADAPTER *pSataAdapter, MV_U8 twsiDevAddr, MV_U16 address, MV_U8_PTR data, MV_BOOLEAN addressRange) DESCRIPTION
Reads a byte from TWSI device.
INPUT pSataAdapter - pointer to Core Driver adapter data structure twsiDevAddr - Address of the slave device in the TWSI address space address - The required address within the TWSI device (can be either 8-bit or 16-bit) data - A pointer to an 8-bit data container that holds the data of the result addressRange - If MV_TRUE then the TWSI device must be accessed by 16-bit addressing.
If MV_FALSE then the device is accessed by 8-bit addressing (only the 8 LSB bits of the above address parameter are valid).
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Software Driver User Manual for Marvell Serial ATA Host Adapters
MV_BOOLEAN mvSataTWSIMasterWriteByte(MV_SATA_ADAPTER *pSataAdapter, MV_U8 twsiDevAddr, MV_U16 address, MV_U8 data, MV_BOOLEAN addressRange) DESCRIPTION
Writes a byte to a TWSI device.
INPUT pSataAdapter - pointer to Core Driver adapter data structure twsiDevAddr - Address of the slave device in the TWSI address space address - The required address within the TWSI device (can be either 8-bit or 16-bit) data - The data to be written addressRange - If MV_TRUE then the TWSI device must be accessed in 16-bit addressing.
If MV_FALSE then the device is accessed by 8-bit addressing (only the 8 LSB bits of the above address parameter above are valid).
RETURN
MV_TRUE on success MV_FALSE on failure
CONFIDENTIAL
Document Classification: Proprietary Information
Revision History
CONFIDENTIAL
Document Classification: Proprietary Information
Marvell Semiconductor, Inc. 700 First Avenue Sunnyvale, CA 94089, USA Tel: 1.408.222.2500 Fax: 1.408.752.9028 www.marvell.com