EFI ATA PASS THRU PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Provides services that allow ATA commands to be sent to ATA Devices attached to an ATA controller.

Contents

GUID

#define EFI_ATA_PASS_THRU_PROTOCOL_GUID \
  {0x1d3de7f0,0x807,0x424f,{0xaa,0x69,0x11,0xa5,0x4e,0x19,0xa4,0x6f}}

Protocol Interface Structure

typedef struct _EFI_ATA_PASS_THRU_PROTOCOL {
  EFI_ATA_PASS_THRU_MODE              *Mode;
  EFI_ATA_PASS_THRU_PASSTHRU          PassThru;
  EFI_ATA_PASS_THRU_GET_NEXT_PORT     GetNextPort;
  EFI_ATA_PASS_THRU_GET_NEXT_DEVICE   GetNextDevice;
  EFI_ATA_PASS_THRU_BUILD_DEVICE_PATH BuildDevicePath;
  EFI_ATA_PASS_THRU_GET_DEVICE        GetDevice;
  EFI_ATA_PASS_THRU_RESET_PORT        ResetPort;
  EFI_ATA_PASS_THRU_RESET_DEVICE      ResetDevice;
} EFI_ATA_PASS_THRU_PROTOCOL;

Members

Members Description
Mode A pointer to the EFI_ATA_PASS_THRU_MODE data for this ATA controller.
PassThru Sends an ATA command to an ATA device that is connected to the ATA controller.
GetNextPort Retrieves the list of legal ports on an ATA controller.
GetNextDevice Retrieves the list of legal devices on a specific port of an ATA controller.
BuildDevicePath Allocates and builds a device path node for an ATA Device on an ATA controller.
GetDevice Translates a device path node to a port and port multiplier port.
ResetPort Resets an ATA port or channel (PATA). This operation resets all the ATA devices connected to the ATA port or channel.
ResetDevice Resets an ATA device that is connected to the ATA controller.

Description

The EFI_ATA_PASS_THRU_PROTOCOL provides information about an ATA controller and the ability to send ATA Command Blocks to any ATA device attached to that ATA controller. The information includes the attributes of the ATA controller.

The printable name for the controller can be provided through the EFI_COMPONENT_NAME2_PROTOCOL for multiple languages.

The Attributes field of the Mode member of the EFI_ATA_PASS_THRU_PROTOCOL interface tells if the interface is for physical ATA devices or logical ATA devices. Drivers for non-RAID ATA controllers will set both the EFI_ATA_PASS_THRU_ATTRIBUTES_PHYSICAL, and the EFI_ATA_PASS_THRU_ATTRIBUTES_LOGICAL bits.

Drivers for RAID controllers that allow access to the physical devices and logical devices will produce two EFI_ATA_PASS_THRU_PROTOCOL interfaces: one with the just the EFI_ATA_PASS_THRU_ATTRIBUTES_PHYSICAL bit set and another with just the EFI_ATA_PASS_THRU_ATTRIBUTES_LOGICAL bit set. One interface can be used to access the physical devices attached to the RAID controller, and the other can be used to access the logical devices attached to the RAID controller for its current configuration.

Drivers for RAID controllers that do not allow access to the physical devices will produce one EFI_ATA_PASS_THRU_PROTOCOL interface with just the EFI_ATA_PASS_THRU_LOGICAL bit set. The interface for logical devices can also be used by a file system driver to mount the RAID volumes. An EFI_ATA_PASS_THRU_PROTOCOL with neither EFI_ATA_PASS_THRU_ATTRIBUTES_LOGICAL nor EFI_ATA_PASS_THRU_ATTRIBUTES_PHYSICAL set is an illegal configuration.

The Attributes field also contains the EFI_ATA_PASS_THRU_ATTRIBUTES_NONBLOCKIO bit. All EFI_ATA_PASS_THRU_PROTOCOL interfaces must support blocking I/O. If this bit is set, then the interface supports both blocking I/O and non-blocking I/O.

Each EFI_ATA_PASS_THRU_PROTOCOL instance must have an associated device path. Typically this will have an ACPI device path node and a PCI device path node, although variation will exist.

Additional information about the ATA controller can be obtained from protocols attached to the same handle as the EFI_ATA_PASS_THRU_PROTOCOL, or one of its parent handles. This would include the device I/O abstraction used to access the internal registers and functions of the ATA controller.

