From ed72955cc855cd232ba75ff8dde334569f90f913 Mon Sep 17 00:00:00 2001 From: darylm503 Date: Fri, 9 Jun 2006 23:41:12 +0000 Subject: [PATCH] Update comments to conform to the new, Doxygen friendly, coding standard. These are structural changes only. There is NO NEW CONTENT. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@461 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Application/HelloWorld/HelloWorld.c | 27 +- .../Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c | 1006 ++++++------ .../Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h | 621 +++---- .../Bus/Pci/AtapiPassThru/Dxe/ComponentName.c | 165 +- .../Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c | 96 +- .../Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h | 155 +- .../CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c | 439 ++--- .../Bus/Pci/CirrusLogic/Dxe/ComponentName.c | 157 +- .../Bus/Pci/IdeBus/Dxe/ComponentName.c | 176 +- .../Bus/Pci/IdeBus/Dxe/DriverConfiguration.c | 309 ++-- .../Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c | 143 +- EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c | 1450 ++++++----------- EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c | 1310 ++++++--------- EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c | 1076 +++++------- EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h | 1402 +++++----------- EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c | 363 ++--- EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h | 291 ++-- EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h | 28 +- 18 files changed, 3602 insertions(+), 5612 deletions(-) diff --git a/EdkModulePkg/Application/HelloWorld/HelloWorld.c b/EdkModulePkg/Application/HelloWorld/HelloWorld.c index f3eda071e4..d3714ebca5 100644 --- a/EdkModulePkg/Application/HelloWorld/HelloWorld.c +++ b/EdkModulePkg/Application/HelloWorld/HelloWorld.c @@ -1,23 +1,16 @@ -/*++ - -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: +/** @file + This driver supports platform security service - HelloWorld.c + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Abstract: - - This driver supports platform security service + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. ---*/ +**/ VOID Print ( diff --git a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c index 6fe81d1521..1bdce40f67 100644 --- a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c +++ b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c @@ -1,23 +1,14 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - AtapiPassThru.c - -Abstract: - - -Revision History ---*/ +**/ #include "AtapiPassThru.h" @@ -46,9 +37,9 @@ AtapiScsiPassThruDriverBindingStop ( IN EFI_HANDLE *ChildHandleBuffer ); -// -// IDE registers' fixed address -// +/// +/// IDE registers' fixed address +/// static IDE_BASE_REGISTERS gAtapiIoPortRegisters[2] = { { 0x1f0, { 0x1f1 }, 0x1f2, 0x1f3, 0x1f4, 0x1f5, 0x1f6, { 0x1f7 }, { 0x3f6 }, 0x3f7, 0 }, { 0x170, { 0x171 }, 0x172, 0x173, 0x174, 0x175, 0x176, { 0x177 }, { 0x376 }, 0x377, 0 } @@ -56,9 +47,9 @@ static IDE_BASE_REGISTERS gAtapiIoPortRegisters[2] = { static SCSI_COMMAND_SET gEndTable = { 0xff, 0xff }; -// -// This table contains all the supported ATAPI commands. -// +/// +/// This table contains all the supported ATAPI commands. +/// static SCSI_COMMAND_SET gSupportedATAPICommands[] = { { OP_INQUIRY, DataIn }, { OP_LOAD_UNLOAD_CD, NoData }, @@ -107,6 +98,18 @@ EFI_DRIVER_BINDING_PROTOCOL gAtapiScsiPassThruDriverBinding = { NULL }; +/** + Supported. + + (Standard DriverBinding Protocol Supported() function) + + @return EFI_STATUS + + @todo This - add argument and description to function comment + @todo Controller - add argument and description to function comment + @todo RemainingDevicePath - add argument and description to function comment + @todo EFI_UNSUPPORTED - add return value to function comment +**/ EFI_STATUS EFIAPI AtapiScsiPassThruDriverBindingSupported ( @@ -114,22 +117,6 @@ AtapiScsiPassThruDriverBindingSupported ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - - Routine Description: - Supported. - - Arguments: - (Standard DriverBinding Protocol Supported() function) - - Returns: - EFI_STATUS - ---*/ -// TODO: This - add argument and description to function comment -// TODO: Controller - add argument and description to function comment -// TODO: RemainingDevicePath - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment { EFI_STATUS Status; EFI_PCI_IO_PROTOCOL *PciIo; @@ -186,6 +173,18 @@ AtapiScsiPassThruDriverBindingSupported ( return Status; } +/** + Create handles for IDE channels specified by RemainingDevicePath. + Install SCSI Pass Thru Protocol onto each created handle. + + (Standard DriverBinding Protocol Start() function) + + @return EFI_STATUS + + @todo This - add argument and description to function comment + @todo Controller - add argument and description to function comment + @todo RemainingDevicePath - add argument and description to function comment +**/ EFI_STATUS EFIAPI AtapiScsiPassThruDriverBindingStart ( @@ -193,22 +192,6 @@ AtapiScsiPassThruDriverBindingStart ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - - Routine Description: - Create handles for IDE channels specified by RemainingDevicePath. - Install SCSI Pass Thru Protocol onto each created handle. - - Arguments: - (Standard DriverBinding Protocol Start() function) - - Returns: - EFI_STATUS - ---*/ -// TODO: This - add argument and description to function comment -// TODO: Controller - add argument and description to function comment -// TODO: RemainingDevicePath - add argument and description to function comment { EFI_STATUS Status; EFI_PCI_IO_PROTOCOL *PciIo; @@ -263,6 +246,19 @@ Done: return Status; } +/** + Stop. + + (Standard DriverBinding Protocol Stop() function) + + @return EFI_STATUS + + @todo This - add argument and description to function comment + @todo Controller - add argument and description to function comment + @todo NumberOfChildren - add argument and description to function comment + @todo ChildHandleBuffer - add argument and description to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS EFIAPI AtapiScsiPassThruDriverBindingStop ( @@ -271,23 +267,6 @@ AtapiScsiPassThruDriverBindingStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/*++ - - Routine Description: - Stop. - - Arguments: - (Standard DriverBinding Protocol Stop() function) - - Returns: - EFI_STATUS - ---*/ -// TODO: This - add argument and description to function comment -// TODO: Controller - add argument and description to function comment -// TODO: NumberOfChildren - add argument and description to function comment -// TODO: ChildHandleBuffer - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; EFI_SCSI_PASS_THRU_PROTOCOL *ScsiPassThru; @@ -337,28 +316,25 @@ AtapiScsiPassThruDriverBindingStop ( return EFI_SUCCESS; } +/** + Attaches SCSI Pass Thru Protocol for specified IDE channel. + + @param Controller: Parent device handle to the IDE channel. + @param PciIo: PCI I/O protocol attached on the "Controller". + + @return EFI_SUCCESS Always returned unless installing SCSI Pass Thru Protocol failed. + + @todo This - add argument and description to function comment + @todo Controller - add argument and description to function comment + @todo PciIo - add argument and description to function comment + @todo EFI_OUT_OF_RESOURCES - add return value to function comment +**/ EFI_STATUS RegisterAtapiScsiPassThru ( IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_HANDLE Controller, IN EFI_PCI_IO_PROTOCOL *PciIo ) -/*++ - - Routine Description: - Attaches SCSI Pass Thru Protocol for specified IDE channel. - - Arguments: - Controller: Parent device handle to the IDE channel. - PciIo: PCI I/O protocol attached on the "Controller". - - Returns: - Always return EFI_SUCCESS unless installing SCSI Pass Thru Protocol failed. ---*/ -// TODO: This - add argument and description to function comment -// TODO: Controller - add argument and description to function comment -// TODO: PciIo - add argument and description to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment { EFI_STATUS Status; ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate; @@ -427,6 +403,29 @@ RegisterAtapiScsiPassThru ( return Status; } +/** + Implements EFI_SCSI_PASS_THRU_PROTOCOL.PassThru() function. + + @param This The EFI_SCSI_PASS_THRU_PROTOCOL instance. + @param Target The Target ID of the ATAPI device to send the SCSI + Request Packet. To ATAPI devices attached on an IDE + Channel, Target ID 0 indicates Master device;Target + ID 1 indicates Slave device. + @param Lun The LUN of the ATAPI device to send the SCSI Request + Packet. To the ATAPI device, Lun is always 0. + @param Packet The SCSI Request Packet to send to the ATAPI device + specified by Target and Lun. + @param 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 SCSI Request Packet completes. + + @todo This - add argument and description to function comment + @todo EFI_INVALID_PARAMETER - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS EFIAPI AtapiScsiPassThruFunction ( @@ -436,34 +435,6 @@ AtapiScsiPassThruFunction ( IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet, IN EFI_EVENT Event OPTIONAL ) -/*++ - - Routine Description: - Implements EFI_SCSI_PASS_THRU_PROTOCOL.PassThru() function. - - Arguments: - This: The EFI_SCSI_PASS_THRU_PROTOCOL instance. - Target: The Target ID of the ATAPI device to send the SCSI - Request Packet. To ATAPI devices attached on an IDE - Channel, Target ID 0 indicates Master device;Target - ID 1 indicates Slave device. - Lun: The LUN of the ATAPI device to send the SCSI Request - Packet. To the ATAPI device, Lun is always 0. - Packet: The SCSI Request Packet to send to the ATAPI device - specified by Target and Lun. - 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 SCSI Request Packet completes. - - Returns: - ---*/ -// TODO: This - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate; EFI_STATUS Status; @@ -515,6 +486,29 @@ AtapiScsiPassThruFunction ( return Status; } +/** + Used to retrieve the list of legal Target IDs for SCSI devices + on a SCSI channel. + + @param This Protocol instance pointer. + @param Target On input, a pointer to the Target ID of a SCSI + device present on the SCSI channel. On output, + a pointer to the Target ID of the next SCSI device + present on a SCSI channel. An input value of + 0xFFFFFFFF retrieves the Target ID of the first + SCSI device present on a SCSI channel. + @param Lun On input, a pointer to the LUN of a SCSI device + present on the SCSI channel. On output, a pointer + to the LUN of the next SCSI device present on + a SCSI channel. + + @retval EFI_SUCCESS The Target ID and Lun of the next SCSI device + on the SCSI channel was returned in Target and Lun. + @retval EFI_NOT_FOUND There are no more SCSI devices on this SCSI channel. + @retval EFI_INVALID_PARAMETER Target is not 0xFFFFFFFF,and Target and Lun were not + returned on a previous call to GetNextDevice(). + +**/ EFI_STATUS EFIAPI AtapiScsiPassThruGetNextDevice ( @@ -522,32 +516,6 @@ AtapiScsiPassThruGetNextDevice ( IN OUT UINT32 *Target, IN OUT UINT64 *Lun ) -/*++ - - Routine Description: - Used to retrieve the list of legal Target IDs for SCSI devices - on a SCSI channel. - - Arguments: - This - Protocol instance pointer. - Target - On input, a pointer to the Target ID of a SCSI - device present on the SCSI channel. On output, - a pointer to the Target ID of the next SCSI device - present on a SCSI channel. An input value of - 0xFFFFFFFF retrieves the Target ID of the first - SCSI device present on a SCSI channel. - Lun - On input, a pointer to the LUN of a SCSI device - present on the SCSI channel. On output, a pointer - to the LUN of the next SCSI device present on - a SCSI channel. - - Returns: - EFI_SUCCESS - The Target ID and Lun of the next SCSI device - on the SCSI channel was returned in Target and Lun. - EFI_NOT_FOUND - There are no more SCSI devices on this SCSI channel. - EFI_INVALID_PARAMETER - Target is not 0xFFFFFFFF,and Target and Lun were not - returned on a previous call to GetNextDevice(). ---*/ { ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate; @@ -591,6 +559,33 @@ AtapiScsiPassThruGetNextDevice ( } +/** + Used to allocate and build a device path node for a SCSI device + on a SCSI channel. Would not build device path for a SCSI Host Controller. + + @param This Protocol instance pointer. + @param Target The Target ID of the SCSI device for which + a device path node is to be allocated and built. + @param Lun The LUN of the SCSI device for which a device + path node is to be allocated and built. + @param DevicePath A pointer to a single device path node that + describes the SCSI device specified by + Target and Lun. 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. + + @retval EFI_SUCCESS The device path node that describes the SCSI device + specified by Target and Lun was allocated and + returned in DevicePath. + @retval EFI_NOT_FOUND The SCSI devices specified by Target and Lun does + not exist on the SCSI channel. + @retval EFI_INVALID_PARAMETER DevicePath is NULL. + @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate + DevicePath. + +**/ EFI_STATUS EFIAPI AtapiScsiPassThruBuildDevicePath ( @@ -599,35 +594,6 @@ AtapiScsiPassThruBuildDevicePath ( IN UINT64 Lun, IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath ) -/*++ - - Routine Description: - Used to allocate and build a device path node for a SCSI device - on a SCSI channel. Would not build device path for a SCSI Host Controller. - - Arguments: - This - Protocol instance pointer. - Target - The Target ID of the SCSI device for which - a device path node is to be allocated and built. - Lun - The LUN of the SCSI device for which a device - path node is to be allocated and built. - DevicePath - A pointer to a single device path node that - describes the SCSI device specified by - Target and Lun. 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. - Returns: - EFI_SUCCESS - The device path node that describes the SCSI device - specified by Target and Lun was allocated and - returned in DevicePath. - EFI_NOT_FOUND - The SCSI devices specified by Target and Lun does - not exist on the SCSI channel. - EFI_INVALID_PARAMETER - DevicePath is NULL. - EFI_OUT_OF_RESOURCES - There are not enough resources to allocate - DevicePath. ---*/ { ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate; EFI_DEV_PATH *Node; @@ -670,6 +636,29 @@ AtapiScsiPassThruBuildDevicePath ( return EFI_SUCCESS; } +/** + Used to translate a device path node to a Target ID and LUN. + + @param This Protocol instance pointer. + @param DevicePath A pointer to the device path node that + describes a SCSI device on the SCSI channel. + @param Target A pointer to the Target ID of a SCSI device + on the SCSI channel. + @param Lun A pointer to the LUN of a SCSI device on + the SCSI channel. + + @retval EFI_SUCCESS DevicePath was successfully translated to a + Target ID and LUN, and they were returned + in Target and Lun. + @retval EFI_INVALID_PARAMETER DevicePath is NULL. + @retval EFI_INVALID_PARAMETER Target is NULL. + @retval EFI_INVALID_PARAMETER Lun is NULL. + @retval EFI_UNSUPPORTED This driver does not support the device path + node type in DevicePath. + @retval EFI_NOT_FOUND A valid translation from DevicePath to a + Target ID and LUN does not exist. + +**/ EFI_STATUS EFIAPI AtapiScsiPassThruGetTargetLun ( @@ -678,31 +667,6 @@ AtapiScsiPassThruGetTargetLun ( OUT UINT32 *Target, OUT UINT64 *Lun ) -/*++ - - Routine Description: - Used to translate a device path node to a Target ID and LUN. - - Arguments: - This - Protocol instance pointer. - DevicePath - A pointer to the device path node that - describes a SCSI device on the SCSI channel. - Target - A pointer to the Target ID of a SCSI device - on the SCSI channel. - Lun - A pointer to the LUN of a SCSI device on - the SCSI channel. - Returns: - EFI_SUCCESS - DevicePath was successfully translated to a - Target ID and LUN, and they were returned - in Target and Lun. - EFI_INVALID_PARAMETER - DevicePath is NULL. - EFI_INVALID_PARAMETER - Target is NULL. - EFI_INVALID_PARAMETER - Lun 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 - Target ID and LUN does not exist. ---*/ { EFI_DEV_PATH *Node; @@ -734,29 +698,26 @@ AtapiScsiPassThruGetTargetLun ( return EFI_SUCCESS; } +/** + Resets a SCSI channel.This operation resets all the + SCSI devices connected to the SCSI channel. + + @param This Protocol instance pointer. + + @retval EFI_SUCCESS The SCSI channel was reset. + @retval EFI_UNSUPPORTED The SCSI channel does not support + a channel reset operation. + @retval EFI_DEVICE_ERROR A device error occurred while + attempting to reset the SCSI channel. + @retval EFI_TIMEOUT A timeout occurred while attempting + to reset the SCSI channel. + +**/ EFI_STATUS EFIAPI AtapiScsiPassThruResetChannel ( IN EFI_SCSI_PASS_THRU_PROTOCOL *This ) -/*++ - - Routine Description: - Resets a SCSI channel.This operation resets all the - SCSI devices connected to the SCSI channel. - - Arguments: - This - Protocol instance pointer. - - Returns: - EFI_SUCCESS - The SCSI channel was reset. - EFI_UNSUPPORTED - The SCSI channel does not support - a channel reset operation. - EFI_DEVICE_ERROR - A device error occurred while - attempting to reset the SCSI channel. - EFI_TIMEOUT - A timeout occurred while attempting - to reset the SCSI channel. ---*/ { UINT8 DeviceControlValue; ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate; @@ -813,6 +774,25 @@ AtapiScsiPassThruResetChannel ( return EFI_SUCCESS; } +/** + Resets a SCSI device that is connected to a SCSI channel. + + @param This Protocol instance pointer. + @param Target The Target ID of the SCSI device to reset. + @param Lun The LUN of the SCSI device to reset. + + @retval EFI_SUCCESS The SCSI device specified by Target and + Lun was reset. + @retval EFI_UNSUPPORTED The SCSI channel does not support a target + reset operation. + @retval EFI_INVALID_PARAMETER Target or Lun are invalid. + @retval EFI_DEVICE_ERROR A device error occurred while attempting + to reset the SCSI device specified by Target + and Lun. + @retval EFI_TIMEOUT A timeout occurred while attempting to reset + the SCSI device specified by Target and Lun. + +**/ EFI_STATUS EFIAPI AtapiScsiPassThruResetTarget ( @@ -820,28 +800,6 @@ AtapiScsiPassThruResetTarget ( IN UINT32 Target, IN UINT64 Lun ) -/*++ - - Routine Description: - Resets a SCSI device that is connected to a SCSI channel. - - Arguments: - This - Protocol instance pointer. - Target - The Target ID of the SCSI device to reset. - Lun - The LUN of the SCSI device to reset. - - Returns: - EFI_SUCCESS - The SCSI device specified by Target and - Lun was reset. - EFI_UNSUPPORTED - The SCSI channel does not support a target - reset operation. - EFI_INVALID_PARAMETER - Target or Lun are invalid. - EFI_DEVICE_ERROR - A device error occurred while attempting - to reset the SCSI device specified by Target - and Lun. - EFI_TIMEOUT - A timeout occurred while attempting to reset - the SCSI device specified by Target and Lun. ---*/ { ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate; UINT8 Command; @@ -899,25 +857,24 @@ AtapiScsiPassThruResetTarget ( } +/** + Checks the parameters in the SCSI Request Packet to make sure + they are valid for a SCSI Pass Thru request. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo Packet - add argument and description to function comment + @todo EFI_INVALID_PARAMETER - add return value to function comment + @todo EFI_INVALID_PARAMETER - add return value to function comment + @todo EFI_INVALID_PARAMETER - add return value to function comment + @todo EFI_UNSUPPORTED - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS CheckSCSIRequestPacket ( EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet ) -/*++ - - Checks the parameters in the SCSI Request Packet to make sure - they are valid for a SCSI Pass Thru request. - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: Packet - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { if (Packet == NULL) { return EFI_INVALID_PARAMETER; @@ -941,21 +898,20 @@ CheckSCSIRequestPacket ( return EFI_SUCCESS; } +/** + Checks the requested SCSI command: + Is it supported by this driver? + Is the Data transfer direction reasonable? + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo Packet - add argument and description to function comment +**/ BOOLEAN IsCommandValid ( EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet ) -/*++ - - Checks the requested SCSI command: - Is it supported by this driver? - Is the Data transfer direction reasonable? - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: Packet - add argument and description to function comment { UINT8 Index; UINT8 *OpCode; @@ -995,30 +951,25 @@ IsCommandValid ( return FALSE; } +/** + Performs blocking I/O request. + + @param AtapiScsiPrivate Private data structure for the specified channel. + @param Target The Target ID of the ATAPI device to send the SCSI + Request Packet. To ATAPI devices attached on an IDE + Channel, Target ID 0 indicates Master device;Target + ID 1 indicates Slave device. + @param Packet The SCSI Request Packet to send to the ATAPI device + specified by Target. + + @todo AtapiScsiPrivate - add argument and description to function comment +**/ EFI_STATUS SubmitBlockingIoCommand ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT32 Target, EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet ) -/*++ - -Routine Description: - Performs blocking I/O request. - - Arguments: - AtapiScsiPrivate: Private data structure for the specified channel. - Target: The Target ID of the ATAPI device to send the SCSI - Request Packet. To ATAPI devices attached on an IDE - Channel, Target ID 0 indicates Master device;Target - ID 1 indicates Slave device. - Packet: The SCSI Request Packet to send to the ATAPI device - specified by Target. - - Returns: - ---*/ -// TODO: AtapiScsiPrivate - add argument and description to function comment { UINT8 PacketCommand[12]; UINT64 TimeoutInMicroSeconds; @@ -1079,6 +1030,23 @@ Routine Description: return PacketCommandStatus; } +/** + RequestSenseCommand + + @param AtapiScsiPrivate + @param Target + @param Timeout + @param SenseData + @param SenseDataLength + + @todo Add function description + @todo AtapiScsiPrivate TODO: add argument description + @todo Target TODO: add argument description + @todo Timeout TODO: add argument description + @todo SenseData TODO: add argument description + @todo SenseDataLength TODO: add argument description + @todo add return values +**/ EFI_STATUS RequestSenseCommand ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, @@ -1087,25 +1055,6 @@ RequestSenseCommand ( VOID *SenseData, UINT8 *SenseDataLength ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AtapiScsiPrivate - TODO: add argument description - Target - TODO: add argument description - Timeout - TODO: add argument description - SenseData - TODO: add argument description - SenseDataLength - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET Packet; UINT8 Cdb[12]; @@ -1130,6 +1079,37 @@ Returns: return Status; } +/** + Submits ATAPI command packet to the specified ATAPI device. + + @param AtapiScsiPrivate: Private data structure for the specified channel. + @param Target: The Target ID of the ATAPI device to send the SCSI + Request Packet. To ATAPI devices attached on an IDE + Channel, Target ID 0 indicates Master device;Target + ID 1 indicates Slave device. + @param PacketCommand: Points to the ATAPI command packet. + @param Buffer: Points to the transferred data. + @param ByteCount: When input,indicates the buffer size; when output, + indicates the actually transferred data size. + @param Direction: Indicates the data transfer direction. + @param TimeoutInMicroSeconds: The timeout, in micro second units, + to use for the execution of this ATAPI command. + A TimeoutInMicroSeconds value of 0 means that + this function will wait indefinitely for the ATAPI + command to execute. +

+ If TimeoutInMicroSeconds is greater than zero, then + this function will return EFI_TIMEOUT if the time + required to execute the ATAPI command is greater + than TimeoutInMicroSeconds. +

+ + @todo AtapiScsiPrivate - add argument and description to function comment + @todo PacketCommand - add argument and description to function comment + @todo Buffer - add argument and description to function comment + @todo ByteCount - add argument and description to function comment + @todo Direction - add argument and description to function comment +**/ EFI_STATUS AtapiPacketCommand ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, @@ -1140,42 +1120,6 @@ AtapiPacketCommand ( DATA_DIRECTION Direction, UINT64 TimeoutInMicroSeconds ) -/*++ - - Routine Description: - Submits ATAPI command packet to the specified ATAPI device. - - Arguments: - AtapiScsiPrivate: Private data structure for the specified channel. - Target: The Target ID of the ATAPI device to send the SCSI - Request Packet. To ATAPI devices attached on an IDE - Channel, Target ID 0 indicates Master device;Target - ID 1 indicates Slave device. - PacketCommand: Points to the ATAPI command packet. - Buffer: Points to the transferred data. - ByteCount: When input,indicates the buffer size; when output, - indicates the actually transferred data size. - Direction: Indicates the data transfer direction. - TimeoutInMicroSeconds: - The timeout, in micro second units, to use for the - execution of this ATAPI command. - A TimeoutInMicroSeconds value of 0 means that - this function will wait indefinitely for the ATAPI - command to execute. - If TimeoutInMicroSeconds is greater than zero, then - this function will return EFI_TIMEOUT if the time - required to execute the ATAPI command is greater - than TimeoutInMicroSeconds. - - Returns: - - ---*/ -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: PacketCommand - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: Direction - add argument and description to function comment { UINT16 *CommandIndex; @@ -1285,6 +1229,35 @@ AtapiPacketCommand ( ); } +/** + Performs data transfer between ATAPI device and host after the + ATAPI command packet is sent. + + @param AtapiScsiPrivate: Private data structure for the specified channel. + @param Buffer: Points to the transferred data. + @param ByteCount: When input,indicates the buffer size; when output, + indicates the actually transferred data size. + @param Direction: Indicates the data transfer direction. + @param TimeoutInMicroSeconds: The timeout, in micro second units, + to use for the execution of this ATAPI command. + A TimeoutInMicroSeconds value of 0 means that + this function will wait indefinitely for the ATAPI + command to execute. +

+ If TimeoutInMicroSeconds is greater than zero, then + this function will return EFI_TIMEOUT if the time + required to execute the ATAPI command is greater + than TimeoutInMicroSeconds. +

+ + @todo AtapiScsiPrivate - add argument and description to function comment + @todo Buffer - add argument and description to function comment + @todo ByteCount - add argument and description to function comment + @todo Direction - add argument and description to function comment + @todo EFI_DEVICE_ERROR - add return value to function comment + @todo EFI_DEVICE_ERROR - add return value to function comment + @todo EFI_WARN_BUFFER_TOO_SMALL - add return value to function comment +**/ EFI_STATUS AtapiPassThruPioReadWriteData ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, @@ -1293,40 +1266,6 @@ AtapiPassThruPioReadWriteData ( DATA_DIRECTION Direction, UINT64 TimeoutInMicroSeconds ) -/*++ - - Routine Description: - Performs data transfer between ATAPI device and host after the - ATAPI command packet is sent. - - Arguments: - AtapiScsiPrivate: Private data structure for the specified channel. - Buffer: Points to the transferred data. - ByteCount: When input,indicates the buffer size; when output, - indicates the actually transferred data size. - Direction: Indicates the data transfer direction. - TimeoutInMicroSeconds: - The timeout, in micro second units, to use for the - execution of this ATAPI command. - A TimeoutInMicroSeconds value of 0 means that - this function will wait indefinitely for the ATAPI - command to execute. - If TimeoutInMicroSeconds is greater than zero, then - this function will return EFI_TIMEOUT if the time - required to execute the ATAPI command is greater - than TimeoutInMicroSeconds. - - Returns: - - ---*/ -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: Direction - add argument and description to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_WARN_BUFFER_TOO_SMALL - add return value to function comment { UINT32 Index; UINT32 RequiredWordCount; @@ -1420,19 +1359,20 @@ AtapiPassThruPioReadWriteData ( } +/** + Read one byte from a specified I/O port. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo PciIo - add argument and description to function comment + @todo Port - add argument and description to function comment +**/ UINT8 ReadPortB ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port ) -/*++ - Read one byte from a specified I/O port. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: PciIo - add argument and description to function comment -// TODO: Port - add argument and description to function comment { UINT8 Data; @@ -1449,19 +1389,20 @@ ReadPortB ( } +/** + Read one word from a specified I/O port. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo PciIo - add argument and description to function comment + @todo Port - add argument and description to function comment +**/ UINT16 ReadPortW ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port ) -/*++ - Read one word from a specified I/O port. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: PciIo - add argument and description to function comment -// TODO: Port - add argument and description to function comment { UINT16 Data; @@ -1478,21 +1419,22 @@ ReadPortW ( } +/** + Write one byte to a specified I/O port. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo PciIo - add argument and description to function comment + @todo Port - add argument and description to function comment + @todo Data - add argument and description to function comment +**/ VOID WritePortB ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port, IN UINT8 Data ) -/*++ - Write one byte to a specified I/O port. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: PciIo - add argument and description to function comment -// TODO: Port - add argument and description to function comment -// TODO: Data - add argument and description to function comment { PciIo->Io.Write ( @@ -1507,21 +1449,22 @@ WritePortB ( } +/** + Write one word to a specified I/O port. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo PciIo - add argument and description to function comment + @todo Port - add argument and description to function comment + @todo Data - add argument and description to function comment +**/ VOID WritePortW ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port, IN UINT16 Data ) -/*++ - Write one word to a specified I/O port. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: PciIo - add argument and description to function comment -// TODO: Port - add argument and description to function comment -// TODO: Data - add argument and description to function comment { PciIo->Io.Write ( @@ -1534,25 +1477,26 @@ WritePortW ( ); } +/** + Check whether DRQ is clear in the Status Register. (BSY must also be cleared) + If TimeoutInMicroSeconds is zero, this routine should wait infinitely for + DRQ clear. Otherwise, it will return EFI_TIMEOUT when specified time is + elapsed. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo TimeoutInMicroSeconds - add argument and description to function comment + @todo EFI_ABORTED - add return value to function comment + @todo EFI_TIMEOUT - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS StatusDRQClear ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeoutInMicroSeconds ) -/*++ - Check whether DRQ is clear in the Status Register. (BSY must also be cleared) - If TimeoutInMicroSeconds is zero, this routine should wait infinitely for - DRQ clear. Otherwise, it will return EFI_TIMEOUT when specified time is - elapsed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: TimeoutInMicroSeconds - add argument and description to function comment -// TODO: EFI_ABORTED - add return value to function comment -// TODO: EFI_TIMEOUT - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 Delay; UINT8 StatusRegister; @@ -1613,26 +1557,27 @@ StatusDRQClear ( return EFI_SUCCESS; } -EFI_STATUS -AltStatusDRQClear ( - ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, - UINT64 TimeoutInMicroSeconds - ) -/*++ +/** Check whether DRQ is clear in the Alternate Status Register. (BSY must also be cleared). If TimeoutInMicroSeconds is zero, this routine should wait infinitely for DRQ clear. Otherwise, it will return EFI_TIMEOUT when specified time is elapsed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: TimeoutInMicroSeconds - add argument and description to function comment -// TODO: EFI_ABORTED - add return value to function comment -// TODO: EFI_TIMEOUT - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo TimeoutInMicroSeconds - add argument and description to function comment + @todo EFI_ABORTED - add return value to function comment + @todo EFI_TIMEOUT - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ +EFI_STATUS +AltStatusDRQClear ( + ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, + UINT64 TimeoutInMicroSeconds + ) { UINT64 Delay; UINT8 AltStatusRegister; @@ -1691,25 +1636,26 @@ AltStatusDRQClear ( return EFI_SUCCESS; } +/** + Check whether DRQ is ready in the Status Register. (BSY must also be cleared) + If TimeoutInMicroSeconds is zero, this routine should wait infinitely for + DRQ ready. Otherwise, it will return EFI_TIMEOUT when specified time is + elapsed. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo TimeoutInMicroSeconds - add argument and description to function comment + @todo EFI_ABORTED - add return value to function comment + @todo EFI_TIMEOUT - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS StatusDRQReady ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeoutInMicroSeconds ) -/*++ - Check whether DRQ is ready in the Status Register. (BSY must also be cleared) - If TimeoutInMicroSeconds is zero, this routine should wait infinitely for - DRQ ready. Otherwise, it will return EFI_TIMEOUT when specified time is - elapsed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: TimeoutInMicroSeconds - add argument and description to function comment -// TODO: EFI_ABORTED - add return value to function comment -// TODO: EFI_TIMEOUT - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 Delay; UINT8 StatusRegister; @@ -1770,26 +1716,27 @@ StatusDRQReady ( return EFI_SUCCESS; } -EFI_STATUS -AltStatusDRQReady ( - ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, - UINT64 TimeoutInMicroSeconds - ) -/*++ +/** Check whether DRQ is ready in the Alternate Status Register. (BSY must also be cleared) If TimeoutInMicroSeconds is zero, this routine should wait infinitely for DRQ ready. Otherwise, it will return EFI_TIMEOUT when specified time is elapsed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: TimeoutInMicroSeconds - add argument and description to function comment -// TODO: EFI_ABORTED - add return value to function comment -// TODO: EFI_TIMEOUT - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo TimeoutInMicroSeconds - add argument and description to function comment + @todo EFI_ABORTED - add return value to function comment + @todo EFI_TIMEOUT - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ +EFI_STATUS +AltStatusDRQReady ( + ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, + UINT64 TimeoutInMicroSeconds + ) { UINT64 Delay; UINT8 AltStatusRegister; @@ -1849,24 +1796,25 @@ AltStatusDRQReady ( return EFI_SUCCESS; } +/** + Check whether BSY is clear in the Status Register. + If TimeoutInMicroSeconds is zero, this routine should wait infinitely for + BSY clear. Otherwise, it will return EFI_TIMEOUT when specified time is + elapsed. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo TimeoutInMicroSeconds - add argument and description to function comment + @todo EFI_TIMEOUT - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS StatusWaitForBSYClear ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeoutInMicroSeconds ) -/*++ - Check whether BSY is clear in the Status Register. - If TimeoutInMicroSeconds is zero, this routine should wait infinitely for - BSY clear. Otherwise, it will return EFI_TIMEOUT when specified time is - elapsed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: TimeoutInMicroSeconds - add argument and description to function comment -// TODO: EFI_TIMEOUT - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 Delay; UINT8 StatusRegister; @@ -1909,24 +1857,25 @@ StatusWaitForBSYClear ( return EFI_SUCCESS; } +/** + Check whether BSY is clear in the Alternate Status Register. + If TimeoutInMicroSeconds is zero, this routine should wait infinitely for + BSY clear. Otherwise, it will return EFI_TIMEOUT when specified time is + elapsed. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo TimeoutInMicroSeconds - add argument and description to function comment + @todo EFI_TIMEOUT - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS AltStatusWaitForBSYClear ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeoutInMicroSeconds ) -/*++ - Check whether BSY is clear in the Alternate Status Register. - If TimeoutInMicroSeconds is zero, this routine should wait infinitely for - BSY clear. Otherwise, it will return EFI_TIMEOUT when specified time is - elapsed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: TimeoutInMicroSeconds - add argument and description to function comment -// TODO: EFI_TIMEOUT - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 Delay; UINT8 AltStatusRegister; @@ -1968,26 +1917,27 @@ AltStatusWaitForBSYClear ( return EFI_SUCCESS; } -EFI_STATUS -StatusDRDYReady ( - ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, - UINT64 TimeoutInMicroSeconds - ) -/*++ +/** Check whether DRDY is ready in the Status Register. (BSY must also be cleared) If TimeoutInMicroSeconds is zero, this routine should wait infinitely for DRDY ready. Otherwise, it will return EFI_TIMEOUT when specified time is elapsed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: TimeoutInMicroSeconds - add argument and description to function comment -// TODO: EFI_ABORTED - add return value to function comment -// TODO: EFI_TIMEOUT - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo TimeoutInMicroSeconds - add argument and description to function comment + @todo EFI_ABORTED - add return value to function comment + @todo EFI_TIMEOUT - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ +EFI_STATUS +StatusDRDYReady ( + ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, + UINT64 TimeoutInMicroSeconds + ) { UINT64 Delay; UINT8 StatusRegister; @@ -2043,26 +1993,27 @@ StatusDRDYReady ( return EFI_SUCCESS; } -EFI_STATUS -AltStatusDRDYReady ( - ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, - UINT64 TimeoutInMicroSeconds - ) -/*++ +/** Check whether DRDY is ready in the Alternate Status Register. (BSY must also be cleared) If TimeoutInMicroSeconds is zero, this routine should wait infinitely for DRDY ready. Otherwise, it will return EFI_TIMEOUT when specified time is elapsed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: TimeoutInMicroSeconds - add argument and description to function comment -// TODO: EFI_ABORTED - add return value to function comment -// TODO: EFI_TIMEOUT - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo TimeoutInMicroSeconds - add argument and description to function comment + @todo EFI_ABORTED - add return value to function comment + @todo EFI_TIMEOUT - add return value to function comment + @todo EFI_SUCCESS - add return value to function comment +**/ +EFI_STATUS +AltStatusDRDYReady ( + ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, + UINT64 TimeoutInMicroSeconds + ) { UINT64 Delay; UINT8 AltStatusRegister; @@ -2118,19 +2069,20 @@ AltStatusDRDYReady ( return EFI_SUCCESS; } +/** + Check Error Register for Error Information. + + @todo function comment is missing 'Routine Description:' + @todo function comment is missing 'Arguments:' + @todo function comment is missing 'Returns:' + @todo AtapiScsiPrivate - add argument and description to function comment + @todo EFI_SUCCESS - add return value to function comment + @todo EFI_DEVICE_ERROR - add return value to function comment +**/ EFI_STATUS AtapiPassThruCheckErrorStatus ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate ) -/*++ - Check Error Register for Error Information. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: function comment is missing 'Returns:' -// TODO: AtapiScsiPrivate - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment { UINT8 StatusRegister; diff --git a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h index d705c65949..659b37c876 100644 --- a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h +++ b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h @@ -1,23 +1,16 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: + Module Name: AtapiPassThru.h - AtapiPassThru.h - -Abstract: - - -Revision History ---*/ +**/ #ifndef _APT_H #define _APT_H @@ -25,12 +18,13 @@ Revision History #include -// -// bit definition -// +/// +/// bit definition +/// #define bit(a) 1 << (a) #define MAX_TARGET_ID 4 + // // IDE Registers // @@ -49,9 +43,9 @@ typedef union { UINT16 DeviceControl; /* when write */ } IDE_AltStatus_OR_DeviceControl; -// -// IDE registers set -// +/// +/// IDE registers set +/// typedef struct { UINT16 Data; IDE_ERROR_OR_FEATURE Reg1; @@ -167,21 +161,21 @@ typedef struct { // // ATA Err Reg bitmap // -#define BBK_ERR bit (7) /* Bad block detected */ -#define UNC_ERR bit (6) /* Uncorrectable Data */ -#define MC_ERR bit (5) /* Media Change */ -#define IDNF_ERR bit (4) /* ID Not Found */ -#define MCR_ERR bit (3) /* Media Change Requested */ -#define ABRT_ERR bit (2) /* Aborted Command */ -#define TK0NF_ERR bit (1) /* Track 0 Not Found */ -#define AMNF_ERR bit (0) /* Address Mark Not Found */ +#define BBK_ERR bit (7) ///< Bad block detected +#define UNC_ERR bit (6) ///< Uncorrectable Data +#define MC_ERR bit (5) ///< Media Change +#define IDNF_ERR bit (4) ///< ID Not Found +#define MCR_ERR bit (3) ///< Media Change Requested +#define ABRT_ERR bit (2) ///< Aborted Command +#define TK0NF_ERR bit (1) ///< Track 0 Not Found +#define AMNF_ERR bit (0) ///< Address Mark Not Found // // ATAPI Err Reg bitmap // #define SENSE_KEY_ERR (bit (7) | bit (6) | bit (5) | bit (4)) -#define EOM_ERR bit (1) /* End of Media Detected */ -#define ILI_ERR bit (0) /* Illegal Length Indication */ +#define EOM_ERR bit (1) ///< End of Media Detected +#define ILI_ERR bit (0) ///< Illegal Length Indication // // Device/Head Reg @@ -201,21 +195,21 @@ typedef struct { // // Status Reg // -#define BSY bit (7) /* Controller Busy */ -#define DRDY bit (6) /* Drive Ready */ -#define DWF bit (5) /* Drive Write Fault */ -#define DSC bit (4) /* Disk Seek Complete */ -#define DRQ bit (3) /* Data Request */ -#define CORR bit (2) /* Corrected Data */ -#define IDX bit (1) /* Index */ -#define ERR bit (0) /* Error */ -#define CHECK bit (0) /* Check bit for ATAPI Status Reg */ +#define BSY bit (7) ///< Controller Busy +#define DRDY bit (6) ///< Drive Ready +#define DWF bit (5) ///< Drive Write Fault +#define DSC bit (4) ///< Disk Seek Complete +#define DRQ bit (3) ///< Data Request +#define CORR bit (2) ///< Corrected Data +#define IDX bit (1) ///< Index +#define ERR bit (0) ///< Error +#define CHECK bit (0) ///< Check bit for ATAPI Status Reg // // Device Control Reg // -#define SRST bit (2) /* Software Reset */ -#define IEN_L bit (1) /* Interrupt Enable #*/ +#define SRST bit (2) ///< Software Reset +#define IEN_L bit (1) ///< Interrupt Enable // // ATAPI Feature Register @@ -242,55 +236,63 @@ typedef struct { // // function prototype // +/** + AtapiScsiPassThruDriverEntryPoint + + @param ImageHandle + @param SystemTable + + @todo Add function description + @todo ImageHandle - add argument description + @todo SystemTable - add argument description + @todo add return values +--*/ EFI_STATUS EFIAPI AtapiScsiPassThruDriverEntryPoint ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) - /*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - ImageHandle - TODO: add argument description - SystemTable - TODO: add argument description - -Returns: +; - TODO: add return values +/** + RegisterAtapiScsiPassThru ---*/ -; + @param This + @param Controller + @param PciIo + @todo Add function description + @todo This add argument description + @todo Controller add argument description + @todo PciIo add argument description + @todo add return values +**/ EFI_STATUS RegisterAtapiScsiPassThru ( IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_HANDLE Controller, IN EFI_PCI_IO_PROTOCOL *PciIo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Controller - TODO: add argument description - PciIo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ ; +/** + AtapiScsiPassThruFunction + + @param This + @param Target + @param Lun + @param Packet + @param Event + + @todo Add function description + @todo This - add argument description + @todo Target - add argument description + @todo Lun - add argument description + @todo Packet - add argument description + @todo Event - add argument description + @todo add return values +**/ EFI_STATUS EFIAPI AtapiScsiPassThruFunction ( @@ -300,27 +302,20 @@ AtapiScsiPassThruFunction ( IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet, IN EFI_EVENT Event OPTIONAL ) -/*++ +; -Routine Description: +/** + AtapiScsiPassThruGetNextDevice TODO: Add function description -Arguments: - - This - TODO: add argument description - Target - TODO: add argument description - Lun - TODO: add argument description - Packet - TODO: add argument description - Event - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Target TODO: add argument description + @param Lun TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI AtapiScsiPassThruGetNextDevice ( @@ -328,25 +323,21 @@ AtapiScsiPassThruGetNextDevice ( IN OUT UINT32 *Target, IN OUT UINT64 *Lun ) -/*++ +; -Routine Description: +/** + AtapiScsiPassThruBuildDevicePath TODO: Add function description -Arguments: - - This - TODO: add argument description - Target - TODO: add argument description - Lun - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Target TODO: add argument description + @param Lun TODO: add argument description + @param DevicePath TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI AtapiScsiPassThruBuildDevicePath ( @@ -355,26 +346,21 @@ AtapiScsiPassThruBuildDevicePath ( IN UINT64 Lun, IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath ) -/*++ +; -Routine Description: +/** + AtapiScsiPassThruGetTargetLun TODO: Add function description -Arguments: - - This - TODO: add argument description - Target - TODO: add argument description - Lun - TODO: add argument description - DevicePath - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param DevicePath TODO: add argument description + @param Target TODO: add argument description + @param Lun TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI AtapiScsiPassThruGetTargetLun ( @@ -383,48 +369,37 @@ AtapiScsiPassThruGetTargetLun ( OUT UINT32 *Target, OUT UINT64 *Lun ) -/*++ +; -Routine Description: +/** + AtapiScsiPassThruResetChannel TODO: Add function description -Arguments: - - This - TODO: add argument description - DevicePath - TODO: add argument description - Target - TODO: add argument description - Lun - TODO: add argument description - -Returns: + @param This TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI AtapiScsiPassThruResetChannel ( IN EFI_SCSI_PASS_THRU_PROTOCOL *This ) -/*++ +; -Routine Description: +/** + AtapiScsiPassThruResetTarget TODO: Add function description -Arguments: - - This - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Target TODO: add argument description + @param Lun TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI AtapiScsiPassThruResetTarget ( @@ -432,92 +407,74 @@ AtapiScsiPassThruResetTarget ( IN UINT32 Target, IN UINT64 Lun ) -/*++ +; -Routine Description: +/** + CheckSCSIRequestPacket TODO: Add function description -Arguments: - - This - TODO: add argument description - Target - TODO: add argument description - Lun - TODO: add argument description - -Returns: + @param Packet TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS CheckSCSIRequestPacket ( EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet ) -/*++ +; -Routine Description: +/** + SubmitBlockingIoCommand TODO: Add function description -Arguments: - - Packet - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param Target TODO: add argument description + @param Packet TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS SubmitBlockingIoCommand ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT32 Target, EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet ) -/*++ +; -Routine Description: +/** + IsCommandValid TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - Target - TODO: add argument description - Packet - TODO: add argument description + @param Packet - TODO: add argument description -Returns: - - TODO: add return values + @return TODO: add return values --*/ -; - BOOLEAN IsCommandValid ( EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet ) - /*++ +; -Routine Description: +/** + RequestSenseCommand TODO: Add function description -Arguments: - - Packet - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param Target TODO: add argument description + @param Timeout TODO: add argument description + @param SenseData TODO: add argument description + @param SenseDataLength TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS RequestSenseCommand ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, @@ -526,27 +483,24 @@ RequestSenseCommand ( VOID *SenseData, UINT8 *SenseDataLength ) -/*++ +; -Routine Description: +/** + AtapiPacketCommand TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - Target - TODO: add argument description - Timeout - TODO: add argument description - SenseData - TODO: add argument description - SenseDataLength - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param Target TODO: add argument description + @param PacketCommand TODO: add argument description + @param Buffer TODO: add argument description + @param ByteCount TODO: add argument description + @param Direction TODO: add argument description + @param TimeOutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtapiPacketCommand ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, @@ -557,313 +511,236 @@ AtapiPacketCommand ( DATA_DIRECTION Direction, UINT64 TimeOutInMicroSeconds ) -/*++ - -Routine Description: +; - TODO: Add function description -Arguments: +/** + ReadPortB - AtapiScsiPrivate - TODO: add argument description - Target - TODO: add argument description - PacketCommand - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - Direction - TODO: add argument description - TimeOutInMicroSeconds - TODO: add argument description + TODO: Add function description -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description TODO: add return values ---*/ -; - - +**/ UINT8 ReadPortB ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port ) -/*++ - -Routine Description: +; - TODO: Add function description -Arguments: +/** + ReadPortW - PciIo - TODO: add argument description - Port - TODO: add argument description + TODO: Add function description -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description TODO: add return values ---*/ -; - - +**/ UINT16 ReadPortW ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port ) -/*++ - -Routine Description: +; - TODO: Add function description -Arguments: +/** + WritePortB - PciIo - TODO: add argument description - Port - TODO: add argument description + TODO: Add function description -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description + @param Data TODO: add argument description TODO: add return values ---*/ -; - - +**/ VOID WritePortB ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port, IN UINT8 Data ) -/*++ - -Routine Description: +; - TODO: Add function description -Arguments: +/** + WritePortW - PciIo - TODO: add argument description - Port - TODO: add argument description - Data - TODO: add argument description + TODO: Add function description -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description + @param Data TODO: add argument description TODO: add return values ---*/ -; - - +**/ VOID WritePortW ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port, IN UINT16 Data ) -/*++ +; -Routine Description: +/** + StatusDRQClear TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - Data - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param TimeOutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS StatusDRQClear ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeOutInMicroSeconds ) -/*++ +; -Routine Description: +/** + AltStatusDRQClear TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - TimeOutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param TimeOutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AltStatusDRQClear ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeOutInMicroSeconds ) -/*++ +; -Routine Description: +/** + StatusDRQReady TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - TimeOutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param TimeOutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS StatusDRQReady ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeOutInMicroSeconds ) -/*++ +; -Routine Description: +/** + AltStatusDRQReady TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - TimeOutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param TimeOutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AltStatusDRQReady ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeOutInMicroSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - TimeOutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param TimeoutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS StatusWaitForBSYClear ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeoutInMicroSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - TimeoutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param TimeoutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AltStatusWaitForBSYClear ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeoutInMicroSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - TimeoutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param TimeoutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS StatusDRDYReady ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeoutInMicroSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - TimeoutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param TimeoutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AltStatusDRDYReady ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, UINT64 TimeoutInMicroSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - TimeoutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description + @param Buffer TODO: add argument description + @param ByteCount TODO: add argument description + @param Direction TODO: add argument description + @param TimeOutInMicroSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtapiPassThruPioReadWriteData ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate, @@ -872,45 +749,19 @@ AtapiPassThruPioReadWriteData ( DATA_DIRECTION Direction, UINT64 TimeOutInMicroSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - AtapiScsiPrivate - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - Direction - TODO: add argument description - TimeOutInMicroSeconds - TODO: add argument description - -Returns: + @param AtapiScsiPrivate TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtapiPassThruCheckErrorStatus ( ATAPI_SCSI_PASS_THRU_DEV *AtapiScsiPrivate ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AtapiScsiPrivate - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ ; #endif diff --git a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c index 14658b0ace..b0b2231705 100644 --- a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c +++ b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c @@ -1,21 +1,16 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: + Module Name: ComponentName.c - ComponentName.c - -Abstract: - ---*/ +**/ #include "AtapiPassThru.h" // @@ -39,9 +34,9 @@ AtapiScsiPassThruComponentNameGetControllerName ( OUT CHAR16 **ControllerName ); -// -// EFI Component Name Protocol -// +/// +/// EFI Component Name Protocol +/// EFI_COMPONENT_NAME_PROTOCOL gAtapiScsiPassThruComponentName = { AtapiScsiPassThruComponentNameGetDriverName, AtapiScsiPassThruComponentNameGetControllerName, @@ -53,6 +48,28 @@ static EFI_UNICODE_STRING_TABLE mAtapiScsiPassThruDriverNameTable[] = { { NULL , NULL } }; +/** + Retrieves a Unicode string that is the user readable name of the EFI Driver. + + @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. + @param Language A pointer to a three character ISO 639-2 language identifier. + This is the language of the driver name that that the caller + is requesting, and it must match one of the languages specified + in SupportedLanguages. The number of languages supported by a + driver is up to the driver writer. + @param DriverName A pointer to the Unicode string to return. This Unicode string + is the name of the driver specified by This in the language + specified by Language. + + @retval EFI_SUCCESS The Unicode string for the Driver specified by This + and the language specified by Language was returned + in DriverName. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER DriverName is NULL. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + language specified by Language. + +**/ EFI_STATUS EFIAPI AtapiScsiPassThruComponentNameGetDriverName ( @@ -60,32 +77,6 @@ AtapiScsiPassThruComponentNameGetDriverName ( IN CHAR8 *Language, OUT CHAR16 **DriverName ) -/*++ - - Routine Description: - Retrieves a Unicode string that is the user readable name of the EFI Driver. - - Arguments: - This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. - Language - A pointer to a three character ISO 639-2 language identifier. - This is the language of the driver name that that the caller - is requesting, and it must match one of the languages specified - in SupportedLanguages. The number of languages supported by a - driver is up to the driver writer. - DriverName - A pointer to the Unicode string to return. This Unicode string - is the name of the driver specified by This in the language - specified by Language. - - Returns: - EFI_SUCCESS - The Unicode string for the Driver specified by This - and the language specified by Language was returned - in DriverName. - EFI_INVALID_PARAMETER - Language is NULL. - EFI_INVALID_PARAMETER - DriverName is NULL. - EFI_UNSUPPORTED - The driver specified by This does not support the - language specified by Language. - ---*/ { return LookupUnicodeString ( Language, @@ -95,6 +86,47 @@ AtapiScsiPassThruComponentNameGetDriverName ( ); } +/** + Retrieves a Unicode string that is the user readable name of the controller + that is being managed by an EFI Driver. + + @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. + @param ControllerHandle The handle of a controller that the driver specified by + This is managing. This handle specifies the controller + whose name is to be returned. + @param ChildHandle The handle of the child controller to retrieve the name + of. This is an optional parameter that may be NULL. It + will be NULL for device drivers. It will also be NULL + for a bus drivers that wish to retrieve the name of the + bus controller. It will not be NULL for a bus driver + that wishes to retrieve the name of a child controller. + @param Language A pointer to a three character ISO 639-2 language + identifier. This is the language of the controller name + that that the caller is requesting, and it must match one + of the languages specified in SupportedLanguages. The + number of languages supported by a driver is up to the + driver writer. + @param ControllerName A pointer to the Unicode string to return. This Unicode + string is the name of the controller specified by + ControllerHandle and ChildHandle in the language + specified by Language from the point of view of the + driver specified by This. + + @retval EFI_SUCCESS The Unicode string for the user readable name in the + language specified by Language for the driver + specified by This was returned in DriverName. + @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid + EFI_HANDLE. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER ControllerName is NULL. + @retval EFI_UNSUPPORTED The driver specified by This is not currently + managing the controller specified by + ControllerHandle and ChildHandle. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + language specified by Language. + +**/ EFI_STATUS EFIAPI AtapiScsiPassThruComponentNameGetControllerName ( @@ -104,51 +136,6 @@ AtapiScsiPassThruComponentNameGetControllerName ( IN CHAR8 *Language, OUT CHAR16 **ControllerName ) -/*++ - - Routine Description: - Retrieves a Unicode string that is the user readable name of the controller - that is being managed by an EFI Driver. - - Arguments: - This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. - ControllerHandle - The handle of a controller that the driver specified by - This is managing. This handle specifies the controller - whose name is to be returned. - ChildHandle - The handle of the child controller to retrieve the name - of. This is an optional parameter that may be NULL. It - will be NULL for device drivers. It will also be NULL - for a bus drivers that wish to retrieve the name of the - bus controller. It will not be NULL for a bus driver - that wishes to retrieve the name of a child controller. - Language - A pointer to a three character ISO 639-2 language - identifier. This is the language of the controller name - that that the caller is requesting, and it must match one - of the languages specified in SupportedLanguages. The - number of languages supported by a driver is up to the - driver writer. - ControllerName - A pointer to the Unicode string to return. This Unicode - string is the name of the controller specified by - ControllerHandle and ChildHandle in the language - specified by Language from the point of view of the - driver specified by This. - - Returns: - EFI_SUCCESS - The Unicode string for the user readable name in the - language specified by Language for the driver - specified by This was returned in DriverName. - EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid - EFI_HANDLE. - EFI_INVALID_PARAMETER - Language is NULL. - EFI_INVALID_PARAMETER - ControllerName is NULL. - EFI_UNSUPPORTED - The driver specified by This is not currently - managing the controller specified by - ControllerHandle and ChildHandle. - EFI_UNSUPPORTED - The driver specified by This does not support the - language specified by Language. - ---*/ { return EFI_UNSUPPORTED; } diff --git a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c index 91d6accd99..68c483071c 100644 --- a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c +++ b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c @@ -1,20 +1,4 @@ -/*++ - -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - CirrusLogic5430.c - -Abstract: - +/** @file Cirrus Logic 5430 Controller Driver. This driver is a sample implementation of the UGA Draw Protocol for the Cirrus Logic 5430 family of PCI video controllers. This driver is only @@ -25,9 +9,16 @@ Abstract: documentation on UGA for details on how to write a UGA driver that is able to function both in the EFI pre-boot environment and from the OS runtime. -Revision History: + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. ---*/ +**/ // // Cirrus Logic 5430 Controller Driver @@ -44,6 +35,13 @@ EFI_DRIVER_BINDING_PROTOCOL gCirrusLogic5430DriverBinding = { NULL }; +/** + CirrusLogic5430ControllerDriverSupported + + TODO: This - add argument and description to function comment + TODO: Controller - add argument and description to function comment + TODO: RemainingDevicePath - add argument and description to function comment +**/ EFI_STATUS EFIAPI CirrusLogic5430ControllerDriverSupported ( @@ -51,20 +49,6 @@ CirrusLogic5430ControllerDriverSupported ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: - -Arguments: - -Returns: - - None - ---*/ -// TODO: This - add argument and description to function comment -// TODO: Controller - add argument and description to function comment -// TODO: RemainingDevicePath - add argument and description to function comment { EFI_STATUS Status; EFI_PCI_IO_PROTOCOL *PciIo; @@ -139,6 +123,13 @@ Done: return Status; } +/** + CirrusLogic5430ControllerDriverStart + + TODO: This - add argument and description to function comment + TODO: Controller - add argument and description to function comment + TODO: RemainingDevicePath - add argument and description to function comment +**/ EFI_STATUS EFIAPI CirrusLogic5430ControllerDriverStart ( @@ -146,20 +137,6 @@ CirrusLogic5430ControllerDriverStart ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: - -Arguments: - -Returns: - - None - ---*/ -// TODO: This - add argument and description to function comment -// TODO: Controller - add argument and description to function comment -// TODO: RemainingDevicePath - add argument and description to function comment { EFI_STATUS Status; CIRRUS_LOGIC_5430_PRIVATE_DATA *Private; @@ -253,6 +230,15 @@ Error: return Status; } +/** + CirrusLogic5430ControllerDriverStop + + TODO: This - add argument and description to function comment + TODO: Controller - add argument and description to function comment + TODO: NumberOfChildren - add argument and description to function comment + TODO: ChildHandleBuffer - add argument and description to function comment + TODO: EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS EFIAPI CirrusLogic5430ControllerDriverStop ( @@ -261,22 +247,6 @@ CirrusLogic5430ControllerDriverStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/*++ - -Routine Description: - -Arguments: - -Returns: - - None - ---*/ -// TODO: This - add argument and description to function comment -// TODO: Controller - add argument and description to function comment -// TODO: NumberOfChildren - add argument and description to function comment -// TODO: ChildHandleBuffer - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_UGA_DRAW_PROTOCOL *UgaDraw; EFI_STATUS Status; diff --git a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h index 79ca7e0293..b1984c8865 100644 --- a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h +++ b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h @@ -1,25 +1,16 @@ -/*++ - -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - CirrusLogic5430.h - -Abstract: - +/** @file Cirrus Logic 5430 Controller Driver -Revision History + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php ---*/ + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ // // Cirrus Logic 5430 Controller Driver @@ -99,78 +90,67 @@ extern EFI_COMPONENT_NAME_PROTOCOL gCirrusLogic5430ComponentName; // // UGA Draw Hardware abstraction internal worker functions // +/** + TODO: Add function description + + @param Private TODO: add argument description + + TODO: add return values + +**/ EFI_STATUS CirrusLogic5430UgaDrawConstructor ( CIRRUS_LOGIC_5430_PRIVATE_DATA *Private ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - Private - TODO: add argument description - -Returns: + @param Private TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS CirrusLogic5430UgaDrawDestructor ( CIRRUS_LOGIC_5430_PRIVATE_DATA *Private ) -/*++ - -Routine Description: +; +// +// EFI 1.1 driver model prototypes for Cirrus Logic 5430 UGA Draw +// +/** TODO: Add function description -Arguments: - - Private - TODO: add argument description - -Returns: + @param ImageHandle TODO: add argument description + @param SystemTable TODO: add argument description TODO: add return values ---*/ -; - -// -// EFI 1.1 driver model prototypes for Cirrus Logic 5430 UGA Draw -// +**/ EFI_STATUS EFIAPI CirrusLogic5430DriverEntryPoint ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) -/*++ - -Routine Description: +; +// +// EFI_DRIVER_BINDING_PROTOCOL Protocol Interface +// +/** TODO: Add function description -Arguments: - - ImageHandle - TODO: add argument description - SystemTable - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Controller TODO: add argument description + @param RemainingDevicePath TODO: add argument description TODO: add return values ---*/ -; - -// -// EFI_DRIVER_BINDING_PROTOCOL Protocol Interface -// +**/ EFI_STATUS EFIAPI CirrusLogic5430ControllerDriverSupported ( @@ -178,25 +158,18 @@ CirrusLogic5430ControllerDriverSupported ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - Controller - TODO: add argument description - RemainingDevicePath - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Controller TODO: add argument description + @param RemainingDevicePath TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI CirrusLogic5430ControllerDriverStart ( @@ -204,25 +177,19 @@ CirrusLogic5430ControllerDriverStart ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - Controller - TODO: add argument description - RemainingDevicePath - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Controller TODO: add argument description + @param NumberOfChildren TODO: add argument description + @param ChildHandleBuffer TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI CirrusLogic5430ControllerDriverStop ( @@ -231,24 +198,6 @@ CirrusLogic5430ControllerDriverStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Controller - TODO: add argument description - NumberOfChildren - TODO: add argument description - ChildHandleBuffer - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ ; #endif diff --git a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c index c33918b675..60e0582cf0 100644 --- a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c +++ b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c @@ -1,31 +1,24 @@ -/*++ - -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - CirrusLogic5430UgaDraw.c - -Abstract: - +/** @file This file produces the graphics abstration of UGA Draw. It is called by CirrusLogic5430.c file which deals with the EFI 1.1 driver model. This file just does graphics. ---*/ + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ #include "CirrusLogic5430.h" -// -// Video Mode structure -// +/// +/// Video Mode structure +/// typedef struct { UINT32 Width; UINT32 Height; @@ -36,18 +29,18 @@ typedef struct { UINT8 MiscSetting; } CIRRUS_LOGIC_5430_VIDEO_MODES; -// -// Generic Attribute Controller Register Settings -// +/// +/// Generic Attribute Controller Register Settings +/// static UINT8 AttributeController[21] = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x41, 0x00, 0x0F, 0x00, 0x00 }; -// -// Generic Graphics Controller Register Settings -// +/// +/// Generic Graphics Controller Register Settings +/// static UINT8 GraphicsController[9] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x05, 0x0F, 0xFF }; @@ -97,9 +90,9 @@ static UINT16 Seq_1024_768_256_60[15] = { 0x5b0c, 0x450d, 0x760e, 0x2b1b, 0x2f1c, 0x301d, 0x341e }; -// -// Table of supported video modes -// +/// +/// Table of supported video modes +/// static CIRRUS_LOGIC_5430_VIDEO_MODES CirrusLogic5430VideoModes[] = { { 640, 480, 8, 60, Crtc_640_480_256_60, Seq_640_480_256_60, 0xe3 }, { 800, 600, 8, 60, Crtc_800_600_256_60, Seq_800_600_256_60, 0xef }, @@ -169,6 +162,20 @@ inw ( // // UGA Draw Protocol Member Functions // +/** + TODO: Add function description + + @param This TODO: add argument description + @param HorizontalResolution TODO: add argument description + @param VerticalResolution TODO: add argument description + @param ColorDepth TODO: add argument description + @param RefreshRate TODO: add argument description + + @retval EFI_NOT_STARTED TODO: Add description for return value + @retval EFI_INVALID_PARAMETER TODO: Add description for return value + @retval EFI_SUCCESS TODO: Add description for return value + +**/ EFI_STATUS EFIAPI CirrusLogic5430UgaDrawGetMode ( @@ -178,27 +185,6 @@ CirrusLogic5430UgaDrawGetMode ( OUT UINT32 *ColorDepth, OUT UINT32 *RefreshRate ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - HorizontalResolution - TODO: add argument description - VerticalResolution - TODO: add argument description - ColorDepth - TODO: add argument description - RefreshRate - TODO: add argument description - -Returns: - - EFI_NOT_STARTED - TODO: Add description for return value - EFI_INVALID_PARAMETER - TODO: Add description for return value - EFI_SUCCESS - TODO: Add description for return value - ---*/ { CIRRUS_LOGIC_5430_PRIVATE_DATA *Private; @@ -223,6 +209,20 @@ Returns: return EFI_SUCCESS; } +/** + TODO: Add function description + + @param This TODO: add argument description + @param HorizontalResolution TODO: add argument description + @param VerticalResolution TODO: add argument description + @param ColorDepth TODO: add argument description + @param RefreshRate TODO: add argument description + + @retval EFI_OUT_OF_RESOURCES TODO: Add description for return value + @retval EFI_SUCCESS TODO: Add description for return value + @retval EFI_NOT_FOUND TODO: Add description for return value + +**/ EFI_STATUS EFIAPI CirrusLogic5430UgaDrawSetMode ( @@ -232,27 +232,6 @@ CirrusLogic5430UgaDrawSetMode ( IN UINT32 ColorDepth, IN UINT32 RefreshRate ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - HorizontalResolution - TODO: add argument description - VerticalResolution - TODO: add argument description - ColorDepth - TODO: add argument description - RefreshRate - TODO: add argument description - -Returns: - - EFI_OUT_OF_RESOURCES - TODO: Add description for return value - EFI_SUCCESS - TODO: Add description for return value - EFI_NOT_FOUND - TODO: Add description for return value - ---*/ { CIRRUS_LOGIC_5430_PRIVATE_DATA *Private; UINTN Index; @@ -299,6 +278,29 @@ Returns: return EFI_NOT_FOUND; } +/** + TODO: Add function description + + @param This TODO: add argument description + @param BltBuffer TODO: add argument description + @param BltOperation TODO: add argument description + @param SourceX TODO: add argument description + @param SourceY TODO: add argument description + @param DestinationX TODO: add argument description + @param DestinationY TODO: add argument description + @param Width TODO: add argument description + @param Height TODO: add argument description + @param Delta TODO: add argument description + + @retval EFI_INVALID_PARAMETER TODO: Add description for return value + @retval EFI_INVALID_PARAMETER TODO: Add description for return value + @retval EFI_INVALID_PARAMETER TODO: Add description for return value + @retval EFI_INVALID_PARAMETER TODO: Add description for return value + @retval EFI_INVALID_PARAMETER TODO: Add description for return value + @retval EFI_INVALID_PARAMETER TODO: Add description for return value + @retval EFI_SUCCESS TODO: Add description for return value + +**/ EFI_STATUS EFIAPI CirrusLogic5430UgaDrawBlt ( @@ -313,36 +315,6 @@ CirrusLogic5430UgaDrawBlt ( IN UINTN Height, IN UINTN Delta ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - BltBuffer - TODO: add argument description - BltOperation - TODO: add argument description - SourceX - TODO: add argument description - SourceY - TODO: add argument description - DestinationX - TODO: add argument description - DestinationY - TODO: add argument description - Width - TODO: add argument description - Height - TODO: add argument description - Delta - TODO: add argument description - -Returns: - - EFI_INVALID_PARAMETER - TODO: Add description for return value - EFI_INVALID_PARAMETER - TODO: Add description for return value - EFI_INVALID_PARAMETER - TODO: Add description for return value - EFI_INVALID_PARAMETER - TODO: Add description for return value - EFI_INVALID_PARAMETER - TODO: Add description for return value - EFI_INVALID_PARAMETER - TODO: Add description for return value - EFI_SUCCESS - TODO: Add description for return value - ---*/ { CIRRUS_LOGIC_5430_PRIVATE_DATA *Private; EFI_TPL OriginalTPL; @@ -597,23 +569,16 @@ Returns: // Construction and Destruction functions // +/** + CirrusLogic5430UgaDrawConstructor + + TODO: Private - add argument and description to function comment + TODO: EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS CirrusLogic5430UgaDrawConstructor ( CIRRUS_LOGIC_5430_PRIVATE_DATA *Private ) -/*++ - -Routine Description: - -Arguments: - -Returns: - - None - ---*/ -// TODO: Private - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_UGA_DRAW_PROTOCOL *UgaDraw; UINTN Index; @@ -657,50 +622,36 @@ Returns: return EFI_SUCCESS; } +/** + CirrusLogic5430UgaDrawDestructor + + TODO: Private - add argument and description to function comment + TODO: EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS CirrusLogic5430UgaDrawDestructor ( CIRRUS_LOGIC_5430_PRIVATE_DATA *Private ) -/*++ - -Routine Description: - -Arguments: - -Returns: - - None - ---*/ -// TODO: Private - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { return EFI_SUCCESS; } +/** + TODO: Add function description + + @param Private TODO: add argument description + @param Address TODO: add argument description + @param Data TODO: add argument description + + TODO: add return values + +**/ VOID outb ( CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, UINTN Address, UINT8 Data ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - Private - TODO: add argument description - Address - TODO: add argument description - Data - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { Private->PciIo->Io.Write ( Private->PciIo, @@ -712,29 +663,22 @@ Returns: ); } +/** + TODO: Add function description + + @param Private TODO: add argument description + @param Address TODO: add argument description + @param Data TODO: add argument description + + TODO: add return values + +**/ VOID outw ( CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, UINTN Address, UINT16 Data ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - Private - TODO: add argument description - Address - TODO: add argument description - Data - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { Private->PciIo->Io.Write ( Private->PciIo, @@ -746,27 +690,20 @@ Returns: ); } -UINT8 -inb ( - CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, - UINTN Address - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - Private - TODO: add argument description - Address - TODO: add argument description - -Returns: + @param Private TODO: add argument description + @param Address TODO: add argument description TODO: add return values ---*/ +**/ +UINT8 +inb ( + CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, + UINTN Address + ) { UINT8 Data; @@ -781,27 +718,20 @@ Returns: return Data; } -UINT16 -inw ( - CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, - UINTN Address - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - Private - TODO: add argument description - Address - TODO: add argument description - -Returns: + @param Private TODO: add argument description + @param Address TODO: add argument description TODO: add return values ---*/ +**/ +UINT16 +inw ( + CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, + UINTN Address + ) { UINT16 Data; @@ -816,6 +746,18 @@ Returns: return Data; } +/** + TODO: Add function description + + @param Private TODO: add argument description + @param Index TODO: add argument description + @param Red TODO: add argument description + @param Green TODO: add argument description + @param Blue TODO: add argument description + + TODO: add return values + +**/ VOID SetPaletteColor ( CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, @@ -824,25 +766,6 @@ SetPaletteColor ( UINT8 Green, UINT8 Blue ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - Private - TODO: add argument description - Index - TODO: add argument description - Red - TODO: add argument description - Green - TODO: add argument description - Blue - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { outb (Private, PALETTE_INDEX_REGISTER, (UINT8) Index); outb (Private, PALETTE_DATA_REGISTER, (UINT8) (Red >> 2)); @@ -850,25 +773,18 @@ Returns: outb (Private, PALETTE_DATA_REGISTER, (UINT8) (Blue >> 2)); } -VOID -SetDefaultPalette ( - CIRRUS_LOGIC_5430_PRIVATE_DATA *Private - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - Private - TODO: add argument description - -Returns: + @param Private TODO: add argument description TODO: add return values ---*/ +**/ +VOID +SetDefaultPalette ( + CIRRUS_LOGIC_5430_PRIVATE_DATA *Private + ) { UINTN Index; UINTN RedIndex; @@ -886,26 +802,19 @@ Returns: } } -STATIC -VOID -ClearScreen ( - CIRRUS_LOGIC_5430_PRIVATE_DATA *Private - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - Private - TODO: add argument description - -Returns: + @param Private TODO: add argument description TODO: add return values ---*/ +**/ +STATIC +VOID +ClearScreen ( + CIRRUS_LOGIC_5430_PRIVATE_DATA *Private + ) { UINT32 Color; @@ -920,25 +829,18 @@ Returns: ); } -VOID -DrawLogo ( - CIRRUS_LOGIC_5430_PRIVATE_DATA *Private - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - Private - TODO: add argument description - -Returns: + @param Private TODO: add argument description TODO: add return values ---*/ +**/ +VOID +DrawLogo ( + CIRRUS_LOGIC_5430_PRIVATE_DATA *Private + ) { UINTN Offset; UINTN X; @@ -968,27 +870,20 @@ Returns: } } -VOID -InitializeGraphicsMode ( - CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, - CIRRUS_LOGIC_5430_VIDEO_MODES *ModeData - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - Private - TODO: add argument description - ModeData - TODO: add argument description - -Returns: + @param Private TODO: add argument description + @param ModeData TODO: add argument description TODO: add return values ---*/ +**/ +VOID +InitializeGraphicsMode ( + CIRRUS_LOGIC_5430_PRIVATE_DATA *Private, + CIRRUS_LOGIC_5430_VIDEO_MODES *ModeData + ) { UINT8 Byte; UINTN Index; diff --git a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c index 5c10b6d7b4..933899fa12 100644 --- a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c +++ b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c @@ -1,21 +1,14 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - ComponentName.c - -Abstract: - ---*/ +**/ #include "CirrusLogic5430.h" @@ -59,6 +52,28 @@ static EFI_UNICODE_STRING_TABLE mCirrusLogic5430ControllerNameTable[] = { { NULL , NULL } }; +/** + Retrieves a Unicode string that is the user readable name of the EFI Driver. + + @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. + @param Language A pointer to a three character ISO 639-2 language identifier. + This is the language of the driver name that that the caller + is requesting, and it must match one of the languages specified + in SupportedLanguages. The number of languages supported by a + driver is up to the driver writer. + @param DriverName A pointer to the Unicode string to return. This Unicode string + is the name of the driver specified by This in the language + specified by Language. + + @retval EFI_SUCCESS The Unicode string for the Driver specified by This + and the language specified by Language was returned + in DriverName. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER DriverName is NULL. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + language specified by Language. + +**/ EFI_STATUS EFIAPI CirrusLogic5430ComponentNameGetDriverName ( @@ -66,32 +81,6 @@ CirrusLogic5430ComponentNameGetDriverName ( IN CHAR8 *Language, OUT CHAR16 **DriverName ) -/*++ - - Routine Description: - Retrieves a Unicode string that is the user readable name of the EFI Driver. - - Arguments: - This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. - Language - A pointer to a three character ISO 639-2 language identifier. - This is the language of the driver name that that the caller - is requesting, and it must match one of the languages specified - in SupportedLanguages. The number of languages supported by a - driver is up to the driver writer. - DriverName - A pointer to the Unicode string to return. This Unicode string - is the name of the driver specified by This in the language - specified by Language. - - Returns: - EFI_SUCCESS - The Unicode string for the Driver specified by This - and the language specified by Language was returned - in DriverName. - EFI_INVALID_PARAMETER - Language is NULL. - EFI_INVALID_PARAMETER - DriverName is NULL. - EFI_UNSUPPORTED - The driver specified by This does not support the - language specified by Language. - ---*/ { return LookupUnicodeString ( Language, @@ -101,6 +90,46 @@ CirrusLogic5430ComponentNameGetDriverName ( ); } +/** + Retrieves a Unicode string that is the user readable name of the controller + that is being managed by an EFI Driver. + + @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. + @param ControllerHandle The handle of a controller that the driver specified by + This is managing. This handle specifies the controller + whose name is to be returned. + @param ChildHandle The handle of the child controller to retrieve the name + of. This is an optional parameter that may be NULL. It + will be NULL for device drivers. It will also be NULL + for a bus drivers that wish to retrieve the name of the + bus controller. It will not be NULL for a bus driver + that wishes to retrieve the name of a child controller. + @param Language A pointer to a three character ISO 639-2 language + identifier. This is the language of the controller name + that that the caller is requesting, and it must match one + of the languages specified in SupportedLanguages. The + number of languages supported by a driver is up to the + driver writer. + @param ControllerName A pointer to the Unicode string to return. This Unicode + string is the name of the controller specified by + ControllerHandle and ChildHandle in the language specified + by Language from the point of view of the driver specified + by This. + + @retval EFI_SUCCESS The Unicode string for the user readable name in the + language specified by Language for the driver + specified by This was returned in DriverName. + @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER ControllerName is NULL. + @retval EFI_UNSUPPORTED The driver specified by This is not currently managing + the controller specified by ControllerHandle and + ChildHandle. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + language specified by Language. + +**/ EFI_STATUS EFIAPI CirrusLogic5430ComponentNameGetControllerName ( @@ -110,50 +139,6 @@ CirrusLogic5430ComponentNameGetControllerName ( IN CHAR8 *Language, OUT CHAR16 **ControllerName ) -/*++ - - Routine Description: - Retrieves a Unicode string that is the user readable name of the controller - that is being managed by an EFI Driver. - - Arguments: - This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. - ControllerHandle - The handle of a controller that the driver specified by - This is managing. This handle specifies the controller - whose name is to be returned. - ChildHandle - The handle of the child controller to retrieve the name - of. This is an optional parameter that may be NULL. It - will be NULL for device drivers. It will also be NULL - for a bus drivers that wish to retrieve the name of the - bus controller. It will not be NULL for a bus driver - that wishes to retrieve the name of a child controller. - Language - A pointer to a three character ISO 639-2 language - identifier. This is the language of the controller name - that that the caller is requesting, and it must match one - of the languages specified in SupportedLanguages. The - number of languages supported by a driver is up to the - driver writer. - ControllerName - A pointer to the Unicode string to return. This Unicode - string is the name of the controller specified by - ControllerHandle and ChildHandle in the language specified - by Language from the point of view of the driver specified - by This. - - Returns: - EFI_SUCCESS - The Unicode string for the user readable name in the - language specified by Language for the driver - specified by This was returned in DriverName. - EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid EFI_HANDLE. - EFI_INVALID_PARAMETER - Language is NULL. - EFI_INVALID_PARAMETER - ControllerName is NULL. - EFI_UNSUPPORTED - The driver specified by This is not currently managing - the controller specified by ControllerHandle and - ChildHandle. - EFI_UNSUPPORTED - The driver specified by This does not support the - language specified by Language. - ---*/ { EFI_UGA_DRAW_PROTOCOL *UgaDraw; EFI_STATUS Status; diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c index 240a6b0082..edead729b4 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c @@ -1,21 +1,14 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - ComponentName.c - -Abstract: - ---*/ +**/ #include "idebus.h" @@ -38,6 +31,28 @@ STATIC EFI_UNICODE_STRING_TABLE mIDEBusControllerNameTable[] = { { NULL , NULL } }; +/** + Retrieves a Unicode string that is the user readable name of the EFI Driver. + + @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. + @param Language A pointer to a three character ISO 639-2 language identifier. + This is the language of the driver name that that the caller + is requesting, and it must match one of the languages specified + in SupportedLanguages. The number of languages supported by a + driver is up to the driver writer. + @param DriverName A pointer to the Unicode string to return. This Unicode string + is the name of the driver specified by This in the language + specified by Language. + + @retval EFI_SUCCESS The Unicode string for the Driver specified by This + and the language specified by Language was returned + in DriverName. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER DriverName is NULL. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + language specified by Language. + +**/ EFI_STATUS EFIAPI IDEBusComponentNameGetDriverName ( @@ -45,32 +60,6 @@ IDEBusComponentNameGetDriverName ( IN CHAR8 *Language, OUT CHAR16 **DriverName ) -/*++ - - Routine Description: - Retrieves a Unicode string that is the user readable name of the EFI Driver. - - Arguments: - This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. - Language - A pointer to a three character ISO 639-2 language identifier. - This is the language of the driver name that that the caller - is requesting, and it must match one of the languages specified - in SupportedLanguages. The number of languages supported by a - driver is up to the driver writer. - DriverName - A pointer to the Unicode string to return. This Unicode string - is the name of the driver specified by This in the language - specified by Language. - - Returns: - EFI_SUCCESS - The Unicode string for the Driver specified by This - and the language specified by Language was returned - in DriverName. - EFI_INVALID_PARAMETER - Language is NULL. - EFI_INVALID_PARAMETER - DriverName is NULL. - EFI_UNSUPPORTED - The driver specified by This does not support the - language specified by Language. - ---*/ { return LookupUnicodeString ( Language, @@ -80,6 +69,47 @@ IDEBusComponentNameGetDriverName ( ); } +/** + Retrieves a Unicode string that is the user readable name of the controller + that is being managed by an EFI Driver. + + @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. + @param ControllerHandle The handle of a controller that the driver specified by + This is managing. This handle specifies the controller + whose name is to be returned. + @param ChildHandle The handle of the child controller to retrieve the name + of. This is an optional parameter that may be NULL. It + will be NULL for device drivers. It will also be NULL + for a bus drivers that wish to retrieve the name of the + bus controller. It will not be NULL for a bus driver + that wishes to retrieve the name of a child controller. + @param Language A pointer to a three character ISO 639-2 language + identifier. This is the language of the controller name + that that the caller is requesting, and it must match one + of the languages specified in SupportedLanguages. The + number of languages supported by a driver is up to the + driver writer. + @param ControllerName A pointer to the Unicode string to return. This Unicode + string is the name of the controller specified by + ControllerHandle and ChildHandle in the language + specified by Language from the point of view of the + driver specified by This. + + @retval EFI_SUCCESS The Unicode string for the user readable name in the + language specified by Language for the driver + specified by This was returned in DriverName. + @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid + EFI_HANDLE. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER ControllerName is NULL. + @retval EFI_UNSUPPORTED The driver specified by This is not currently + managing the controller specified by + ControllerHandle and ChildHandle. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + language specified by Language. + +**/ EFI_STATUS EFIAPI IDEBusComponentNameGetControllerName ( @@ -89,51 +119,6 @@ IDEBusComponentNameGetControllerName ( IN CHAR8 *Language, OUT CHAR16 **ControllerName ) -/*++ - - Routine Description: - Retrieves a Unicode string that is the user readable name of the controller - that is being managed by an EFI Driver. - - Arguments: - This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. - ControllerHandle - The handle of a controller that the driver specified by - This is managing. This handle specifies the controller - whose name is to be returned. - ChildHandle - The handle of the child controller to retrieve the name - of. This is an optional parameter that may be NULL. It - will be NULL for device drivers. It will also be NULL - for a bus drivers that wish to retrieve the name of the - bus controller. It will not be NULL for a bus driver - that wishes to retrieve the name of a child controller. - Language - A pointer to a three character ISO 639-2 language - identifier. This is the language of the controller name - that that the caller is requesting, and it must match one - of the languages specified in SupportedLanguages. The - number of languages supported by a driver is up to the - driver writer. - ControllerName - A pointer to the Unicode string to return. This Unicode - string is the name of the controller specified by - ControllerHandle and ChildHandle in the language - specified by Language from the point of view of the - driver specified by This. - - Returns: - EFI_SUCCESS - The Unicode string for the user readable name in the - language specified by Language for the driver - specified by This was returned in DriverName. - EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid - EFI_HANDLE. - EFI_INVALID_PARAMETER - Language is NULL. - EFI_INVALID_PARAMETER - ControllerName is NULL. - EFI_UNSUPPORTED - The driver specified by This is not currently - managing the controller specified by - ControllerHandle and ChildHandle. - EFI_UNSUPPORTED - The driver specified by This does not support the - language specified by Language. - ---*/ { EFI_STATUS Status; EFI_BLOCK_IO_PROTOCOL *BlockIo; @@ -188,21 +173,16 @@ IDEBusComponentNameGetControllerName ( ); } +/** + Add the component name for the IDE/ATAPI device + + @param IdeBlkIoDevicePtr A pointer to the IDE_BLK_IO_DEV instance. + +**/ VOID AddName ( IN IDE_BLK_IO_DEV *IdeBlkIoDevicePtr ) -/*++ - - Routine Description: - Add the component name for the IDE/ATAPI device - - Arguments: - IdeBlkIoDevicePtr - A pointer to the IDE_BLK_IO_DEV instance. - - Returns: - ---*/ { UINTN StringIndex; CHAR16 ModelName[41]; diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c index 5a23a43189..dfe134a2ee 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c @@ -1,21 +1,14 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - DriverConfiguration.c - -Abstract: - ---*/ +**/ #include "idebus.h" @@ -63,27 +56,18 @@ EFI_DRIVER_CONFIGURATION_PROTOCOL gIDEBusDriverConfiguration = { "eng" }; +/** + TODO: Add function description + + @retval EFI_ABORTED TODO: Add description for return value + @retval EFI_SUCCESS TODO: Add description for return value + @retval EFI_NOT_FOUND TODO: Add description for return value + +**/ EFI_STATUS GetResponse ( VOID ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - None - -Returns: - - EFI_ABORTED - TODO: Add description for return value - EFI_SUCCESS - TODO: Add description for return value - EFI_NOT_FOUND - TODO: Add description for return value - ---*/ { EFI_STATUS Status; EFI_INPUT_KEY Key; @@ -118,6 +102,51 @@ Returns: } } +/** + Allows the user to set controller specific options for a controller that a + driver is currently managing. + + @param This A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL + instance. + @param ControllerHandle The handle of the controller to set options on. + @param ChildHandle The handle of the child controller to set options on. + This is an optional parameter that may be NULL. + It will be NULL for device drivers, and for a bus drivers + that wish to set options for the bus controller. + It will not be NULL for a bus driver that wishes to set + options for one of its child controllers. + @param Language A pointer to a three character ISO 639-2 language + identifier. This is the language of the user interface + that should be presented to the user, and it must match + one of the languages specified in SupportedLanguages. + The number of languages supported by a driver is up to + the driver writer. + @param ActionRequired A pointer to the action that the calling agent is + required to perform when this function returns. + See "Related Definitions" for a list of the actions that + the calling agent is required to perform prior to + accessing ControllerHandle again. + + @retval EFI_SUCCESS The driver specified by This successfully set the + configuration options for the controller specified + by ControllerHandle.. + @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a + valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ActionRequired is NULL. + @retval EFI_UNSUPPORTED The driver specified by This does not support + setting configuration options for the controller + specified by ControllerHandle and ChildHandle. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + language specified by Language. + @retval EFI_DEVICE_ERROR A device error occurred while attempt to set the + configuration options for the controller specified + by ControllerHandle and ChildHandle. + @retval EFI_OUT_RESOURCES There are not enough resources available to set the + configuration options for the controller specified + by ControllerHandle and ChildHandle. + +**/ EFI_STATUS IDEBusDriverConfigurationSetOptions ( IN EFI_DRIVER_CONFIGURATION_PROTOCOL *This, @@ -126,55 +155,6 @@ IDEBusDriverConfigurationSetOptions ( IN CHAR8 *Language, OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED *ActionRequired ) -/*++ - - Routine Description: - Allows the user to set controller specific options for a controller that a - driver is currently managing. - - Arguments: - This - A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL - instance. - ControllerHandle - The handle of the controller to set options on. - ChildHandle - The handle of the child controller to set options on. - This is an optional parameter that may be NULL. - It will be NULL for device drivers, and for a bus drivers - that wish to set options for the bus controller. - It will not be NULL for a bus driver that wishes to set - options for one of its child controllers. - Language - A pointer to a three character ISO 639-2 language - identifier. This is the language of the user interface - that should be presented to the user, and it must match - one of the languages specified in SupportedLanguages. - The number of languages supported by a driver is up to - the driver writer. - ActionRequired - A pointer to the action that the calling agent is - required to perform when this function returns. - See "Related Definitions" for a list of the actions that - the calling agent is required to perform prior to - accessing ControllerHandle again. - - Returns: - EFI_SUCCESS - The driver specified by This successfully set the - configuration options for the controller specified - by ControllerHandle.. - EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a - valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ActionRequired is NULL. - EFI_UNSUPPORTED - The driver specified by This does not support - setting configuration options for the controller - specified by ControllerHandle and ChildHandle. - EFI_UNSUPPORTED - The driver specified by This does not support the - language specified by Language. - EFI_DEVICE_ERROR - A device error occurred while attempt to set the - configuration options for the controller specified - by ControllerHandle and ChildHandle. - EFI_OUT_RESOURCES - There are not enough resources available to set the - configuration options for the controller specified - by ControllerHandle and ChildHandle. - ---*/ { EFI_STATUS Status; UINT8 Value; @@ -232,49 +212,45 @@ IDEBusDriverConfigurationSetOptions ( return EFI_SUCCESS; } +/** + Tests to see if a controller's current configuration options are valid. + + @param This A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL + instance. + @param ControllerHandle The handle of the controller to test if it's current + configuration options are valid. + @param ChildHandle The handle of the child controller to test if it's + current + configuration options are valid. This is an optional + parameter that may be NULL. It will be NULL for device + drivers. It will also be NULL for a bus drivers that + wish to test the configuration options for the bus + controller. It will not be NULL for a bus driver that + wishes to test configuration options for one of + its child controllers. + + @retval EFI_SUCCESS The controller specified by ControllerHandle and + ChildHandle that is being managed by the driver + specified by This has a valid set of configuration + options. + @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid + EFI_HANDLE. + @retval EFI_UNSUPPORTED The driver specified by This is not currently + managing the controller specified by + ControllerHandle and ChildHandle. + @retval EFI_DEVICE_ERROR The controller specified by ControllerHandle and + ChildHandle that is being managed by the driver + specified by This has an invalid set of + configuration options. + +**/ EFI_STATUS IDEBusDriverConfigurationOptionsValid ( IN EFI_DRIVER_CONFIGURATION_PROTOCOL *This, IN EFI_HANDLE ControllerHandle, IN EFI_HANDLE ChildHandle OPTIONAL ) -/*++ - - Routine Description: - Tests to see if a controller's current configuration options are valid. - - Arguments: - This - A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL - instance. - ControllerHandle - The handle of the controller to test if it's current - configuration options are valid. - ChildHandle - The handle of the child controller to test if it's - current - configuration options are valid. This is an optional - parameter that may be NULL. It will be NULL for device - drivers. It will also be NULL for a bus drivers that - wish to test the configuration options for the bus - controller. It will not be NULL for a bus driver that - wishes to test configuration options for one of - its child controllers. - - Returns: - EFI_SUCCESS - The controller specified by ControllerHandle and - ChildHandle that is being managed by the driver - specified by This has a valid set of configuration - options. - EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid - EFI_HANDLE. - EFI_UNSUPPORTED - The driver specified by This is not currently - managing the controller specified by - ControllerHandle and ChildHandle. - EFI_DEVICE_ERROR - The controller specified by ControllerHandle and - ChildHandle that is being managed by the driver - specified by This has an invalid set of - configuration options. - ---*/ { EFI_STATUS Status; UINT8 Value; @@ -300,6 +276,51 @@ IDEBusDriverConfigurationOptionsValid ( return EFI_SUCCESS; } +/** + Forces a driver to set the default configuration options for a controller. + + @param This A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL + instance. + @param ControllerHandle The handle of the controller to force default + configuration options on. + @param ChildHandle The handle of the child controller to force default + configuration options on This is an optional parameter + that may be NULL. It will be NULL for device drivers. + It will also be NULL for a bus drivers that wish to + force default configuration options for the bus + controller. It will not be NULL for a bus driver that + wishes to force default configuration options for one + of its child controllers. + @param DefaultType The type of default configuration options to force on + the controller specified by ControllerHandle and + ChildHandle. See Table 9-1 for legal values. + A DefaultType of 0x00000000 must be supported + by this protocol. + @param ActionRequired A pointer to the action that the calling agent + is required to perform when this function returns. + + @retval EFI_SUCCESS The driver specified by This successfully forced + the default configuration options on the + controller specified by ControllerHandle and + ChildHandle. + @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a + valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ActionRequired is NULL. + @retval EFI_UNSUPPORTED The driver specified by This does not support + forcing the default configuration options on + the controller specified by ControllerHandle + and ChildHandle. + @retval EFI_UNSUPPORTED The driver specified by This does not support + the configuration type specified by DefaultType. + @retval EFI_DEVICE_ERROR A device error occurred while attempt to force + the default configuration options on the controller + specified by ControllerHandle and ChildHandle. + @retval EFI_OUT_RESOURCES There are not enough resources available to force + the default configuration options on the controller + specified by ControllerHandle and ChildHandle. + +**/ EFI_STATUS IDEBusDriverConfigurationForceDefaults ( IN EFI_DRIVER_CONFIGURATION_PROTOCOL *This, @@ -308,56 +329,6 @@ IDEBusDriverConfigurationForceDefaults ( IN UINT32 DefaultType, OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED *ActionRequired ) -/*++ - - Routine Description: - Forces a driver to set the default configuration options for a controller. - - Arguments: - This - A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL - instance. - ControllerHandle - The handle of the controller to force default - configuration options on. - ChildHandle - The handle of the child controller to force default - configuration options on This is an optional parameter - that may be NULL. It will be NULL for device drivers. - It will also be NULL for a bus drivers that wish to - force default configuration options for the bus - controller. It will not be NULL for a bus driver that - wishes to force default configuration options for one - of its child controllers. - DefaultType - The type of default configuration options to force on - the controller specified by ControllerHandle and - ChildHandle. See Table 9-1 for legal values. - A DefaultType of 0x00000000 must be supported - by this protocol. - ActionRequired - A pointer to the action that the calling agent - is required to perform when this function returns. - - - Returns: - EFI_SUCCESS - The driver specified by This successfully forced - the default configuration options on the - controller specified by ControllerHandle and - ChildHandle. - EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a - valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ActionRequired is NULL. - EFI_UNSUPPORTED - The driver specified by This does not support - forcing the default configuration options on - the controller specified by ControllerHandle - and ChildHandle. - EFI_UNSUPPORTED - The driver specified by This does not support - the configuration type specified by DefaultType. - EFI_DEVICE_ERROR - A device error occurred while attempt to force - the default configuration options on the controller - specified by ControllerHandle and ChildHandle. - EFI_OUT_RESOURCES - There are not enough resources available to force - the default configuration options on the controller - specified by ControllerHandle and ChildHandle. - ---*/ { UINT8 Value; diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c index d3f2a8e31c..c7bd30aa94 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c @@ -1,21 +1,14 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - DriverDiagnostics.c - -Abstract: - ---*/ +**/ #include "idebus.h" @@ -44,6 +37,63 @@ EFI_DRIVER_DIAGNOSTICS_PROTOCOL gIDEBusDriverDiagnostics = { "eng" }; +/** + Runs diagnostics on a controller. + + @param This A pointer to the EFI_DRIVER_DIAGNOSTICS_PROTOCOL + instance. + @param ControllerHandle The handle of the controller to run diagnostics on. + @param ChildHandle The handle of the child controller to run diagnostics on + This is an optional parameter that may be NULL. It will + be NULL for device drivers. It will also be NULL for a + bus drivers that wish to run diagnostics on the bus + controller. It will not be NULL for a bus driver that + wishes to run diagnostics on one of its child + controllers. + @param DiagnosticType Indicates type of diagnostics to perform on the + controller specified by ControllerHandle and ChildHandle. + See "Related Definitions" for the list of supported + types. + @param Language A pointer to a three character ISO 639-2 language + identifier. This is the language in which the optional + error message should be returned in Buffer, and it must + match one of the languages specified in + SupportedLanguages. The number of languages supported by + a driver is up to the driver writer. + @param ErrorType A GUID that defines the format of the data returned in + Buffer. + @param BufferSize The size, in bytes, of the data returned in Buffer. + @param Buffer A buffer that contains a Null-terminated Unicode string + plus some additional data whose format is defined by + ErrorType. Buffer is allocated by this function with + AllocatePool(), and it is the caller's responsibility + to free it with a call to FreePool(). + + @retval EFI_SUCCESS The controller specified by ControllerHandle and + ChildHandle passed the diagnostic. + @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. + @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid + EFI_HANDLE. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER ErrorType is NULL. + @retval EFI_INVALID_PARAMETER BufferType is NULL. + @retval EFI_INVALID_PARAMETER Buffer is NULL. + @retval EFI_UNSUPPORTED The driver specified by This does not support + running diagnostics for the controller specified + by ControllerHandle and ChildHandle. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + type of diagnostic specified by DiagnosticType. + @retval EFI_UNSUPPORTED The driver specified by This does not support the + language specified by Language. + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to complete + the diagnostics. + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to return + the status information in ErrorType, BufferSize, + and Buffer. + @retval EFI_DEVICE_ERROR The controller specified by ControllerHandle and + ChildHandle did not pass the diagnostic. + +**/ EFI_STATUS IDEBusDriverDiagnosticsRunDiagnostics ( IN EFI_DRIVER_DIAGNOSTICS_PROTOCOL *This, @@ -55,67 +105,6 @@ IDEBusDriverDiagnosticsRunDiagnostics ( OUT UINTN *BufferSize, OUT CHAR16 **Buffer ) -/*++ - - Routine Description: - Runs diagnostics on a controller. - - Arguments: - This - A pointer to the EFI_DRIVER_DIAGNOSTICS_PROTOCOL - instance. - ControllerHandle - The handle of the controller to run diagnostics on. - ChildHandle - The handle of the child controller to run diagnostics on - This is an optional parameter that may be NULL. It will - be NULL for device drivers. It will also be NULL for a - bus drivers that wish to run diagnostics on the bus - controller. It will not be NULL for a bus driver that - wishes to run diagnostics on one of its child - controllers. - DiagnosticType - Indicates type of diagnostics to perform on the - controller specified by ControllerHandle and ChildHandle. - See "Related Definitions" for the list of supported - types. - Language - A pointer to a three character ISO 639-2 language - identifier. This is the language in which the optional - error message should be returned in Buffer, and it must - match one of the languages specified in - SupportedLanguages. The number of languages supported by - a driver is up to the driver writer. - ErrorType - A GUID that defines the format of the data returned in - Buffer. - BufferSize - The size, in bytes, of the data returned in Buffer. - Buffer - A buffer that contains a Null-terminated Unicode string - plus some additional data whose format is defined by - ErrorType. Buffer is allocated by this function with - AllocatePool(), and it is the caller's responsibility - to free it with a call to FreePool(). - - Returns: - EFI_SUCCESS - The controller specified by ControllerHandle and - ChildHandle passed the diagnostic. - EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE. - EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid - EFI_HANDLE. - EFI_INVALID_PARAMETER - Language is NULL. - EFI_INVALID_PARAMETER - ErrorType is NULL. - EFI_INVALID_PARAMETER - BufferType is NULL. - EFI_INVALID_PARAMETER - Buffer is NULL. - EFI_UNSUPPORTED - The driver specified by This does not support - running diagnostics for the controller specified - by ControllerHandle and ChildHandle. - EFI_UNSUPPORTED - The driver specified by This does not support the - type of diagnostic specified by DiagnosticType. - EFI_UNSUPPORTED - The driver specified by This does not support the - language specified by Language. - EFI_OUT_OF_RESOURCES - There are not enough resources available to complete - the diagnostics. - EFI_OUT_OF_RESOURCES - There are not enough resources available to return - the status information in ErrorType, BufferSize, - and Buffer. - EFI_DEVICE_ERROR - The controller specified by ControllerHandle and - ChildHandle did not pass the diagnostic. - ---*/ { EFI_STATUS Status; EFI_PCI_IO_PROTOCOL *PciIo; diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c index 88e81c0ada..9a1542d0ea 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c @@ -1,33 +1,25 @@ -/*++ - -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - ata.c - -Abstract: - -Revision History - - 2002-6: Add Atapi6 enhancement, support >120GB hard disk, including - update - ATAIdentity() func - update - AtaBlockIoReadBlocks() func - update - AtaBlockIoWriteBlocks() func - add - AtaAtapi6Identify() func - add - AtaReadSectorsExt() func - add - AtaWriteSectorsExt() func - add - AtaPioDataInExt() func - add - AtaPioDataOutExt() func - ---*/ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + 2002-6: Add Atapi6 enhancement, support >120GB hard disk, including + update - ATAIdentity() func + update - AtaBlockIoReadBlocks() func + update - AtaBlockIoWriteBlocks() func + add - AtaAtapi6Identify() func + add - AtaReadSectorsExt() func + add - AtaWriteSectorsExt() func + add - AtaPioDataInExt() func + add - AtaPioDataOutExt() func + +**/ #include "idebus.h" @@ -68,46 +60,34 @@ AtaPioDataOutExt ( IN UINT16 SectorCount ); -EFI_STATUS -ATAIdentify ( - IN IDE_BLK_IO_DEV *IdeDev - ) -/*++ - Name: - ATAIdentify - +/** + Sends out an ATA Identify Command to the specified device. - Purpose: - 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. + 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[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure,used + to record all the information of the IDE device. - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure,used - to record all the information of the IDE device. - - - Returns: - EFI_SUCCESS - Identify ATA device successfully. - - EFI_DEVICE_ERROR - ATA Identify Device Command failed or device is not - ATA device. + @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. - Notes: - parameter IdeDev will be updated in this function. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment +**/ +EFI_STATUS +ATAIdentify ( + IN IDE_BLK_IO_DEV *IdeDev + ) { EFI_STATUS Status; EFI_IDENTIFY_DATA *AtaIdentifyPointer; @@ -213,42 +193,30 @@ ATAIdentify ( } -EFI_STATUS -AtaAtapi6Identify ( - IN IDE_BLK_IO_DEV *IdeDev - ) -/*++ - Name: - - AtaAtapi6Identify +/** + This function is called by ATAIdentify() to identity whether this disk + supports ATA/ATAPI6 48bit addressing, ie support >120G capacity - Purpose: + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @retval EFI_SUCCESS The disk specified by IdeDev is a Atapi6 supported one + and 48-bit addressing must be used - This function is called by ATAIdentify() to identity whether this disk - supports ATA/ATAPI6 48bit addressing, ie support >120G capacity + @retval EFI_UNSUPPORTED The disk dosn't not support Atapi6 or it supports but + the capacity is below 120G, 48bit addressing is not + needed - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. + @note + This function must be called after DEVICE_IDENTITY command has been + successfully returned - Returns: - - EFI_SUCCESS - The disk specified by IdeDev is a Atapi6 supported one - and 48-bit addressing must be used - - EFI_UNSUPPORTED - The disk dosn't not support Atapi6 or it supports but - the capacity is below 120G, 48bit addressing is not - needed - - Notes: - - This function must be called after DEVICE_IDENTITY command has been - successfully returned ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment +**/ +EFI_STATUS +AtaAtapi6Identify ( + IN IDE_BLK_IO_DEV *IdeDev + ) { UINT8 Index; EFI_LBA TmpLba; @@ -304,33 +272,19 @@ AtaAtapi6Identify ( return EFI_UNSUPPORTED; } +/** + This function is called by ATAIdentify() or ATAPIIdentify() + to print device's module name. + + @param[in] *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 ) -/*++ - Name: - PrintAtaModuleName - - - Purpose: - This function is called by ATAIdentify() or ATAPIIdentify() - to print device's module name. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - Returns: - no returns. - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment { if (IdeDev->pIdData == NULL) { return ; @@ -340,6 +294,44 @@ PrintAtaModuleName ( IdeDev->ModelName[40] = 0x00; } +/** + This function is used to send out ATA commands conforms to the + PIO Data In Protocol. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] *Buffer + buffer contained data transferred from device to host. + + @param[in] ByteCount + data size in byte unit of the buffer. + + @param[in] AtaCommand + value of the Command Register + + @param[in] Head + value of the Head/Device Register + + @param[in] SectorCount + value of the Sector Count Register + + @param[in] SectorNumber + value of the Sector Number Register + + @param[in] CylinderLsb + value of the low byte of the Cylinder Register + + @param[in] 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 AtaPioDataIn ( IN IDE_BLK_IO_DEV *IdeDev, @@ -352,66 +344,6 @@ AtaPioDataIn ( IN UINT8 CylinderLsb, IN UINT8 CylinderMsb ) -/*++ - Name: - AtaPioDataIn - - - Purpose: - This function is used to send out ATA commands conforms to the - PIO Data In Protocol. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *Buffer - buffer contained data transferred from device to host. - - UINT32 IN ByteCount - data size in byte unit of the buffer. - - UINT8 IN AtaCommand - value of the Command Register - - UINT8 IN Head - value of the Head/Device Register - - UINT8 IN SectorCount - value of the Sector Count Register - - UINT8 IN SectorNumber - value of the Sector Number Register - - UINT8 IN CylinderLsb - value of the low byte of the Cylinder Register - - UINT8 IN CylinderMsb - value of the high byte of the Cylinder Register - - - Returns: - EFI_SUCCESS - send out the ATA command and device send required - data successfully. - - EFI_DEVICE_ERROR - command sent failed. - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: AtaCommand - add argument and description to function comment -// TODO: Head - add argument and description to function comment -// TODO: SectorCount - add argument and description to function comment -// TODO: SectorNumber - add argument and description to function comment -// TODO: CylinderLsb - add argument and description to function comment -// TODO: CylinderMsb - add argument and description to function comment { UINTN WordCount; UINTN Increment; @@ -529,6 +461,29 @@ AtaPioDataIn ( return CheckErrorStatus (IdeDev); } +/** + This function is used to send out ATA commands conforms to the + PIO Data Out Protocol. + + @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 + + @retval EFI_SUCCESS send out the ATA command and device received required + data successfully. + + @retval EFI_DEVICE_ERROR command sent failed. + +**/ EFI_STATUS AtaPioDataOut ( IN IDE_BLK_IO_DEV *IdeDev, @@ -541,67 +496,6 @@ AtaPioDataOut ( IN UINT8 CylinderLsb, IN UINT8 CylinderMsb ) -/*++ - Name: - AtaPioDataOut - - - Purpose: - This function is used to send out ATA commands conforms to the - PIO Data Out Protocol. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *Buffer - buffer contained data transferred from host to device. - - UINT32 IN ByteCount - data size in byte unit of the buffer. - - UINT8 IN AtaCommand - value of the Command Register - - UINT8 IN Head - value of the Head/Device Register - - UINT8 IN SectorCount - value of the Sector Count Register - - UINT8 IN SectorNumber - value of the Sector Number Register - - UINT8 IN CylinderLsb - value of the low byte of the Cylinder Register - - UINT8 IN CylinderMsb - value of the high byte of the Cylinder Register - - - Returns: - EFI_SUCCESS - send out the ATA command and device received required - data successfully. - - EFI_DEVICE_ERROR - command sent failed. - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: AtaCommand - add argument and description to function comment -// TODO: Head - add argument and description to function comment -// TODO: SectorCount - add argument and description to function comment -// TODO: SectorNumber - add argument and description to function comment -// TODO: CylinderLsb - add argument and description to function comment -// TODO: CylinderMsb - add argument and description to function comment { UINTN WordCount; UINTN Increment; @@ -718,38 +612,23 @@ AtaPioDataOut ( return CheckErrorStatus (IdeDev); } +/** + 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[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @retval EFI_SUCCESS No err information in the Status Register. + @retval EFI_DEVICE_ERROR Any err information in the Status Register. + +**/ EFI_STATUS CheckErrorStatus ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - CheckErrorStatus - - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - Returns: - EFI_SUCCESS - No err information in the Status Register. - - EFI_DEVICE_ERROR - Any err information in the Status Register. - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment { UINT8 StatusRegister; @@ -841,6 +720,28 @@ CheckErrorStatus ( } +/** + This function is called by the AtaBlkIoReadBlocks() to perform + reading from media in block unit. + + @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 destination buffer for the data. + + @param[in] Lba + The starting logical block address to read from + on the device media. + + @param[in] NumberOfBlocks + The number of transfer data blocks. + + @return return status is fully dependent on the return status + of AtaPioDataIn() function. + +**/ EFI_STATUS AtaReadSectors ( IN IDE_BLK_IO_DEV *IdeDev, @@ -848,43 +749,6 @@ AtaReadSectors ( IN EFI_LBA Lba, IN UINTN NumberOfBlocks ) -/*++ - Name: - AtaReadSectors - - - Purpose: - This function is called by the AtaBlkIoReadBlocks() to perform - reading from media in block unit. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *DataBuffer - A pointer to the destination buffer for the data. - - EFI_LBA IN Lba - The starting logical block address to read from - on the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - return status is fully dependent on the return status - of AtaPioDataIn() function. - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: DataBuffer - add argument and description to function comment -// TODO: Lba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment { EFI_STATUS Status; UINTN BlocksRemaining; @@ -974,6 +838,28 @@ AtaReadSectors ( return Status; } +/** + This function is called by the AtaBlkIoWriteBlocks() to perform + writing onto media in block unit. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure,used + to record all the information of the IDE device. + + @param[in] *BufferData + A pointer to the source buffer for the data. + + @param[in] Lba + The starting logical block address to write onto + the device media. + + @param[in] NumberOfBlocks + The number of transfer data blocks. + + @return return status is fully dependent on the return status + of AtaPioDataOut() function. + +**/ EFI_STATUS AtaWriteSectors ( IN IDE_BLK_IO_DEV *IdeDev, @@ -981,44 +867,6 @@ AtaWriteSectors ( IN EFI_LBA Lba, IN UINTN NumberOfBlocks ) -/*++ - Name: - AtaWriteSectors - - - Purpose: - This function is called by the AtaBlkIoWriteBlocks() to perform - writing onto media in block unit. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure,used - to record all the information of the IDE device. - - VOID IN *BufferData - A pointer to the source buffer for the data. - - EFI_LBA IN Lba - The starting logical block address to write onto - the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - - Returns: - return status is fully dependent on the return status - of AtaPioDataOut() function. - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: BufferData - add argument and description to function comment -// TODO: Lba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment { EFI_STATUS Status; UINTN BlocksRemaining; @@ -1095,41 +943,34 @@ AtaWriteSectors ( return Status; } +/** + 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. + + It is called by IdeBlkIoReset(), a interface function of Block + I/O protocol. + + This function can also be used by the ATAPI device to perform reset when + ATAPI Reset command is failed. + + @param[in] *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 ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - AtaSoftReset - - Purpose: - 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. - It is called by IdeBlkIoReset(), a interface function of Block - I/O protocol. - This function can also be used by the ATAPI device to perform reset when - ATAPI Reset command is failed. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - Returns: - EFI_SUCCESS - Soft reset completes successfully. - - EFI_DEVICE_ERROR - Any step during the reset process is failed. - Notes: - The registers initial values after ATA soft reset are different - to the ATA device and ATAPI device. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment { UINT8 DeviceControl; @@ -1165,77 +1006,55 @@ AtaSoftReset ( return EFI_SUCCESS; } -EFI_STATUS -AtaBlkIoReadBlocks ( - IN IDE_BLK_IO_DEV *IdeBlkIoDevice, - IN UINT32 MediaId, - IN EFI_LBA LBA, - IN UINTN BufferSize, - OUT VOID *Buffer - ) -/*++ - Name: - AtaBlkIoReadBlocks - - - Purpose: - This function is the ATA implementation for ReadBlocks in the - Block I/O Protocol interface. - +/** + This function is the ATA implementation for ReadBlocks in the + Block I/O Protocol interface. - Parameters: - IDE_BLK_IO_DEV IN *IdeBlkIoDevice - Indicates the calling context. + @param[in] *IdeBlkIoDevice + Indicates the calling context. - UINT32 IN MediaId - The media id that the read request is for. + @param[in] MediaId + The media id that the read request is for. - EFI_LBA IN LBA - The starting logical block address to read from - on the device. + @param[in] LBA + The starting logical block address to read from + on the device. - UINTN IN BufferSize - The size of the Buffer in bytes. This must be a - multiple of the intrinsic block size of the device. + @param[in] BufferSize + The size of the Buffer in bytes. This must be a + multiple of the intrinsic block size of the device. - VOID OUT *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. + @param[out] *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. - Returns: - EFI_SUCCESS - Read Blocks successfully. - - EFI_DEVICE_ERROR - Read Blocks failed. - - EFI_NO_MEDIA - There is no media in the device. - - EFI_MEDIA_CHANGE - The MediaId is not for the current media. - - EFI_BAD_BUFFER_SIZE - The BufferSize parameter is not a multiple of the - intrinsic block size of the device. + @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. - 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. - Notes: - If Read Block error because of device error, this function will call - AtaSoftReset() function to reset device. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeBlkIoDevice - add argument and description to function comment -// TODO: MediaId - add argument and description to function comment -// TODO: LBA - add argument and description to function comment -// TODO: BufferSize - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: EFI_MEDIA_CHANGED - add return value to function comment +**/ +EFI_STATUS +AtaBlkIoReadBlocks ( + IN IDE_BLK_IO_DEV *IdeBlkIoDevice, + IN UINT32 MediaId, + IN EFI_LBA LBA, + IN UINTN BufferSize, + OUT VOID *Buffer + ) { EFI_BLOCK_IO_MEDIA *Media; UINTN BlockSize; @@ -1315,6 +1134,48 @@ AtaBlkIoReadBlocks ( } +/** + This function is the ATA implementation for WriteBlocks in the + Block I/O Protocol interface. + + @param[in] *IdeBlkIoDevice + Indicates the calling context. + + @param[in] MediaId + The media id that the write request is for. + + @param[in] LBA + The starting logical block address to write onto + the device. + + @param[in] BufferSize + The size of the Buffer in bytes. This must be a + multiple of the intrinsic block size of the device. + + @param[out] *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. + + @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. + + @note + If Write Block error because of device error, this function will call + AtaSoftReset() function to reset device. + +**/ EFI_STATUS AtaBlkIoWriteBlocks ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice, @@ -1323,70 +1184,6 @@ AtaBlkIoWriteBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - Name: - AtaBlkIoWriteBlocks - - - Purpose: - This function is the ATA implementation for WriteBlocks in the - Block I/O Protocol interface. - - Parameters: - IDE_BLK_IO_DEV IN *IdeBlkIoDevice - Indicates the calling context. - - UINT32 IN MediaId - The media id that the write request is for. - - EFI_LBA IN LBA - The starting logical block address to write onto - the device. - - UINTN IN BufferSize - The size of the Buffer in bytes. This must be a - multiple of the intrinsic block size of the device. - - VOID OUT *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. - - - Returns: - EFI_SUCCESS - Write Blocks successfully. - - EFI_DEVICE_ERROR - Write Blocks failed. - - EFI_NO_MEDIA - There is no media in the device. - - EFI_MEDIA_CHANGE - The MediaId is not for the current media. - - EFI_BAD_BUFFER_SIZE - The BufferSize parameter is not a multiple of the - intrinsic block size of the device. - - EFI_INVALID_PARAMETER - The write request contains LBAs that are not valid, - or the data buffer is not valid. - - Notes: - If Write Block error because of device error, this function will call - AtaSoftReset() function to reset device. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeBlkIoDevice - add argument and description to function comment -// TODO: MediaId - add argument and description to function comment -// TODO: LBA - add argument and description to function comment -// TODO: BufferSize - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: EFI_MEDIA_CHANGED - add return value to function comment { EFI_BLOCK_IO_MEDIA *Media; @@ -1457,6 +1254,24 @@ AtaBlkIoWriteBlocks ( return EFI_SUCCESS; } +/** + This function is called by the AtaBlkIoReadBlocks() to perform + reading from media in block unit. The function has been enhanced to + support >120GB access and transfer at most 65536 blocks per command + + @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 destination buffer for the data. + @param[in] StartLba The starting logical block address to read from + on the device media. + @param[in] NumberOfBlocks The number of transfer data blocks. + + @return return status is fully dependent on the return status + of AtaPioDataInExt() function. + +**/ EFI_STATUS AtaReadSectorsExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1464,46 +1279,6 @@ AtaReadSectorsExt ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - Name: - - AtaReadSectorsExt - - Purpose: - - This function is called by the AtaBlkIoReadBlocks() to perform - reading from media in block unit. The function has been enhanced to - support >120GB access and transfer at most 65536 blocks per command - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *DataBuffer - A pointer to the destination buffer for the data. - - EFI_LBA IN StartLba - The starting logical block address to read from - on the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - - return status is fully dependent on the return status - of AtaPioDataInExt() function. - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: DataBuffer - add argument and description to function comment -// TODO: StartLba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment { EFI_STATUS Status; UINTN BlocksRemaining; @@ -1562,6 +1337,29 @@ AtaReadSectorsExt ( return Status; } +/** + This function is called by the AtaBlkIoWriteBlocks() to perform + writing onto media in block unit. The function has been enhanced to + support >120GB access and transfer at most 65536 blocks per command + + @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] Lba + The starting logical block address to write onto + the device media. + + @param[in] NumberOfBlocks + The number of transfer data blocks. + + @return status is fully dependent on the return status + of AtaPioDataOutExt() function. + +**/ EFI_STATUS AtaWriteSectorsExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1569,46 +1367,6 @@ AtaWriteSectorsExt ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - Name: - - AtaWriteSectorsExt - - Purpose: - - This function is called by the AtaBlkIoWriteBlocks() to perform - writing onto media in block unit. The function has been enhanced to - support >120GB access and transfer at most 65536 blocks per command - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure,used - to record all the information of the IDE device. - - VOID IN *DataBuffer - A pointer to the source buffer for the data. - - EFI_LBA IN Lba - The starting logical block address to write onto - the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - - return status is fully dependent on the return status - of AtaPioDataOutExt() function. - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: DataBuffer - add argument and description to function comment -// TODO: StartLba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment { EFI_STATUS Status; EFI_LBA Lba64; @@ -1668,6 +1426,32 @@ AtaWriteSectorsExt ( return Status; } +/** + This function is used to send out ATA commands conforms to the + PIO Data In Protocol, supporting ATA/ATAPI-6 standard + + Comparing with ATA-3 data in protocol, we have two differents here:
+ 1. Do NOT wait for DRQ clear before sending command into IDE device.(the + wait will frequently fail... cause writing function return error) + + 2. Do NOT wait for DRQ clear after all data readed.(the wait greatly + slow down writing performance by 100 times!) + + @param[in] *IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in,out] *Buffer buffer contained data transferred from device to host. + @param[in] ByteCount data size in byte unit of the buffer. + @param[in] AtaCommand value of the Command Register + @param[in] StartLba the start LBA of this transaction + @param[in] SectorCount the count of sectors to be transfered + + @retval EFI_SUCCESS send out the ATA command and device send required + data successfully. + + @retval EFI_DEVICE_ERROR command sent failed. + +**/ EFI_STATUS AtaPioDataInExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1677,63 +1461,6 @@ AtaPioDataInExt ( IN EFI_LBA StartLba, IN UINT16 SectorCount ) -/*++ - Name: - - AtaPioDataInExt - - Purpose: - - This function is used to send out ATA commands conforms to the - PIO Data In Protocol, supporting ATA/ATAPI-6 standard - - Comparing with ATA-3 data in protocol, we have two differents here: - 1. Do NOT wait for DRQ clear before sending command into IDE device.(the - wait will frequently fail... cause writing function return error) - - 2. Do NOT wait for DRQ clear after all data readed.(the wait greatly - slow down writing performance by 100 times!) - - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN OUT *Buffer - buffer contained data transferred from device to host. - - UINT32 IN ByteCount - data size in byte unit of the buffer. - - UINT8 IN AtaCommand - value of the Command Register - - EFI_LBA IN StartLba - the start LBA of this transaction - - UINT16 IN SectorCount - the count of sectors to be transfered - - Returns: - - EFI_SUCCESS - send out the ATA command and device send required - data successfully. - - EFI_DEVICE_ERROR - command sent failed. - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: AtaCommand - add argument and description to function comment -// TODO: StartLba - add argument and description to function comment -// TODO: SectorCount - add argument and description to function comment { UINT8 DevSel; UINT8 SectorCount8; @@ -1864,6 +1591,33 @@ AtaPioDataInExt ( return CheckErrorStatus (IdeDev); } +/** + This function is used to send out ATA commands conforms to the + PIO Data Out Protocol, supporting ATA/ATAPI-6 standard + + Comparing with ATA-3 data out protocol, we have two differents here:
+ 1. Do NOT wait for DRQ clear before sending command into IDE device.(the + wait will frequently fail... cause writing function return error) + + 2. Do NOT wait for DRQ clear after all data readed.(the wait greatly + slow down writing performance by 100 times!) + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] *Buffer buffer contained data transferred from host to device. + @param[in] ByteCount data size in byte unit of the buffer. + @param[in] AtaCommand value of the Command Register + @param[in] StartLba the start LBA of this transaction + @param[in] SectorCount the count of sectors to be transfered + + @retval EFI_SUCCESS send out the ATA command and device receive required + data successfully. + + @retval EFI_DEVICE_ERROR command sent failed. + +**/ EFI_STATUS AtaPioDataOutExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1873,62 +1627,6 @@ AtaPioDataOutExt ( IN EFI_LBA StartLba, IN UINT16 SectorCount ) -/*++ - Name: - - AtaPioDataOutExt - - Purpose: - - This function is used to send out ATA commands conforms to the - PIO Data Out Protocol, supporting ATA/ATAPI-6 standard - - Comparing with ATA-3 data out protocol, we have two differents here: - 1. Do NOT wait for DRQ clear before sending command into IDE device.(the - wait will frequently fail... cause writing function return error) - - 2. Do NOT wait for DRQ clear after all data readed.(the wait greatly - slow down writing performance by 100 times!) - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *Buffer - buffer contained data transferred from host to device. - - UINT32 IN ByteCount - data size in byte unit of the buffer. - - UINT8 IN AtaCommand - value of the Command Register - - EFI_LBA IN StartLba - the start LBA of this transaction - - UINT16 IN SectorCount - the count of sectors to be transfered - - Returns: - - EFI_SUCCESS - send out the ATA command and device receive required - data successfully. - - EFI_DEVICE_ERROR - command sent failed. - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: AtaCommand - add argument and description to function comment -// TODO: StartLba - add argument and description to function comment -// TODO: SectorCount - add argument and description to function comment { UINT8 DevSel; UINT8 SectorCount8; @@ -2055,31 +1753,18 @@ AtaPioDataOutExt ( } +/** + Enable SMART of the disk if supported + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure,used + to record all the information of the IDE device. + +**/ VOID AtaSMARTSupport ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - AtaSMARTSupport - - Purpose: - - Enable SMART of the disk if supported - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure,used - to record all the information of the IDE device. - - Returns: - - NONE ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment { EFI_STATUS Status; BOOLEAN SMARTSupported; @@ -2213,6 +1898,20 @@ AtaSMARTSupport ( return ; } +/** + Send ATA Ext command into device with NON_DATA protocol + + @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 + + @retval EFI_SUCCESS Reading succeed + @retval EFI_DEVICE_ERROR Error executing commands on this device + +**/ EFI_STATUS AtaCommandIssueExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -2222,27 +1921,6 @@ AtaCommandIssueExt ( IN UINT16 SectorCount, IN EFI_LBA LbaAddress ) -/*++ - -Routine Description: - - Send ATA Ext command into device with NON_DATA protocol - -Arguments: - - IdeDev - Standard IDE device private data structure - AtaCommand - The ATA command to be sent - Device - The value in Device register - Feature - The value in Feature register - SectorCount - The value in SectorCount register - LbaAddress - The LBA address in 48-bit mode - -Returns: - - EFI_SUCCESS - Reading succeed - EFI_DEVICE_ERROR - Error executing commands on this device - ---*/ { EFI_STATUS Status; UINT8 SectorCount8; @@ -2332,6 +2010,20 @@ Returns: return EFI_SUCCESS; } +/** + Send ATA Ext command into device with NON_DATA protocol + + @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 + + @retval EFI_SUCCESS Reading succeed + @retval EFI_DEVICE_ERROR Error executing commands on this device + +**/ EFI_STATUS AtaCommandIssue ( IN IDE_BLK_IO_DEV *IdeDev, @@ -2341,27 +2033,6 @@ AtaCommandIssue ( IN UINT16 SectorCount, IN EFI_LBA LbaAddress ) -/*++ - -Routine Description: - - Send ATA Ext command into device with NON_DATA protocol - -Arguments: - - IdeDev - Standard IDE device private data structure - AtaCommand - The ATA command to be sent - Device - The value in Device register - Feature - The value in Feature register - SectorCount - The value in SectorCount register - LbaAddress - The LBA address in 48-bit mode - -Returns: - - EFI_SUCCESS - Reading succeed - EFI_DEVICE_ERROR - Error executing commands on this device - ---*/ { EFI_STATUS Status; UINT8 SectorCount8; @@ -2437,6 +2108,29 @@ Returns: return EFI_SUCCESS; } +/** + This function is called by the AtaBlkIoReadBlocks() to perform + reading from media in block unit. The function has been enhanced to + support >120GB access and transfer at most 65536 blocks per command + + @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 destination buffer for the data. + + @param[in] StartLba The starting logical block address to read from + on the device media. + + @param[in] NumberOfBlocks The number of transfer data blocks. + + @return The device status of UDMA operation. If the operation is + successful, return EFI_SUCCESS. + + TODO: EFI_UNSUPPORTED - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment +**/ EFI_STATUS AtaUdmaReadExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -2444,49 +2138,6 @@ AtaUdmaReadExt ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - Name: - - AtaUdmaReadExt - - Purpose: - - This function is called by the AtaBlkIoReadBlocks() to perform - reading from media in block unit. The function has been enhanced to - support >120GB access and transfer at most 65536 blocks per command - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *DataBuffer - A pointer to the destination buffer for the data. - - EFI_LBA IN StartLba - The starting logical block address to read from - on the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - - The device status of UDMA operation. If the operation is - successful, return EFI_SUCCESS. - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: DataBuffer - add argument and description to function comment -// TODO: StartLba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment { IDE_DMA_PRD *PrdAddr; IDE_DMA_PRD *UsedPrdAddr; @@ -2752,6 +2403,28 @@ AtaUdmaReadExt ( return EFI_SUCCESS; } +/** + This function is called by the AtaBlkIoReadBlocks() to perform + reading from media in block unit. The function has been enhanced to + support >120GB access and transfer at most 65536 blocks per command + + @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 destination buffer for the data. + @param[in] StartLba The starting logical block address to read from + on the device media. + @param[in] NumberOfBlocks The number of transfer data blocks. + + @return The device status of UDMA operation. If the operation is + successful, return EFI_SUCCESS. + + TODO: EFI_UNSUPPORTED - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment +**/ EFI_STATUS AtaUdmaRead ( IN IDE_BLK_IO_DEV *IdeDev, @@ -2759,49 +2432,6 @@ AtaUdmaRead ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - Name: - - AtaUdmaRead - - Purpose: - - This function is called by the AtaBlkIoReadBlocks() to perform - reading from media in block unit. The function has been enhanced to - support >120GB access and transfer at most 65536 blocks per command - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *DataBuffer - A pointer to the destination buffer for the data. - - EFI_LBA IN StartLba - The starting logical block address to read from - on the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - - The device status of UDMA operation. If the operation is - successful, return EFI_SUCCESS. - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: DataBuffer - add argument and description to function comment -// TODO: StartLba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment { IDE_DMA_PRD *PrdAddr; IDE_DMA_PRD *UsedPrdAddr; @@ -3066,6 +2696,28 @@ AtaUdmaRead ( return EFI_SUCCESS; } +/** + This function is called by the AtaBlkIoWriteBlocks() to perform + writing to media in block unit. The function has been enhanced to + support >120GB access and transfer at most 65536 blocks per command + + @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. + + @return The device status of UDMA operation. If the operation is + successful, return EFI_SUCCESS. + + TODO: EFI_UNSUPPORTED - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment +**/ EFI_STATUS AtaUdmaWriteExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -3073,48 +2725,6 @@ AtaUdmaWriteExt ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - Name: - - AtaUdmaWriteExt - - Purpose: - - This function is called by the AtaBlkIoWriteBlocks() to perform - writing to media in block unit. The function has been enhanced to - support >120GB access and transfer at most 65536 blocks per command - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *DataBuffer - A pointer to the source buffer for the data. - - EFI_LBA IN StartLba - The starting logical block address to write to - on the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - - The device status of UDMA operation. If the operation is - successful, return EFI_SUCCESS. - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: DataBuffer - add argument and description to function comment -// TODO: StartLba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment { IDE_DMA_PRD *PrdAddr; IDE_DMA_PRD *UsedPrdAddr; @@ -3377,6 +2987,32 @@ AtaUdmaWriteExt ( return EFI_SUCCESS; } +/** + This function is called by the AtaBlkIoWriteBlocks() to perform + writing to media in block unit. The function has been enhanced to + support >120GB access and transfer at most 65536 blocks per command + + @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. + + @return The device status of UDMA operation. If the operation is + successful, return EFI_SUCCESS. + + TODO: EFI_UNSUPPORTED - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment +**/ EFI_STATUS AtaUdmaWrite ( IN IDE_BLK_IO_DEV *IdeDev, @@ -3384,48 +3020,6 @@ AtaUdmaWrite ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - Name: - - AtaUdmaWrite - - Purpose: - - This function is called by the AtaBlkIoWriteBlocks() to perform - writing to media in block unit. The function has been enhanced to - support >120GB access and transfer at most 65536 blocks per command - - Parameters: - - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *DataBuffer - A pointer to the source buffer for the data. - - EFI_LBA IN StartLba - The starting logical block address to write to - on the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - - The device status of UDMA operation. If the operation is - successful, return EFI_SUCCESS. - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: DataBuffer - add argument and description to function comment -// TODO: StartLba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment { IDE_DMA_PRD *PrdAddr; IDE_DMA_PRD *UsedPrdAddr; diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c index fa004e3d7f..7043306642 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c @@ -1,67 +1,50 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: +**/ - atapi.c - -Abstract: - +#include "idebus.h" -Revision History ---*/ +/** + This function is used to get the current status of the media residing + in the LS-120 drive or ZIP drive. The media status is returned in the + Error Status. -#include "idebus.h" + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @retval EFI_SUCCESS + The media status is achieved successfully and the media + can be read/written. + + @retval EFI_DEVICE_ERROR + Get Media Status Command is failed. + + @retval EFI_NO_MEDIA + There is no media in the drive. + + @retval EFI_WRITE_PROTECTED + The media is writing protected. + @note + This function must be called after the LS120EnableMediaStatus() + with second parameter set to TRUE + (means enable media status notification) is called. + +**/ STATIC EFI_STATUS LS120GetMediaStatus ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - LS120GetMediaStatus - - Purpose: - This function is used to get the current status of the media residing - in the LS-120 drive or ZIP drive. The media status is returned in the - Error Status. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - Returns: - EFI_SUCCESS - The media status is achieved successfully and the media - can be read/written. - - EFI_DEVICE_ERROR - Get Media Status Command is failed. - - EFI_NO_MEDIA - There is no media in the drive. - - EFI_WRITE_PROTECTED - The media is writing protected. - - Notes: - This function must be called after the LS120EnableMediaStatus() - with second parameter set to TRUE - (means enable media status notification) is called. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment { UINT8 DeviceSelect; UINT8 StatusValue; @@ -119,43 +102,31 @@ LS120GetMediaStatus ( } } +/** + This function is used to send Enable Media Status Notification Command + or Disable Media Status Notification Command. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] Enable + a flag that indicates whether enable or disable media + status notification. + + @retval EFI_SUCCESS + If command completes successfully. + + @retval EFI_DEVICE_ERROR + If command failed. + +**/ STATIC EFI_STATUS LS120EnableMediaStatus ( IN IDE_BLK_IO_DEV *IdeDev, IN BOOLEAN Enable ) -/*++ - Name: - LS120EnableMediaStatus - - Purpose: - This function is used to send Enable Media Status Notification Command - or Disable Media Status Notification Command. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - BOOLEAN IN Enable - a flag that indicates whether enable or disable media - status notification. - - Returns: - EFI_SUCCESS - If command completes successfully. - - EFI_DEVICE_ERROR - If command failed. - - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Enable - add argument and description to function comment { UINT8 DeviceSelect; EFI_STATUS Status; @@ -211,60 +182,51 @@ LS120EnableMediaStatus ( return EFI_SUCCESS; } +/** + 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[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @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. + + @note + Parameter "IdeDev" will be updated in this function. + + TODO: EFI_OUT_OF_RESOURCES - add return value to function comment + TODO: EFI_OUT_OF_RESOURCES - add return value to function comment +**/ EFI_STATUS ATAPIIdentify ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - ATAPIIdentify - - - Purpose: - 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 - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - Returns: - EFI_SUCCESS - Identify ATAPI device successfully. - - EFI_DEVICE_ERROR - ATAPI Identify Device Command failed or device type - is not supported by this IDE driver. - - Notes: - Parameter "IdeDev" will be updated in this function. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment { EFI_IDENTIFY_DATA *AtapiIdentifyPointer; UINT8 DeviceSelect; @@ -409,35 +371,28 @@ ATAPIIdentify ( return EFI_SUCCESS; } +/** + Sends out ATAPI Inquiry Packet Command to the specified device. + This command will return INQUIRY data of the device. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @retval EFI_SUCCESS + Inquiry command completes successfully. + + @retval EFI_DEVICE_ERROR + Inquiry command failed. + + @note + Parameter "IdeDev" will be updated in this function. + +**/ EFI_STATUS AtapiInquiry ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - AtapiInquiry - - Purpose: - Sends out ATAPI Inquiry Packet Command to the specified device. - This command will return INQUIRY data of the device. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - Returns: - EFI_SUCCESS - Inquiry command completes successfully. - - EFI_DEVICE_ERROR - Inquiry command failed. - Notes: - Parameter "IdeDev" will be updated in this function. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment { ATAPI_PACKET_COMMAND Packet; EFI_STATUS Status; @@ -476,6 +431,36 @@ AtapiInquiry ( return EFI_SUCCESS; } +/** + This function is used to send out ATAPI commands conforms to the + Packet Command with PIO Data In Protocol. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] *Packet + pointer pointing to ATAPI_PACKET_COMMAND data structure + which contains the contents of the command. + + @param[in] *Buffer + buffer contained data transferred from device to host. + + @param[in] ByteCount + data size in byte unit of the buffer. + + @param[in] TimeOut + this parameter is used to specify the timeout + value for the PioReadWriteData() function. + + @retval EFI_SUCCESS + send out the ATAPI packet command successfully + and device sends data successfully. + + @retval EFI_DEVICE_ERROR + the device failed to send data. + +**/ EFI_STATUS AtapiPacketCommandIn ( IN IDE_BLK_IO_DEV *IdeDev, @@ -484,50 +469,6 @@ AtapiPacketCommandIn ( IN UINT32 ByteCount, IN UINTN TimeOut ) -/*++ - Name: - AtapiPacketCommandIn - - Purpose: - This function is used to send out ATAPI commands conforms to the - Packet Command with PIO Data In Protocol. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - ATAPI_PACKET_COMMAND IN *Packet - pointer pointing to ATAPI_PACKET_COMMAND data structure - which contains the contents of the command. - - UINT16 IN *Buffer - buffer contained data transferred from device to host. - - UINT32 IN ByteCount - data size in byte unit of the buffer. - - UINTN IN TimeOut - this parameter is used to specify the timeout - value for the PioReadWriteData() function. - - Returns: - EFI_SUCCESS - send out the ATAPI packet command successfully - and device sends data successfully. - - EFI_DEVICE_ERROR - the device failed to send data. - - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Packet - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: TimeOut - add argument and description to function comment { UINT16 *CommandIndex; EFI_STATUS Status; @@ -605,6 +546,36 @@ AtapiPacketCommandIn ( return PioReadWriteData (IdeDev, Buffer, ByteCount, 1, TimeOut); } +/** + This function is used to send out ATAPI commands conforms to the + Packet Command with PIO Data Out Protocol. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] *Packet + pointer pointing to ATAPI_PACKET_COMMAND data structure + which contains the contents of the command. + + @param[in] *Buffer + buffer contained data transferred from host to device. + + @param[in] ByteCount + data size in byte unit of the buffer. + + @param[in] TimeOut + this parameter is used to specify the timeout + value for the PioReadWriteData() function. + + @retval EFI_SUCCESS + send out the ATAPI packet command successfully + and device received data successfully. + + @retval EFI_DEVICE_ERROR + the device failed to send data. + +**/ EFI_STATUS AtapiPacketCommandOut ( IN IDE_BLK_IO_DEV *IdeDev, @@ -613,51 +584,6 @@ AtapiPacketCommandOut ( IN UINT32 ByteCount, IN UINTN TimeOut ) -/*++ - Name: - AtapiPacketCommandOut - - Purpose: - This function is used to send out ATAPI commands conforms to the - Packet Command with PIO Data Out Protocol. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - ATAPI_PACKET_COMMAND IN *Packet - pointer pointing to ATAPI_PACKET_COMMAND data structure - which contains the contents of the command. - - VOID IN *Buffer - buffer contained data transferred from host to device. - - UINT32 IN ByteCount - data size in byte unit of the buffer. - - UINTN IN TimeOut - this parameter is used to specify the timeout - value for the PioReadWriteData() function. - - Returns: - EFI_SUCCESS - send out the ATAPI packet command successfully - and device received data successfully. - - EFI_DEVICE_ERROR - the device failed to send data. - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Packet - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: TimeOut - add argument and description to function comment { UINT16 *CommandIndex; EFI_STATUS Status; @@ -733,6 +659,38 @@ AtapiPacketCommandOut ( return PioReadWriteData (IdeDev, Buffer, ByteCount, 0, TimeOut); } +/** + This function is called by either AtapiPacketCommandIn() or + AtapiPacketCommandOut(). It is used to transfer data between + host and device. The data direction is specified by the fourth + parameter. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] *Buffer + buffer contained data transferred between host and device. + + @param[in] ByteCount + data size in byte unit of the buffer. + + @param[in] Read + flag used to determine the data transfer direction. + Read equals 1, means data transferred from device to host; + Read equals 0, means data transferred from host to device. + + @param[in] TimeOut + timeout value for wait DRQ ready before each data + stream's transfer. + + @retval EFI_SUCCESS + data is transferred successfully. + + @retval EFI_DEVICE_ERROR + the device failed to transfer data. + +**/ EFI_STATUS PioReadWriteData ( IN IDE_BLK_IO_DEV *IdeDev, @@ -741,54 +699,6 @@ PioReadWriteData ( IN BOOLEAN Read, IN UINTN TimeOut ) -/*++ - Name: - PioReadWriteData - - Purpose: - This function is called by either AtapiPacketCommandIn() or - AtapiPacketCommandOut(). It is used to transfer data between - host and device. The data direction is specified by the fourth - parameter. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *Buffer - buffer contained data transferred between host and device. - - UINT32 IN ByteCount - data size in byte unit of the buffer. - - BOOLEAN IN Read - flag used to determine the data transfer direction. - Read equals 1, means data transferred from device to host; - Read equals 0, means data transferred from host to device. - - UINTN IN TimeOut - timeout value for wait DRQ ready before each data - stream's transfer. - - Returns: - EFI_SUCCESS - data is transferred successfully. - - EFI_DEVICE_ERROR - the device failed to transfer data. - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: ByteCount - add argument and description to function comment -// TODO: Read - add argument and description to function comment -// TODO: TimeOut - add argument and description to function comment { // // required transfer data in word unit. @@ -888,36 +798,25 @@ PioReadWriteData ( return CheckErrorStatus (IdeDev); } +/** + Sends out ATAPI Test Unit Ready Packet Command to the specified device + to find out whether device is accessible. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @retval EFI_SUCCESS + device is accessible. + + @retval EFI_DEVICE_ERROR + device is not accessible. + +**/ EFI_STATUS AtapiTestUnitReady ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - AtapiTestUnitReady - - Purpose: - Sends out ATAPI Test Unit Ready Packet Command to the specified device - to find out whether device is accessible. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - Returns: - EFI_SUCCESS - device is accessible. - - EFI_DEVICE_ERROR - device is not accessible. - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment { ATAPI_PACKET_COMMAND Packet; EFI_STATUS Status; @@ -935,50 +834,38 @@ AtapiTestUnitReady ( return Status; } -EFI_STATUS -AtapiRequestSense ( - IN IDE_BLK_IO_DEV *IdeDev, - OUT UINTN *SenseCounts - ) -/*++ - Name: - AtapiRequestSense - - Purpose: - Sends out ATAPI Request Sense Packet Command to the specified device. - This command will return all the current Sense data in the device. - This function will pack all the Sense data in one single buffer. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. +/** + Sends out ATAPI Request Sense Packet Command to the specified device. + This command will return all the current Sense data in the device. + This function will pack all the Sense data in one single buffer. - UINT16 OUT **SenseBuffers - allocated in this function, and freed by the calling function. - This buffer is used to accommodate all the sense data returned - by the device. + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. - UINTN OUT *BufUnit - record the unit size of the sense data block in the SenseBuffers, + @param[out] **SenseBuffers + allocated in this function, and freed by the calling function. + This buffer is used to accommodate all the sense data returned + by the device. - UINTN OUT *BufNumbers - record the number of units in the SenseBuffers. + @param[out] *BufUnit + record the unit size of the sense data block in the SenseBuffers, - Returns: - EFI_SUCCESS - Request Sense command completes successfully. + @param[out] *BufNumbers + record the number of units in the SenseBuffers. - EFI_DEVICE_ERROR - Request Sense command failed. - - Notes: + @retval EFI_SUCCESS + Request Sense command completes successfully. + + @retval EFI_DEVICE_ERROR + Request Sense command failed. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: SenseCounts - add argument and description to function comment +**/ +EFI_STATUS +AtapiRequestSense ( + IN IDE_BLK_IO_DEV *IdeDev, + OUT UINTN *SenseCounts + ) { EFI_STATUS Status; REQUEST_SENSE_DATA *Sense; @@ -1053,45 +940,36 @@ AtapiRequestSense ( return EFI_SUCCESS; } +/** + Sends out ATAPI Read Capacity Packet Command to the specified device. + This command will return the information regarding the capacity of the + media in the device. + + Current device status will impact device's response to the Read Capacity + Command. For example, if the device once reset, the Read Capacity + Command will fail. The Sense data record the current device status, so + if the Read Capacity Command failed, the Sense data must be requested + and be analyzed to determine if the Read Capacity Command should retry. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @retval EFI_SUCCESS + Read Capacity Command finally completes successfully. + + @retval EFI_DEVICE_ERROR + Read Capacity Command failed because of device error. + + @note + parameter "IdeDev" will be updated in this function. + + TODO: EFI_NOT_READY - add return value to function comment +**/ EFI_STATUS AtapiReadCapacity ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - AtapiReadCapacity - - Purpose: - Sends out ATAPI Read Capacity Packet Command to the specified device. - This command will return the information regarding the capacity of the - media in the device. - - Current device status will impact device's response to the Read Capacity - Command. For example, if the device once reset, the Read Capacity - Command will fail. The Sense data record the current device status, so - if the Read Capacity Command failed, the Sense data must be requested - and be analyzed to determine if the Read Capacity Command should retry. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - Returns: - EFI_SUCCESS - Read Capacity Command finally completes successfully. - - EFI_DEVICE_ERROR - Read Capacity Command failed because of device error. - - Notes: - parameter "IdeDev" will be updated in this function. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: EFI_NOT_READY - add return value to function comment { // // status returned by Read Capacity Packet Command @@ -1207,48 +1085,39 @@ AtapiReadCapacity ( } } +/** + Used before read/write blocks from/to ATAPI device media. + Since ATAPI device media is removable, it is necessary to detect + whether media is present and get current present media's + information, and if media has been changed, Block I/O Protocol + need to be reinstalled. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[out] *MediaChange + return value that indicates if the media of the device has been + changed. + + @retval EFI_SUCCESS + media found successfully. + + @retval EFI_DEVICE_ERROR + any error encounters during media detection. + + @retval EFI_NO_MEDIA + media not found. + + @note + parameter IdeDev may be updated in this function. + +**/ EFI_STATUS AtapiDetectMedia ( IN IDE_BLK_IO_DEV *IdeDev, OUT BOOLEAN *MediaChange ) -/*++ - Name: - AtapiDetectMedia - - Purpose: - Used before read/write blocks from/to ATAPI device media. - Since ATAPI device media is removable, it is necessary to detect - whether media is present and get current present media's - information, and if media has been changed, Block I/O Protocol - need to be reinstalled. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - BOOLEAN OUT *MediaChange - return value that indicates if the media of the device has been - changed. - - Returns: - EFI_SUCCESS - media found successfully. - - EFI_DEVICE_ERROR - any error encounters during media detection. - - EFI_NO_MEDIA - media not found. - - Notes: - parameter IdeDev may be updated in this function. ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: MediaChange - add argument and description to function comment { EFI_STATUS Status; EFI_STATUS ReadCapacityStatus; @@ -1558,6 +1427,35 @@ AtapiDetectMedia ( } +/** + This function is called by the AtapiBlkIoReadBlocks() to perform + read from media in block unit. + + The main command used to access media here is READ(10) Command. + READ(10) Command requests that the ATAPI device media transfer + specified data to the host. Data is transferred in block(sector) + unit. The maximum number of blocks that can be transferred once is + 65536. This is the main difference between READ(10) and READ(12) + Command. The maximum number of blocks in READ(12) is 2 power 32. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] *Buffer + A pointer to the destination buffer for the data. + + @param[in] Lba + The starting logical block address to read from + on the device media. + + @param[in] NumberOfBlocks + The number of transfer data blocks. + + @return status is fully dependent on the return status + of AtapiPacketCommandIn() function. + +**/ EFI_STATUS AtapiReadSectors ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1565,49 +1463,6 @@ AtapiReadSectors ( IN EFI_LBA Lba, IN UINTN NumberOfBlocks ) -/*++ - Name: - AtapiReadSectors - - Purpose: - This function is called by the AtapiBlkIoReadBlocks() to perform - read from media in block unit. - - The main command used to access media here is READ(10) Command. - READ(10) Command requests that the ATAPI device media transfer - specified data to the host. Data is transferred in block(sector) - unit. The maximum number of blocks that can be transferred once is - 65536. This is the main difference between READ(10) and READ(12) - Command. The maximum number of blocks in READ(12) is 2 power 32. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *Buffer - A pointer to the destination buffer for the data. - - EFI_LBA IN Lba - The starting logical block address to read from - on the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - return status is fully dependent on the return status - of AtapiPacketCommandIn() function. - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: Lba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment { ATAPI_PACKET_COMMAND Packet; @@ -1699,6 +1554,33 @@ AtapiReadSectors ( return Status; } +/** + This function is called by the AtapiBlkIoWriteBlocks() to perform + write onto media in block unit. + The main command used to access media here is Write(10) Command. + Write(10) Command requests that the ATAPI device media transfer + specified data to the host. Data is transferred in block (sector) + unit. The maximum number of blocks that can be transferred once is + 65536. + + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] *Buffer + A pointer to the source buffer for the data. + + @param[in] Lba + The starting logical block address to write onto + the device media. + + @param[in] NumberOfBlocks + The number of transfer data blocks. + + @return status is fully dependent on the return status + of AtapiPacketCommandOut() function. + +**/ EFI_STATUS AtapiWriteSectors ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1706,47 +1588,6 @@ AtapiWriteSectors ( IN EFI_LBA Lba, IN UINTN NumberOfBlocks ) -/*++ - Name: - AtapiWriteSectors - - Purpose: - This function is called by the AtapiBlkIoWriteBlocks() to perform - write onto media in block unit. - The main command used to access media here is Write(10) Command. - Write(10) Command requests that the ATAPI device media transfer - specified data to the host. Data is transferred in block (sector) - unit. The maximum number of blocks that can be transferred once is - 65536. - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - VOID IN *Buffer - A pointer to the source buffer for the data. - - EFI_LBA IN Lba - The starting logical block address to write onto - the device media. - - UINTN IN NumberOfBlocks - The number of transfer data blocks. - - Returns: - return status is fully dependent on the return status - of AtapiPacketCommandOut() function. - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: Lba - add argument and description to function comment -// TODO: NumberOfBlocks - add argument and description to function comment { ATAPI_PACKET_COMMAND Packet; @@ -1834,45 +1675,33 @@ AtapiWriteSectors ( return Status; } +/** + 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[in] *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. + +**/ EFI_STATUS AtapiSoftReset ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Name: - AtapiSoftReset - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - Returns: - EFI_SUCCESS - Soft reset completes successfully. - - EFI_DEVICE_ERROR - Any step during the reset process is failed. - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment { UINT8 Command; UINT8 DeviceSelect; @@ -1906,6 +1735,50 @@ AtapiSoftReset ( return EFI_SUCCESS; } +/** + This function is the ATAPI implementation for ReadBlocks in the + Block I/O Protocol interface. + + @param[in] *IdeBlkIoDev + Indicates the calling context. + + @param[in] MediaId + The media id that the read request is for. + + @param[in] LBA + The starting logical block address to read from + on the device. + + @param[in] BufferSize + The size of the Buffer in bytes. This must be a + multiple of the intrinsic block size of the device. + + @param[out] *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 ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice, @@ -1914,65 +1787,6 @@ AtapiBlkIoReadBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - Name: - AtapiBlkIoReadBlocks - - Purpose: - This function is the ATAPI implementation for ReadBlocks in the - Block I/O Protocol interface. - - Parameters: - IDE_BLK_IO_DEV IN *IdeBlkIoDev - Indicates the calling context. - - UINT32 IN MediaId - The media id that the read request is for. - - EFI_LBA IN LBA - The starting logical block address to read from - on the device. - - UINTN IN BufferSize - The size of the Buffer in bytes. This must be a - multiple of the intrinsic block size of the device. - - VOID OUT *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. - - Returns: - EFI_SUCCESS - Read Blocks successfully. - - EFI_DEVICE_ERROR - Read Blocks failed. - - EFI_NO_MEDIA - There is no media in the device. - - EFI_MEDIA_CHANGED - The MediaId is not for the current media. - - EFI_BAD_BUFFER_SIZE - The BufferSize parameter is not a multiple of the - intrinsic block size of the device. - - EFI_INVALID_PARAMETER - The read request contains LBAs that are not valid, - or the data buffer is not valid. - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeBlkIoDevice - add argument and description to function comment -// TODO: MediaId - add argument and description to function comment -// TODO: LBA - add argument and description to function comment -// TODO: BufferSize - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment { EFI_BLOCK_IO_MEDIA *Media; UINTN BlockSize; @@ -2074,6 +1888,53 @@ AtapiBlkIoReadBlocks ( } +/** + This function is the ATAPI implementation for WriteBlocks in the + Block I/O Protocol interface. + + @param[in] *This + Indicates the calling context. + + @param[in] MediaId + The media id that the write request is for. + + @param[in] LBA + The starting logical block address to write onto + the device. + + @param[in] BufferSize + The size of the Buffer in bytes. This must be a + multiple of the intrinsic block size of the device. + + @param[out] *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. + + @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. + + TODO: EFI_MEDIA_CHANGED - add return value to function comment + TODO: EFI_WRITE_PROTECTED - add return value to function comment +**/ EFI_STATUS AtapiBlkIoWriteBlocks ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice, @@ -2082,68 +1943,6 @@ AtapiBlkIoWriteBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - Name: - AtapiBlkIoWriteBlocks - - Purpose: - This function is the ATAPI implementation for WriteBlocks in the - Block I/O Protocol interface. - - Parameters: - EFI_BLOCK_IO IN *This - Indicates the calling context. - - UINT32 IN MediaId - The media id that the write request is for. - - EFI_LBA IN LBA - The starting logical block address to write onto - the device. - - UINTN IN BufferSize - The size of the Buffer in bytes. This must be a - multiple of the intrinsic block size of the device. - - VOID OUT *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. - - Returns: - EFI_SUCCESS - Write Blocks successfully. - - EFI_DEVICE_ERROR - Write Blocks failed. - - EFI_NO_MEDIA - There is no media in the device. - - EFI_MEDIA_CHANGE - The MediaId is not for the current media. - - EFI_BAD_BUFFER_SIZE - The BufferSize parameter is not a multiple of the - intrinsic block size of the device. - - EFI_INVALID_PARAMETER - The write request contains LBAs that are not valid, - or the data buffer is not valid. - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeBlkIoDevice - add argument and description to function comment -// TODO: MediaId - add argument and description to function comment -// TODO: LBA - add argument and description to function comment -// TODO: BufferSize - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: EFI_MEDIA_CHANGED - add return value to function comment -// TODO: EFI_WRITE_PROTECTED - add return value to function comment { EFI_BLOCK_IO_MEDIA *Media; @@ -2243,27 +2042,20 @@ AtapiBlkIoWriteBlocks ( // which are used to parse sense key returned by the device. // -BOOLEAN -IsNoMedia ( - IN REQUEST_SENSE_DATA *SenseData, - IN UINTN SenseCounts - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - -Returns: + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description TODO: add return values ---*/ +**/ +BOOLEAN +IsNoMedia ( + IN REQUEST_SENSE_DATA *SenseData, + IN UINTN SenseCounts + ) { REQUEST_SENSE_DATA *SensePointer; UINTN Index; @@ -2289,35 +2081,23 @@ Returns: return NoMedia; } +/** + Test if the device meets a media error after media changed + + @param[in] *SenseData + pointer pointing to ATAPI device sense data list. + @param[in] SenseCounts + sense data number of the list + + @retval TRUE Device meets a media error + @retval FALSE No media error + +**/ BOOLEAN IsMediaError ( IN REQUEST_SENSE_DATA *SenseData, IN UINTN SenseCounts ) -/*++ - Name: - IsMediaError - - Purpose: - Test if the device meets a media error after media changed - - Parameters: - EQUEST_SENSE_DATA IN *SenseData - pointer pointing to ATAPI device sense data list. - UINTN IN SenseCounts - sense data number of the list - - Returns: - TRUE - Device meets a media error - - FALSE - No media error ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: SenseData - add argument and description to function comment -// TODO: SenseCounts - add argument and description to function comment { REQUEST_SENSE_DATA *SensePointer; UINTN Index; @@ -2375,27 +2155,20 @@ IsMediaError ( return IsError; } -BOOLEAN -IsMediaChange ( - IN REQUEST_SENSE_DATA *SenseData, - IN UINTN SenseCounts - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - -Returns: + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description TODO: add return values ---*/ +**/ +BOOLEAN +IsMediaChange ( + IN REQUEST_SENSE_DATA *SenseData, + IN UINTN SenseCounts + ) { REQUEST_SENSE_DATA *SensePointer; UINTN Index; @@ -2420,29 +2193,22 @@ Returns: return IsMediaChange; } +/** + TODO: Add function description + + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description + @param NeedRetry TODO: add argument description + + TODO: add return values + +**/ BOOLEAN IsDriveReady ( IN REQUEST_SENSE_DATA *SenseData, IN UINTN SenseCounts, OUT BOOLEAN *NeedRetry ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - NeedRetry - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { REQUEST_SENSE_DATA *SensePointer; UINTN Index; @@ -2496,27 +2262,20 @@ Returns: return IsReady; } -BOOLEAN -HaveSenseKey ( - IN REQUEST_SENSE_DATA *SenseData, - IN UINTN SenseCounts - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - -Returns: + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description TODO: add return values ---*/ +**/ +BOOLEAN +HaveSenseKey ( + IN REQUEST_SENSE_DATA *SenseData, + IN UINTN SenseCounts + ) { BOOLEAN Have; @@ -2533,29 +2292,22 @@ Returns: return Have; } +/** + TODO: Add function description + + @param IdeDev TODO: add argument description + @param WriteProtected TODO: add argument description + + @retval EFI_DEVICE_ERROR TODO: Add description for return value + @retval EFI_DEVICE_ERROR TODO: Add description for return value + @retval EFI_SUCCESS TODO: Add description for return value + +**/ EFI_STATUS IsLS120orZipWriteProtected ( IN IDE_BLK_IO_DEV *IdeDev, OUT BOOLEAN *WriteProtected ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - IdeDev - TODO: add argument description - WriteProtected - TODO: add argument description - -Returns: - - EFI_DEVICE_ERROR - TODO: Add description for return value - EFI_DEVICE_ERROR - TODO: Add description for return value - EFI_SUCCESS - TODO: Add description for return value - ---*/ { EFI_STATUS Status; diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c index d318fd23df..c41d995879 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c @@ -1,50 +1,34 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - ide.c - -Abstract: - - -Revision History ---*/ +**/ #include "idebus.h" BOOLEAN SlaveDeviceExist = FALSE; BOOLEAN MasterDeviceExist = FALSE; -UINT8 -IDEReadPortB ( - IN EFI_PCI_IO_PROTOCOL *PciIo, - IN UINT16 Port - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description TODO: add return values ---*/ +**/ +UINT8 +IDEReadPortB ( + IN EFI_PCI_IO_PROTOCOL *PciIo, + IN UINT16 Port + ) { UINT8 Data; @@ -63,6 +47,17 @@ Returns: return Data; } +/** + 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 + + @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 IDEReadPortWMultiple ( IN EFI_PCI_IO_PROTOCOL *PciIo, @@ -70,23 +65,6 @@ IDEReadPortWMultiple ( IN UINTN Count, IN VOID *Buffer ) -/*++ - -Routine 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 - - -Arguments: - PciIo - Pointer to the EFI_PCI_IO instance - Port - IO port to read - Count - No. of UINT16's to read - Buffer - Pointer to the data buffer for read - -++*/ -// TODO: function comment should end with '--*/' -// TODO: function comment is missing 'Returns:' { UINT16 *AlignedBuffer; UINT16 *WorkingBuffer; @@ -127,29 +105,22 @@ Arguments: gBS->FreePool (WorkingBuffer); } +/** + 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 + +**/ VOID IDEWritePortB ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port, IN UINT8 Data ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - Data - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { // // perform 1-byte data write to register @@ -165,29 +136,22 @@ Returns: } +/** + 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 + +**/ VOID IDEWritePortW ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port, IN UINT16 Data ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - Data - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { // // perform 1-word data write to register @@ -202,6 +166,17 @@ Returns: ); } +/** + 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 + + @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 IDEWritePortWMultiple ( IN EFI_PCI_IO_PROTOCOL *PciIo, @@ -209,23 +184,6 @@ IDEWritePortWMultiple ( IN UINTN Count, IN VOID *Buffer ) -/*++ - -Routine 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 - - -Arguments: - PciIo - Pointer to the EFI_PCI_IO instance - Port - IO port to read - Count - No. of UINT16's to read - Buffer - Pointer to the data buffer for read - -++*/ -// TODO: function comment should end with '--*/' -// TODO: function comment is missing 'Returns:' { UINT16 *AlignedBuffer; UINT32 *WorkingBuffer; @@ -267,25 +225,18 @@ Arguments: gBS->FreePool (WorkingBuffer); } -BOOLEAN -BadIdeDeviceCheck ( - IN IDE_BLK_IO_DEV *IdeDev - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ +**/ +BOOLEAN +BadIdeDeviceCheck ( + IN IDE_BLK_IO_DEV *IdeDev + ) { // // check whether all registers return 0xff, @@ -341,63 +292,62 @@ Returns: // // GetIdeRegistersBaseAddr // -EFI_STATUS -GetIdeRegistersBaseAddr ( - IN EFI_PCI_IO_PROTOCOL *PciIo, - OUT IDE_REGISTERS_BASE_ADDR *IdeRegsBaseAddr - ) -/*++ - -Routine 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. - + The steps to get IDE IO port registers' base addresses for each channel as follows: 1. Examine the Programming Interface byte of the Class Code fields in PCI IDE - controller's Configuration Space to determine the operating mode. - + controller's Configuration Space to determine the operating mode. + 2. a) In 'Compatibility' mode, use fixed addresses shown in the Table 1 below. - ___________________________________________ - | | Command Block | Control Block | - | Channel | Registers | Registers | - |___________|_______________|_______________| - | Primary | 1F0h - 1F7h | 3F6h - 3F7h | - |___________|_______________|_______________| - | Secondary | 170h - 177h | 376h - 377h | - |___________|_______________|_______________| - - Table 1. Compatibility resource mappings - - 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. - ___________________________________________________ - | | 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 - 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. - + 
+  ___________________________________________
+  |           | Command Block | Control Block |
+  |  Channel  |   Registers   |   Registers   |
+  |___________|_______________|_______________|
+  |  Primary  |  1F0h - 1F7h  |  3F6h - 3F7h  |
+  |___________|_______________|_______________|
+  | Secondary |  170h - 177h  |  376h - 377h  |
+  |___________|_______________|_______________|
+
+  Table 1. Compatibility resource mappings
+
+ + 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. + 
+  ___________________________________________________
+  |           |   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
+
+ @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. - -Arguments: - PciIo - Pointer to the EFI_PCI_IO_PROTOCOL instance - IdeRegsBaseAddr - Pointer to IDE_REGISTERS_BASE_ADDR to - receive IDE IO port registers' base addresses - -Returns: - ---*/ + + @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 +GetIdeRegistersBaseAddr ( + IN EFI_PCI_IO_PROTOCOL *PciIo, + OUT IDE_REGISTERS_BASE_ADDR *IdeRegsBaseAddr + ) // TODO: EFI_UNSUPPORTED - add return value to function comment // TODO: EFI_UNSUPPORTED - add return value to function comment // TODO: EFI_SUCCESS - add return value to function comment @@ -464,24 +414,19 @@ Returns: return EFI_SUCCESS; } -EFI_STATUS -ReassignIdeResources ( - IN IDE_BLK_IO_DEV *IdeDev - ) -/*++ - -Routine 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. - -Arguments: - IdeDev - The BLK_IO private data which specifies the IDE device - -++*/ -// TODO: function comment should end with '--*/' -// TODO: function comment is missing 'Returns:' + + @param IdeDev The BLK_IO private data which specifies the IDE device + +**/ +EFI_STATUS +ReassignIdeResources ( + IN IDE_BLK_IO_DEV *IdeDev + ) // TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; @@ -519,22 +464,16 @@ Arguments: return EFI_SUCCESS; } +/** + Read SATA registers to detect SATA disks + + @param IdeDev The BLK_IO private data which specifies the IDE device + +**/ EFI_STATUS CheckPowerMode ( IDE_BLK_IO_DEV *IdeDev ) -/*++ - Routine Description: - - Read SATA registers to detect SATA disks - - Arguments: - - IdeDev - The BLK_IO private data which specifies the IDE device - -++*/ -// TODO: function comment should end with '--*/' -// TODO: function comment is missing 'Returns:' // TODO: EFI_NOT_FOUND - add return value to function comment // TODO: EFI_SUCCESS - add return value to function comment // TODO: EFI_NOT_FOUND - add return value to function comment @@ -579,22 +518,16 @@ CheckPowerMode ( // // DiscoverIdeDevice // +/** + Detect if there is disk connected to this port + + @param IdeDev The BLK_IO private data which specifies the IDE device + +**/ EFI_STATUS DiscoverIdeDevice ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - Routine Description: - - Detect if there is disk connected to this port - - Arguments: - - IdeDev - The BLK_IO private data which specifies the IDE device - -++*/ -// TODO: function comment should end with '--*/' -// TODO: function comment is missing 'Returns:' // TODO: EFI_NOT_FOUND - add return value to function comment // TODO: EFI_NOT_FOUND - add return value to function comment // TODO: EFI_SUCCESS - add return value to function comment @@ -662,54 +595,42 @@ DiscoverIdeDevice ( return EFI_SUCCESS; } -EFI_STATUS -DetectIDEController ( - IN IDE_BLK_IO_DEV *IdeDev - ) -/*++ - - Name: DetectIDEController - - - Purpose: - This function is called by DiscoverIdeDevice(). It is used for detect - whether the IDE device exists in the specified Channel as the specified - Device Number. - - There is two IDE channels: one is Primary Channel, the other is - Secondary Channel.(Channel is the logical name for the physical "Cable".) - Different channel has different register group. +/** + This function is called by DiscoverIdeDevice(). It is used for detect + whether the IDE device exists in the specified Channel as the specified + Device Number. - On each IDE channel, at most two IDE devices attach, - one is called Device 0 (Master device), the other is called Device 1 - (Slave device). The devices on the same channel co-use the same register - group, so before sending out a command for a specified device via command - register, it is a must to select the current device to accept the command - by set the device number in the Head/Device Register. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. + There is two IDE channels: one is Primary Channel, the other is + Secondary Channel.(Channel is the logical name for the physical "Cable".) + Different channel has different register group. + On each IDE channel, at most two IDE devices attach, + one is called Device 0 (Master device), the other is called Device 1 + (Slave device). The devices on the same channel co-use the same register + group, so before sending out a command for a specified device via command + register, it is a must to select the current device to accept the command + by set the device number in the Head/Device Register. - Returns: - TRUE - successfully detects device. + @param[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. - FALSE - any failure during detection process will return this - value. + @retval TRUE + successfully detects device. + + @retval FALSE + any failure during detection process will return this + value. + @note + TODO: EFI_SUCCESS - add return value to function comment + TODO: EFI_NOT_FOUND - add return value to function comment - Notes: ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: IdeDev - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment +**/ +EFI_STATUS +DetectIDEController ( + IN IDE_BLK_IO_DEV *IdeDev + ) { EFI_STATUS Status; UINT8 ErrorReg; @@ -846,40 +767,33 @@ DetectIDEController ( } +/** + 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[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] 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 Status Register will clear interrupt status. + +**/ EFI_STATUS DRQClear ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - Name: DRQClear - - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - UINTN IN TimeoutInMilliSeconds - used to designate the timeout for the DRQ clear. - - Returns: - EFI_SUCCESS - DRQ bit clear within the time out. - - EFI_TIMEOUT - DRQ bit not clear within the time out. - - - Notes: - Read Status Register will clear interrupt status. ---*/ // TODO: function comment is missing 'Routine Description:' // TODO: function comment is missing 'Arguments:' // TODO: IdeDev - add argument and description to function comment @@ -926,41 +840,34 @@ DRQClear ( return EFI_SUCCESS; } +/** + 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[in] *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] 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 DRQClear2 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - Name: DRQClear2 - - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - UINTN IN TimeoutInMilliSeconds - used to designate the timeout for the DRQ clear. - - Returns: - EFI_SUCCESS - DRQ bit clear within the time out. - - EFI_TIMEOUT - DRQ bit not clear within the time out. - - - Notes: - Read Alternate Status Register will not clear interrupt status. ---*/ // TODO: function comment is missing 'Routine Description:' // TODO: function comment is missing 'Arguments:' // TODO: IdeDev - add argument and description to function comment @@ -1007,46 +914,38 @@ DRQClear2 ( return EFI_SUCCESS; } -EFI_STATUS -DRQReady ( - IN IDE_BLK_IO_DEV *IdeDev, - IN UINTN TimeoutInMilliSeconds - ) -/*++ - Name: DRQReady +/** + 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[in] IDE_BLK_IO_DEV IN *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure,used + to record all the information of the IDE device. - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure,used - to record all the information of the IDE device. - - UINTN IN TimeoutInMilliSeconds - used to designate the timeout for the DRQ ready. - + @param[in] UINTN IN TimeoutInMilliSeconds + used to designate the timeout for the DRQ ready. - Returns: - EFI_SUCCESS - DRQ bit set within the time out. - - EFI_TIMEOUT - DRQ bit not set within the time out. - - EFI_ABORTED - DRQ bit not set caused by the command abort. + @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. - Notes: - Read Status Register will clear interrupt status. + @note + Read Status Register will clear interrupt status. ---*/ +**/ +EFI_STATUS +DRQReady ( + IN IDE_BLK_IO_DEV *IdeDev, + IN UINTN TimeoutInMilliSeconds + ) // TODO: function comment is missing 'Routine Description:' // TODO: function comment is missing 'Arguments:' // TODO: IdeDev - add argument and description to function comment @@ -1093,43 +992,37 @@ DRQReady ( return EFI_SUCCESS; } +/** + 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[in] IDE_BLK_IO_DEV IN *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] UINTN IN 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 DRQReady2 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - Name: DRQReady2 - - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - UINTN IN TimeoutInMilliSeconds - used to designate the timeout for the DRQ ready. - - Returns: - EFI_SUCCESS - DRQ bit set within the time out. - - EFI_TIMEOUT - DRQ bit not set within the time out. - - EFI_ABORTED - DRQ bit not set caused by the command abort. - - Notes: - Read Alternate Status Register will not clear interrupt status. ---*/ // TODO: function comment is missing 'Routine Description:' // TODO: function comment is missing 'Arguments:' // TODO: IdeDev - add argument and description to function comment @@ -1176,41 +1069,33 @@ DRQReady2 ( return EFI_SUCCESS; } +/** + 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[in] IDE_BLK_IO_DEV IN *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] UINTN IN TimeoutInMilliSeconds + used to designate the timeout for the DRQ ready. + + @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 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - Name: - WaitForBSYClear - - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - UINTN IN TimeoutInMilliSeconds - used to designate the timeout for the DRQ ready. - - Returns: - EFI_SUCCESS - BSY bit clear within the time out. - - EFI_TIMEOUT - BSY bit not clear within the time out. - - - Notes: - Read Status Register will clear interrupt status. ---*/ // TODO: function comment is missing 'Routine Description:' // TODO: function comment is missing 'Arguments:' // TODO: IdeDev - add argument and description to function comment @@ -1245,41 +1130,33 @@ WaitForBSYClear ( // // WaitForBSYClear2 // +/** + 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[in] IDE_BLK_IO_DEV IN *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] UINTN IN TimeoutInMilliSeconds + used to designate the timeout for the DRQ ready. + + @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 WaitForBSYClear2 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - Name: - WaitForBSYClear2 - - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - UINTN IN TimeoutInMilliSeconds - used to designate the timeout for the DRQ ready. - - Returns: - EFI_SUCCESS - BSY bit clear within the time out. - - EFI_TIMEOUT - BSY bit not clear within the time out. - - - Notes: - Read Alternate Status Register will not clear interrupt status. ---*/ // TODO: function comment is missing 'Routine Description:' // TODO: function comment is missing 'Arguments:' // TODO: IdeDev - add argument and description to function comment @@ -1311,42 +1188,34 @@ WaitForBSYClear2 ( // // DRDYReady // +/** + 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[in] IDE_BLK_IO_DEV IN *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] UINTN IN TimeoutInMilliSeconds + used to designate the timeout for the DRQ ready. + + @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 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN DelayInMilliSeconds ) -/*++ - Name: - DRDYReady - - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - UINTN IN TimeoutInMilliSeconds - used to designate the timeout for the DRQ ready. - - Returns: - EFI_SUCCESS - DRDY bit set within the time out. - - EFI_TIMEOUT - DRDY bit not set within the time out. - - - Notes: - Read Status Register will clear interrupt status. ---*/ // TODO: function comment is missing 'Routine Description:' // TODO: function comment is missing 'Arguments:' // TODO: IdeDev - add argument and description to function comment @@ -1390,42 +1259,34 @@ DRDYReady ( // // DRDYReady2 // +/** + 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[in] IDE_BLK_IO_DEV IN *IdeDev + pointer pointing to IDE_BLK_IO_DEV data structure, used + to record all the information of the IDE device. + + @param[in] UINTN IN TimeoutInMilliSeconds + used to designate the timeout for the DRQ ready. + + @retval EFI_SUCCESS + DRDY bit set within the time out. + + @retval EFI_TIMEOUT + DRDY bit not set within the time out. + + @note + Read Alternate Status Register will clear interrupt status. + +**/ EFI_STATUS DRDYReady2 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN DelayInMilliSeconds ) -/*++ - Name: - DRDYReady2 - - - Purpose: - 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. - - - Parameters: - IDE_BLK_IO_DEV IN *IdeDev - pointer pointing to IDE_BLK_IO_DEV data structure, used - to record all the information of the IDE device. - - UINTN IN TimeoutInMilliSeconds - used to designate the timeout for the DRQ ready. - - Returns: - EFI_SUCCESS - DRDY bit set within the time out. - - EFI_TIMEOUT - DRDY bit not set within the time out. - - - Notes: - Read Alternate Status Register will clear interrupt status. ---*/ // TODO: function comment is missing 'Routine Description:' // TODO: function comment is missing 'Arguments:' // TODO: IdeDev - add argument and description to function comment @@ -1469,52 +1330,34 @@ DRDYReady2 ( // // SwapStringChars // +/** + This function is a helper function used to change the char order in a + string. It is designed specially for the PrintAtaModuleName() function. + After the IDE device is detected, the IDE driver gets the device module + name by sending ATA command called ATA Identify Command or ATAPI + Identify Command to the specified IDE device. The module name returned + is a string of ASCII characters: the first character is bit8--bit15 + of the first word, the second character is bit0--bit7 of the first word + and so on. Thus the string can not be print directly before it is + preprocessed by this func to change the order of characters in + each word in the string. + + @param[in] CHAR8 IN *Destination + Indicates the destination string. + + @param[in] CHAR8 IN *Source + Indicates the source string. + + @param[in] UINT8 IN Size + the length of the string + +**/ VOID SwapStringChars ( IN CHAR8 *Destination, IN CHAR8 *Source, IN UINT32 Size ) -/*++ - Name: - SwapStringChars - - - Purpose: - This function is a helper function used to change the char order in a - string. It is designed specially for the PrintAtaModuleName() function. - After the IDE device is detected, the IDE driver gets the device module - name by sending ATA command called ATA Identify Command or ATAPI - Identify Command to the specified IDE device. The module name returned - is a string of ASCII characters: the first character is bit8--bit15 - of the first word, the second character is bit0--bit7 of the first word - and so on. Thus the string can not be print directly before it is - preprocessed by this func to change the order of characters in - each word in the string. - - - Parameters: - CHAR8 IN *Destination - Indicates the destination string. - - CHAR8 IN *Source - Indicates the source string. - - UINT8 IN Size - the length of the string - - - Returns: - none - - Notes: - ---*/ -// TODO: function comment is missing 'Routine Description:' -// TODO: function comment is missing 'Arguments:' -// TODO: Destination - add argument and description to function comment -// TODO: Source - add argument and description to function comment -// TODO: Size - add argument and description to function comment { UINT32 Index; CHAR8 Temp; @@ -1530,26 +1373,16 @@ SwapStringChars ( // // ReleaseIdeResources // +/** + Release resources of an IDE device before stopping it. + + @param[in] *IdeBlkIoDevice Standard IDE device private data structure + +**/ VOID ReleaseIdeResources ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice ) -/*++ -Routing Description: - - Release resources of an IDE device before stopping it. - -Arguments: - - IdeBlkIoDevice -- Standard IDE device private data structure - - -Returns: - - NONE - ----*/ -// TODO: function comment is missing 'Routine Description:' { if (IdeBlkIoDevice == NULL) { return ; @@ -1601,26 +1434,20 @@ Returns: // // SetDeviceTransferMode // +/** + Set the calculated Best transfer mode to a detected device + + @param[in] *IdeDev Standard IDE device private data structure + @param[in] *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 ) -/*++ -Routing Description: - - Set the calculated Best transfer mode to a detected device - -Arguments: - - IdeDev -- Standard IDE device private data structure - TransferMode -- The device transfer mode to be set - -Returns: - - Set transfer mode Command execute status - ----*/ // TODO: function comment is missing 'Routine Description:' { EFI_STATUS Status; @@ -1648,6 +1475,23 @@ Returns: return Status; } +/** + Send ATA command into device with NON_DATA protocol + + @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 + + @retval EFI_SUCCESS Reading succeed + @retval EFI_ABORTED Command failed + @retval EFI_DEVICE_ERROR Device status error + +**/ EFI_STATUS AtaNonDataCommandIn ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1659,30 +1503,6 @@ AtaNonDataCommandIn ( IN UINT8 LbaMiddle, IN UINT8 LbaHigh ) -/*++ - -Routine Description: - - Send ATA command into device with NON_DATA protocol - -Arguments: - - IdeDev - Standard IDE device private data structure - AtaCommand - The ATA command to be sent - Device - The value in Device register - Feature - The value in Feature register - SectorCount - The value in SectorCount register - LbaLow - The value in LBA_LOW register - LbaMiddle - The value in LBA_MIDDLE register - LbaHigh - The value in LBA_HIGH register - -Returns: - - EFI_SUCCESS - Reading succeed - EFI_ABORTED - Command failed - EFI_DEVICE_ERROR - Device status error - ---*/ { EFI_STATUS Status; UINT8 StatusRegister; @@ -1743,6 +1563,21 @@ Returns: return EFI_SUCCESS; } +/** + Send ATA Ext command into device with NON_DATA protocol + + @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 + + @retval EFI_SUCCESS Reading succeed + @retval EFI_ABORTED Command failed + @retval EFI_DEVICE_ERROR Device status error + +**/ EFI_STATUS AtaNonDataCommandInExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1752,28 +1587,6 @@ AtaNonDataCommandInExt ( IN UINT16 SectorCount, IN EFI_LBA LbaAddress ) -/*++ - -Routine Description: - - Send ATA Ext command into device with NON_DATA protocol - -Arguments: - - IdeDev - Standard IDE device private data structure - AtaCommand - The ATA command to be sent - Device - The value in Device register - Feature - The value in Feature register - SectorCount - The value in SectorCount register - LbaAddress - The LBA address in 48-bit mode - -Returns: - - EFI_SUCCESS - Reading succeed - EFI_ABORTED - Command failed - EFI_DEVICE_ERROR - Device status error - ---*/ { EFI_STATUS Status; UINT8 StatusRegister; @@ -1872,26 +1685,20 @@ Returns: // // SetDriveParameters // +/** + Set drive parameters for devices not support PACKETS command + + @param[in] IdeDev Standard IDE device private data structure + @param[in] DriveParameters The device parameters to be set into the disk + + @return SetParameters Command execute status + +**/ EFI_STATUS SetDriveParameters ( IN IDE_BLK_IO_DEV *IdeDev, IN ATA_DRIVE_PARMS *DriveParameters ) -/*++ -Routine Description: - - Set drive parameters for devices not support PACKETS command - -Arguments: - - IdeDev -- Standard IDE device private data structure - DriveParameters -- The device parameters to be set into the disk - -Returns: - - SetParameters Command execute status - ---*/ { EFI_STATUS Status; UINT8 DeviceSelect; @@ -1932,25 +1739,18 @@ Returns: return Status; } -EFI_STATUS -EnableInterrupt ( - IN IDE_BLK_IO_DEV *IdeDev - ) -/*++ - -Routine Description: - +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description + @param IdeDev TODO: add argument description -Returns: + @retval EFI_SUCCESS TODO: Add description for return value - EFI_SUCCESS - TODO: Add description for return value - ---*/ +**/ +EFI_STATUS +EnableInterrupt ( + IN IDE_BLK_IO_DEV *IdeDev + ) { UINT8 DeviceControl; diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h index 4c43ab94cd..177e842714 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h @@ -1,62 +1,58 @@ -/*++ -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +/** @file + Header file for IDE Bus Driver, containing the helper functions' + entire prototype. -Module Name: + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php - ide.h + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Abstract: + @par Revision Reference: + 2002-6: Add Atapi6 enhancement, support >120GB hard disk, including + Add - IDEBlkIoReadBlocksExt() func definition + Add - IDEBlkIoWriteBlocksExt() func definition - Header file for IDE Bus Driver, containing the helper functions' - entire prototype. +**/ -Revision History - - 2002-6: Add Atapi6 enhancement, support >120GB hard disk, including - Add - IDEBlkIoReadBlocksExt() func definition - Add - IDEBlkIoWriteBlocksExt() func definition - -++*/ - -// TODO: fix comment to end with --*/ #ifndef _IDE_H #define _IDE_H // // Helper functions Prototype // +/** + TODO: Add function description + + @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 ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - Controller - TODO: add argument description - Handle - TODO: add argument description - -Returns: + @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, @@ -64,49 +60,35 @@ EnableIdeDevice ( IN EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - Controller - TODO: add argument description - PciIo - TODO: add argument description - ParentDevicePath - TODO: add argument description - RemainingDevicePath - TODO: add argument description - -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description TODO: add return values ---*/ -; - +**/ UINT8 IDEReadPortB ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description + @param Count TODO: add argument description + @param Buffer TODO: add argument description TODO: add return values ---*/ -; - +**/ VOID IDEReadPortWMultiple ( IN EFI_PCI_IO_PROTOCOL *PciIo, @@ -114,76 +96,55 @@ IDEReadPortWMultiple ( IN UINTN Count, OUT VOID *Buffer ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - Count - TODO: add argument description - Buffer - TODO: add argument description - -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description + @param Data TODO: add argument description TODO: add return values ---*/ -; - +**/ VOID IDEWritePortB ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port, IN UINT8 Data ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - Data - TODO: add argument description - -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description + @param Data TODO: add argument description TODO: add return values ---*/ -; - +**/ VOID IDEWritePortW ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN UINT16 Port, IN UINT16 Data ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - Data - TODO: add argument description - -Returns: + @param PciIo TODO: add argument description + @param Port TODO: add argument description + @param Count TODO: add argument description + @param Buffer TODO: add argument description TODO: add return values ---*/ -; - +**/ VOID IDEWritePortWMultiple ( IN EFI_PCI_IO_PROTOCOL *PciIo, @@ -191,366 +152,259 @@ IDEWritePortWMultiple ( IN UINTN Count, IN VOID *Buffer ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - Port - TODO: add argument description - Count - TODO: add argument description - Buffer - TODO: add argument description - -Returns: + @param PciIo TODO: add argument description + @param IdeRegsBaseAddr TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS GetIdeRegistersBaseAddr ( IN EFI_PCI_IO_PROTOCOL *PciIo, OUT IDE_REGISTERS_BASE_ADDR *IdeRegsBaseAddr ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - IdeRegsBaseAddr - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS ReassignIdeResources ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS DiscoverIdeDevice ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS DetectIDEController ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param TimeoutInMilliSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS DRQClear ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - TimeoutInMilliSeconds - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param TimeoutInMilliSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS DRQClear2 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - TimeoutInMilliSeconds - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param TimeoutInMilliSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS DRQReady ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - TimeoutInMilliSeconds - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param TimeoutInMilliSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS DRQReady2 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - TimeoutInMilliSeconds - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param TimeoutInMilliSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS WaitForBSYClear ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - TimeoutInMilliSeconds - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param TimeoutInMilliSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS WaitForBSYClear2 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN TimeoutInMilliSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - TimeoutInMilliSeconds - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param DelayInMilliSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS DRDYReady ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN DelayInMilliSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DelayInMilliSeconds - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param DelayInMilliSeconds TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS DRDYReady2 ( IN IDE_BLK_IO_DEV *IdeDev, IN UINTN DelayInMilliSeconds ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DelayInMilliSeconds - TODO: add argument description - -Returns: + @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 ) -/*++ - -Routine Description: +; +// +// ATA device functions' prototype +// +/** TODO: Add function description -Arguments: - - Destination - TODO: add argument description - Source - TODO: add argument description - Size - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - -// -// ATA device functions' prototype -// +**/ EFI_STATUS ATAIdentify ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ VOID PrintAtaModuleName ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @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 ---*/ -; - +**/ EFI_STATUS AtaPioDataIn ( IN IDE_BLK_IO_DEV *IdeDev, @@ -563,31 +417,24 @@ AtaPioDataIn ( IN UINT8 CylinderLsb, IN UINT8 CylinderMsb ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - AtaCommand - TODO: add argument description - Head - TODO: add argument description - SectorCount - TODO: add argument description - SectorNumber - TODO: add argument description - CylinderLsb - TODO: add argument description - CylinderMsb - TODO: add argument description - -Returns: + @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 ---*/ -; - +**/ EFI_STATUS AtaPioDataOut ( IN IDE_BLK_IO_DEV *IdeDev, @@ -600,52 +447,33 @@ AtaPioDataOut ( IN UINT8 CylinderLsb, IN UINT8 CylinderMsb ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - AtaCommand - TODO: add argument description - Head - TODO: add argument description - SectorCount - TODO: add argument description - SectorNumber - TODO: add argument description - CylinderLsb - TODO: add argument description - CylinderMsb - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS CheckErrorStatus ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param DataBuffer TODO: add argument description + @param Lba TODO: add argument description + @param NumberOfBlocks TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtaReadSectors ( IN IDE_BLK_IO_DEV *IdeDev, @@ -653,26 +481,19 @@ AtaReadSectors ( IN EFI_LBA Lba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DataBuffer - TODO: add argument description - Lba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @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, @@ -680,47 +501,34 @@ AtaWriteSectors ( IN EFI_LBA Lba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - BufferData - TODO: add argument description - Lba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtaSoftReset ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @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 ---*/ -; - +**/ EFI_STATUS AtaBlkIoReadBlocks ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice, @@ -729,27 +537,20 @@ AtaBlkIoReadBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeBlkIoDevice - TODO: add argument description - MediaId - TODO: add argument description - LBA - TODO: add argument description - BufferSize - TODO: add argument description - Buffer - TODO: add argument description - -Returns: + @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 ---*/ -; - +**/ EFI_STATUS AtaBlkIoWriteBlocks ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice, @@ -758,72 +559,51 @@ AtaBlkIoWriteBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: +; +// +// ATAPI device functions' prototype +// +/** TODO: Add function description -Arguments: - - IdeBlkIoDevice - TODO: add argument description - MediaId - TODO: add argument description - LBA - TODO: add argument description - BufferSize - TODO: add argument description - Buffer - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - -// -// ATAPI device functions' prototype -// +**/ EFI_STATUS ATAPIIdentify ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtapiInquiry ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @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, @@ -832,27 +612,20 @@ AtapiPacketCommandIn ( IN UINT32 ByteCount, IN UINTN TimeOut ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Packet - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - TimeOut - TODO: add argument description - -Returns: + @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, @@ -861,27 +634,20 @@ AtapiPacketCommandOut ( IN UINT32 ByteCount, IN UINTN TimeOut ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Packet - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - TimeOut - TODO: add argument description - -Returns: + @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, @@ -890,115 +656,79 @@ PioReadWriteData ( IN BOOLEAN Read, IN UINTN TimeOut ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - Read - TODO: add argument description - TimeOut - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtapiTestUnitReady ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @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 ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - SenseCounts - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtapiReadCapacity ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @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 ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - MediaChange - TODO: add argument description - -Returns: + @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, @@ -1006,26 +736,19 @@ AtapiReadSectors ( IN EFI_LBA Lba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Buffer - TODO: add argument description - Lba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @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, @@ -1033,47 +756,34 @@ AtapiWriteSectors ( IN EFI_LBA Lba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Buffer - TODO: add argument description - Lba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtapiSoftReset ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @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 ---*/ -; - +**/ EFI_STATUS AtapiBlkIoReadBlocks ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice, @@ -1082,27 +792,20 @@ AtapiBlkIoReadBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeBlkIoDevice - TODO: add argument description - MediaId - TODO: add argument description - LBA - TODO: add argument description - BufferSize - TODO: add argument description - Buffer - TODO: add argument description - -Returns: + @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 ---*/ -; - +**/ EFI_STATUS AtapiBlkIoWriteBlocks ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice, @@ -1111,259 +814,185 @@ AtapiBlkIoWriteBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeBlkIoDevice - TODO: add argument description - MediaId - TODO: add argument description - LBA - TODO: add argument description - BufferSize - TODO: add argument description - Buffer - TODO: add argument description - -Returns: + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description TODO: add return values ---*/ -; - +**/ BOOLEAN IsNoMedia ( IN REQUEST_SENSE_DATA *SenseData, IN UINTN SenseCounts ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - -Returns: + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description TODO: add return values ---*/ -; - +**/ BOOLEAN IsMediaError ( IN REQUEST_SENSE_DATA *SenseData, IN UINTN SenseCounts ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - -Returns: + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description TODO: add return values ---*/ -; - +**/ BOOLEAN IsMediaChange ( IN REQUEST_SENSE_DATA *SenseData, IN UINTN SenseCounts ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - -Returns: + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description + @param NeedRetry TODO: add argument description TODO: add return values ---*/ -; - +**/ BOOLEAN IsDriveReady ( IN REQUEST_SENSE_DATA *SenseData, IN UINTN SenseCounts, OUT BOOLEAN *NeedRetry ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - NeedRetry - TODO: add argument description - -Returns: + @param SenseData TODO: add argument description + @param SenseCounts TODO: add argument description TODO: add return values ---*/ -; - +**/ BOOLEAN HaveSenseKey ( IN REQUEST_SENSE_DATA *SenseData, IN UINTN SenseCounts ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - SenseData - TODO: add argument description - SenseCounts - TODO: add argument description - -Returns: + @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 ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - WriteProtected - TODO: add argument description - -Returns: + @param IdeBlkIoDevice TODO: add argument description TODO: add return values ---*/ -; - +**/ VOID ReleaseIdeResources ( IN IDE_BLK_IO_DEV *IdeBlkIoDevice ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeBlkIoDevice - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param TransferMode TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS SetDeviceTransferMode ( IN IDE_BLK_IO_DEV *IdeDev, IN ATA_TRANSFER_MODE *TransferMode ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - TransferMode - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param NativeMaxAddress TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS ReadNativeMaxAddress ( IN IDE_BLK_IO_DEV *IdeDev, OUT EFI_LBA *NativeMaxAddress ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - NativeMaxAddress - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param MaxAddress TODO: add argument description + @param bVolatile TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS SetMaxAddress ( IN IDE_BLK_IO_DEV *IdeDev, IN EFI_LBA MaxAddress, IN BOOLEAN bVolatile ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - MaxAddress - TODO: add argument description - bVolatile - TODO: add argument description - -Returns: + @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 ---*/ -; - +**/ EFI_STATUS AtaNonDataCommandIn ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1375,30 +1004,21 @@ AtaNonDataCommandIn ( IN UINT8 LbaMiddle, IN UINT8 LbaHigh ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - AtaCommand - TODO: add argument description - Device - TODO: add argument description - Feature - TODO: add argument description - SectorCount - TODO: add argument description - LbaLow - TODO: add argument description - LbaMiddle - TODO: add argument description - LbaHigh - TODO: add argument description - -Returns: + @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 AtaNonDataCommandInExt ( IN IDE_BLK_IO_DEV *IdeDev, @@ -1408,28 +1028,19 @@ AtaNonDataCommandInExt ( IN UINT16 SectorCount, IN EFI_LBA LbaAddress ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - AtaCommand - TODO: add argument description - Device - TODO: add argument description - Feature - TODO: add argument description - SectorCount - TODO: add argument description - LbaAddress - TODO: add argument description - -Returns: + @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, @@ -1437,26 +1048,19 @@ AtaReadSectorsExt ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DataBuffer - TODO: add argument description - StartLba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @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, @@ -1464,26 +1068,19 @@ AtaWriteSectorsExt ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DataBuffer - TODO: add argument description - StartLba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @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, @@ -1491,26 +1088,19 @@ AtaUdmaReadExt ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DataBuffer - TODO: add argument description - StartLba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @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, @@ -1518,26 +1108,19 @@ AtaUdmaRead ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DataBuffer - TODO: add argument description - StartLba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @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, @@ -1545,26 +1128,19 @@ AtaUdmaWriteExt ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DataBuffer - TODO: add argument description - StartLba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @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, @@ -1572,26 +1148,21 @@ AtaUdmaWrite ( IN EFI_LBA StartLba, IN UINTN NumberOfBlocks ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DataBuffer - TODO: add argument description - StartLba - TODO: add argument description - NumberOfBlocks - TODO: add argument description - -Returns: + @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, @@ -1601,28 +1172,21 @@ AtaCommandIssueExt ( IN UINT16 SectorCount, IN EFI_LBA LbaAddress ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - AtaCommand - TODO: add argument description - Device - TODO: add argument description - Feature - TODO: add argument description - SectorCount - TODO: add argument description - LbaAddress - TODO: add argument description - -Returns: + @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, @@ -1632,71 +1196,50 @@ AtaCommandIssue ( IN UINT16 SectorCount, IN EFI_LBA LbaAddress ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - AtaCommand - TODO: add argument description - Device - TODO: add argument description - Feature - TODO: add argument description - SectorCount - TODO: add argument description - LbaAddress - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS AtaAtapi6Identify ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ +; -Routine Description: +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - - +**/ VOID AtaSMARTSupport ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - -Returns: + @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, @@ -1706,28 +1249,21 @@ AtaPioDataInExt ( IN EFI_LBA StartLba, IN UINT16 SectorCount ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - AtaCommand - TODO: add argument description - StartLba - TODO: add argument description - SectorCount - TODO: add argument description - -Returns: + @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, @@ -1737,70 +1273,36 @@ AtaPioDataOutExt ( IN EFI_LBA StartLba, IN UINT16 SectorCount ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - Buffer - TODO: add argument description - ByteCount - TODO: add argument description - AtaCommand - TODO: add argument description - StartLba - TODO: add argument description - SectorCount - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description + @param DriveParameters TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS SetDriveParameters ( IN IDE_BLK_IO_DEV *IdeDev, IN ATA_DRIVE_PARMS *DriveParameters ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - IdeDev - TODO: add argument description - DriveParameters - TODO: add argument description - -Returns: + @param IdeDev TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EnableInterrupt ( IN IDE_BLK_IO_DEV *IdeDev ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - IdeDev - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ ; #endif diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c index 4cf882eb00..e5157dab70 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c @@ -1,25 +1,17 @@ -/*++ +/** @file + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - idebus.c - -Abstract: - - -Revision History + @par Revision Reference: This module is modified from DXE\IDE module for Ide Contriller Init support ---*/ +**/ #include "idebus.h" @@ -44,6 +36,17 @@ EFI_DRIVER_BINDING_PROTOCOL gIDEBusDriverBinding = { // IDEBusDriverBindingSupported // *********************************************************************************** // +/** + Register Driver Binding protocol for this driver. + + @param[in] This -- A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. + @param[in] ControllerHandle -- The handle of the controller to test. + @param[in] RemainingDevicePath -- A pointer to the remaining portion of a device path. + + @retval EFI_SUCCESS Driver loaded. + @retval other Driver not loaded. + +**/ EFI_STATUS EFIAPI IDEBusDriverBindingSupported ( @@ -51,20 +54,6 @@ IDEBusDriverBindingSupported ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: - Register Driver Binding protocol for this driver. - -Arguments: - This -- A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. - ControllerHandle -- The handle of the controller to test. - RemainingDevicePath -- A pointer to the remaining portion of a device path. - -Returns: - EFI_SUCCESS - Driver loaded. - other - Driver not loaded. ---*/ // TODO: Controller - add argument and description to function comment // TODO: EFI_UNSUPPORTED - add return value to function comment { @@ -150,6 +139,19 @@ Returns: // IDEBusDriverBindingStart // *********************************************************************************** // +/** + Start this driver on Controller by detecting all disks and installing + BlockIo protocol on them. + + @param This Protocol instance pointer. + @param Controller Handle of device to bind driver to. + @param RemainingDevicePath Not used, always produce all possible children. + + @retval EFI_SUCCESS This driver is added to ControllerHandle. + @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle. + @retval other This driver does not support this device. + +**/ EFI_STATUS EFIAPI IDEBusDriverBindingStart ( @@ -157,23 +159,6 @@ IDEBusDriverBindingStart ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - - Routine Description: - Start this driver on Controller by detecting all disks and installing - BlockIo protocol on them. - - Arguments: - This - Protocol instance pointer. - Controller - Handle of device to bind driver to. - RemainingDevicePath - Not used, always produce all possible children. - - Returns: - EFI_SUCCESS - This driver is added to ControllerHandle. - EFI_ALREADY_STARTED - This driver is already running on ControllerHandle. - other - This driver does not support this device. - ---*/ { EFI_STATUS Status; EFI_STATUS SavedStatus; @@ -791,6 +776,18 @@ ErrorExit: // IDEBusDriverBindingStop // *********************************************************************************** // +/** + Stop this driver on Controller Handle. + + @param This Protocol instance pointer. + @param DeviceHandle Handle of device to stop driver on + @param NumberOfChildren Not used + @param ChildHandleBuffer Not used + + @retval EFI_SUCCESS This driver is removed DeviceHandle + @retval other This driver was not removed from this device + +**/ EFI_STATUS EFIAPI IDEBusDriverBindingStop ( @@ -799,22 +796,6 @@ IDEBusDriverBindingStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/*++ - - Routine Description: - Stop this driver on Controller Handle. - - Arguments: - This - Protocol instance pointer. - DeviceHandle - Handle of device to stop driver on - NumberOfChildren - Not used - ChildHandleBuffer - Not used - - Returns: - EFI_SUCCESS - This driver is removed DeviceHandle - other - This driver was not removed from this device - ---*/ // TODO: Controller - add argument and description to function comment // TODO: EFI_DEVICE_ERROR - add return value to function comment { @@ -912,29 +893,22 @@ IDEBusDriverBindingStop ( // DeRegisterIdeDevice // *********************************************************************************** // +/** + Deregister an IDE device and free resources + + @param This Protocol instance pointer. + @param Controller Ide device handle + @param Handle Handle of device to deregister driver on + + @return EFI_STATUS + +**/ EFI_STATUS DeRegisterIdeDevice ( IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_HANDLE Controller, IN EFI_HANDLE Handle ) -/*++ - -Routine Description: - - Deregister an IDE device and free resources - -Arguments: - - This - Protocol instance pointer. - Controller - Ide device handle - Handle - Handle of device to deregister driver on - -Returns: - - EFI_STATUS - ---*/ // TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; @@ -1015,26 +989,18 @@ Returns: // IDEBlkIoReset // *********************************************************************************** // +/** + TODO: This - add argument and description to function comment + TODO: ExtendedVerification - add argument and description to function comment + TODO: EFI_DEVICE_ERROR - add return value to function comment + +**/ EFI_STATUS EFIAPI IDEBlkIoReset ( IN EFI_BLOCK_IO_PROTOCOL *This, IN BOOLEAN ExtendedVerification ) -/*++ - -Routine Description: - -Arguments: - -Returns: - - None - ---*/ -// TODO: This - add argument and description to function comment -// TODO: ExtendedVerification - add argument and description to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment { IDE_BLK_IO_DEV *IdeBlkIoDevice; EFI_STATUS Status; @@ -1067,6 +1033,18 @@ Returns: return Status; } +/** + Read data from block io device + + @param This Protocol instance pointer. + @param MediaId The media ID of the device + @param LBA Starting LBA address to read data + @param BufferSize The size of data to be read + @param Buffer Caller supplied buffer to save data + + @return read data status + +**/ EFI_STATUS EFIAPI IDEBlkIoReadBlocks ( @@ -1076,25 +1054,6 @@ IDEBlkIoReadBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Read data from block io device - -Arguments: - - This - Protocol instance pointer. - MediaId - The media ID of the device - LBA - Starting LBA address to read data - BufferSize - The size of data to be read - Buffer - Caller supplied buffer to save data - -Returns: - - read data status - ---*/ // TODO: EFI_DEVICE_ERROR - add return value to function comment { IDE_BLK_IO_DEV *IdeBlkIoDevice; @@ -1137,6 +1096,18 @@ Returns: } +/** + Write data to block io device + + @param This Protocol instance pointer. + @param MediaId The media ID of the device + @param LBA Starting LBA address to write data + @param BufferSize The size of data to be written + @param Buffer Caller supplied buffer to save data + + @return write data status + +**/ EFI_STATUS EFIAPI IDEBlkIoWriteBlocks ( @@ -1146,25 +1117,6 @@ IDEBlkIoWriteBlocks ( IN UINTN BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: - - Write data to block io device - -Arguments: - - This - Protocol instance pointer. - MediaId - The media ID of the device - LBA - Starting LBA address to write data - BufferSize - The size of data to be written - Buffer - Caller supplied buffer to save data - -Returns: - - write data status - ---*/ // TODO: EFI_DEVICE_ERROR - add return value to function comment { IDE_BLK_IO_DEV *IdeBlkIoDevice; @@ -1211,24 +1163,15 @@ Returns: // IDEBlkIoFlushBlocks // *********************************************************************************** // +/** + TODO: This - add argument and description to function comment + TODO: EFI_SUCCESS - add return value to function comment +**/ EFI_STATUS EFIAPI IDEBlkIoFlushBlocks ( IN EFI_BLOCK_IO_PROTOCOL *This ) -/*++ - -Routine Description: - -Arguments: - -Returns: - - None - ---*/ -// TODO: This - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { // // return directly @@ -1236,6 +1179,20 @@ Returns: return EFI_SUCCESS; } +/** + Return the results of the Inquiry command to a drive in InquiryData. + Data format of Inquiry data is defined by the Interface GUID. + + @param This Protocol instance pointer. + @param InquiryData Results of Inquiry command to device + @param InquiryDataSize Size of InquiryData in bytes. + + @retval EFI_SUCCESS InquiryData valid + @retval EFI_NOT_FOUND Device does not support this data class + @retval EFI_DEVICE_ERROR Error reading InquiryData from device + @retval EFI_BUFFER_TOO_SMALL IntquiryDataSize not big enough + +**/ EFI_STATUS EFIAPI IDEDiskInfoInquiry ( @@ -1243,24 +1200,6 @@ IDEDiskInfoInquiry ( IN OUT VOID *InquiryData, IN OUT UINT32 *InquiryDataSize ) -/*++ - - Routine Description: - Return the results of the Inquiry command to a drive in InquiryData. - Data format of Inquiry data is defined by the Interface GUID. - - Arguments: - This - Protocol instance pointer. - InquiryData - Results of Inquiry command to device - InquiryDataSize - Size of InquiryData in bytes. - - Returns: - EFI_SUCCESS - InquiryData valid - EFI_NOT_FOUND - Device does not support this data class - EFI_DEVICE_ERROR - Error reading InquiryData from device - EFI_BUFFER_TOO_SMALL - IntquiryDataSize not big enough - ---*/ { IDE_BLK_IO_DEV *IdeBlkIoDevice; @@ -1281,6 +1220,20 @@ IDEDiskInfoInquiry ( return EFI_SUCCESS; } +/** + Return the results of the Identify command to a drive in IdentifyData. + Data format of Identify data is defined by the Interface GUID. + + @param This Protocol instance pointer. + @param IdentifyData Results of Identify command to device + @param IdentifyDataSize Size of IdentifyData in bytes. + + @retval EFI_SUCCESS IdentifyData valid + @retval EFI_NOT_FOUND Device does not support this data class + @retval EFI_DEVICE_ERROR Error reading IdentifyData from device + @retval EFI_BUFFER_TOO_SMALL IdentifyDataSize not big enough + +**/ EFI_STATUS EFIAPI IDEDiskInfoIdentify ( @@ -1288,24 +1241,6 @@ IDEDiskInfoIdentify ( IN OUT VOID *IdentifyData, IN OUT UINT32 *IdentifyDataSize ) -/*++ - - Routine Description: - Return the results of the Identify command to a drive in IdentifyData. - Data format of Identify data is defined by the Interface GUID. - - Arguments: - This - Protocol instance pointer. - IdentifyData - Results of Identify command to device - IdentifyDataSize - Size of IdentifyData in bytes. - - Returns: - EFI_SUCCESS - IdentifyData valid - EFI_NOT_FOUND - Device does not support this data class - EFI_DEVICE_ERROR - Error reading IdentifyData from device - EFI_BUFFER_TOO_SMALL - IdentifyDataSize not big enough - ---*/ { IDE_BLK_IO_DEV *IdeBlkIoDevice; @@ -1326,6 +1261,21 @@ IDEDiskInfoIdentify ( return EFI_SUCCESS; } +/** + Return the results of the Request Sense command to a drive in SenseData. + Data format of Sense data is defined by the Interface GUID. + + @param This Protocol instance pointer. + @param SenseData Results of Request Sense command to device + @param SenseDataSize Size of SenseData in bytes. + @param SenseDataNumber Type of SenseData + + @retval EFI_SUCCESS InquiryData valid + @retval EFI_NOT_FOUND Device does not support this data class + @retval EFI_DEVICE_ERROR Error reading InquiryData from device + @retval EFI_BUFFER_TOO_SMALL SenseDataSize not big enough + +**/ EFI_STATUS EFIAPI IDEDiskInfoSenseData ( @@ -1334,29 +1284,22 @@ IDEDiskInfoSenseData ( IN OUT UINT32 *SenseDataSize, OUT UINT8 *SenseDataNumber ) -/*++ - - Routine Description: - Return the results of the Request Sense command to a drive in SenseData. - Data format of Sense data is defined by the Interface GUID. - - Arguments: - This - Protocol instance pointer. - SenseData - Results of Request Sense command to device - SenseDataSize - Size of SenseData in bytes. - SenseDataNumber - Type of SenseData - - Returns: - EFI_SUCCESS - InquiryData valid - EFI_NOT_FOUND - Device does not support this data class - EFI_DEVICE_ERROR - Error reading InquiryData from device - EFI_BUFFER_TOO_SMALL - SenseDataSize not big enough - ---*/ { return EFI_NOT_FOUND; } +/** + Return the results of the Request Sense command to a drive in SenseData. + Data format of Sense data is defined by the Interface GUID. + + @param This Protocol instance pointer. + @param IdeChannel Primary or Secondary + @param IdeDevice Master or Slave + + @retval EFI_SUCCESS IdeChannel and IdeDevice are valid + @retval EFI_UNSUPPORTED This is not an IDE device + +**/ EFI_STATUS EFIAPI IDEDiskInfoWhichIde ( @@ -1364,22 +1307,6 @@ IDEDiskInfoWhichIde ( OUT UINT32 *IdeChannel, OUT UINT32 *IdeDevice ) -/*++ - - Routine Description: - Return the results of the Request Sense command to a drive in SenseData. - Data format of Sense data is defined by the Interface GUID. - - Arguments: - This - Protocol instance pointer. - IdeChannel - Primary or Secondary - IdeDevice - Master or Slave - - Returns: - EFI_SUCCESS - IdeChannel and IdeDevice are valid - EFI_UNSUPPORTED - This is not an IDE device - ---*/ { IDE_BLK_IO_DEV *IdeBlkIoDevice; diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h index 428dffa65d..d1721b956f 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h @@ -1,25 +1,17 @@ -/*++ -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +/** @file + Header file for IDE Bus Driver. -Module Name: + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php - idebus.h + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Abstract: +**/ - Header file for IDE Bus Driver. - -Revision History -++*/ - -// TODO: fix comment to end with --*/ #ifndef _IDE_BUS_H #define _IDE_BUS_H @@ -94,30 +86,33 @@ extern EFI_DRIVER_BINDING_PROTOCOL gIDEBusDriverBinding; // Prototypes // Driver model protocol interface // +/** + TODO: Add function description + + @param ImageHandle TODO: add argument description + @param SystemTable TODO: add argument description + + TODO: add return values + +**/ EFI_STATUS EFIAPI IDEBusControllerDriverEntryPoint ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - ImageHandle - TODO: add argument description - SystemTable - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Controller TODO: add argument description + @param RemainingDevicePath TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI IDEBusDriverBindingSupported ( @@ -125,25 +120,18 @@ IDEBusDriverBindingSupported ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - Controller - TODO: add argument description - RemainingDevicePath - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Controller TODO: add argument description + @param RemainingDevicePath TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI IDEBusDriverBindingStart ( @@ -151,25 +139,19 @@ IDEBusDriverBindingStart ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - Controller - TODO: add argument description - RemainingDevicePath - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param Controller TODO: add argument description + @param NumberOfChildren TODO: add argument description + @param ChildHandleBuffer TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI IDEBusDriverBindingStop ( @@ -178,53 +160,40 @@ IDEBusDriverBindingStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/*++ - -Routine Description: +; +// +// Block I/O Protocol Interface +// +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - Controller - TODO: add argument description - NumberOfChildren - TODO: add argument description - ChildHandleBuffer - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param ExtendedVerification TODO: add argument description TODO: add return values ---*/ -; - -// -// Block I/O Protocol Interface -// +**/ EFI_STATUS EFIAPI IDEBlkIoReset ( IN EFI_BLOCK_IO_PROTOCOL *This, IN BOOLEAN ExtendedVerification ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - ExtendedVerification - TODO: add argument description - -Returns: + @param This 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 ---*/ -; - +**/ EFI_STATUS EFIAPI IDEBlkIoReadBlocks ( @@ -234,27 +203,20 @@ IDEBlkIoReadBlocks ( IN UINTN BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - MediaId - TODO: add argument description - LBA - TODO: add argument description - BufferSize - TODO: add argument description - Buffer - TODO: add argument description - -Returns: + @param This 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 ---*/ -; - +**/ EFI_STATUS EFIAPI IDEBlkIoWriteBlocks ( @@ -264,72 +226,49 @@ IDEBlkIoWriteBlocks ( IN UINTN BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - MediaId - TODO: add argument description - LBA - TODO: add argument description - BufferSize - TODO: add argument description - Buffer - TODO: add argument description - -Returns: + @param This TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI IDEBlkIoFlushBlocks ( IN EFI_BLOCK_IO_PROTOCOL *This ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - -Returns: + @param PciIo TODO: add argument description + @param Enable TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS IDERegisterDecodeEnableorDisable ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN BOOLEAN Enable ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - PciIo - TODO: add argument description - Enable - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param InquiryData TODO: add argument description + @param IntquiryDataSize TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI IDEDiskInfoInquiry ( @@ -337,25 +276,18 @@ IDEDiskInfoInquiry ( IN OUT VOID *InquiryData, IN OUT UINT32 *IntquiryDataSize ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - InquiryData - TODO: add argument description - IntquiryDataSize - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param IdentifyData TODO: add argument description + @param IdentifyDataSize TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI IDEDiskInfoIdentify ( @@ -363,25 +295,19 @@ IDEDiskInfoIdentify ( IN OUT VOID *IdentifyData, IN OUT UINT32 *IdentifyDataSize ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - IdentifyData - TODO: add argument description - IdentifyDataSize - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param SenseData TODO: add argument description + @param SenseDataSize TODO: add argument description + @param SenseDataNumber TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI IDEDiskInfoSenseData ( @@ -390,26 +316,18 @@ IDEDiskInfoSenseData ( IN OUT UINT32 *SenseDataSize, OUT UINT8 *SenseDataNumber ) -/*++ - -Routine Description: +; +/** TODO: Add function description -Arguments: - - This - TODO: add argument description - SenseData - TODO: add argument description - SenseDataSize - TODO: add argument description - SenseDataNumber - TODO: add argument description - -Returns: + @param This TODO: add argument description + @param IdeChannel TODO: add argument description + @param IdeDevice TODO: add argument description TODO: add return values ---*/ -; - +**/ EFI_STATUS EFIAPI IDEDiskInfoWhichIde ( @@ -417,23 +335,6 @@ IDEDiskInfoWhichIde ( OUT UINT32 *IdeChannel, OUT UINT32 *IdeDevice ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - IdeChannel - TODO: add argument description - IdeDevice - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ ; #endif diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h index 50b1f05a47..55ae217d44 100644 --- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h +++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h @@ -1,25 +1,17 @@ -/*++ -Copyright (c) 2006, Intel Corporation -All rights reserved. This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +/** @file + Header file for IDE Bus Driver's Data Structures -Module Name: + Copyright (c) 2006, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php - idedata.h + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Abstract: +**/ - Header file for IDE Bus Driver's Data Structures - -Revision History -++*/ - -// TODO: fix comment to end with --*/ #ifndef _IDE_DATA_H #define _IDE_DATA_H -- 2.39.2