From ffa5008abba273f4c35f165ce534e9614b4e3473 Mon Sep 17 00:00:00 2001 From: vanjeff Date: Wed, 9 Apr 2008 08:33:17 +0000 Subject: [PATCH] apply for doxgen format. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5030 6f19259b-4bc3-4df7-8a09-765794883524 --- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Decode.c | 583 ++++---- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.c | 1275 ++++++++---------- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.h | 13 +- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Init.c | 324 ++--- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Undi32.h | 18 +- 5 files changed, 919 insertions(+), 1294 deletions(-) diff --git a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Decode.c b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Decode.c index df5a6b5ac5..a898eebecb 100644 --- a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Decode.c +++ b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Decode.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Provides the basic UNID functions. Copyright (c) 2006 - 2007, Intel Corporation All rights reserved. This program and the accompanying materials @@ -9,16 +10,8 @@ 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: - decode.c +**/ -Abstract: - -Revision history: - ---*/ - -// TODO: fix comment to add: Module Name: DECODE.C #include "Undi32.h" // @@ -49,53 +42,41 @@ UNDI_CALL_TABLE api_table[PXE_OPCODE_LAST_VALID+1] = { \ // end of global variables // -VOID -UNDI_GetState ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine determines the operational state of the UNDI. It updates the state flags in the Command Descriptor Block based on information derived from the AdapterInfo instance data. - To ensure the command has completed successfully, CdbPtr->StatCode will contain the result of the command execution. - The CdbPtr->StatFlags will contain a STOPPED, STARTED, or INITIALIZED state once the command has successfully completed. - Keep in mind the AdapterInfo->State is the active state of the adapter (based on software interrogation), and the CdbPtr->StateFlags is the passed back information that is reflected to the caller of the UNDI API. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_GetState ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { CdbPtr->StatFlags = (PXE_STATFLAGS) (CdbPtr->StatFlags | AdapterInfo->State); return ; } -VOID -UNDI_Start ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to change the operational state of the UNDI from stopped to started. It will do this as long as the adapter's state is PXE_STATFLAGS_GET_STATE_STOPPED, otherwise the CdbPtr->StatFlags will reflect a command failure, and the CdbPtr->StatCode will reflect the UNDI as having already been started. - This routine is modified to reflect the undi 1.1 specification changes. The changes in the spec are mainly in the callback routines, the new spec adds 3 more callbacks and a unique id. @@ -106,17 +87,20 @@ Routine Description: and Sync_Mem routines and a unique id variable for the new version. This is the function which an external entity (SNP, O/S, etc) would call to provide it's I/O abstraction to the UNDI. - It's final action is to change the AdapterInfo->State to PXE_STATFLAGS_GET_STATE_STARTED. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Start ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { PXE_CPB_START_30 *CpbPtr; PXE_CPB_START_31 *CpbPtr_31; @@ -187,31 +171,27 @@ Returns: return ; } -VOID -UNDI_Stop ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to change the operational state of the UNDI from started to stopped. It will not do this if the adapter's state is PXE_STATFLAGS_GET_STATE_INITIALIZED, otherwise the CdbPtr->StatFlags will reflect a command failure, and the CdbPtr->StatCode will reflect the UNDI as having already not been shut down. - The NIC's data structure will have the Delay, Virt2Phys, and Block, pointers zero'd out.. - It's final action is to change the AdapterInfo->State to PXE_STATFLAGS_GET_STATE_STOPPED. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Stop ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { if (AdapterInfo->State == PXE_STATFLAGS_GET_STATE_INITIALIZED) { CdbPtr->StatFlags = PXE_STATFLAGS_COMMAND_FAILED; @@ -236,31 +216,27 @@ Returns: return ; } -VOID -UNDI_GetInitInfo ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to retrieve the initialization information that is needed by drivers and applications to initialize the UNDI. This will fill in data in the Data Block structure that is pointed to by the caller's CdbPtr->DBaddr. The fields filled in are as follows: - MemoryRequired, FrameDataLen, LinkSpeeds[0-3], NvCount, NvWidth, MediaHeaderLen, HWaddrLen, MCastFilterCnt, TxBufCnt, TxBufSize, RxBufCnt, RxBufSize, IFtype, Duplex, and LoopBack. - In addition, the CdbPtr->StatFlags ORs in that this NIC supports cable detection. (APRIORI knowledge) -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_GetInitInfo ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { PXE_DB_GET_INIT_INFO *DbPtr; @@ -292,30 +268,26 @@ Returns: return ; } -VOID -UNDI_GetConfigInfo ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to retrieve the configuration information about the NIC being controlled by this driver. This will fill in data in the Data Block structure that is pointed to by the caller's CdbPtr->DBaddr. The fields filled in are as follows: - DbPtr->pci.BusType, DbPtr->pci.Bus, DbPtr->pci.Device, and DbPtr->pci. - In addition, the DbPtr->pci.Config.Dword[0-63] grabs a copy of this NIC's PCI configuration space. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_GetConfigInfo ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINT16 Index; PXE_DB_GET_CONFIG_INFO *DbPtr; @@ -334,37 +306,32 @@ Returns: return ; } -VOID -UNDI_Initialize ( - IN PXE_CDB *CdbPtr, - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine resets the network adapter and initializes the UNDI using the parameters supplied in the CPB. This command must be issued before the network adapter can be setup to transmit and receive packets. - Once the memory requirements of the UNDI are obtained by using the GetInitInfo command, a block of non-swappable memory may need to be allocated. The address of this memory must be passed to UNDI during the Initialize in the CPB. This memory is used primarily for transmit and receive buffers. - The fields CableDetect, LinkSpeed, Duplex, LoopBack, MemoryPtr, and MemoryLength are set with information that was passed in the CPB and the NIC is initialized. - If the NIC initialization fails, the CdbPtr->StatFlags are updated with PXE_STATFLAGS_COMMAND_FAILED Otherwise, AdapterInfo->State is updated with PXE_STATFLAGS_GET_STATE_INITIALIZED showing the state of the UNDI is now initialized. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Initialize ( + IN PXE_CDB *CdbPtr, + NIC_DATA_INSTANCE *AdapterInfo + ) { PXE_CPB_INITIALIZE *CpbPtr; @@ -414,27 +381,24 @@ Returns: return ; } -VOID -UNDI_Reset ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine resets the network adapter and initializes the UNDI using the parameters supplied in the CPB. The transmit and receive queues are emptied and any pending interrupts are cleared. - If the NIC reset fails, the CdbPtr->StatFlags are updated with PXE_STATFLAGS_COMMAND_FAILED -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Reset ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { if (CdbPtr->OpFlags != PXE_OPFLAGS_NOT_USED && CdbPtr->OpFlags != PXE_OPFLAGS_RESET_DISABLE_INTERRUPTS && @@ -452,32 +416,28 @@ Returns: } } -VOID -UNDI_Shutdown ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine resets the network adapter and leaves it in a safe state for another driver to initialize. Any pending transmits or receives are lost. Receive filters and external interrupt enables are disabled. Once the UNDI has been shutdown, it can then be stopped or initialized again. - If the NIC reset fails, the CdbPtr->StatFlags are updated with PXE_STATFLAGS_COMMAND_FAILED - Otherwise, AdapterInfo->State is updated with PXE_STATFLAGS_GET_STATE_STARTED showing the state of the NIC as being started. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Shutdown ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { // // do the shutdown stuff here @@ -493,29 +453,26 @@ Returns: return ; } -VOID -UNDI_Interrupt ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine can be used to read and/or change the current external interrupt enable settings. Disabling an external interrupt enable prevents and external (hardware) interrupt from being signaled by the network device. Internally the interrupt events can still be polled by using the UNDI_GetState command. - The resulting information on the interrupt state will be passed back in the CdbPtr->StatFlags. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Interrupt ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINT8 IntMask; @@ -573,25 +530,23 @@ Returns: return ; } -VOID -UNDI_RecFilter ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to read and change receive filters and, if supported, read and change multicast MAC address filter list. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_RecFilter ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINT16 NewFilter; UINT16 OpFlags; @@ -753,25 +708,23 @@ BadCdb: CdbPtr->StatCode = PXE_STATCODE_INVALID_CDB; } -VOID -UNDI_StnAddr ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to get the current station and broadcast MAC addresses, and to change the current station MAC address. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_StnAddr ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { PXE_CPB_STATION_ADDRESS *CpbPtr; PXE_DB_STATION_ADDRESS *DbPtr; @@ -822,17 +775,10 @@ Returns: return ; } -VOID -UNDI_Statistics ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to read and clear the NIC traffic statistics. This command is supported only if the !PXE structure's Implementation flags say so. - Results will be parsed out in the following manner: CdbPtr->DBaddr.Data[0] R Total Frames (Including frames with errors and dropped frames) CdbPtr->DBaddr.Data[1] R Good Frames (All frames copied into receive buffer) @@ -845,14 +791,18 @@ Routine Description: CdbPtr->DBaddr.Data[E] T Dropped Frames (Frames that were dropped because of collisions) CdbPtr->DBaddr.Data[14] T Total Collision Frames (Total collisions on this subnet) -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Statistics ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { if ((CdbPtr->OpFlags &~(PXE_OPFLAGS_STATISTICS_RESET)) != 0) { CdbPtr->StatFlags = PXE_STATFLAGS_COMMAND_FAILED; @@ -872,27 +822,24 @@ Returns: return ; } -VOID -UNDI_ip2mac ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to translate a multicast IP address to a multicast MAC address. - This results in a MAC address composed of 25 bits of fixed data with the upper 23 bits of the IP address being appended to it. Results passed back in the equivalent of CdbPtr->DBaddr->MAC[0-5]. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_ip2mac ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { PXE_CPB_MCAST_IP_TO_MAC *CpbPtr; PXE_DB_MCAST_IP_TO_MAC *DbPtr; @@ -934,27 +881,24 @@ Returns: return ; } -VOID -UNDI_NVData ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to read and write non-volatile storage on the NIC (if supported). The NVRAM could be EEPROM, FLASH, or battery backed RAM. - This is an optional function according to the UNDI specification (or will be......) -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_NVData ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { PXE_DB_NVDATA *DbPtr; UINT16 Index; @@ -985,32 +929,28 @@ Returns: return ; } -VOID -UNDI_Status ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine returns the current interrupt status and/or the transmitted buffer addresses. If the current interrupt status is returned, pending interrupts will be acknowledged by this command. Transmitted buffer addresses that are written to the DB are removed from the transmit buffer queue. - Normally, this command would be polled with interrupts disabled. - The transmit buffers are returned in CdbPtr->DBaddr->TxBufer[0 - NumEntries]. The interrupt status is returned in CdbPtr->StatFlags. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Status ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { PXE_DB_GET_STATUS *DbPtr; PXE_DB_GET_STATUS TmpGetStatus; @@ -1123,26 +1063,24 @@ Returns: return ; } -VOID -UNDI_FillHeader ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to fill media header(s) in transmit packet(s). Copies the MAC address into the media header whether it is dealing with fragmented or non-fragmented packets. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_FillHeader ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { PXE_CPB_FILL_HEADER *Cpb; PXE_CPB_FILL_HEADER_FRAGMENTED *Cpbf; @@ -1198,40 +1136,34 @@ Returns: return ; } -VOID -UNDI_Transmit ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine is used to place a packet into the transmit queue. The data buffers given to this command are to be considered locked and the application or network driver loses ownership of these buffers and must not free or relocate them until the ownership returns. - When the packets are transmitted, a transmit complete interrupt is generated (if interrupts are disabled, the transmit interrupt status is still set and can be checked using the UNDI_Status command. - Some implementations and adapters support transmitting multiple packets with one transmit command. If this feature is supported, the transmit CPBs can be linked in one transmit command. - All UNDIs support fragmented frames, now all network devices or protocols do. If a fragmented frame CPB is given to UNDI and the network device does not support fragmented frames (see !PXE.Implementation flag), the UNDI will have to copy the fragments into a local buffer before transmitting. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @return None -Returns: - None - ---*/ +**/ +VOID +UNDI_Transmit ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { if (CdbPtr->CPBsize == PXE_CPBSIZE_NOT_USED) { @@ -1249,26 +1181,24 @@ Returns: return ; } -VOID -UNDI_Receive ( - IN PXE_CDB *CdbPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** When the network adapter has received a frame, this command is used to copy the frame into the driver/application storage location. Once a frame has been copied, it is removed from the receive queue. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ +VOID +UNDI_Receive ( + IN PXE_CDB *CdbPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { // @@ -1291,27 +1221,25 @@ Returns: } -VOID -UNDI_APIEntry_new ( - IN UINT64 cdb - ) -/*++ -Routine Description: +/** This is the main SW UNDI API entry using the newer nii protocol. The parameter passed in is a 64 bit flat model virtual address of the cdb. We then jump into the common routine for both old and new nii protocol entries. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ // TODO: cdb - add argument and description to function comment +VOID +UNDI_APIEntry_new ( + IN UINT64 cdb + ) { PXE_CDB *CdbPtr; NIC_DATA_INSTANCE *AdapterInfo; @@ -1337,27 +1265,25 @@ Returns: UNDI_APIEntry_Common (cdb); } -VOID -UNDI_APIEntry_Common ( - IN UINT64 cdb - ) -/*++ -Routine Description: +/** This is the common routine for both old and new entry point procedures. The parameter passed in is a 64 bit flat model virtual address of the cdb. We then jump into the service routine pointed to by the Api_Table[OpCode]. -Arguments: - CdbPtr - Pointer to the command descriptor block. - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: - None + @return None ---*/ +**/ // TODO: cdb - add argument and description to function comment +VOID +UNDI_APIEntry_Common ( + IN UINT64 cdb + ) { PXE_CDB *CdbPtr; NIC_DATA_INSTANCE *AdapterInfo; @@ -1453,26 +1379,23 @@ badcdb: return ; } -STATIC -UINT8 -ChkSum ( - IN VOID *Buffer, - IN UINT16 Len - ) -/*++ -Routine Description: +/** This does an 8 bit check sum of the passed in buffer for Len bytes. This is primarily used to update the check sum in the SW UNDI header. -Arguments: - Buffer - Pointer to the passed in buffer to check sum - Len - Length of buffer to be check summed in bytes. + @param Buffer Pointer to the passed in buffer to check sum + @param Len Length of buffer to be check summed in bytes. -Returns: - None + @return None ---*/ +**/ +STATIC +UINT8 +ChkSum ( + IN VOID *Buffer, + IN UINT16 Len + ) { UINT8 Chksum; INT8 *Bp; @@ -1489,27 +1412,24 @@ Returns: return Chksum; } -VOID -PxeUpdate ( - IN NIC_DATA_INSTANCE *NicPtr, - IN PXE_SW_UNDI *PxePtr - ) -/*++ -Routine Description: +/** When called with a null NicPtr, this routine decrements the number of NICs this UNDI is supporting and removes the NIC_DATA_POINTER from the array. Otherwise, it increments the number of NICs this UNDI is supported and updates the pxe.Fudge to ensure a proper check sum results. -Arguments: - NicPtr - Pointer to the NIC data structure. + @param NicPtr Pointer to the NIC data structure. -Returns: - None + @return None ---*/ +**/ // TODO: PxePtr - add argument and description to function comment +VOID +PxeUpdate ( + IN NIC_DATA_INSTANCE *NicPtr, + IN PXE_SW_UNDI *PxePtr + ) { if (NicPtr == NULL) { if (PxePtr->IFcnt > 0) { @@ -1532,25 +1452,22 @@ Returns: return ; } -VOID -PxeStructInit ( - IN PXE_SW_UNDI *PxePtr - ) -/*++ -Routine Description: +/** Initialize the !PXE structure -Arguments: - RemainingDevicePath - Not used, always produce all possible children. + @param RemainingDevicePath Not used, always produce all possible children. -Returns: - EFI_SUCCESS - This driver is added to Controller. - other - This driver does not support this device. + @retval EFI_SUCCESS This driver is added to Controller. + @retval other This driver does not support this device. ---*/ +**/ // TODO: PxePtr - add argument and description to function comment // TODO: VersionFlag - add argument and description to function comment +VOID +PxeStructInit ( + IN PXE_SW_UNDI *PxePtr + ) { // // Initialize the !PXE structure diff --git a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.c b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.c index 2bd7813b18..6612d46041 100644 --- a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.c +++ b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Provides basic function upon network adapter card. Copyright (c) 2006, Intel Corporation All rights reserved. This program and the accompanying materials @@ -9,17 +10,7 @@ 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: - - - E100B.C - -Abstract: - - -Revision History - ---*/ +**/ #include "Undi32.h" @@ -50,28 +41,25 @@ static UINT8 basic_config_cmd[22] = { DelayIt (AdapterInfo, 50); \ } -UINT8 -InByte ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN UINT32 Port - ) -/*++ -Routine Description: +/** This function calls the MemIo callback to read a byte from the device's address space Since UNDI3.0 uses the TmpMemIo function (instead of the callback routine) which also takes the UniqueId parameter (as in UNDI3.1 spec) we don't have to make undi3.0 a special case -Arguments: - Port - Which port to read from. + @param Port Which port to read from. -Returns: - Results - The data read from the port. + @retval Results The data read from the port. ---*/ +**/ // TODO: AdapterInfo - add argument and description to function comment +UINT8 +InByte ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN UINT32 Port + ) { UINT8 Results; @@ -85,28 +73,25 @@ Returns: return Results; } -UINT16 -InWord ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN UINT32 Port - ) -/*++ -Routine Description: +/** This function calls the MemIo callback to read a word from the device's address space Since UNDI3.0 uses the TmpMemIo function (instead of the callback routine) which also takes the UniqueId parameter (as in UNDI3.1 spec) we don't have to make undi3.0 a special case -Arguments: - Port - Which port to read from. + @param Port Which port to read from. -Returns: - Results - The data read from the port. + @retval Results The data read from the port. ---*/ +**/ // TODO: AdapterInfo - add argument and description to function comment +UINT16 +InWord ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN UINT32 Port + ) { UINT16 Results; @@ -120,28 +105,25 @@ Returns: return Results; } -UINT32 -InLong ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN UINT32 Port - ) -/*++ -Routine Description: +/** This function calls the MemIo callback to read a dword from the device's address space Since UNDI3.0 uses the TmpMemIo function (instead of the callback routine) which also takes the UniqueId parameter (as in UNDI3.1 spec) we don't have to make undi3.0 a special case -Arguments: - Port - Which port to read from. + @param Port Which port to read from. -Returns: - Results - The data read from the port. + @retval Results The data read from the port. ---*/ +**/ // TODO: AdapterInfo - add argument and description to function comment +UINT32 +InLong ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN UINT32 Port + ) { UINT32 Results; @@ -155,30 +137,27 @@ Returns: return Results; } -VOID -OutByte ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN UINT8 Data, - IN UINT32 Port - ) -/*++ -Routine Description: +/** This function calls the MemIo callback to write a byte from the device's address space Since UNDI3.0 uses the TmpMemIo function (instead of the callback routine) which also takes the UniqueId parameter (as in UNDI3.1 spec) we don't have to make undi3.0 a special case -Arguments: - Data - Data to write to Port. - Port - Which port to write to. + @param Data Data to write to Port. + @param Port Which port to write to. -Returns: - none + @return none ---*/ +**/ // TODO: AdapterInfo - add argument and description to function comment +VOID +OutByte ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN UINT8 Data, + IN UINT32 Port + ) { UINT8 Val; @@ -193,30 +172,27 @@ Returns: return ; } -VOID -OutWord ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN UINT16 Data, - IN UINT32 Port - ) -/*++ -Routine Description: +/** This function calls the MemIo callback to write a word from the device's address space Since UNDI3.0 uses the TmpMemIo function (instead of the callback routine) which also takes the UniqueId parameter (as in UNDI3.1 spec) we don't have to make undi3.0 a special case -Arguments: - Data - Data to write to Port. - Port - Which port to write to. + @param Data Data to write to Port. + @param Port Which port to write to. -Returns: - none + @return none ---*/ +**/ // TODO: AdapterInfo - add argument and description to function comment +VOID +OutWord ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN UINT16 Data, + IN UINT32 Port + ) { UINT16 Val; @@ -231,30 +207,27 @@ Returns: return ; } -VOID -OutLong ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN UINT32 Data, - IN UINT32 Port - ) -/*++ -Routine Description: +/** This function calls the MemIo callback to write a dword from the device's address space Since UNDI3.0 uses the TmpMemIo function (instead of the callback routine) which also takes the UniqueId parameter (as in UNDI3.1 spec) we don't have to make undi3.0 a special case -Arguments: - Data - Data to write to Port. - Port - Which port to write to. + @param Data Data to write to Port. + @param Port Which port to write to. -Returns: - none + @return none ---*/ +**/ // TODO: AdapterInfo - add argument and description to function comment +VOID +OutLong ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN UINT32 Data, + IN UINT32 Port + ) { UINT32 Val; @@ -269,6 +242,19 @@ Returns: return ; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param MemAddr TODO: add argument description + @param Size TODO: add argument description + @param Direction TODO: add argument description + @param MappedAddr TODO: add argument description + + @return TODO: add return values + +**/ STATIC UINTN MapIt ( @@ -278,25 +264,6 @@ MapIt ( IN UINT32 Direction, OUT UINT64 MappedAddr ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - MemAddr - TODO: add argument description - Size - TODO: add argument description - Direction - TODO: add argument description - MappedAddr - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { UINT64 *PhyAddr; @@ -338,6 +305,19 @@ Returns: return PXE_STATCODE_SUCCESS; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param MemAddr TODO: add argument description + @param Size TODO: add argument description + @param Direction TODO: add argument description + @param MappedAddr TODO: add argument description + + @return TODO: add return values + +**/ STATIC VOID UnMapIt ( @@ -347,25 +327,6 @@ UnMapIt ( IN UINT32 Direction, IN UINT64 MappedAddr ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - MemAddr - TODO: add argument description - Size - TODO: add argument description - Direction - TODO: add argument description - MappedAddr - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { if (AdapterInfo->VersionFlag > 0x30) { // @@ -386,24 +347,22 @@ Returns: return ; } + +/** + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + +**/ +// TODO: MicroSeconds - add argument and description to function comment STATIC VOID DelayIt ( IN NIC_DATA_INSTANCE *AdapterInfo, UINT16 MicroSeconds ) -/*++ - -Routine Description: - -Arguments: - AdapterInfo - Pointer to the NIC data structure information - which the UNDI driver is layering on.. - -Returns: - ---*/ -// TODO: MicroSeconds - add argument and description to function comment { if (AdapterInfo->VersionFlag == 0x30) { (*AdapterInfo->Delay_30) (MicroSeconds); @@ -412,24 +371,22 @@ Returns: } } + +/** + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + +**/ +// TODO: flag - add argument and description to function comment STATIC VOID BlockIt ( IN NIC_DATA_INSTANCE *AdapterInfo, UINT32 flag ) -/*++ - -Routine Description: - -Arguments: - AdapterInfo - Pointer to the NIC data structure information - which the UNDI driver is layering on.. - -Returns: - ---*/ -// TODO: flag - add argument and description to function comment { if (AdapterInfo->VersionFlag == 0x30) { (*AdapterInfo->Block_30) (flag); @@ -438,26 +395,20 @@ Returns: } } -STATIC -UINT8 -Load_Base_Regs ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +STATIC +UINT8 +Load_Base_Regs ( + NIC_DATA_INSTANCE *AdapterInfo + ) { // // we will use the linear (flat) memory model and fill our base registers @@ -488,28 +439,22 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param cmd_ptr TODO: add argument description + + @return TODO: add return values + +**/ STATIC UINT8 IssueCB ( NIC_DATA_INSTANCE *AdapterInfo, TxCB *cmd_ptr ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - cmd_ptr - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { UINT16 status; @@ -555,26 +500,20 @@ Returns: return 0; } -STATIC -UINT8 -Configure ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +STATIC +UINT8 +Configure ( + NIC_DATA_INSTANCE *AdapterInfo + ) { // // all command blocks are of TxCB format @@ -632,25 +571,19 @@ Returns: return 0; } -UINT8 -E100bSetupIAAddr ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: + @param AdapterInfo TODO: add argument description - AdapterInfo - TODO: add argument description + @return TODO: add return values -Returns: - - TODO: add return values - ---*/ +**/ +UINT8 +E100bSetupIAAddr ( + NIC_DATA_INSTANCE *AdapterInfo + ) { // // all command blocks are of TxCB format @@ -693,22 +626,21 @@ Returns: return 0; } + +/** + Instructs the NIC to stop receiving packets. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + +**/ STATIC VOID StopRU ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - Instructs the NIC to stop receiving packets. - -Arguments: - AdapterInfo - Pointer to the NIC data structure information - which the UNDI driver is layering on.. -Returns: - ---*/ { if (AdapterInfo->Receive_Started) { @@ -729,23 +661,23 @@ Returns: return ; } + +/** + Instructs the NIC to start receiving packets. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + @retval 0 Successful + @retval -1 Already Started + +**/ STATIC INT8 StartRU ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - Instructs the NIC to start receiving packets. - -Arguments: - AdapterInfo - Pointer to the NIC data structure information - which the UNDI driver is layering on.. -Returns: - 0 - Successful - -1 - Already Started ---*/ { if (AdapterInfo->Receive_Started) { @@ -769,24 +701,23 @@ Returns: return 0; } -UINTN -E100bInit ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** Configures the chip. This routine expects the NIC_DATA_INSTANCE structure to be filled in. -Arguments: - AdapterInfo - Pointer to the NIC data structure information - which the UNDI driver is layering on.. + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. -Returns: - 0 - Successful - PXE_STATCODE_NOT_ENOUGH_MEMORY - Insufficient length of locked memory - other - Failure initializing chip ---*/ + @retval 0 Successful + @retval PXE_STATCODE_NOT_ENOUGH_MEMORY Insufficient length of locked memory + @retval other Failure initializing chip + +**/ +UINTN +E100bInit ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { PCI_CONFIG_HEADER *CfgHdr; UINTN stat; @@ -865,21 +796,21 @@ Returns: return InitializeChip (AdapterInfo); } + +/** + Sets the interrupt state for the NIC. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + @retval 0 Successful + +**/ UINT8 E100bSetInterruptState ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - Sets the interrupt state for the NIC. - -Arguments: - AdapterInfo - Pointer to the NIC data structure information - which the UNDI driver is layering on.. -Returns: - 0 - Successful ---*/ { // // don't set receive interrupt if receiver is disabled... @@ -912,6 +843,20 @@ Returns: // // we are not going to disable broadcast for the WOL's sake! // + +/** + Instructs the NIC to start receiving packets. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. new_filter + - cpb - + cpbsize - + + @retval 0 Successful + @retval -1 Already Started + +**/ UINTN E100bSetfilter ( NIC_DATA_INSTANCE *AdapterInfo, @@ -919,22 +864,6 @@ E100bSetfilter ( UINT64 cpb, UINT32 cpbsize ) -/*++ - -Routine Description: - Instructs the NIC to start receiving packets. - -Arguments: - AdapterInfo - Pointer to the NIC data structure information - which the UNDI driver is layering on.. - new_filter - - cpb - - cpbsize - - -Returns: - 0 - Successful - -1 - Already Started ---*/ { PXE_CPB_RECEIVE_FILTERS *mc_list = (PXE_CPB_RECEIVE_FILTERS *) (UINTN)cpb; UINT16 cfg_flt; @@ -1074,29 +1003,23 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param cpb TODO: add argument description + @param opflags TODO: add argument description + + @return TODO: add return values + +**/ UINTN E100bTransmit ( NIC_DATA_INSTANCE *AdapterInfo, UINT64 cpb, UINT16 opflags ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - cpb - TODO: add argument description - opflags - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { PXE_CPB_TRANSMIT_FRAGMENTS *tx_ptr_f; PXE_CPB_TRANSMIT *tx_ptr_1; @@ -1262,29 +1185,23 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param cpb TODO: add argument description + @param db TODO: add argument description + + @return TODO: add return values + +**/ UINTN E100bReceive ( NIC_DATA_INSTANCE *AdapterInfo, UINT64 cpb, UINT64 db ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - cpb - TODO: add argument description - db - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { PXE_CPB_RECEIVE *rx_cpbptr; PXE_DB_RECEIVE *rx_dbptr; @@ -1392,7 +1309,7 @@ Returns: // mcast // - pkt_type = PXE_FRAME_TYPE_MULTICAST; + pkt_type = PXE_FRAME_TYPE_FILTERED_MULTICAST; } else { pkt_type = PXE_FRAME_TYPE_PROMISCUOUS; } @@ -1449,25 +1366,19 @@ FreeRFD: return ret_code; } -INT16 -E100bReadEepromAndStationAddress ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +INT16 +E100bReadEepromAndStationAddress ( + NIC_DATA_INSTANCE *AdapterInfo + ) { INT32 Index; INT32 Index2; @@ -1524,25 +1435,19 @@ Returns: // 3) when one is free, Tail == Head and Freecount == 1 // 4) First non-Free frame is always at Tail->next // -UINT8 -SetupCBlink ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +UINT8 +SetupCBlink ( + NIC_DATA_INSTANCE *AdapterInfo + ) { TxCB *head_ptr; TxCB *tail_ptr; @@ -1590,25 +1495,19 @@ Returns: return 0; } -TxCB * -GetFreeCB ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +TxCB * +GetFreeCB ( + NIC_DATA_INSTANCE *AdapterInfo + ) { TxCB *free_cb_ptr; @@ -1637,27 +1536,21 @@ Returns: return free_cb_ptr; } -VOID -SetFreeCB ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN TxCB *cb_ptr - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - cb_ptr - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description + @param cb_ptr TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +VOID +SetFreeCB ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN TxCB *cb_ptr + ) { // // here we assume cb are returned in the order they are taken out @@ -1671,25 +1564,19 @@ Returns: return ; } -UINT16 -next ( - IN UINT16 ind - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - ind - TODO: add argument description + @param ind TODO: add argument description -Returns: - - TODO: add return values + @return TODO: add return values ---*/ +**/ +UINT16 +next ( + IN UINT16 ind + ) { UINT16 Tmp; @@ -1701,25 +1588,19 @@ Returns: return Tmp; } -UINT16 -CheckCBList ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +UINT16 +CheckCBList ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { TxCB *Tmp_ptr; UINT16 cnt; @@ -1762,25 +1643,19 @@ Returns: // bit in the previous RXFD is cleared. // Allocation done during INIT, this is making linked list. // -UINT8 -SetupReceiveQueues ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +UINT8 +SetupReceiveQueues ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { RxFD *rx_ptr; RxFD *tail_ptr; @@ -1823,27 +1698,21 @@ Returns: return 0; } -VOID -Recycle_RFD ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN UINT16 rx_index - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - rx_index - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description + @param rx_index TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +VOID +Recycle_RFD ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN UINT16 rx_index + ) { RxFD *rx_ptr; RxFD *tail_ptr; @@ -1956,26 +1825,20 @@ Returns: } } -STATIC -UINT16 -shift_bits_in ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +STATIC +UINT16 +shift_bits_in ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINT8 Tmp; INT32 Index; @@ -2008,26 +1871,25 @@ Returns: return retval; } -STATIC -BOOLEAN -E100bSetEepromLockOut ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine sets the EEPROM lockout bit to gain exclusive access to the eeprom. the access bit is the most significant bit in the General Control Register 2 in the SCB space. -Arguments: - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. -Returns: - TRUE - if it got the access - FALSE - if it fails to get the exclusive access + @retval TRUE if it got the access + @retval FALSE if it fails to get the exclusive access ---*/ +**/ +STATIC +BOOLEAN +E100bSetEepromLockOut ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINTN wait; UINT8 tmp; @@ -2057,25 +1919,24 @@ Returns: return TRUE; } -STATIC -VOID -E100bReSetEepromLockOut ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** This routine Resets the EEPROM lockout bit to giveup access to the eeprom. the access bit is the most significant bit in the General Control Register 2 in the SCB space. -Arguments: - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. -Returns: - None + @return None ---*/ +**/ +STATIC +VOID +E100bReSetEepromLockOut ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINT8 tmp; @@ -2090,26 +1951,25 @@ Returns: } } + +/** + Using the NIC data structure information, read the EEPROM to get a Word of data for the MAC address. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + @param Location Word offset into the MAC address to read. + @param AddrLen Number of bits of address length. + + @retval RetVal The word read from the EEPROM. + +**/ UINT16 E100bReadEeprom ( IN NIC_DATA_INSTANCE *AdapterInfo, IN INT32 Location, IN UINT8 AddrLen ) -/*++ - -Routine Description: - Using the NIC data structure information, read the EEPROM to get a Word of data for the MAC address. - -Arguments: - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. - Location - Word offset into the MAC address to read. - AddrLen - Number of bits of address length. - -Returns: - RetVal - The word read from the EEPROM. - ---*/ { UINT16 RetVal; UINT8 Tmp; @@ -2174,23 +2034,22 @@ Returns: return RetVal; } -UINT8 -E100bGetEepromAddrLen ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: +/** Using the NIC data structure information, read the EEPROM to determine how many bits of address length this EEPROM is in Words. -Arguments: - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. -Returns: - RetVal - The word read from the EEPROM. + @retval RetVal The word read from the EEPROM. ---*/ +**/ +UINT8 +E100bGetEepromAddrLen ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINT8 Tmp; UINT8 AddrLen; @@ -2286,29 +2145,23 @@ Returns: return AddrLen; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param DBaddr TODO: add argument description + @param DBsize TODO: add argument description + + @return TODO: add return values + +**/ UINTN E100bStatistics ( NIC_DATA_INSTANCE *AdapterInfo, UINT64 DBaddr, UINT16 DBsize ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - DBaddr - TODO: add argument description - DBsize - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { PXE_DB_STATISTICS db; // @@ -2426,27 +2279,21 @@ Returns: return PXE_STATCODE_SUCCESS; } -UINTN -E100bReset ( - IN NIC_DATA_INSTANCE *AdapterInfo, - IN INT32 OpFlags - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - OpFlags - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description + @param OpFlags TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +UINTN +E100bReset ( + IN NIC_DATA_INSTANCE *AdapterInfo, + IN INT32 OpFlags + ) { UINT16 save_filter; @@ -2497,25 +2344,19 @@ Returns: return 0; } -UINTN -E100bShutdown ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +UINTN +E100bShutdown ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { // // disable the interrupts @@ -2546,6 +2387,22 @@ Returns: return 0; } + +/** + This routine will write a value to the specified MII register + of an external MDI compliant device (e.g. PHY 100). The command will + execute in polled mode. + + @param AdapterInfo pointer to the structure that contains + the NIC's context. + @param RegAddress The MII register that we are writing to + @param PhyAddress The MDI address of the Phy component. + @param DataValue The value that we are writing to the MII + register. + + @return nothing + +**/ VOID MdiWrite ( IN NIC_DATA_INSTANCE *AdapterInfo, @@ -2553,22 +2410,6 @@ MdiWrite ( IN UINT8 PhyAddress, IN UINT16 DataValue ) -/*++ - -Routine Description: - This routine will write a value to the specified MII register - of an external MDI compliant device (e.g. PHY 100). The command will - execute in polled mode. - -Arguments: - AdapterInfo - pointer to the structure that contains the NIC's context. - RegAddress - The MII register that we are writing to - PhyAddress - The MDI address of the Phy component. - DataValue - The value that we are writing to the MII register. - -Returns: - nothing ---*/ { UINT32 WriteCommand; @@ -2595,6 +2436,21 @@ Returns: } } + +/** + This routine will read a value from the specified MII register + of an external MDI compliant device (e.g. PHY 100), and return + it to the calling routine. The command will execute in polled mode. + + @param AdapterInfo pointer to the structure that contains + the NIC's context. + @param RegAddress The MII register that we are reading from + @param PhyAddress The MDI address of the Phy component. + @param DataValue pointer to the value that we read from + the MII register. + + +**/ VOID MdiRead ( IN NIC_DATA_INSTANCE *AdapterInfo, @@ -2602,22 +2458,6 @@ MdiRead ( IN UINT8 PhyAddress, IN OUT UINT16 *DataValue ) -/*++ - -Routine Description: - This routine will read a value from the specified MII register - of an external MDI compliant device (e.g. PHY 100), and return - it to the calling routine. The command will execute in polled mode. - -Arguments: - AdapterInfo - pointer to the structure that contains the NIC's context. - RegAddress - The MII register that we are reading from - PhyAddress - The MDI address of the Phy component. - DataValue - pointer to the value that we read from the MII register. - -Returns: - ---*/ { UINT32 ReadCommand; @@ -2647,22 +2487,20 @@ Returns: *DataValue = InWord (AdapterInfo, AdapterInfo->ioaddr + SCBCtrlMDI); } -VOID -PhyReset ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ -Routine Description: - This routine will reset the PHY that the adapter is currently - configured to use. +/** + This routine will reset the PHY that the adapter is currently + configured to use. -Arguments: - AdapterInfo - pointer to the structure that contains the NIC's context. + @param AdapterInfo pointer to the structure that contains + the NIC's context. -Returns: ---*/ +**/ +VOID +PhyReset ( + NIC_DATA_INSTANCE *AdapterInfo + ) { UINT16 MdiControlReg; @@ -2683,53 +2521,49 @@ Returns: return ; } + +/** + This routine will detect what phy we are using, set the line + speed, FDX or HDX, and configure the phy if necessary. + The following combinations are supported: + - TX or T4 PHY alone at PHY address 1 + - T4 or TX PHY at address 1 and MII PHY at address 0 + - 82503 alone (10Base-T mode, no full duplex support) + - 82503 and MII PHY (TX or T4) at address 0 + The sequence / priority of detection is as follows: + - PHY 1 with cable termination + - PHY 0 with cable termination + - PHY 1 (if found) without cable termination + - 503 interface + Additionally auto-negotiation capable (NWAY) and parallel + detection PHYs are supported. The flow-chart is described in + the 82557 software writer's manual. + NOTE: 1. All PHY MDI registers are read in polled mode. + 2. The routines assume that the 82557 has been RESET and we have + obtained the virtual memory address of the CSR. + 3. PhyDetect will not RESET the PHY. + 4. If FORCEFDX is set, SPEED should also be set. The driver will + check the values for inconsistency with the detected PHY + technology. + 5. PHY 1 (the PHY on the adapter) may have an address in the range + 1 through 31 inclusive. The driver will accept addresses in + this range. + 6. Driver ignores FORCEFDX and SPEED overrides if a 503 interface + is detected. + + @param AdapterInfo pointer to the structure that contains + the NIC's context. + + @retval TRUE If a Phy was detected, and configured + correctly. + @retval FALSE If a valid phy could not be detected and + configured. + +**/ BOOLEAN PhyDetect ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - This routine will detect what phy we are using, set the line - speed, FDX or HDX, and configure the phy if necessary. - - The following combinations are supported: - - TX or T4 PHY alone at PHY address 1 - - T4 or TX PHY at address 1 and MII PHY at address 0 - - 82503 alone (10Base-T mode, no full duplex support) - - 82503 and MII PHY (TX or T4) at address 0 - - The sequence / priority of detection is as follows: - - PHY 1 with cable termination - - PHY 0 with cable termination - - PHY 1 (if found) without cable termination - - 503 interface - - Additionally auto-negotiation capable (NWAY) and parallel - detection PHYs are supported. The flow-chart is described in - the 82557 software writer's manual. - - NOTE: 1. All PHY MDI registers are read in polled mode. - 2. The routines assume that the 82557 has been RESET and we have - obtained the virtual memory address of the CSR. - 3. PhyDetect will not RESET the PHY. - 4. If FORCEFDX is set, SPEED should also be set. The driver will - check the values for inconsistency with the detected PHY - technology. - 5. PHY 1 (the PHY on the adapter) may have an address in the range - 1 through 31 inclusive. The driver will accept addresses in - this range. - 6. Driver ignores FORCEFDX and SPEED overrides if a 503 interface - is detected. - -Arguments: - AdapterInfo - pointer to the structure that contains the NIC's context. - -Returns: - TRUE - If a Phy was detected, and configured correctly. - FALSE - If a valid phy could not be detected and configured. - ---*/ { UINT16 *eedata; UINT16 MdiControlReg; @@ -3005,35 +2839,33 @@ Returns: } } + +/** + This routine will setup phy 1 or phy 0 so that it is configured + to match a speed and duplex over-ride option. If speed or + duplex mode is not explicitly specified in the registry, the + driver will skip the speed and duplex over-ride code, and + assume the adapter is automatically setting the line speed, and + the duplex mode. At the end of this routine, any truly Phy + specific code will be executed (each Phy has its own quirks, + and some require that certain special bits are set). + NOTE: The driver assumes that SPEED and FORCEFDX are specified at the + same time. If FORCEDPX is set without speed being set, the driver + will encouter a fatal error and log a message into the event viewer. + + @param AdapterInfo pointer to the structure that contains + the NIC's context. + + @retval TRUE If the phy could be configured correctly + @retval FALSE If the phy couldn't be configured + correctly, because an unsupported + over-ride option was used + +**/ BOOLEAN SetupPhy ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - This routine will setup phy 1 or phy 0 so that it is configured - to match a speed and duplex over-ride option. If speed or - duplex mode is not explicitly specified in the registry, the - driver will skip the speed and duplex over-ride code, and - assume the adapter is automatically setting the line speed, and - the duplex mode. At the end of this routine, any truly Phy - specific code will be executed (each Phy has its own quirks, - and some require that certain special bits are set). - - NOTE: The driver assumes that SPEED and FORCEFDX are specified at the - same time. If FORCEDPX is set without speed being set, the driver - will encouter a fatal error and log a message into the event viewer. - -Arguments: - AdapterInfo - pointer to the structure that contains the NIC's context. - -Returns: - TRUE - If the phy could be configured correctly - FALSE - If the phy couldn't be configured correctly, because an - unsupported over-ride option was used - ---*/ { UINT16 MdiControlReg; UINT16 MdiStatusReg; @@ -3229,24 +3061,23 @@ Returns: return (TRUE); } + +/** + This routine will figure out what line speed and duplex mode + the PHY is currently using. + + @param AdapterInfo pointer to the structure that contains + the NIC's context. + @param PhyId The ID of the PHY in question. + + @return NOTHING + +**/ VOID FindPhySpeedAndDpx ( IN NIC_DATA_INSTANCE *AdapterInfo, IN UINT32 PhyId ) -/*++ - -Routine Description: - This routine will figure out what line speed and duplex mode - the PHY is currently using. - -Arguments: - AdapterInfo - pointer to the structure that contains the NIC's context. - PhyId - The ID of the PHY in question. - -Returns: - NOTHING ---*/ { UINT16 MdiStatusReg; UINT16 MdiMiscReg; @@ -3452,25 +3283,19 @@ Returns: } } -VOID -XmitWaitForCompletion ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +VOID +XmitWaitForCompletion ( + NIC_DATA_INSTANCE *AdapterInfo + ) { TxCB *TxPtr; @@ -3490,27 +3315,21 @@ Returns: } } -INT8 -CommandWaitForCompletion ( - TxCB *cmd_ptr, - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - cmd_ptr - TODO: add argument description - AdapterInfo - TODO: add argument description - -Returns: + @param cmd_ptr TODO: add argument description + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +INT8 +CommandWaitForCompletion ( + TxCB *cmd_ptr, + NIC_DATA_INSTANCE *AdapterInfo + ) { INT16 wait; wait = 5000; @@ -3525,26 +3344,20 @@ Returns: return 0; } -STATIC -INT8 -SoftwareReset ( - NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +STATIC +INT8 +SoftwareReset ( + NIC_DATA_INSTANCE *AdapterInfo + ) { UINT8 tco_stat; UINT16 wait; @@ -3632,25 +3445,19 @@ Returns: return 0; } -UINT8 -SelectiveReset ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +UINT8 +SelectiveReset ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINT16 wait; UINT32 stat; @@ -3686,25 +3493,19 @@ Returns: return 0; } -UINT16 -InitializeChip ( - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** TODO: Add function description -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: + @param AdapterInfo TODO: add argument description - TODO: add return values + @return TODO: add return values ---*/ +**/ +UINT16 +InitializeChip ( + IN NIC_DATA_INSTANCE *AdapterInfo + ) { UINT16 ret_val; if (SoftwareReset (AdapterInfo) != 0) { diff --git a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.h b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.h index d1107ddba7..957e92b604 100644 --- a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.h +++ b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.h @@ -1,4 +1,5 @@ -/*++ +/** @file + Definitions for network adapter card. Copyright (c) 2006 - 2007, Intel Corporation All rights reserved. This program and the accompanying materials @@ -9,16 +10,8 @@ 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: +**/ - E100B.H - -Abstract: - - -Revision History - ---*/ // pci config offsets: #define RX_BUFFER_COUNT 32 diff --git a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Init.c b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Init.c index 413ef32a7a..28ce111269 100644 --- a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Init.c +++ b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Init.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Initialization functions for EFI UNDI32 driver. Copyright (c) 2006 - 2007, Intel Corporation All rights reserved. This program and the accompanying materials @@ -9,20 +10,9 @@ 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: - - init.c - -Abstract: - - Initialization functions for EFI UNDI32 driver - -Revision History - ---*/ +**/ #include "Undi32.h" -#include // // Global Variables // @@ -31,29 +21,23 @@ PXE_SW_UNDI *pxe_31 = NULL; // 3.1 entry UNDI32_DEV *UNDI32DeviceList[MAX_NIC_INTERFACES]; NII_TABLE *UndiDataPointer = NULL; -VOID -EFIAPI -UndiNotifyVirtual ( - EFI_EVENT Event, - VOID *Context - ) -/*++ - -Routine Description: +/** When address mapping changes to virtual this should make the appropriate address conversions. -Arguments: - (Standard Event handler) -Returns: + @return None - None - ---*/ +**/ // TODO: Context - add argument and description to function comment +VOID +EFIAPI +UndiNotifyVirtual ( + EFI_EVENT Event, + VOID *Context + ) { UINT16 Index; VOID *Pxe31Pointer; @@ -62,7 +46,7 @@ Returns: Pxe31Pointer = (VOID *) pxe_31; EfiConvertPointer ( - EFI_OPTIONAL_POINTER, + EFI_OPTIONAL_PTR, (VOID **) &Pxe31Pointer ); @@ -72,13 +56,13 @@ Returns: for (Index = 0; Index < pxe_31->IFcnt; Index++) { UNDI32DeviceList[Index]->NIIProtocol_31.ID = (UINT64) (UINTN) Pxe31Pointer; EfiConvertPointer ( - EFI_OPTIONAL_POINTER, + EFI_OPTIONAL_PTR, (VOID **) &(UNDI32DeviceList[Index]) ); } EfiConvertPointer ( - EFI_OPTIONAL_POINTER, + EFI_OPTIONAL_PTR, (VOID **) &(pxe_31->EntryPoint) ); pxe_31 = Pxe31Pointer; @@ -86,35 +70,29 @@ Returns: for (Index = 0; Index <= PXE_OPCODE_LAST_VALID; Index++) { EfiConvertPointer ( - EFI_OPTIONAL_POINTER, + EFI_OPTIONAL_PTR, (VOID **) &api_table[Index].api_ptr ); } } -VOID -EFIAPI -UndiNotifyExitBs ( - EFI_EVENT Event, - VOID *Context - ) -/*++ - -Routine Description: +/** When EFI is shuting down the boot services, we need to install a configuration table for UNDI to work at runtime! -Arguments: - (Standard Event handler) -Returns: + @return None - None - ---*/ +**/ // TODO: Context - add argument and description to function comment +VOID +EFIAPI +UndiNotifyExitBs ( + EFI_EVENT Event, + VOID *Context + ) { InstallConfigTable (); } @@ -131,38 +109,29 @@ EFI_DRIVER_BINDING_PROTOCOL gUndiDriverBinding = { }; -EFI_STATUS -EFIAPI -UndiDriverSupported ( - IN EFI_DRIVER_BINDING_PROTOCOL *This, - IN EFI_HANDLE Controller, - IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath - ) -/*++ - -Routine Description: +/** Test to see if this driver supports ControllerHandle. Any ControllerHandle than contains a DevicePath, PciIo protocol, Class code of 2, Vendor ID of 0x8086, and DeviceId of (D100_DEVICE_ID || D102_DEVICE_ID || ICH3_DEVICE_ID_1 || ICH3_DEVICE_ID_2 || ICH3_DEVICE_ID_3 || ICH3_DEVICE_ID_4 || ICH3_DEVICE_ID_5 || ICH3_DEVICE_ID_6 || ICH3_DEVICE_ID_7 || ICH3_DEVICE_ID_8) can be supported. -Arguments: - - This - Protocol instance pointer. - - Controller - Handle of device to test. + @param This Protocol instance pointer. + @param Controller Handle of device to test. + @param RemainingDevicePath Not used. - RemainingDevicePath - Not used. + @retval EFI_SUCCESS This driver supports this device. + @retval other This driver does not support this device. -Returns: - - EFI_SUCCESS - This driver supports this device. - - other - This driver does not support this device. - ---*/ +**/ +EFI_STATUS +EFIAPI +UndiDriverSupported ( + IN EFI_DRIVER_BINDING_PROTOCOL *This, + IN EFI_HANDLE Controller, + IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath + ) { EFI_STATUS Status; EFI_PCI_IO_PROTOCOL *PciIo; @@ -246,37 +215,28 @@ Returns: return Status; } -EFI_STATUS -EFIAPI -UndiDriverStart ( - IN EFI_DRIVER_BINDING_PROTOCOL *This, - IN EFI_HANDLE Controller, - IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath - ) -/*++ - -Routine Description: +/** Start this driver on Controller by opening PciIo and DevicePath protocol. Initialize PXE structures, create a copy of the Controller Device Path with the NIC's MAC address appended to it, install the NetworkInterfaceIdentifier protocol on the newly created Device Path. -Arguments: - - This - Protocol instance pointer. - - Controller - Handle of device to work with. + @param This Protocol instance pointer. + @param Controller Handle of device to work with. + @param RemainingDevicePath Not used, always produce all possible children. - RemainingDevicePath - Not used, always produce all possible children. + @retval EFI_SUCCESS This driver is added to Controller. + @retval other This driver does not support this device. -Returns: - - EFI_SUCCESS - This driver is added to Controller. - - other - This driver does not support this device. - ---*/ +**/ +EFI_STATUS +EFIAPI +UndiDriverStart ( + IN EFI_DRIVER_BINDING_PROTOCOL *This, + IN EFI_HANDLE Controller, + IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath + ) { EFI_STATUS Status; EFI_DEVICE_PATH_PROTOCOL *UndiDevicePath; @@ -506,7 +466,7 @@ Returns: // if the table exists, free it and alloc again, or alloc it directly // if (UndiDataPointer != NULL) { - Status = gBS->FreePool(UndiDataPointer); + Status = gBS->FreePool(UndiDataPointer); } if (EFI_ERROR (Status)) { goto UndiErrorDeleteDevicePath; @@ -586,6 +546,21 @@ UndiError: return Status; } + +/** + Stop this driver on Controller by removing NetworkInterfaceIdentifier protocol and + closing the DevicePath and PciIo protocols on Controller. + + @param This Protocol instance pointer. + @param Controller Handle of device to stop driver on. + @param NumberOfChildren How many children need to be stopped. + @param ChildHandleBuffer Not used. + + @retval EFI_SUCCESS This driver is removed Controller. + @retval other This driver was not removed from this device. + +**/ +// TODO: EFI_DEVICE_ERROR - add return value to function comment EFI_STATUS EFIAPI UndiDriverStop ( @@ -594,24 +569,6 @@ UndiDriverStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/*++ - -Routine Description: - Stop this driver on Controller by removing NetworkInterfaceIdentifier protocol and - closing the DevicePath and PciIo protocols on Controller. - -Arguments: - This - Protocol instance pointer. - Controller - Handle of device to stop driver on. - NumberOfChildren - How many children need to be stopped. - ChildHandleBuffer - Not used. - -Returns: - EFI_SUCCESS - This driver is removed Controller. - other - This driver was not removed from this device. - ---*/ -// TODO: EFI_DEVICE_ERROR - add return value to function comment { EFI_STATUS Status; BOOLEAN AllChildrenStopped; @@ -717,34 +674,44 @@ Returns: } -VOID -TmpDelay ( - IN UINT64 UnqId, - IN UINTN MicroSeconds - ) -/*++ - -Routine Description: +/** Use the EFI boot services to produce a pause. This is also the routine which gets replaced during RunTime by the O/S in the NIC_DATA_INSTANCE so it can do it's own pause. -Arguments: - - UnqId - Runtime O/S routine might use this, this temp routine does not use it - - MicroSeconds - Determines the length of pause. + @param UnqId Runtime O/S routine might use this, this temp + routine does not use it + @param MicroSeconds Determines the length of pause. -Returns: - - none + @return none ---*/ +**/ +VOID +TmpDelay ( + IN UINT64 UnqId, + IN UINTN MicroSeconds + ) { gBS->Stall ((UINT32) MicroSeconds); } + +/** + Use the PCI IO abstraction to issue memory or I/O reads and writes. This is also the routine which + gets replaced during RunTime by the O/S in the NIC_DATA_INSTANCE so it can do it's own I/O abstractions. + + @param UnqId Runtime O/S routine may use this field, this temp + routine does not. + @param ReadWrite Determine if it is an I/O or Memory Read/Write + Operation. + @param Len Determines the width of the data operation. + @param Port What port to Read/Write from. + @param BuffAddr Address to read to or write from. + + @return none + +**/ VOID TmpMemIo ( IN UINT64 UnqId, @@ -753,30 +720,6 @@ TmpMemIo ( IN UINT64 Port, IN UINT64 BuffAddr ) -/*++ - -Routine Description: - - Use the PCI IO abstraction to issue memory or I/O reads and writes. This is also the routine which - gets replaced during RunTime by the O/S in the NIC_DATA_INSTANCE so it can do it's own I/O abstractions. - -Arguments: - - UnqId - Runtime O/S routine may use this field, this temp routine does not. - - ReadWrite - Determine if it is an I/O or Memory Read/Write Operation. - - Len - Determines the width of the data operation. - - Port - What port to Read/Write from. - - BuffAddr - Address to read to or write from. - -Returns: - - none - ---*/ { EFI_PCI_IO_PROTOCOL_WIDTH Width; NIC_DATA_INSTANCE *AdapterInfo; @@ -846,35 +789,31 @@ Returns: return ; } -EFI_STATUS -AppendMac2DevPath ( - IN OUT EFI_DEVICE_PATH_PROTOCOL **DevPtr, - IN EFI_DEVICE_PATH_PROTOCOL *BaseDevPtr, - IN NIC_DATA_INSTANCE *AdapterInfo - ) -/*++ - -Routine Description: +/** Using the NIC data structure information, read the EEPROM to get the MAC address and then allocate space for a new devicepath (**DevPtr) which will contain the original device path the NIC was found on (*BaseDevPtr) and an added MAC node. -Arguments: - - DevPtr - Pointer which will point to the newly created device path with the MAC node attached. - - BaseDevPtr - Pointer to the device path which the UNDI device driver is latching on to. - - AdapterInfo - Pointer to the NIC data structure information which the UNDI driver is layering on.. + @param DevPtr Pointer which will point to the newly created device + path with the MAC node attached. + @param BaseDevPtr Pointer to the device path which the UNDI device + driver is latching on to. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. -Returns: + @retval EFI_SUCCESS A MAC address was successfully appended to the Base + Device Path. + @retval other Not enough resources available to create new Device + Path node. - EFI_SUCCESS - A MAC address was successfully appended to the Base Device Path. - - other - Not enough resources available to create new Device Path node. - ---*/ +**/ +EFI_STATUS +AppendMac2DevPath ( + IN OUT EFI_DEVICE_PATH_PROTOCOL **DevPtr, + IN EFI_DEVICE_PATH_PROTOCOL *BaseDevPtr, + IN NIC_DATA_INSTANCE *AdapterInfo + ) { EFI_MAC_ADDRESS MACAddress; PCI_CONFIG_HEADER *CfgHdr; @@ -986,28 +925,23 @@ Returns: return EFI_SUCCESS; } -EFI_STATUS -InstallConfigTable ( - IN VOID - ) -/*++ - -Routine Description: +/** Install a GUID/Pointer pair into the system's configuration table. -Arguments: - none -Returns: + @retval EFI_SUCCESS Install a GUID/Pointer pair into the system's + configuration table. + @retval other Did not successfully install the GUID/Pointer pair + into the configuration table. - EFI_SUCCESS - Install a GUID/Pointer pair into the system's configuration table. - - other - Did not successfully install the GUID/Pointer pair into the configuration table. - ---*/ +**/ // TODO: VOID - add argument and description to function comment +EFI_STATUS +InstallConfigTable ( + IN VOID + ) { EFI_STATUS Status; EFI_CONFIGURATION_TABLE *CfgPtr; @@ -1020,7 +954,7 @@ Returns: } if(UndiDataPointer == NULL) { - return EFI_SUCCESS; + return EFI_SUCCESS; } UndiData = (NII_TABLE *)UndiDataPointer; @@ -1080,14 +1014,6 @@ Returns: /** - Install driver binding protocol of UNDI. - - @param[in] ImageHandle The firmware allocated handle for the EFI image. - @param[in] SystemTable A pointer to the EFI System Table. - - @retval EFI_SUCCESS The entry point is executed successfully. - @retval other Some error occurs when executing this entry point. - **/ EFI_STATUS EFIAPI diff --git a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Undi32.h b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Undi32.h index 32f80fa8f2..43994c7121 100644 --- a/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Undi32.h +++ b/MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Undi32.h @@ -1,5 +1,5 @@ - -/*++ +/** @file + EFI internal structures for the EFI UNDI driver. Copyright (c) 2006 - 2007, Intel Corporation. All rights reserved. This program and the accompanying materials @@ -10,19 +10,7 @@ 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: - - undi32.h - -Abstract: - - EFI internal structures for the EFI UNDI driver - - - -Revision History - ---*/ +**/ #ifndef _UNDI_32_H_ #define _UNDI_32_H_ -- 2.39.2