This protocol may also be used for PATA devices (or devices in a PATA-compatible mode). PATA devices are mapped to ports and port multiplier ports using the following table:

PATA Device Connection Emulated Port Number Emulated Port Multiplier Port Number
Primary Master 0 0
Primary Slave 0 1
Secondary Master 1 0
Secondary Slave 1 1

PassThru()

Sends an ATA command to an ATA device that is attached to the ATA controller. This function supports both blocking I/O and non-blocking I/O. The blocking I/O functionality is required, and the non-blocking I/O functionality is optional.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_ATA_PASS_THRU_PASSTHRU) (
  IN     EFI_ATA_PASS_THRU_PROTOCOL        *This,
  IN     UINT16                            Port,
  IN     UINT16                            PortMultiplierPort,
  IN OUT EFI_ATA_PASS_THRU_COMMAND_PACKET  *Packet,
  IN     EFI_EVENT                         Event OPTIONAL
  );

Parameters

Parameters Description
This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance.
Port The port number of the ATA device to send the command.
PortMultiplierPort The port multiplier port number of the ATA device to send the command. If there is no port multiplier, then specify 0.
Packet A pointer to the ATA command to send to the ATA device specified by Port and PortMultiplierPort.
Event If non-blocking I/O is not supported then Event is ignored, and blocking I/O is performed. If Event is NULL, then blocking I/O is performed. If Event is not NULL and non blocking I/O is supported, then non-blocking I/O is performed, and Event will be signaled when the ATA command completes.

Description
The PassThru() function sends the ATA command specified by Packet to the ATA device specified by Port and PortMultiplierPort. If the driver supports non-blocking I/O and Event is not NULL, then the driver will return immediately after the command is sent to the selected device, and will later signal Event when the command has completed.

If the driver supports non-blocking I/O and Event is NULL, then the driver will send the command to the selected device and block until it is complete. If the driver does not support non-blocking I/O, then the Event parameter is ignored, and the driver will send the command to the selected device and block until it is complete.

If Packet is successfully sent to the ATA device, then EFI_SUCCESS is returned. If Packet cannot be sent because there are too many packets already queued up, then EFI_NOT_READY is returned. The caller may retry Packet at a later time. If a device error occurs while sending the Packet, then EFI_DEVICE_ERROR is returned. If a timeout occurs during the execution of Packet, then EFI_TIMEOUT is returned.

If Port or PortMultiplierPort are not in a valid range for the ATA controller, then EFI_INVALID_PARAMETER is returned. If InDataBuffer, OutDataBuffer or Asb do not meet the alignment requirement specified by the IoAlign field of the EFI_ATA_PASS_THRU_MODE structure, then EFI_INVALID_PARAMETER is returned. If any of the other fields of Packet are invalid, then EFI_INVALID_PARAMETER is returned.

If the data buffer described by InDataBuffer and InTransferLength is too big to be transferred in a single command, then no data is transferred and EFI_BAD_BUFFER_SIZE is returned. The number of bytes that can be transferred in a single command are returned in InTransferLength. If the data buffer described by OutDataBuffer and OutTransferLength is too big to be transferred in a single command, then no data is transferred and EFI_BAD_BUFFER_SIZE is returned. The number of bytes that can be transferred in a single command are returned in OutTransferLength.

If the command described in Packet is not supported by the host adapter, then EFI_UNSUPPORTED is returned.

If EFI_SUCCESS, EFI_BAD_BUFFER_SIZE, EFI_DEVICE_ERROR, or EFI_TIMEOUT is returned, then the caller must examine Asb.

If non-blocking I/O is being used, then the status fields in Packet will not be valid until the Event associated with Packet is signaled.

If EFI_NOT_READY, EFI_INVALID_PARAMETER or EFI_UNSUPPORTED is returned, then Packet was never sent, so the status fields in Packet are not valid. If non-blocking I/O is being used, the Event associated with Packet will not be signaled.

This function will determine if data transfer is necessary based on the Acb->Protocol and Acb->Length fields. The Acb->AtaCommand field is ignored except to copy it into the ATA Command register. The following table describes special programming considerations based on the protocol specified by Acb->Protocol.

