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 | 709 +++++----- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.c | 1309 ++++++++---------- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/E100b.h | 13 +- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Init.c | 350 ++--- MdeModulePkg/Bus/Pci/UndiRuntimeDxe/Undi32.h | 18 +- 5 files changed, 1012 insertions(+), 1387 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 // + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { 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 ; } + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { if (AdapterInfo->State == PXE_STATFLAGS_GET_STATE_INITIALIZED) { CdbPtr->StatFlags = PXE_STATFLAGS_COMMAND_FAILED; @@ -236,31 +216,27 @@ Returns: return ; } + +/** + 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) + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { PXE_DB_GET_INIT_INFO *DbPtr; @@ -292,30 +268,26 @@ Returns: return ; } + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { UINT16 Index; PXE_DB_GET_CONFIG_INFO *DbPtr; @@ -334,37 +306,32 @@ Returns: return ; } + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { PXE_CPB_INITIALIZE *CpbPtr; @@ -414,27 +381,24 @@ Returns: return ; } + +/** + 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 + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { if (CdbPtr->OpFlags != PXE_OPFLAGS_NOT_USED && CdbPtr->OpFlags != PXE_OPFLAGS_RESET_DISABLE_INTERRUPTS && @@ -452,32 +416,28 @@ Returns: } } + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { // // do the shutdown stuff here @@ -493,29 +453,26 @@ Returns: return ; } + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { UINT8 IntMask; @@ -573,25 +530,23 @@ Returns: return ; } + +/** + This routine is used to read and change receive filters and, if supported, read + and change multicast MAC address filter list. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { UINT16 NewFilter; UINT16 OpFlags; @@ -753,25 +708,23 @@ BadCdb: CdbPtr->StatCode = PXE_STATCODE_INVALID_CDB; } + +/** + This routine is used to get the current station and broadcast MAC addresses, and to change the + current station MAC address. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { 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 ; } + +/** + 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]. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { PXE_CPB_MCAST_IP_TO_MAC *CpbPtr; PXE_DB_MCAST_IP_TO_MAC *DbPtr; @@ -934,27 +881,24 @@ Returns: return ; } + +/** + 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......) + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { PXE_DB_NVDATA *DbPtr; UINT16 Index; @@ -985,32 +929,28 @@ Returns: return ; } + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { PXE_DB_GET_STATUS *DbPtr; PXE_DB_GET_STATUS TmpGetStatus; @@ -1123,26 +1063,24 @@ Returns: return ; } + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { 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 ; } + +/** + 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. + + @param CdbPtr Pointer to the command descriptor block. + @param AdapterInfo Pointer to the NIC data structure information which + the UNDI driver is layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { // @@ -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 ; } + +/** + 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. + + @param Buffer Pointer to the passed in buffer to check sum + @param Len Length of buffer to be check summed in bytes. + + @return None + +**/ 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. - -Returns: - None - ---*/ { 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 ; } + +/** + Initialize the !PXE structure + + @param 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. + +**/ +// 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 ) -/*++ - -Routine Description: - Initialize the !PXE structure - -Arguments: - 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. - ---*/ -// TODO: PxePtr - add argument and description to function comment -// TODO: VersionFlag - add argument and description to function comment { // // 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: } } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ STATIC UINT8 Load_Base_Regs ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { // // 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; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ STATIC UINT8 Configure ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { // // all command blocks are of TxCB format @@ -632,25 +571,19 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ UINT8 E100bSetupIAAddr ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { // // 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; } + +/** + Configures the chip. This routine expects the NIC_DATA_INSTANCE structure to be filled in. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + @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 ) -/*++ - -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.. - -Returns: - 0 - Successful - PXE_STATCODE_NOT_ENOUGH_MEMORY - Insufficient length of locked memory - other - Failure initializing chip ---*/ { 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; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ INT16 E100bReadEepromAndStationAddress ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { 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 // + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ UINT8 SetupCBlink ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { TxCB *head_ptr; TxCB *tail_ptr; @@ -1590,25 +1495,19 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ TxCB * GetFreeCB ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { TxCB *free_cb_ptr; @@ -1637,27 +1536,21 @@ Returns: return free_cb_ptr; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param cb_ptr TODO: add argument description + + @return TODO: add return values + +**/ 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: - - TODO: add return values - ---*/ { // // here we assume cb are returned in the order they are taken out @@ -1671,25 +1564,19 @@ Returns: return ; } + +/** + TODO: Add function description + + @param ind TODO: add argument description + + @return TODO: add return values + +**/ UINT16 next ( IN UINT16 ind ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - ind - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { UINT16 Tmp; @@ -1701,25 +1588,19 @@ Returns: return Tmp; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ UINT16 CheckCBList ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { 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. // + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ UINT8 SetupReceiveQueues ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { RxFD *rx_ptr; RxFD *tail_ptr; @@ -1823,27 +1698,21 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param rx_index TODO: add argument description + + @return TODO: add return values + +**/ 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: - - TODO: add return values - ---*/ { RxFD *rx_ptr; RxFD *tail_ptr; @@ -1956,26 +1825,20 @@ Returns: } } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ STATIC UINT16 shift_bits_in ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { UINT8 Tmp; INT32 Index; @@ -2008,26 +1871,25 @@ Returns: return retval; } + +/** + 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. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + @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 ) -/*++ - -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.. - -Returns: - TRUE - if it got the access - FALSE - if it fails to get the exclusive access - ---*/ { UINTN wait; UINT8 tmp; @@ -2057,25 +1919,24 @@ Returns: return TRUE; } + +/** + 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. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + @return None + +**/ 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.. - -Returns: - None - ---*/ { 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; } + +/** + Using the NIC data structure information, read the EEPROM to determine how many bits of address length + this EEPROM is in Words. + + @param AdapterInfo Pointer to the NIC data structure + information which the UNDI driver is + layering on.. + + @retval RetVal The word read from the EEPROM. + +**/ 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.. - -Returns: - RetVal - The word read from the EEPROM. - ---*/ { 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; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + @param OpFlags TODO: add argument description + + @return TODO: add return values + +**/ 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: - - TODO: add return values - ---*/ { UINT16 save_filter; @@ -2497,25 +2344,19 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ UINTN E100bShutdown ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { // // 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); } + +/** + This routine will reset the PHY that the adapter is currently + configured to use. + + @param AdapterInfo pointer to the structure that contains + the NIC's context. + + +**/ VOID PhyReset ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - 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. - -Returns: - ---*/ { 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: } } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ VOID XmitWaitForCompletion ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { TxCB *TxPtr; @@ -3490,27 +3315,21 @@ Returns: } } + +/** + TODO: Add function description + + @param cmd_ptr TODO: add argument description + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ 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: - - TODO: add return values - ---*/ { INT16 wait; wait = 5000; @@ -3525,26 +3344,20 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ STATIC INT8 SoftwareReset ( NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { UINT8 tco_stat; UINT16 wait; @@ -3632,25 +3445,19 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ UINT8 SelectiveReset ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { UINT16 wait; UINT32 stat; @@ -3686,25 +3493,19 @@ Returns: return 0; } + +/** + TODO: Add function description + + @param AdapterInfo TODO: add argument description + + @return TODO: add return values + +**/ UINT16 InitializeChip ( IN NIC_DATA_INSTANCE *AdapterInfo ) -/*++ - -Routine Description: - - TODO: Add function description - -Arguments: - - AdapterInfo - TODO: add argument description - -Returns: - - TODO: add return values - ---*/ { 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; + +/** + When address mapping changes to virtual this should make the appropriate + address conversions. + + (Standard Event handler) + + @return None + +**/ +// TODO: Context - add argument and description to function comment 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: - - None - ---*/ -// TODO: Context - add argument and description to function comment { 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 ); } } + +/** + When EFI is shuting down the boot services, we need to install a + configuration table for UNDI to work at runtime! + + (Standard Event handler) + + @return None + +**/ +// TODO: Context - add argument and description to function comment 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: - - None - ---*/ -// TODO: Context - add argument and description to function comment { InstallConfigTable (); } @@ -131,6 +109,22 @@ EFI_DRIVER_BINDING_PROTOCOL gUndiDriverBinding = { }; + +/** + 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. + + @param This Protocol instance pointer. + @param Controller Handle of device to test. + @param RemainingDevicePath Not used. + + @retval EFI_SUCCESS This driver supports this device. + @retval other This driver does not support this device. + +**/ EFI_STATUS EFIAPI UndiDriverSupported ( @@ -138,31 +132,6 @@ UndiDriverSupported ( 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. - - RemainingDevicePath - Not used. - -Returns: - - EFI_SUCCESS - This driver supports this device. - - other - This driver does not support this device. - ---*/ { EFI_STATUS Status; EFI_PCI_IO_PROTOCOL *PciIo; @@ -246,6 +215,21 @@ Returns: return Status; } + +/** + 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. + + @param This Protocol instance pointer. + @param Controller Handle of device to work with. + @param 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. + +**/ EFI_STATUS EFIAPI UndiDriverStart ( @@ -253,30 +237,6 @@ UndiDriverStart ( 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. - - 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. - ---*/ { 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: } + +/** + 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. + + @param UnqId Runtime O/S routine might use this, this temp + routine does not use it + @param MicroSeconds Determines the length of pause. + + @return none + +**/ 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. - -Returns: - - none - ---*/ { 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 ; } + +/** + 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. + + @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.. + + @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_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.. - -Returns: - - 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_MAC_ADDRESS MACAddress; PCI_CONFIG_HEADER *CfgHdr; @@ -986,28 +925,23 @@ Returns: return EFI_SUCCESS; } + +/** + Install a GUID/Pointer pair into the system's configuration table. + + none + + @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. + +**/ +// TODO: VOID - add argument and description to function comment EFI_STATUS InstallConfigTable ( IN VOID ) -/*++ - -Routine Description: - - Install a GUID/Pointer pair into the system's configuration table. - -Arguments: - - none - -Returns: - - 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 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_