sata_hba.h revision 6f9b9bf43c10fb1741a40302efe9db1a139745c8
* Address qualifier flags are used to specify what is addressed (device * or port) and where (controller or port multiplier data port). * SATA address Qualifier flags (in qual field of sata_address struct). * They are mutually exclusive. * SATA port status and control register block. * The sstatus, serror, scontrol, sactive and snotific * are the copies of the SATA port status and control registers. * (Port SStatus, SError, SControl, SActive and SNotification are * defined by Serial ATA r1.0a sepc and Serial ATA II spec. * SATA Device Structure (rev 1) * Used to request/return state of the controller, port, port multiplier * fields are used to specify SATA address (see sata_address structure * The satadev_scr structure is used to pass the content of a port * status and control registers. * The satadev_add_info field is used by SATA HBA driver to return an * additional information, which type depends on the function using * sata_device as argument. For example: * - in case of sata_tran_probe_port() this field should contain * a number of available Port Multiplier device ports; * - in case of sata_hba_event_notify() this field may contain * a value specific for a reported event. * satadev_state field of sata_device structure. * Common flags specifying current state of a port or an attached drive. * These states are mutually exclusive, except SATA_STATE_PROBED and * SATA_STATE_READY that may be set at the same time. * Attached drive specific states (satadev_state field of the sata_device * SATA_DSTATE_PWR_ACTIVE, SATA_DSTATE_PWR_IDLE and SATA_DSTATE_PWR_STANDBY * are mutually exclusive. All other states may be combined with each other * and with one of the power states. * These flags may be used only if the address qualifier (satadev_addr.qual) is * set to SATA_ADDR_DCPORT or SATA_ADDR_DPMPORT value. /* Mask for drive power states */ * SATA Port specific states (satadev_state field of sata_device structure). * SATA_PSTATE_PWRON and SATA_PSTATE_PWROFF are mutually exclusive. * All other states may be combined with each other and with one of the power * These flags may be used only if the address qualifier (satadev_addr.qual) is * set to SATA_ADDR_CPORT or SATA_ADDR_PMPORT value. /* Mask for the valid port-specific state flags */ /* Mask for a port power states */ * Device type (in satadev_type field of sata_device structure). * More device types may be added in the future. * SATA cmd structure (rev 1) * SATA HBA framework always sets all fields except status_reg and error_reg. * SATA HBA driver action depends on the addressing type specified by * If LBA48 addressing is indicated, SATA HBA driver has to load values from * satacmd_sec_count_msb_reg, satacmd_lba_low_msb_reg, * satacmd_lba_mid_msb_reg and satacmd_lba_hi_msb_reg * to appropriate registers prior to loading other registers. * For other addressing modes, SATA HBA driver should skip loading values * from satacmd_sec_count_msb_reg, satacmd_lba_low_msb_reg, * satacmd_lba_mid_msb_reg and satacmd_lba_hi_msb_reg * fields and load only remaining field values to corresponding registers. * satacmd_sec_count_msb and satamcd_sec_count_lsb values are loaded into * sec_count register, satacmd_sec_count_msb loaded first (if LBA48 * satacmd_lba_low_msb and satacmd_lba_low_lsb values are loaded into the * lba_low register, satacmd_lba_low_msb loaded first (if LBA48 addressing * is used). The lba_low register is the newer name for the old * sector_number register. * satacmd_lba_mid_msb and satacmd_lba_mid_lsb values are loaded into lba_mid * register, satacmd_lba_mid_msb loaded first (if LBA48 addressing is used). * The lba_mid register is the newer name for the old cylinder_low register. * satacmd_lba_high_msb and satacmd_lba_high_lsb values are loaded into * the lba_high regster, satacmd_lba_high_msb loaded first (if LBA48 * addressing is used). The lba_high register is a newer name for the old * cylinder_high register. * No addressing mode is selected when an ata command does not involve actual * SET FEATURE command), or the ATAPI PACKET command is sent. * If ATAPI PACKET command is sent and tagged commands are used, * SATA HBA driver has to provide and manage a tag value and * set it into the sector_count register. * Device Control register is not specified in sata_cmd structure - SATA HBA * driver shall set it accordingly to current mode of operation (interrupt * Buffer structure's b_flags should be used to determine the * address type of b_un.b_addr. However, there is no need to allocate DMA * resources for the buffer in SATA HBA driver. * DMA resources for a buffer structure are allocated by the SATA HBA * framework. Scatter/gather list is to be used only for DMA transfers * and it should be based on the DMA cookies list. * Upon completion of a command, SATA HBA driver has to update * satacmd_status_reg and satacmd_error_reg to reflect the contents of * the corresponding device status and error registers. * specify what register fields should be updated in sata_cmd structure. * If the command completed with error, SATA HBA driver has to update * satacmd_sec_count_msb, satacmd_sec_count_lsb, satacmd_lba_low_msb, * satacmd_lba_low_lsb, satacmd_lba_mid_msb, satacmd_lba_mid_lsb, * satacmd_lba_high_msb and satacmd_lba_high_lsb to values read from the * corresponding device registers. * If an operation could not complete because of the port error, the * If ATAPI PACKET command was sent and command completed with error, * rqsense structure has to be filed by SATA HBA driver. The satacmd_arq_cdb * points to pre-set request sense cdb that may be used for issuing request * sense data from the device. * The sata_max_queue_depth field specifies the maximum allowable queue depth * minus one, i.e. for maximum queue depth of 32, sata_max_queue_depth would * If FPDMA-type command was sent and command completed with error, the HBA * driver may use pre-set command READ LOG EXTENDED command pointed to * by satacmd_rle_sata_cmd field to retrieve error data from a device. * Only ATA register fields of the sata_cmd are set-up for that purpose. * If the READ MULTIPLIER command was specified in cmd_reg (command directed * to a port multiplier host port rather then to an attached device), * upon the command completion SATA HBA driver has to update_sector count * and lba fields of the sata_cmd structure to values returned via * command block registers (task file registers). uint32_t :
2;
/* reserved */ /* 14-15 */ /* kept for binary compat. */ * (for buffer DMA syncing) /* ptr to dma cookie list */ /* ATA address type (in satacmd_addr_type field */ * satacmd_flags : contain data transfer direction flags, * tagged queuing type flags, queued command flag, and reset state handling * Direction flags are mutually exclusive. * Tagged Queuing type flags * These flags indicate how the SATA command should be queued. * Simple-queue-tagged command. It may be executed out-of-order in respect * to other queued commands. * Ordered-queue-tagged command. It cannot be executed out-of-order in * respect to other commands, i.e. it should be executed in the order of * being transported to the HBA. * Translated head-of-queue-tagged scsi commands and commands that are * to be put at the head of the queue are treated as SATA_QUEUE_OTAG_CMD * This flag indicates that sata_cmd was set-up for DMA Queued command * (either READ_DMA_QUEUED, READ_DMA_QUEUED_EXT, WRITE_DMA_QUEUED or * WRITE_DMA_QUEUED_EXT command) or one of the Native Command Queuing commands * (either READ_FPDMA_QUEUED or WRITE_FPDMA_QUEUED). * This flag will be used only if sata_tran_hba_flags indicates controller * support for queuing and the device for which sata_cmd is prepared supports * either legacy queuing (indicated by Device Identify data word 83 bit 2) * or NCQ (indicated by word 76 of Device Identify data). * SATA HBA device enters reset state if the device was subjected to * the Device Reset (may also enter this state if the device was reset * as a side effect of port reset). SATA HBA driver sets this state. * Device stays in this condition until explicit request from SATA HBA * framework to clear the state. * SATA Packet structure (rev 1) * hba_driver_private is for a private use of the SATA HBA driver; * satapkt_framework_private is used only by SATA HBA framework; * satapkt_comp is a callback function to be called when packet * execution is completed (for any reason) if mode of operation is not * synchronous (SATA_OPMODE_SYNCH); * satapkt_reason specifies why the packet operation was completed * NOTE: after the packet completion callback SATA HBA driver should not * attempt to access any sata_pkt fields because sata_pkt is not valid anymore * (it could have been destroyed). * Since satapkt_hba_driver_private field cannot be retrieved, any hba private * data respources allocated per packet and accessed via this pointer should * either be freed before the completion callback is done, or the pointer has * to be saved by the HBA driver before the completion callback. /* HBA driver private data */ /* SATA framework priv data */ /* Rqsted mode of operation */ * Operation mode flags (in satapkt_op_mode field of sata_pkt structure). * Use to specify what should be a mode of operation for specified command. * Default (000b) means use Interrupt and Asynchronous mode to * Synchronous operation menas that the packet operation has to be completed * before the function called to initiate the operation returns. * SATA_PKT_QUEUE_FULL - cmd not sent because of queue full (detected * by the controller). If a device reject command for this reason, it * should be reported as SATA_PKT_DEV_ERROR * SATA_PKT_CMD_NOT_SUPPORTED - command not supported by a controller * Controller is unable to send such command to a device. * If device rejects a command, it should be reported as * SATA_PKT_DEV_ERROR - cmd failed because of device reported an error. * The content of status_reg (ERROR bit has to be set) and error_reg * fields of the sata_cmd structure have to be set and will be used * by SATA HBA Framework to determine the error cause. * SATA_PKT_PORT_ERROR - cmd failed because of a link or a port error. * Link failed / no communication with a device / communication error * or other port related error was detected by a controller. * SATA_PKT_ABORTED - cmd execution was aborted by the request from the * framework. Abort mechanism is HBA driver specific. * SATA_PKT_TIMEOUT - cmd execution has timed-out. Timeout specified by * pkt_time was exceeded. The command was terminated by the SATA HBA * SATA_PKT_COMPLETED - this is a value returned when an operation * completes without errors. * SATA_PKT_BUSY - packet was not accepted for execution because the * driver was busy performing some other operation(s). * SATA_PKT_RESET - packet execution was aborted because of device * reset originated by either the HBA driver or the SATA framework. * Error retrieval sata packet types * Hoplug functions vector structure (rev 1) * Power management functions vector structure (rev 1) * The embedded function returns information about the controller's * Additional functions may be added in the future without changes to * SATA port PHY Power Level * These states correspond to the interface power management state as defined * SATA HBA Tran structure (rev 1) * Registered with SATA Framework * dma_attr is a pointer to data (buffer) dma attibutes of the controller * The qdepth field specifies number of commands that may be accepted by * the controller. Value range 1-32. A value greater than 1 indicates that * the controller supports queuing. Support for Native Command Queuing * indicated by SATA_CTLF_NCQ flag also requires qdepth set to a value * Controller's features support flags (sata_tran_hba_features_support). * Note: SATA_CTLF_NCQ indicates that SATA controller supports NCQ in addition * to legacy queuing commands, indicated by SATA_CTLF_QCMD flag. * sata_tran_start() return values. * When pkt is not accepted, the satapkt_reason has to be updated * before function returns - it should reflect the same reason for not being * executed as the return status of above functions. * If pkt was accepted and executed synchronously, * satapk_reason should indicate a completion status. * sata_tran_abort() abort type flag * Events handled by SATA HBA Framework * More then one event may be reported at the same time * SATA_EVNT__DEVICE_ATTACHED * HBA detected the presence of a device ( electrical connection with * a device was detected ). * SATA_EVNT_DEVICE_DETACHED * HBA detected the detachment of a device (electrical connection with * HBA lost link with an attached device * SATA_EVNT_LINK_ESTABLISHED * HBA established a link with an attached device * HBA has determined that the port failed and is unuseable * SATA_EVENT_DEVICE_RESET * SATA device was reset, causing loss of the device setting * SATA_EVNT_PWR_LEVEL_CHANGED * A port or entire SATA controller power level has changed * SATA Framework interface entry points