Protocol Value Description
EFI_ATA_PASS_THRU_PROTOCOL_ATA_HARDWARE_RESET For PATA devices, then RST- is asserted. For SATA devices, then COMRESET will be issued.
EFI_ATA_PASS_THRU_PROTOCOL_ATA_SOFTWARE_RESET A software reset will be issued to the ATA device.
EFI_ATA_PASS_THRU_PROTOCOL_PIO_DATA_IN - EFI_ATA_PASS_THRU_PROTOCOL_FPDMA The command is sent to the ATA device. If the value is inappropriate for the command specified by Acb->AtaCommand, the results are undefined.
EFI_ATA_PASS_THRU_RETURN_RESPONSE This command will only return the contents of the ATA status block.

The ATA host and the ATA device should already be configured for the PIO, DMA, and UDMA transfer rates that are supported by the ATA controller and the ATA device. The results of changing the device’s timings using this function are undefined.

If Acb->Length is not set to EFI_ATA_PASS_THRU_LENGTH_NO_DATA_TRANSFER, then EFI_ATA_PASS_THRU_LENGTH_BYTES specifies whether Acb->InTransferLength and Acb->OutTransferLength are interpreted as bytes (1) or blocks (0).

If Acb->Length is set to EFI_ATA_PASS_THRU_LENGTH_FEATURES is set, then the transfer length will be programmed into the AtaFeatures register. If Acb->Length is set to EFI_ATA_PASS_THRU_LENGTH_SECTOR_COUNT, then the transfer length will be programmed into the AtaSectorCount register. If Acb->Length is set to EFI_ATA_PASS_THRU_LENGTH_TPSIU, then the transfer length will be programmed into the TPSIU.

For PIO data transfers, the number of sectors to transfer is 2^EFI_ATA_PASS_THRU_LENGTH_COUNT (where EFI_ATA_PASS_THRU_LENGTH_COUNT is the field from Acb->Length).

For all commands, the contents of the ATA status block will be returned in Asb.

Status Codes Returned

Status Code Description
EFI_SUCCESS The ATA command was sent by the host. For bi-directional commands, InTransferLength bytes were transferred from InDataBuffer. For write and bi-directional commands, OutTransferLength bytes were transferred by OutDataBuffer. See Asb for additional status information.
EFI_BAD_BUFFER_SIZE The ATA command was not executed. The number of bytes that could be transferred is returned in InTransferLength. For write and bidirectional commands, OutTransferLength bytes were transferred by OutDataBuffer. See Asb for additional status information.
EFI_NOT_READY The ATA command could not be sent because there are too many ATA commands already queued. The caller may retry again later.
EFI_DEVICE_ERROR A device error occurred while attempting to send the ATA command. See Asb for additional status information.
EFI_INVALID_PARAMETER Port, PortMultiplierPort, or the contents of Acb are invalid. The ATA command was not sent, so no additional status information is available.
EFI_UNSUPPORTED The command described by the ATA command is not supported by the host adapter. The ATA command was not sent, so no additional status information is available.
EFI_TIMEOUT A timeout occurred while waiting for the ATA command to execute. See Asb for additional status information.

GetNextPort()

Used to retrieve the list of legal port numbers for ATA devices on an ATA controller. These can either be the list of ports where ATA devices are actually present or the list of legal port numbers for the ATA controller. Regardless, the caller of this function must probe the port number returned to see if an ATA device is actually present at that location on the ATA controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_ATA_PASS_THRU_GET_NEXT_PORT) (
  IN     EFI_ATA_PASS_THRU_PROTOCOL *This,
  IN OUT UINT16                         *Port
  );

Parameters

Parameters Description
This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance.
Port On input, a pointer to the port number on the ATA controller. On output, a pointer to the next port number on the ATA controller. An input value of 0xFFFF retrieves the first port number on the ATA controller.

Description
The GetNextPort() function retrieves the port number on an ATA controller. If on input Port is 0xFFFF, then the port number of the first port on the ATA controller is returned in Port and EFI_SUCCESS is returned.

If Port is a port number that was returned on a previous call to GetNextPort(), then the port number of the next port on the ATA controller is returned in Port, and EFI_SUCCESS is returned.

If Port is not 0xFFFF and Port was not returned on a previous call to GetNextPort(), then EFI_INVALID_PARAMETER is returned.

If Port is the port number of the last port on the ATA controller, then EFI_NOT_FOUND is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The next port number on the ATA controller was returned in Port.
EFI_NOT_FOUND There are no more ports on this ATA controller.
EFI_INVALID_PARAMETER Port is not 0xFFFF and Port was not returned on a previous call to GetNextPort().

