[ Previous |
Next |
Contents |
Home |
Search ]
AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts
ataide_buf Structure
The ataide_buf structure is used for communication between the IDE device driver and the IDE adapter device driver during an initiator I/O request. This structure is passed to and from the strategy routine in the same way a standard driver uses a struct buf structure.
Fields in the ataide_buf Structure
The ataide_buf structure contains certain fields used to pass an IDE command and associated parameters to the IDE adapter device driver. Other fields within this structure are used to pass returned status back to the IDE device driver. The ataide_buf structure is defined in the /usr/include/sys/ide.h file.
Fields in the ataide_buf structure are used as follows:
- Reserved
fields should be set to a value of 0, except where noted.
- The bufstruct
field contains a copy of the standard buf buffer structure that documents the I/O request. Included in this structure, for example, are the buffer address, byte count, and transfer direction. The b_work
field in the buf structure is reserved for use by the IDE adapter device driver. The current definition of the buf structure is in the /usr/include/sys/buf.h include file.
- The bp
field points to the original buffer structure received by the IDE device driver from the caller, if any. This can be a chain of entries in the case of spanned transfers (IDE commands that transfer data from or to more than one system-memory buffer). A null pointer indicates a nonspanned transfer. The null value specifically tells the IDE adapter device driver all the information needed to perform the DMA data transfer is contained in the bufstruct
fields of the ataide_buf structure. If the bp
field is set to a non-null value, the ataide_buf.sg_ptr
field must have a value of null, or else the operation is not allowed.
- The ata
field, defined as an ata_cmd structure, contains the IDE command (ATA or ATAPI), status, error indicator, and a flag variable:
- The flags field contains the following bit flags:
ATA_CHS_MODE |
Execute the command in cylinder head sector mode. |
ATA_LBA_MODE |
Execute the command in logical block addressing mode. |
ATA_BUS_RESET |
Reset the ATA bus, ignore the current command. |
- The command
field is the IDE ATA command opcode. For ATAPI packet commands, this field must be set to ATA_ATAPI_PACKET_COMMAND (0xA1).
- The device
field is the IDE indicator for either the master (0) or slave (1) IDE device.
- The sector_cnt_cmd
field is the number of sectors affected by the command. A value of zero usually indicates 256 sectors.
- The startblk
field is the starting LBA or CHS sector.
- The feature
field is the ATA feature register.
- The status
field is an output parameter indicating the ending status for the command. This field is updated by the IDE adapter device driver upon completion of a command.
- The errval
field is the error type indicator when the ATA_ERROR bit is set in the status field. This field has slightly different interpretations for ATA and ATAPI commands.
- The sector_cnt_ret
field is the number of sectors not processed by the device.
- The endblk
field is the completion LBA or CHS sector.
- The atapi
field is defined as an atapi_command structure, which contains the IDE ATAPI command. The 12 or 16 bytes of a single IDE command are stored in consecutive bytes, with the opcode identified individually. The atapi_command structure contains the following fields:
- The length
field is the number of bytes in the actual IDE command. This is normally 12 or 16 (decimal).
- The packet.op_code
field specifies the standard IDE ATAPI opcode for this command.
- The packet.bytes
field contains the remaining command-unique bytes of the IDE ATAPI command block. The actual number of bytes depends on the value in the length
field.
- The sg_ptr
field is set to a non-null value to indicate a request for a gathered write. A gathered write means the IDE command conducts a system-to-device data transfer where multiple, noncontiguous system buffers contain the write data. This data is transferred in order as a single data transfer for the IDE command in this ataide_buf structure.
The contents of the sg_ptr
field, if non-null, must be a pointer to the uio structure that is passed to the IDE device driver. The IDE adapter device driver treats the sg_ptr
field as a pointer to a uio structure that accesses the iovec structures containing pointers to the data. There are no address-alignment restrictions on the data in the iovec structures. The only restriction is that the total transfer length of all the data must not exceed the maximum transfer length for the adapter device driver.
The ataide_buf.bufstruct.b_un.b_addr
field normally contains the starting system-buffer address and is ignored and can be altered by the IDE adapter device driver when the ataide_buf is returned. The ataide_buf.bufstruct.b_bcount
field should be set by the caller to the total transfer length for the data.
- The timeout_value
field specifies the time-out limit (in seconds) to be used for completion of this command. A time-out value of 0 means no time-out is applied to this I/O request.
- The status_validity
field contains an output parameter that can have the following bit flags as a value:
ATA_IDE_STATUS |
The ata.status
field is valid. |
ATA_ERROR_VALID |
The ata.errval
field contains a valid error indicator. |
ATA_CMD_TIMEOUT |
The IDE adapter driver caused the command to time out. |
ATA_NO_DEVICE_RESPONSE |
The IDE device is not ready. |
ATA_IDE_DMA_ERROR |
The IDE adapter driver encountered a DMA error. |
ATA_IDE_DMA_NORES |
The IDE adapter driver was not able to transfer entire request. The bufstruct.b_resid
contains the count not transferred. |
If an error is detected during execution of an IDE command, and the error prevented the IDE command from actually being sent to the IDE bus by the adapter, then the error should be processed or recovered, or both, by the IDE adapter device driver.
If it is recovered successfully by the IDE adapter device driver, the error is logged, as appropriate, but is not reflected in the ata.errval
byte. If the error cannot be recovered by the IDE adapter device driver, the appropriate ata.errval
bit is set and the ataide_buf structure is returned to the IDE device driver for further processing.
If an error is detected after the command was actually sent to the IDE device, then it should be processed or recovered, or both, by the IDE device driver.
For error logging, the IDE adapter device driver logs IDE bus- and adapter-related conditions, while the IDE device driver logs IDE device-related errors. In the following description, a capital letter "A" after the error name indicates that the IDE adapter device driver handles error logging. A capital letter "H" indicates that the IDE device driver handles error logging.
Some of the following error conditions indicate an IDE device failure. Others are IDE bus- or adapter-related.
ATA_IDE_DMA_ERROR (A) |
The system I/O bus generated or detected an error during a DMA transfer. |
ATA_ERROR_VALID (H) |
The request sent to the device failed. |
ATA_CMD_TIMEOUT (H) |
The command timed out before completion. |
ATA_NO_DEVICE_RESPONSE (A) |
The target device did not respond. |
ATA_IDE_BUS_RESET (A) |
The adapter indicated the IDE bus reset failed. |
[ Previous |
Next |
Contents |
Home |
Search ]