diff options
Diffstat (limited to 'IntelFrameworkModulePkg/Bus/Pci/IdeBusDxe/Ide.h')
| -rw-r--r-- | IntelFrameworkModulePkg/Bus/Pci/IdeBusDxe/Ide.h | 1200 |
1 files changed, 385 insertions, 815 deletions
diff --git a/IntelFrameworkModulePkg/Bus/Pci/IdeBusDxe/Ide.h b/IntelFrameworkModulePkg/Bus/Pci/IdeBusDxe/Ide.h index 89bc191ab9..b919457bb5 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/IdeBusDxe/Ide.h +++ b/IntelFrameworkModulePkg/Bus/Pci/IdeBusDxe/Ide.h @@ -1,6 +1,6 @@ /** @file
Header file for IDE Bus Driver, containing the helper functions'
- entire prototype.
+ prototype.
Copyright (c) 2006 - 2007 Intel Corporation. <BR>
All rights reserved. This program and the accompanying materials
@@ -25,49 +25,12 @@ // Helper functions Prototype
//
/**
- TODO: Add function description
+ read a one-byte data from a IDE port
- @param This TODO: add argument description
- @param Controller TODO: add argument description
- @param Handle TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-DeRegisterIdeDevice (
- IN EFI_DRIVER_BINDING_PROTOCOL *This,
- IN EFI_HANDLE Controller,
- IN EFI_HANDLE Handle
- );
-
-/**
- TODO: Add function description
-
- @param Controller TODO: add argument description
- @param PciIo TODO: add argument description
- @param ParentDevicePath TODO: add argument description
- @param RemainingDevicePath TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-EnableIdeDevice (
- IN EFI_HANDLE Controller,
- IN EFI_PCI_IO_PROTOCOL *PciIo,
- IN EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath,
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
- );
-
-/**
- TODO: Add function description
-
- @param PciIo TODO: add argument description
- @param Port TODO: add argument description
-
- TODO: add return values.
+ @param PciIo The PCI IO protocol instance
+ @param Port the IDE Port number
+ return the one-byte data read from IDE port
**/
UINT8
IDEReadPortB (
@@ -76,14 +39,14 @@ IDEReadPortB ( );
/**
- TODO: Add function description
-
- @param PciIo TODO: add argument description
- @param Port TODO: add argument description
- @param Count TODO: add argument description
- @param Buffer TODO: add argument description
+ Reads multiple words of data from the IDE data port.
+ Call the IO abstraction once to do the complete read,
+ not one word at a time
- TODO: add return values.
+ @param PciIo Pointer to the EFI_PCI_IO instance
+ @param Port IO port to read
+ @param Count No. of UINT16's to read
+ @param Buffer Pointer to the data buffer for read
**/
VOID
@@ -95,14 +58,11 @@ IDEReadPortWMultiple ( );
/**
- TODO: Add function description
-
- @param PciIo TODO: add argument description
- @param Port TODO: add argument description
- @param Data TODO: add argument description
-
- TODO: add return values.
+ write a 1-byte data to a specific IDE port
+ @param PciIo PCI IO protocol instance
+ @param Port The IDE port to be writen
+ @param Data The data to write to the port
**/
VOID
IDEWritePortB (
@@ -112,14 +72,11 @@ IDEWritePortB ( );
/**
- TODO: Add function description
-
- @param PciIo TODO: add argument description
- @param Port TODO: add argument description
- @param Data TODO: add argument description
-
- TODO: add return values.
+ write a 1-word data to a specific IDE port
+ @param PciIo PCI IO protocol instance
+ @param Port The IDE port to be writen
+ @param Data The data to write to the port
**/
VOID
IDEWritePortW (
@@ -129,14 +86,14 @@ IDEWritePortW ( );
/**
- TODO: Add function description
-
- @param PciIo TODO: add argument description
- @param Port TODO: add argument description
- @param Count TODO: add argument description
- @param Buffer TODO: add argument description
+ Write multiple words of data to the IDE data port.
+ Call the IO abstraction once to do the complete read,
+ not one word at a time
- TODO: add return values.
+ @param PciIo Pointer to the EFI_PCI_IO instance
+ @param Port IO port to read
+ @param Count No. of UINT16's to read
+ @param Buffer Pointer to the data buffer for read
**/
VOID
@@ -148,12 +105,54 @@ IDEWritePortWMultiple ( );
/**
- TODO: Add function description
+ Get IDE IO port registers' base addresses by mode. In 'Compatibility' mode,
+ use fixed addresses. In Native-PCI mode, get base addresses from BARs in
+ the PCI IDE controller's Configuration Space.
- @param PciIo TODO: add argument description
- @param IdeRegsBaseAddr TODO: add argument description
+ The steps to get IDE IO port registers' base addresses for each channel
+ as follows:
- TODO: add return values.
+ 1. Examine the Programming Interface byte of the Class Code fields in PCI IDE
+ controller's Configuration Space to determine the operating mode.
+
+ 2. a) In 'Compatibility' mode, use fixed addresses shown in the Table 1 below.
+ <pre>
+ ___________________________________________
+ | | Command Block | Control Block |
+ | Channel | Registers | Registers |
+ |___________|_______________|_______________|
+ | Primary | 1F0h - 1F7h | 3F6h - 3F7h |
+ |___________|_______________|_______________|
+ | Secondary | 170h - 177h | 376h - 377h |
+ |___________|_______________|_______________|
+
+ Table 1. Compatibility resource mappings
+ </pre>
+
+ b) In Native-PCI mode, IDE registers are mapped into IO space using the BARs
+ in IDE controller's PCI Configuration Space, shown in the Table 2 below.
+ <pre>
+ ___________________________________________________
+ | | Command Block | Control Block |
+ | Channel | Registers | Registers |
+ |___________|___________________|___________________|
+ | Primary | BAR at offset 0x10| BAR at offset 0x14|
+ |___________|___________________|___________________|
+ | Secondary | BAR at offset 0x18| BAR at offset 0x1C|
+ |___________|___________________|___________________|
+
+ Table 2. BARs for Register Mapping
+ </pre>
+ @note Refer to Intel ICH4 datasheet, Control Block Offset: 03F4h for
+ primary, 0374h for secondary. So 2 bytes extra offset should be
+ added to the base addresses read from BARs.
+
+ For more details, please refer to PCI IDE Controller Specification and Intel
+ ICH4 Datasheet.
+
+ @param PciIo Pointer to the EFI_PCI_IO_PROTOCOL instance
+ @param IdeRegsBaseAddr Pointer to IDE_REGISTERS_BASE_ADDR to
+ receive IDE IO port registers' base addresses
**/
EFI_STATUS
@@ -163,11 +162,12 @@ GetIdeRegistersBaseAddr ( );
/**
- TODO: Add function description
+ This function is used to requery IDE resources. The IDE controller will
+ probably switch between native and legacy modes during the EFI->CSM->OS
+ transfer. We do this everytime before an BlkIo operation to ensure its
+ succeess.
- @param IdeDev TODO: add argument description
-
- TODO: add return values.
+ @param IdeDev The BLK_IO private data which specifies the IDE device
**/
EFI_STATUS
@@ -176,11 +176,9 @@ ReassignIdeResources ( );
/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
+ Detect if there is disk attached to this port
- TODO: add return values.
+ @param IdeDev The BLK_IO private data which specifies the IDE device.
**/
EFI_STATUS
@@ -201,25 +199,20 @@ InitializeIDEChannelData ( );
/**
- TODO: Add function description
+ This function is used to poll for the DRQ bit clear in the Status
+ Register. DRQ is cleared when the device is finished transferring data.
+ So this function is called after data transfer is finished.
- @param IdeDev TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used
+ to record all the information of the IDE device.
+ @param TimeoutInMilliSeconds used to designate the timeout for the DRQ clear.
- TODO: add return values.
+ @retval EFI_SUCCESS DRQ bit clear within the time out.
-**/
-EFI_STATUS
-DetectIDEController (
- IN IDE_BLK_IO_DEV *IdeDev
- );
+ @retval EFI_TIMEOUT DRQ bit not clear within the time out.
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param TimeoutInMilliSeconds TODO: add argument description
-
- TODO: add return values.
+ @note
+ Read Status Register will clear interrupt status.
**/
EFI_STATUS
@@ -229,12 +222,21 @@ DRQClear ( );
/**
- TODO: Add function description
+ This function is used to poll for the DRQ bit clear in the Alternate
+ Status Register. DRQ is cleared when the device is finished
+ transferring data. So this function is called after data transfer
+ is finished.
- @param IdeDev TODO: add argument description
- @param TimeoutInMilliSeconds TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used
+ to record all the information of the IDE device.
- TODO: add return values.
+ @param TimeoutInMilliSeconds used to designate the timeout for the DRQ clear.
+
+ @retval EFI_SUCCESS DRQ bit clear within the time out.
+
+ @retval EFI_TIMEOUT DRQ bit not clear within the time out.
+ @note
+ Read Alternate Status Register will not clear interrupt status.
**/
EFI_STATUS
@@ -244,12 +246,21 @@ DRQClear2 ( );
/**
- TODO: Add function description
+ This function is used to poll for the DRQ bit set in the
+ Status Register.
+ DRQ is set when the device is ready to transfer data. So this function
+ is called after the command is sent to the device and before required
+ data is transferred.
+
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure,used to
+ record all the information of the IDE device.
+ @param TimeoutInMilliSeconds used to designate the timeout for the DRQ ready.
- @param IdeDev TODO: add argument description
- @param TimeoutInMilliSeconds TODO: add argument description
+ @retval EFI_SUCCESS DRQ bit set within the time out.
+ @retval EFI_TIMEOUT DRQ bit not set within the time out.
+ @retval EFI_ABORTED DRQ bit not set caused by the command abort.
- TODO: add return values.
+ @note Read Status Register will clear interrupt status.
**/
EFI_STATUS
@@ -259,12 +270,19 @@ DRQReady ( );
/**
- TODO: Add function description
+ This function is used to poll for the DRQ bit set in the Alternate Status Register.
+ DRQ is set when the device is ready to transfer data. So this function is called after
+ the command is sent to the device and before required data is transferred.
- @param IdeDev TODO: add argument description
- @param TimeoutInMilliSeconds TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used to
+ record all the information of the IDE device.
- TODO: add return values.
+ @param TimeoutInMilliSeconds used to designate the timeout for the DRQ ready.
+
+ @retval EFI_SUCCESS DRQ bit set within the time out.
+ @retval EFI_TIMEOUT DRQ bit not set within the time out.
+ @retval EFI_ABORTED DRQ bit not set caused by the command abort.
+ @note Read Alternate Status Register will not clear interrupt status.
**/
EFI_STATUS
@@ -274,13 +292,17 @@ DRQReady2 ( );
/**
- TODO: Add function description
+ This function is used to poll for the BSY bit clear in the Status Register. BSY
+ is clear when the device is not busy. Every command must be sent after device is not busy.
- @param IdeDev TODO: add argument description
- @param TimeoutInMilliSeconds TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used
+ to record all the information of the IDE device.
+ @param TimeoutInMilliSeconds used to designate the timeout for the DRQ ready.
- TODO: add return values.
+ @retval EFI_SUCCESS BSY bit clear within the time out.
+ @retval EFI_TIMEOUT BSY bit not clear within the time out.
+ @note Read Status Register will clear interrupt status.
**/
EFI_STATUS
WaitForBSYClear (
@@ -289,12 +311,17 @@ WaitForBSYClear ( );
/**
- TODO: Add function description
+ This function is used to poll for the BSY bit clear in the Alternate Status Register.
+ BSY is clear when the device is not busy. Every command must be sent after device is
+ not busy.
- @param IdeDev TODO: add argument description
- @param TimeoutInMilliSeconds TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used to record
+ all the information of the IDE device.
+ @paramTimeoutInMilliSeconds used to designate the timeout for the DRQ ready.
- TODO: add return values.
+ @retval EFI_SUCCESS BSY bit clear within the time out.
+ @retval EFI_TIMEOUT BSY bit not clear within the time out.
+ @note Read Alternate Status Register will not clear interrupt status.
**/
EFI_STATUS
@@ -304,13 +331,18 @@ WaitForBSYClear2 ( );
/**
- TODO: Add function description
+ This function is used to poll for the DRDY bit set in the Status Register. DRDY
+ bit is set when the device is ready to accept command. Most ATA commands must be
+ sent after DRDY set except the ATAPI Packet Command.
- @param IdeDev TODO: add argument description
- @param DelayInMilliSeconds TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used
+ to record all the information of the IDE device.
+ @param DelayInMilliSeconds used to designate the timeout for the DRQ ready.
- TODO: add return values.
+ @retval EFI_SUCCESS DRDY bit set within the time out.
+ @retval EFI_TIMEOUT DRDY bit not set within the time out.
+ @note Read Status Register will clear interrupt status.
**/
EFI_STATUS
DRDYReady (
@@ -319,12 +351,18 @@ DRDYReady ( );
/**
- TODO: Add function description
+ This function is used to poll for the DRDY bit set in the Alternate Status Register.
+ DRDY bit is set when the device is ready to accept command. Most ATA commands must
+ be sent after DRDY set except the ATAPI Packet Command.
+
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used
+ to record all the information of the IDE device.
+ @param DelayInMilliSeconds used to designate the timeout for the DRQ ready.
- @param IdeDev TODO: add argument description
- @param DelayInMilliSeconds TODO: add argument description
+ @retval EFI_SUCCESS DRDY bit set within the time out.
+ @retval EFI_TIMEOUT DRDY bit not set within the time out.
- TODO: add return values.
+ @note Read Alternate Status Register will clear interrupt status.
**/
EFI_STATUS
@@ -333,32 +371,26 @@ DRDYReady2 ( IN UINTN DelayInMilliSeconds
);
-/**
- TODO: Add function description
-
- @param Destination TODO: add argument description
- @param Source TODO: add argument description
- @param Size TODO: add argument description
-
- TODO: add return values.
-
-**/
-VOID
-SwapStringChars (
- IN CHAR8 *Destination,
- IN CHAR8 *Source,
- IN UINT32 Size
- );
-
//
// ATA device functions' prototype
//
/**
- TODO: Add function description
+ Sends out an ATA Identify Command to the specified device.
+
+ This function is called by DiscoverIdeDevice() during its device
+ identification. It sends out the ATA Identify Command to the
+ specified device. Only ATA device responses to this command. If
+ the command succeeds, it returns the Identify data structure which
+ contains information about the device. This function extracts the
+ information it needs to fill the IDE_BLK_IO_DEV data structure,
+ including device type, media block size, media capacity, and etc.
- @param IdeDev TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure,used to record
+ all the information of the IDE device.
- TODO: add return values.
+ @retval EFI_SUCCESS Identify ATA device successfully.
+ @retval EFI_DEVICE_ERROR ATA Identify Device Command failed or device is not ATA device.
+ @note parameter IdeDev will be updated in this function.
**/
EFI_STATUS
@@ -367,32 +399,31 @@ ATAIdentify ( );
/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
-
- TODO: add return values.
+ This function is called by ATAIdentify() or ATAPIIdentify() to print device's module name.
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used to record
+ all the information of the IDE device.
**/
VOID
PrintAtaModuleName (
IN IDE_BLK_IO_DEV *IdeDev
);
-
/**
- TODO: Add function description
+ This function is used to send out ATA commands conforms to the PIO Data In Protocol.
- @param IdeDev TODO: add argument description
- @param Buffer TODO: add argument description
- @param ByteCount TODO: add argument description
- @param AtaCommand TODO: add argument description
- @param Head TODO: add argument description
- @param SectorCount TODO: add argument description
- @param SectorNumber TODO: add argument description
- @param CylinderLsb TODO: add argument description
- @param CylinderMsb TODO: add argument description
-
- TODO: add return values.
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used to record
+ all the information of the IDE device.
+ @param Buffer buffer contained data transferred from device to host.
+ @param ByteCount data size in byte unit of the buffer.
+ @param AtaCommand value of the Command Register
+ @param Head value of the Head/Device Register
+ @param SectorCount value of the Sector Count Register
+ @param SectorNumber value of the Sector Number Register
+ @param CylinderLsb value of the low byte of the Cylinder Register
+ @param CylinderMsb value of the high byte of the Cylinder Register
+
+ @retval EFI_SUCCESS send out the ATA command and device send required data successfully.
+ @retval EFI_DEVICE_ERROR command sent failed.
**/
EFI_STATUS
@@ -409,19 +440,23 @@ AtaPioDataIn ( );
/**
- TODO: Add function description
+ This function is used to send out ATA commands conforms to the
+ PIO Data Out Protocol.
- @param IdeDev TODO: add argument description
- @param Buffer TODO: add argument description
- @param ByteCount TODO: add argument description
- @param AtaCommand TODO: add argument description
- @param Head TODO: add argument description
- @param SectorCount TODO: add argument description
- @param SectorNumber TODO: add argument description
- @param CylinderLsb TODO: add argument description
- @param CylinderMsb TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used
+ to record all the information of the IDE device.
+ @param *Buffer buffer contained data transferred from host to device.
+ @param ByteCount data size in byte unit of the buffer.
+ @param AtaCommand value of the Command Register
+ @param Head value of the Head/Device Register
+ @param SectorCount value of the Sector Count Register
+ @param SectorNumber value of the Sector Number Register
+ @param CylinderLsb value of the low byte of the Cylinder Register
+ @param CylinderMsb value of the high byte of the Cylinder Register
- TODO: add return values.
+ @retval EFI_SUCCESS send out the ATA command and device received required
+ data successfully.
+ @retval EFI_DEVICE_ERROR command sent failed.
**/
EFI_STATUS
@@ -438,11 +473,15 @@ AtaPioDataOut ( );
/**
- TODO: Add function description
+ This function is used to analyze the Status Register and print out
+ some debug information and if there is ERR bit set in the Status
+ Register, the Error Register's value is also be parsed and print out.
- @param IdeDev TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used to
+ record all the information of the IDE device.
- TODO: add return values.
+ @retval EFI_SUCCESS No err information in the Status Register.
+ @retval EFI_DEVICE_ERROR Any err information in the Status Register.
**/
EFI_STATUS
@@ -451,50 +490,23 @@ CheckErrorStatus ( );
/**
- TODO: Add function description
+ This function is used to implement the Soft Reset on the specified device. But,
+ the ATA Soft Reset mechanism is so strong a reset method that it will force
+ resetting on both devices connected to the same cable.
- @param IdeDev TODO: add argument description
- @param DataBuffer TODO: add argument description
- @param Lba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
+ It is called by IdeBlkIoReset(), a interface function of Block
+ I/O protocol.
- TODO: add return values.
+ This function can also be used by the ATAPI device to perform reset when
+ ATAPI Reset command is failed.
-**/
-EFI_STATUS
-AtaReadSectors (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *DataBuffer,
- IN EFI_LBA Lba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param BufferData TODO: add argument description
- @param Lba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaWriteSectors (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *BufferData,
- IN EFI_LBA Lba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
-
- TODO: add return values.
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used to record
+ all the information of the IDE device.
+ @retval EFI_SUCCESS Soft reset completes successfully.
+ @retval EFI_DEVICE_ERROR Any step during the reset process is failed.
+ @note The registers initial values after ATA soft reset are different
+ to the ATA device and ATAPI device.
**/
EFI_STATUS
AtaSoftReset (
@@ -502,15 +514,30 @@ AtaSoftReset ( );
/**
- TODO: Add function description
+ This function is the ATA implementation for ReadBlocks in the
+ Block I/O Protocol interface.
+
+ @param IdeBlkIoDevice Indicates the calling context.
+ @param MediaId The media id that the read request is for.
+ @param LBA The starting logical block address to read from on the device.
+ @param BufferSize The size of the Buffer in bytes. This must be a multiple
+ of the intrinsic block size of the device.
- @param IdeBlkIoDevice TODO: add argument description
- @param MediaId TODO: add argument description
- @param Lba TODO: add argument description
- @param BufferSize TODO: add argument description
- @param Buffer TODO: add argument description
+ @param Buffer A pointer to the destination buffer for the data. The caller
+ is responsible for either having implicit or explicit ownership
+ of the memory that data is read into.
- TODO: add return values.
+ @retval EFI_SUCCESS Read Blocks successfully.
+ @retval EFI_DEVICE_ERROR Read Blocks failed.
+ @retval EFI_NO_MEDIA There is no media in the device.
+ @retval EFI_MEDIA_CHANGE The MediaId is not for the current media.
+ @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the
+ intrinsic block size of the device.
+ @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
+ or the data buffer is not valid.
+
+ @note If Read Block error because of device error, this function will call
+ AtaSoftReset() function to reset device.
**/
EFI_STATUS
@@ -523,16 +550,30 @@ AtaBlkIoReadBlocks ( );
/**
- TODO: Add function description
+ This function is the ATA implementation for WriteBlocks in the
+ Block I/O Protocol interface.
+
+ @param IdeBlkIoDevice Indicates the calling context.
+ @param MediaId The media id that the write request is for.
+ @param LBA The starting logical block address to write onto the device.
+ @param BufferSize The size of the Buffer in bytes. This must be a multiple
+ of the intrinsic block size of the device.
+ @param Buffer A pointer to the source buffer for the data.The caller
+ is responsible for either having implicit or explicit
+ ownership of the memory that data is written from.
- @param IdeBlkIoDevice TODO: add argument description
- @param MediaId TODO: add argument description
- @param Lba TODO: add argument description
- @param BufferSize TODO: add argument description
- @param Buffer TODO: add argument description
+ @retval EFI_SUCCESS Write Blocks successfully.
+ @retval EFI_DEVICE_ERROR Write Blocks failed.
+ @retval EFI_NO_MEDIA There is no media in the device.
+ @retval EFI_MEDIA_CHANGE The MediaId is not for the current media.
- TODO: add return values.
+ @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the
+ intrinsic block size of the device.
+ @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
+ or the data buffer is not valid.
+ @note If Write Block error because of device error, this function will call
+ AtaSoftReset() function to reset device.
**/
EFI_STATUS
AtaBlkIoWriteBlocks (
@@ -543,16 +584,35 @@ AtaBlkIoWriteBlocks ( OUT VOID *Buffer
);
-//
-// ATAPI device functions' prototype
-//
/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
+ This function is called by DiscoverIdeDevice() during its device
+ identification.
+ Its main purpose is to get enough information for the device media
+ to fill in the Media data structure of the Block I/O Protocol interface.
+
+ There are 5 steps to reach such objective:
+ 1. Sends out the ATAPI Identify Command to the specified device.
+ Only ATAPI device responses to this command. If the command succeeds,
+ it returns the Identify data structure which filled with information
+ about the device. Since the ATAPI device contains removable media,
+ the only meaningful information is the device module name.
+ 2. Sends out ATAPI Inquiry Packet Command to the specified device.
+ This command will return inquiry data of the device, which contains
+ the device type information.
+ 3. Allocate sense data space for future use. We don't detect the media
+ presence here to improvement boot performance, especially when CD
+ media is present. The media detection will be performed just before
+ each BLK_IO read/write
+
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used
+ to record all the information of the IDE device.
- TODO: add return values.
+ @retval EFI_SUCCESS Identify ATAPI device successfully.
+ @retval EFI_DEVICE_ERROR ATAPI Identify Device Command failed or device type
+ is not supported by this IDE driver.
+ @retval EFI_OUT_OF_RESOURCES Allocate memory for sense data failed
+ @note Parameter "IdeDev" will be updated in this function.
**/
EFI_STATUS
ATAPIIdentify (
@@ -560,185 +620,22 @@ ATAPIIdentify ( );
/**
- TODO: Add function description
+ This function is used to implement the Soft Reset on the specified
+ ATAPI device. Different from the AtaSoftReset(), here reset is a ATA
+ Soft Reset Command special for ATAPI device, and it only take effects
+ on the specified ATAPI device, not on the whole IDE bus.
+ Since the ATAPI soft reset is needed when device is in exceptional
+ condition (such as BSY bit is always set ), I think the Soft Reset
+ command should be sent without waiting for the BSY clear and DRDY
+ set.
+ This function is called by IdeBlkIoReset(),
+ a interface function of Block I/O protocol.
- @param IdeDev TODO: add argument description
+ @param IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used
+ to record all the information of the IDE device.
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiInquiry (
- IN IDE_BLK_IO_DEV *IdeDev
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param Packet TODO: add argument description
- @param Buffer TODO: add argument description
- @param ByteCount TODO: add argument description
- @param TimeOut TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiPacketCommandIn (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN ATAPI_PACKET_COMMAND *Packet,
- IN UINT16 *Buffer,
- IN UINT32 ByteCount,
- IN UINTN TimeOut
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param Packet TODO: add argument description
- @param Buffer TODO: add argument description
- @param ByteCount TODO: add argument description
- @param TimeOut TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiPacketCommandOut (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN ATAPI_PACKET_COMMAND *Packet,
- IN UINT16 *Buffer,
- IN UINT32 ByteCount,
- IN UINTN TimeOut
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param Buffer TODO: add argument description
- @param ByteCount TODO: add argument description
- @param Read TODO: add argument description
- @param TimeOut TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-PioReadWriteData (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN UINT16 *Buffer,
- IN UINT32 ByteCount,
- IN BOOLEAN Read,
- IN UINTN TimeOut
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param SResult TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiTestUnitReady (
- IN IDE_BLK_IO_DEV *IdeDev,
- OUT SENSE_RESULT *SResult
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param SenseCounts TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiRequestSense (
- IN IDE_BLK_IO_DEV *IdeDev,
- OUT UINTN *SenseCounts
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param SResult TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiReadCapacity (
- IN IDE_BLK_IO_DEV *IdeDev,
- OUT SENSE_RESULT *SResult
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param MediaChange TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiDetectMedia (
- IN IDE_BLK_IO_DEV *IdeDev,
- OUT BOOLEAN *MediaChange
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param Buffer TODO: add argument description
- @param Lba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiReadSectors (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *Buffer,
- IN EFI_LBA Lba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param Buffer TODO: add argument description
- @param Lba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiWriteSectors (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *Buffer,
- IN EFI_LBA Lba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
-
- TODO: add return values.
+ @retval EFI_SUCCESS Soft reset completes successfully.
+ @retval EFI_DEVICE_ERROR Any step during the reset process is failed.
**/
EFI_STATUS
@@ -747,16 +644,26 @@ AtapiSoftReset ( );
/**
- TODO: Add function description
-
- @param IdeBlkIoDevice TODO: add argument description
- @param MediaId TODO: add argument description
- @param Lba TODO: add argument description
- @param BufferSize TODO: add argument description
- @param Buffer TODO: add argument description
-
- TODO: add return values.
+ This function is the ATAPI implementation for ReadBlocks in the
+ Block I/O Protocol interface.
+ @param IdeBlkIoDevice Indicates the calling context.
+ @param MediaId The media id that the read request is for.
+ @param LBA The starting logical block address to read from on the device.
+ @param BufferSize The size of the Buffer in bytes. This must be a multiple
+ of the intrinsic block size of the device.
+ @param Buffer A pointer to the destination buffer for the data. The caller
+ is responsible for either having implicit or explicit
+ ownership of the memory that data is read into.
+
+ @retval EFI_SUCCESS Read Blocks successfully.
+ @retval EFI_DEVICE_ERROR Read Blocks failed.
+ @retval EFI_NO_MEDIA There is no media in the device.
+ @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
+ @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the
+ intrinsic block size of the device.
+ @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
+ or the data buffer is not valid.
**/
EFI_STATUS
AtapiBlkIoReadBlocks (
@@ -768,16 +675,28 @@ AtapiBlkIoReadBlocks ( );
/**
- TODO: Add function description
+ This function is the ATAPI implementation for WriteBlocks in the
+ Block I/O Protocol interface.
- @param IdeBlkIoDevice TODO: add argument description
- @param MediaId TODO: add argument description
- @param Lba TODO: add argument description
- @param BufferSize TODO: add argument description
- @param Buffer TODO: add argument description
+ @param IdeBlkIoDevice Indicates the calling context.
+ @param MediaId The media id that the write request is for.
+ @param LBA The starting logical block address to write onto the device.
+ @param BufferSize The size of the Buffer in bytes. This must be a multiple
+ of the intrinsic block size of the device.
+ @param Buffer A pointer to the source buffer for the data. The caller
+ is responsible for either having implicit or explicit ownership
+ of the memory that data is written from.
- TODO: add return values.
+ @retval EFI_SUCCESS Write Blocks successfully.
+ @retval EFI_DEVICE_ERROR Write Blocks failed.
+ @retval EFI_NO_MEDIA There is no media in the device.
+ @retval EFI_MEDIA_CHANGE The MediaId is not for the current media.
+ @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the
+ intrinsic block size of the device.
+ @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
+ or the data buffer is not valid.
+ @retval EFI_WRITE_PROTECTED The write protected is enabled or the media does not support write
**/
EFI_STATUS
AtapiBlkIoWriteBlocks (
@@ -789,56 +708,9 @@ AtapiBlkIoWriteBlocks ( );
/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param SenseCount TODO: add argument description
- @param Result TODO: add argument description
+ Release resources of an IDE device before stopping it.
- TODO: add return values.
-
-**/
-EFI_STATUS
-ParseSenseData (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN UINTN SenseCount,
- OUT SENSE_RESULT *Result
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtapiReadPendingData (
- IN IDE_BLK_IO_DEV *IdeDev
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param WriteProtected TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-IsLS120orZipWriteProtected (
- IN IDE_BLK_IO_DEV *IdeDev,
- OUT BOOLEAN *WriteProtected
- );
-
-/**
- TODO: Add function description
-
- @param IdeBlkIoDevice TODO: add argument description
-
- TODO: add return values.
+ @param IdeBlkIoDevice Standard IDE device private data structure
**/
VOID
@@ -847,49 +719,32 @@ ReleaseIdeResources ( );
/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param TransferMode TODO: add argument description
-
- TODO: add return values.
+ Set the calculated Best transfer mode to a detected device
+ @param IdeDev Standard IDE device private data structure
+ @param TransferMode The device transfer mode to be set
+ @return Set transfer mode Command execute status.
**/
EFI_STATUS
SetDeviceTransferMode (
IN IDE_BLK_IO_DEV *IdeDev,
IN ATA_TRANSFER_MODE *TransferMode
);
-
/**
- TODO: Add function description
+ Send ATA command into device with NON_DATA protocol
- @param IdeDev TODO: add argument description
- @param NativeMaxAddress TODO: add argument description
+ @param IdeDev Standard IDE device private data structure
+ @param AtaCommand The ATA command to be sent
+ @param Device The value in Device register
+ @param Feature The value in Feature register
+ @param SectorCount The value in SectorCount register
+ @param LbaLow The value in LBA_LOW register
+ @param LbaMiddle The value in LBA_MIDDLE register
+ @param LbaHigh The value in LBA_HIGH register
- TODO: add return values.
-
-**/
-EFI_STATUS
-ReadNativeMaxAddress (
- IN IDE_BLK_IO_DEV *IdeDev,
- OUT EFI_LBA *NativeMaxAddress
- );
-
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param AtaCommand TODO: add argument description
- @param Device TODO: add argument description
- @param Feature TODO: add argument description
- @param SectorCount TODO: add argument description
- @param LbaLow TODO: add argument description
- @param LbaMiddle TODO: add argument description
- @param LbaHigh TODO: add argument description
-
- TODO: add return values.
+ @retval EFI_SUCCESS Reading succeed
+ @retval EFI_ABORTED Command failed
+ @retval EFI_DEVICE_ERROR Device status error.
**/
EFI_STATUS
@@ -905,16 +760,18 @@ AtaNonDataCommandIn ( );
/**
- TODO: Add function description
+ Send ATA Ext command into device with NON_DATA protocol
- @param IdeDev TODO: add argument description
- @param AtaCommand TODO: add argument description
- @param Device TODO: add argument description
- @param Feature TODO: add argument description
- @param SectorCount TODO: add argument description
- @param LbaAddress TODO: add argument description
+ @param IdeDev Standard IDE device private data structure
+ @param AtaCommand The ATA command to be sent
+ @param Device The value in Device register
+ @param Feature The value in Feature register
+ @param SectorCount The value in SectorCount register
+ @param LbaAddress The LBA address in 48-bit mode
- TODO: add return values.
+ @retval EFI_SUCCESS Reading succeed
+ @retval EFI_ABORTED Command failed
+ @retval EFI_DEVICE_ERROR Device status error.
**/
EFI_STATUS
@@ -926,230 +783,6 @@ AtaNonDataCommandInExt ( IN UINT16 SectorCount,
IN EFI_LBA LbaAddress
);
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param DataBuffer TODO: add argument description
- @param StartLba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaReadSectorsExt (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *DataBuffer,
- IN EFI_LBA StartLba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param DataBuffer TODO: add argument description
- @param StartLba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaWriteSectorsExt (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *DataBuffer,
- IN EFI_LBA StartLba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param DataBuffer TODO: add argument description
- @param StartLba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaUdmaReadExt (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *DataBuffer,
- IN EFI_LBA StartLba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param DataBuffer TODO: add argument description
- @param StartLba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaUdmaRead (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *DataBuffer,
- IN EFI_LBA StartLba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param DataBuffer TODO: add argument description
- @param StartLba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaUdmaWriteExt (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *DataBuffer,
- IN EFI_LBA StartLba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- Perform an ATA Udma operation (Read, ReadExt, Write, WriteExt).
-
- @param[in] *IdeDev
- pointer pointing to IDE_BLK_IO_DEV data structure, used
- to record all the information of the IDE device.
-
- @param[in] *DataBuffer
- A pointer to the source buffer for the data.
-
- @param[in] StartLba
- The starting logical block address to write to
- on the device media.
-
- @param[in] NumberOfBlocks
- The number of transfer data blocks.
-
- @param[in] UdmaOp
- The perform operations could be AtaUdmaReadOp, AtaUdmaReadExOp,
- AtaUdmaWriteOp, AtaUdmaWriteExOp
-
- @return The device status of UDMA operation. If the operation is
- successful, return EFI_SUCCESS.
-
-**/
-EFI_STATUS
-DoAtaUdma (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *DataBuffer,
- IN EFI_LBA StartLba,
- IN UINTN NumberOfBlocks,
- IN ATA_UDMA_OPERATION UdmaOp
- );
-
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param DataBuffer TODO: add argument description
- @param StartLba TODO: add argument description
- @param NumberOfBlocks TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaUdmaWrite (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *DataBuffer,
- IN EFI_LBA StartLba,
- IN UINTN NumberOfBlocks
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param AtaCommand TODO: add argument description
- @param Device TODO: add argument description
- @param Feature TODO: add argument description
- @param SectorCount TODO: add argument description
- @param LbaAddress TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaCommandIssueExt (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN UINT8 AtaCommand,
- IN UINT8 Device,
- IN UINT16 Feature,
- IN UINT16 SectorCount,
- IN EFI_LBA LbaAddress
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param AtaCommand TODO: add argument description
- @param Device TODO: add argument description
- @param Feature TODO: add argument description
- @param SectorCount TODO: add argument description
- @param LbaAddress TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaCommandIssue (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN UINT8 AtaCommand,
- IN UINT8 Device,
- IN UINT16 Feature,
- IN UINT16 SectorCount,
- IN EFI_LBA LbaAddress
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaAtapi6Identify (
- IN IDE_BLK_IO_DEV *IdeDev
- );
-
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
-
- TODO: add return values.
-
-**/
-VOID
-AtaSMARTSupport (
- IN IDE_BLK_IO_DEV *IdeDev
- );
-
-
/**
Enable Long Physical Sector Feature for ATA device.
@@ -1166,58 +799,11 @@ AtaEnableLongPhysicalSector ( );
/**
- TODO: Add function description
+ Set drive parameters for devices not support PACKETS command
- @param IdeDev TODO: add argument description
- @param Buffer TODO: add argument description
- @param ByteCount TODO: add argument description
- @param AtaCommand TODO: add argument description
- @param StartLba TODO: add argument description
- @param SectorCount TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaPioDataInExt (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN OUT VOID *Buffer,
- IN UINT32 ByteCount,
- IN UINT8 AtaCommand,
- IN EFI_LBA StartLba,
- IN UINT16 SectorCount
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param Buffer TODO: add argument description
- @param ByteCount TODO: add argument description
- @param AtaCommand TODO: add argument description
- @param StartLba TODO: add argument description
- @param SectorCount TODO: add argument description
-
- TODO: add return values.
-
-**/
-EFI_STATUS
-AtaPioDataOutExt (
- IN IDE_BLK_IO_DEV *IdeDev,
- IN VOID *Buffer,
- IN UINT32 ByteCount,
- IN UINT8 AtaCommand,
- IN EFI_LBA StartLba,
- IN UINT16 SectorCount
- );
-
-/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
- @param DriveParameters TODO: add argument description
-
- TODO: add return values.
+ @param IdeDev Standard IDE device private data structure
+ @param DriveParameters The device parameters to be set into the disk
+ @return SetParameters Command execute status.
**/
EFI_STATUS
@@ -1227,30 +813,14 @@ SetDriveParameters ( );
/**
- TODO: Add function description
-
- @param IdeDev TODO: add argument description
+ Enable Interrupt on IDE controller
- TODO: add return values.
+ @param IdeDev Standard IDE device private data structure
+ @retval EFI_SUCCESS Enable Interrupt successfully
**/
EFI_STATUS
EnableInterrupt (
IN IDE_BLK_IO_DEV *IdeDev
);
-
-/**
- Clear pending IDE interrupt before OS loader/kernel take control of the IDE device.
-
- @param[in] Event Pointer to this event.
- @param[in] Context Event hanlder private data.
-
-**/
-VOID
-EFIAPI
-ClearInterrupt (
- IN EFI_EVENT Event,
- IN VOID *Context
- );
-
#endif
|