Data Structures For Drivers sata_pkt(9S) NAME sata_pkt - SATA packet structure SYNOPSIS #include INTERFACE LEVEL Consolidation Private DESCRIPTION The sata_pkt structure defines the packet specifying device and the operation to be performed on this device. SATA HBA framework fills in some information based on the original request from the scsi target driver packet, and passes it to SATA host bus adapter (HBA) driver's sata_tran_start() for execution on the target. The SATA HBA driver fills in some other information as the command is processed. When the command completes (or cannot progress any further) the completion function specified in the packet is called, with a pointer to the packet as its argument. From fields within the sata packet the SATA HBA Framework can determine the success or failure of the command and pass the appropriate status and informantion to the scsi target driver. STRUCTURE MEMBERS int sata_pkt_rev; /* structure version */ sata_device_t device; /* sata port/device address and state */ void *hba_driver_private; /* pointer to SATA HBA driver private data */ void *sata_framework_private; /* pointer to opaque SATA framework private data */ uint32_t op_mode; /* mode of operation */ sata_cmd_t sata_cmd; /* composite sata command */ int pkt_time; /* time allotted to command execution */ void (*spkt_completion)(struct sata_pkt *); /* packet completion callback */ int completion_reason; /* reason for the packet completion */ sata_pkt_rev Version of the sata_pkt structure. device sata_device structure identifying device address and returning device configuration stata and port status hba_driver_private An opaque pointer that SATA HBA driver uses to address some private data structures related to the packet operations. sata_framework_private An opaque pointer that SATA HBA Framework uses to address private data structures. op_mode Field containing flags specifying the mode of the packet operation: SATA_OPMODE_INTERRUPTS Use interrupts while performing packet operation - it's a hint rather then the requirement. SATA_OPMODE_POLLING Use polling instead of interrupts performing packet operation. Polling implies synchronous operation. SATA_OPMODE_ASYNCH If the packet is accepted by SATA HBA driver for execution, the function called with sata_pkt argument should return immediately indicating that packet was accepted. When the packet operation is completed, SATA HBA driver should call spkt_completion() callback function. The completion_reason field and other appropriate info in sata_pkt has to be updated before the callback. SATA_OPMODE_SYNCH Perform synchronous operation. The function called with the sata_pkt argument should not return until the packet operation is completed. The completion_reason field and other appropriate info in sata_pkt has to be updated before the function return. sata_cmd Structure defining specifc SATA command (ATA/ATAPI), data buffer address, and DMA cookies needed for the command execution. SATA HBA driver should use values set up in sata_cmd structure to program SATA device registers, in the HBA-specific manner. pkt_time Time value representing the maximum time in seconds that this command is allowed to take to complete. Timeout starts when the command SATA command is sent to a SATA device. pkt_time shall be set to 0 if no timeout is required. spkt_completion Specifies the packet completion callback routine. It is valid only when sata_pkt op_mode field does not have SATA_OPMODE_SUNCH flag set. When the SATA HBA driver rejected the packet, or it has gone as far as it could in performing packet operation, the driver should call the function pointed to by this field and pass a pointer to the packet as argument. The completion_reason field and other appropriate info in sata_pkt has to be updated before the callback. The callback function may be called from the interrupt contex. completion_reason This field specifies the reason for the packet operation completion: SATA_PKT_BUSY Packet operation was not completed - the packet was rejected by SATA HBA driver because the driver was busy performing some other operation(s). SATA_PKT_COMPLETED Packet operation was completed without an error. SATA_PKT_DEV_ERROR Packet operation was not completed because of a SATA device error. Other information in the sata_pkt provides specifics of the error and a state of the operation. SATA_PKT_QUEUE_FULL Packet operation was not completed - it was rejected because the SATA HBA driver detected queue full condition. The target driver is free to try to submit this packet again later. SATA_PKT_PORT_ERROR Packet operation was not completed because of a sata port error. Other information in the sata_pkt provides specifics of the error and a state of the operation. SATA_PKT_CMD_UNSUPPORTED Packet operation was not completed - the packet was rejected by the SATA HBA driver because packet's SATA command was not supported by the HBA. SATA_PKT_ABORTED Packet operation was aborted by a request from the SATA HBA Framework. SATA_PKT_TIMEOUT Packet operation was not completed because of a timeout detected by SATA HBA driver. After the time specified by pkt_time field was exceeded, the packet's command was terminated by the SATA HBA driver. SEE ALSO sata_hba_tran(9S), sata_address(9S), sata_device(9S), sata_cmd(9S)