GetNextDevice()

Used to retrieve the list of legal port multiplier port numbers for ATA devices on a port of an ATA controller. These can either be the list of port multiplier ports where ATA devices are actually present on port or the list of legal port multiplier ports on that port. Regardless, the caller of this function must probe the port number and port multiplier port number returned to see if an ATA device is actually present.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_ATA_PASS_THRU_GET_NEXT_DEVICE) (
  IN     EFI_ATA_PASS_THRU_PROTOCOL *This,
  IN     UINT16                         Port,
  IN OUT UINT16                         *PortMultiplierPort
  );

Parameters

Parameters Description
This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance.
Port The port number present on the ATA controller.
PortMultiplierPort On input, a pointer to the port multiplier port number of an ATA device present on the ATA controller. If on input a PortMultiplierPort of 0xFFFF is specified, then the port multiplier port number of the first ATA device is returned. On output, a pointer to the port multiplier port number of the next ATA device present on an ATA controller.

Description
The GetNextDevice() function retrieves the port multiplier port number of an ATA device present on a port of an ATA controller.

If PortMultiplierPort points to a port multiplier port number value that was returned on a previous call to GetNextDevice(), then the port multiplier port number of the next ATA device on the port of the ATA controller is returned in PortMultiplierPort, and EFI_SUCCESS is returned.

If PortMultiplierPort points to 0xFFFF, then the port multiplier port number of the first ATA device on port of the ATA controller is returned in PortMultiplierPort and EFI_SUCCESS is returned.

If PortMultiplierPort is not 0xFFFF and the value pointed to by PortMultiplierPort was not returned on a previous call to GetNextDevice(), then EFI_INVALID_PARAMETER is returned.

If PortMultiplierPort is the port multiplier port number of the last ATA device on the port of the ATA controller, then EFI_NOT_FOUND is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The port multiplier port number of the next ATA device on the port of the ATA controller was returned in PortMultiplierPort.
EFI_NOT_FOUND There are no more ATA devices on this port of the ATA controller.
EFI_INVALID_PARAMETER PortMultiplierPort is not 0xFFFF, and PortMultiplierPort was not returned on a previous call to GetNextDevice().

BuildDevicePath()

Used to allocate and build a device path node for an ATA device on an ATA controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_ATA_PASS_THRU_BUILD_DEVICE_PATH) (
  IN     EFI_ATA_PASS_THRU_PROTOCOL *This,
  IN     UINT16                     Port,
  IN     UINT16                     PortMultiplierPort,
  IN OUT EFI_DEVICE_PATH_PROTOCOL   **DevicePath
  );

Parameters

Parameters Description
This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance.
Port Port specifies the port number of the ATA device for which a device path node is to be allocated and built.
PortMultiplierPort The port multiplier port number of the ATA device for which a device path node is to be allocated and built. If there is no port multiplier, then specify 0.
DevicePath A pointer to a single device path node that describes the ATA device specified by Port and PortMultiplierPort. This function is responsible for allocating the buffer DevicePath with the boot service AllocatePool(). It is the caller’s responsibility to free DevicePath when the caller is finished with DevicePath.

Description
The BuildDevicePath() function allocates and builds a single device node for the ATA device specified by Port and PortMultiplierPort. If the ATA device specified by Port and PortMultiplierPort is not present on the ATA controller, then EFI_NOT_FOUND is returned. If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned. If there are not enough resources to allocate the device path node, then EFI_OUT_OF_RESOURCES is returned.

Otherwise, DevicePath is allocated with the boot service AllocatePool(), the contents of DevicePath are initialized to describe the ATA device specified by Port and PortMultiplierPort, and EFI_SUCCESS is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The device path node that describes the ATA device specified by Port and PortMultiplierPort was allocated and returned in

DevicePath.

EFI_NOT_FOUND The ATA device specified by Port and PortMultiplierPort does not exist on the ATA controller.
EFI_INVALID_PARAMETER DevicePath is NULL.
EFI_OUT_OF_RESOURCES There are not enough resources to allocate DevicePath.

GetDevice()

Used to translate a device path node to a port number and port multiplier port number.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_ATA_PASS_THRU_GET_DEVICE) (
  IN  EFI_ATA_PASS_THRU_PROTOCOL *This,
  IN  EFI_DEVICE_PATH_PROTOCOL   *DevicePath,
  OUT UINT16                     *Port,
  OUT UINT16                     *PortMultiplierPort
  );

Parameters

Parameters Description
This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance.
DevicePath A pointer to the device path node that describes an ATA device on the ATA controller.
Port On return, points to the port number of an ATA device on the ATA controller.
PortMultiplierPort On return, points to the port multiplier port number of an ATA device on the ATA controller.

Description
The GetDevice() function determines the port and port multiplier port number associated with the ATA device described by DevicePath. If DevicePath is a device path node type that the ATA Pass Thru driver supports, then the ATA Pass Thru driver will attempt to translate the contents DevicePath into a port number and port multiplier port number.

If this translation is successful, then that port number and port multiplier port number are returned in Port and PortMultiplierPort, and EFI_SUCCESS is returned.

If DevicePath, Port, or PortMultiplierPort are NULL, then EFI_INVALID_PARAMETER is returned.

If DevicePath is not a device path node type that the ATA Pass Thru driver supports, then EFI_UNSUPPORTED is returned.

If DevicePath is a device path node type that the ATA Pass Thru driver supports, but there is not a valid translation from DevicePath to a port number and port multiplier port number, then EFI_NOT_FOUND is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS DevicePath was successfully translated to a port number and port multiplier port number, and they were returned in Port and

PortMultiplierPort.

EFI_INVALID_PARAMETER DevicePath is NULL.
EFI_INVALID_PARAMETER Port is NULL
EFI_INVALID_PARAMETER PortMultiplierPort is NULL
EFI_UNSUPPORTED This driver does not support the device path node type in DevicePath.
EFI_NOT_FOUND A valid translation from DevicePath to a port number and port multiplier port number does not exist.

ResetPort()

Resets a specific port on the ATA controller. This operation also resets all the ATA devices connected to the port.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_ATA_PASS_THRU_RESET_PORT) (
  IN EFI_ATA_PASS_THRU_PROTOCOL *This,
  IN UINT16                     Port
  );

Parameters

Parameters Description
This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance.
Port The port number on the ATA controller.

Description
The ResetChannel() function resets an a specific port on an ATA controller. This operation resets all the ATA devices connected to that port. If this ATA controller does not support a reset port operation, then EFI_UNSUPPORTED is returned.

If a device error occurs while executing that port reset operation, then EFI_DEVICE_ERROR is returned.

If a timeout occurs during the execution of the port reset operation, then EFI_TIMEOUT is returned. If the port reset operation is completed, then EFI_SUCCESS is returned.

Status Codes Returned

Parameters Status Code
EFI_SUCCESS The ATA controller port was reset.
EFI_UNSUPPORTED The ATA controller does not support a port reset operation.
EFI_DEVICE_ERROR A device error occurred while attempting to reset the ATA port.
EFI_TIMEOUT A timeout occurred while attempting to reset the ATA port.

ResetDevice()

Resets an ATA device that is connected to an ATA controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_ATA_PASS_THRU_RESET_DEVICE) (
  IN EFI_ATA_PASS_THRU_PROTOCOL *This,
  IN UINT16                     Port,
  IN UINT16                     PortMultiplierPort
  );

Parameters

Parameters Description
This A pointer to the EFI_ATA_PASS_THRU_PROTOCOL instance.
Port Port represents the port number of the ATA device to be reset.
PortMultiplierPort The port multiplier port number of the ATA device to reset. If there is no port multiplier, then specify 0.

Description
The ResetDevice() function resets the ATA device specified by Port and PortMultiplierPort. If this ATA controller does not support a device reset operation, then EFI_UNSUPPORTED is returned.

If Port or PortMultiplierPort are not in a valid range for this ATA controller, then EFI_INVALID_PARAMETER is returned.

If a device error occurs while executing that device reset operation, then EFI_DEVICE_ERROR is returned.

If a timeout occurs during the execution of the device reset operation, then EFI_TIMEOUT is returned.

If the device reset operation is completed, then EFI_SUCCESS is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The ATA device specified by Port and PortMultiplierPort was reset
EFI_UNSUPPORTED The ATA controller does not support a device reset operation.
EFI_INVALID_PARAMETER Port or PortMultiplierPort are invalid.
EFI_DEVICE_ERROR A device error occurred while attempting to reset the ATA device specified by Port and PortMultiplierPort.
EFI_TIMEOUT A timeout occurred while attempting to reset the ATA device specified by Port and PortMultiplierPort.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools