/** @file\r
- Declaration of structures and functions of MnpDxe driver.\r
+ Declaration of structures and functions of MnpDxe driver.\r
\r
Copyright (c) 2005 - 2008, Intel Corporation. <BR>\r
All rights reserved. This program and the accompanying materials\r
MNP_INSTANCE_DATA_SIGNATURE \\r
)\r
\r
-typedef struct _MNP_INSTANCE_DATA {\r
+typedef struct {\r
UINT32 Signature;\r
\r
MNP_SERVICE_DATA *MnpServiceData;\r
UINT8 ReceiveFilter;\r
} MNP_INSTANCE_DATA;\r
\r
-typedef struct _MNP_GROUP_ADDRESS {\r
+typedef struct {\r
LIST_ENTRY AddrEntry;\r
EFI_MAC_ADDRESS Address;\r
INTN RefCnt;\r
} MNP_GROUP_ADDRESS;\r
\r
-typedef struct _MNP_GROUP_CONTROL_BLOCK {\r
+typedef struct {\r
LIST_ENTRY CtrlBlkEntry;\r
MNP_GROUP_ADDRESS *GroupAddress;\r
} MNP_GROUP_CONTROL_BLOCK;\r
\r
-typedef struct _MNP_RXDATA_WRAP {\r
+typedef struct {\r
LIST_ENTRY WrapEntry;\r
MNP_INSTANCE_DATA *Instance;\r
EFI_MANAGED_NETWORK_RECEIVE_DATA RxData;\r
/**\r
Initialize the mnp service context data.\r
\r
- @param MnpServiceData Pointer to the mnp service context data.\r
- @param ImageHandle The driver image handle.\r
- @param ControllerHandle Handle of device to bind driver to.\r
+ @param[in, out] MnpServiceData Pointer to the mnp service context data.\r
+ @param[in] ImageHandle The driver image handle.\r
+ @param[in] ControllerHandle Handle of device to bind driver to.\r
\r
@retval EFI_SUCCESS The mnp service context is initialized.\r
- @retval Other Some error occurs.\r
+ @retval EFI_UNSUPPORTED ControllerHandle does not support Simple Network Protocol.\r
+ @retval Others Other errors as indicated.\r
\r
**/\r
EFI_STATUS\r
MnpInitializeServiceData (\r
- IN MNP_SERVICE_DATA *MnpServiceData,\r
- IN EFI_HANDLE ImageHandle,\r
- IN EFI_HANDLE ControllerHandle\r
+ IN OUT MNP_SERVICE_DATA *MnpServiceData,\r
+ IN EFI_HANDLE ImageHandle,\r
+ IN EFI_HANDLE ControllerHandle\r
);\r
\r
/**\r
Flush the mnp service context data.\r
\r
- @param MnpServiceData Pointer to the mnp service context data.\r
- @param ImageHandle The driver image handle.\r
+ @param[in, out] MnpServiceData Pointer to the mnp service context data.\r
+ @param[in] ImageHandle The driver image handle.\r
\r
**/\r
VOID\r
MnpFlushServiceData (\r
- IN MNP_SERVICE_DATA *MnpServiceData,\r
- IN EFI_HANDLE ImageHandle\r
+ IN OUT MNP_SERVICE_DATA *MnpServiceData,\r
+ IN EFI_HANDLE ImageHandle\r
);\r
\r
/**\r
Initialize the mnp instance context data.\r
\r
- @param MnpServiceData Pointer to the mnp service context data.\r
- @param Instance Pointer to the mnp instance context data to\r
- initialize.\r
+ @param[in] MnpServiceData Pointer to the mnp service context data.\r
+ @param[in, out] Instance Pointer to the mnp instance context data \r
+ to initialize.\r
\r
**/\r
VOID\r
MnpInitializeInstanceData (\r
- IN MNP_SERVICE_DATA *MnpServiceData,\r
- IN MNP_INSTANCE_DATA *Instance\r
+ IN MNP_SERVICE_DATA *MnpServiceData,\r
+ IN OUT MNP_INSTANCE_DATA *Instance\r
);\r
\r
/**\r
- Check whether the token specified by Arg maches the token in Item.\r
+ Check whether the token specified by Arg matches the token in Item.\r
\r
- @param Map Pointer to the NET_MAP.\r
- @param Item Pointer to the NET_MAP_ITEM\r
- @param Arg Pointer to the Arg, it's a pointer to the token to\r
+ @param[in] Map Pointer to the NET_MAP.\r
+ @param[in] Item Pointer to the NET_MAP_ITEM.\r
+ @param[in] Arg Pointer to the Arg, it's a pointer to the token to\r
check.\r
\r
@retval EFI_SUCCESS The token specified by Arg is different from the\r
/**\r
Cancel the token specified by Arg if it matches the token in Item.\r
\r
- @param Map Pointer to the NET_MAP.\r
- @param Item Pointer to the NET_MAP_ITEM\r
- @param Arg Pointer to the Arg, it's a pointer to the token to\r
- cancel.\r
+ @param[in, out] Map Pointer to the NET_MAP.\r
+ @param[in, out] Item Pointer to the NET_MAP_ITEM.\r
+ @param[in] Arg Pointer to the Arg, it's a pointer to the \r
+ token to cancel.\r
\r
- @retval EFI_SUCCESS The Arg is NULL, and the token in Item is\r
- cancelled, or the Arg isn't NULL, and the token in\r
- Item is different from the Arg.\r
- @retval EFI_ABORTED The Arg isn't NULL, the token in Item mathces the\r
- Arg, and the token is cancelled.\r
+ @retval EFI_SUCCESS The Arg is NULL, and the token in Item is cancelled, \r
+ or the Arg isn't NULL, and the token in Item is\r
+ different from the Arg.\r
+ @retval EFI_ABORTED The Arg isn't NULL, the token in Item mathces the\r
+ Arg, and the token is cancelled.\r
\r
**/\r
EFI_STATUS\r
MnpCancelTokens (\r
- IN OUT NET_MAP *Map,\r
- IN NET_MAP_ITEM *Item,\r
- IN VOID *Arg\r
+ IN OUT NET_MAP *Map,\r
+ IN OUT NET_MAP_ITEM *Item,\r
+ IN VOID *Arg\r
);\r
\r
/**\r
Flush the instance's received data.\r
\r
- @param Instance Pointer to the mnp instance context data.\r
+ @param[in, out] Instance Pointer to the mnp instance context data.\r
\r
**/\r
VOID\r
MnpFlushRcvdDataQueue (\r
- IN MNP_INSTANCE_DATA *Instance\r
+ IN OUT MNP_INSTANCE_DATA *Instance\r
);\r
\r
/**\r
Configure the Instance using ConfigData.\r
\r
- @param Instance Pointer to the mnp instance context data.\r
- @param ConfigData Pointer to the configuration data used to configure\r
+ @param[in, out] Instance Pointer to the mnp instance context data.\r
+ @param[in] ConfigData Pointer to the configuration data used to configure\r
the isntance.\r
\r
@retval EFI_SUCCESS The Instance is configured.\r
@retval EFI_UNSUPPORTED EnableReceiveTimestamps is on and the\r
implementation doesn't support it.\r
- @retval Other Some error occurs.\r
+ @retval Others Other errors as indicated.\r
\r
**/\r
EFI_STATUS\r
MnpConfigureInstance (\r
- IN MNP_INSTANCE_DATA *Instance,\r
- IN EFI_MANAGED_NETWORK_CONFIG_DATA *ConfigData OPTIONAL\r
+ IN OUT MNP_INSTANCE_DATA *Instance,\r
+ IN EFI_MANAGED_NETWORK_CONFIG_DATA *ConfigData OPTIONAL\r
);\r
\r
/**\r
Do the group operations for this instance.\r
\r
- @param Instance Pointer to the instance context data.\r
- @param JoinFlag Set to TRUE to join a group. Set to TRUE to leave a\r
- group/groups.\r
- @param MacAddress Pointer to the group address to join or leave.\r
- @param CtrlBlk Pointer to the group control block if JoinFlag if\r
- FALSE.\r
+ @param[in, out] Instance Pointer to the instance context data.\r
+ @param[in] JoinFlag Set to TRUE to join a group. Set to TRUE to \r
+ leave a group/groups.\r
+ @param[in] MacAddress Pointer to the group address to join or leave.\r
+ @param[in] CtrlBlk Pointer to the group control block if JoinFlag \r
+ is FALSE.\r
\r
- @retval EFI_SUCCESS The group operation finished.\r
- @retval Other Some error occurs.\r
+ @retval EFI_SUCCESS The group operation finished.\r
+ @retval EFI_OUT_OF_RESOURCES Failed due to lack of memory resources.\r
+ @retval Others Other errors as indicated.\r
\r
**/\r
EFI_STATUS\r
MnpGroupOp (\r
- IN MNP_INSTANCE_DATA *Instance,\r
+ IN OUT MNP_INSTANCE_DATA *Instance,\r
IN BOOLEAN JoinFlag,\r
- IN EFI_MAC_ADDRESS *MacAddr OPTIONAL,\r
+ IN EFI_MAC_ADDRESS *MacAddress OPTIONAL,\r
IN MNP_GROUP_CONTROL_BLOCK *CtrlBlk OPTIONAL\r
);\r
\r
/**\r
Validates the Mnp transmit token.\r
\r
- @param Instance Pointer to the Mnp instance context data.\r
- @param Token Pointer to the transmit token to check.\r
+ @param[in] Instance Pointer to the Mnp instance context data.\r
+ @param[in] Token Pointer to the transmit token to check.\r
\r
@return The Token is valid or not.\r
\r
/**\r
Build the packet to transmit from the TxData passed in.\r
\r
- @param MnpServiceData Pointer to the mnp service context data.\r
- @param TxData Pointer to the transmit data containing the\r
- information to build the packet.\r
- @param PktBuf Pointer to record the address of the packet.\r
- @param PktLen Pointer to a UINT32 variable used to record the\r
- packet's length.\r
+ @param[in] MnpServiceData Pointer to the mnp service context data.\r
+ @param[in] TxData Pointer to the transmit data containing the information \r
+ to build the packet.\r
+ @param[out] PktBuf Pointer to record the address of the packet.\r
+ @param[out] PktLen Pointer to a UINT32 variable used to record the packet's \r
+ length.\r
\r
**/\r
VOID\r
/**\r
Synchronously send out the packet.\r
\r
- @param MnpServiceData Pointer to the mnp service context data.\r
- @param Packet Pointer to the pakcet buffer.\r
- @param Length The length of the packet.\r
- @param Token Pointer to the token the packet generated from.\r
+ @param[in] MnpServiceData Pointer to the mnp service context data.\r
+ @param[in] Packet Pointer to the pakcet buffer.\r
+ @param[in] Length The length of the packet.\r
+ @param[in, out] Token Pointer to the token the packet generated from.\r
\r
- @retval EFI_SUCCESS The packet is sent out.\r
- @retval EFI_TIMEOUT Time out occurs, the packet isn't sent.\r
- @retval EFI_DEVICE_ERROR An unexpected network error occurs.\r
+ @retval EFI_SUCCESS The packet is sent out.\r
+ @retval EFI_TIMEOUT Time out occurs, the packet isn't sent.\r
+ @retval EFI_DEVICE_ERROR An unexpected network error occurs.\r
\r
**/\r
EFI_STATUS\r
MnpSyncSendPacket (\r
- IN MNP_SERVICE_DATA *MnpServiceData,\r
- IN UINT8 *Packet,\r
- IN UINT32 Length,\r
- IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token\r
+ IN MNP_SERVICE_DATA *MnpServiceData,\r
+ IN UINT8 *Packet,\r
+ IN UINT32 Length,\r
+ IN OUT EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token\r
);\r
\r
/**\r
Try to deliver the received packet to the instance.\r
\r
- @param Instance Pointer to the mnp instance context data.\r
+ @param[in, out] Instance Pointer to the mnp instance context data.\r
\r
@retval EFI_SUCCESS The received packet is delivered, or there is no\r
packet to deliver, or there is no available receive\r
**/\r
EFI_STATUS\r
MnpInstanceDeliverPacket (\r
- IN MNP_INSTANCE_DATA *Instance\r
+ IN OUT MNP_INSTANCE_DATA *Instance\r
);\r
\r
/**\r
Recycle the RxData and other resources used to hold and deliver the received\r
packet.\r
\r
- @param Event The event this notify function registered to.\r
- @param Context Pointer to the context data registerd to the Event.\r
+ @param[in] Event The event this notify function registered to.\r
+ @param[in] Context Pointer to the context data registerd to the Event.\r
\r
**/\r
VOID\r
/**\r
Try to receive a packet and deliver it.\r
\r
- @param MnpServiceData Pointer to the mnp service context data.\r
+ @param[in, out] MnpServiceData Pointer to the mnp service context data.\r
\r
@retval EFI_SUCCESS add return value to function comment\r
@retval EFI_NOT_STARTED The simple network protocol is not started.\r
**/\r
EFI_STATUS\r
MnpReceivePacket (\r
- IN MNP_SERVICE_DATA *MnpServiceData\r
+ IN OUT MNP_SERVICE_DATA *MnpServiceData\r
);\r
\r
/**\r
in the queue, first try to allocate some and add them into the queue, then\r
fetch the NET_BUF from the updated FreeNbufQue.\r
\r
- @param MnpServiceData Pointer to the MNP_SERVICE_DATA.\r
+ @param[in, out] MnpServiceData Pointer to the MNP_SERVICE_DATA.\r
\r
- @return Pointer to the allocated free NET_BUF structure, if NULL the operation is failed.\r
+ @return Pointer to the allocated free NET_BUF structure, if NULL the \r
+ operation is failed.\r
\r
**/\r
NET_BUF *\r
MnpAllocNbuf (\r
- IN MNP_SERVICE_DATA *MnpServiceData\r
+ IN OUT MNP_SERVICE_DATA *MnpServiceData\r
);\r
\r
/**\r
Try to reclaim the Nbuf into the buffer pool.\r
\r
- @param MnpServiceData Pointer to the mnp service context data.\r
- @param Nbuf Pointer to the NET_BUF to free.\r
+ @param[in,out] MnpServiceData Pointer to the mnp service context data.\r
+ @param[in,out] Nbuf Pointer to the NET_BUF to free.\r
\r
**/\r
VOID\r
MnpFreeNbuf (\r
- IN MNP_SERVICE_DATA *MnpServiceData,\r
- IN NET_BUF *Nbuf\r
+ IN OUT MNP_SERVICE_DATA *MnpServiceData,\r
+ IN OUT NET_BUF *Nbuf\r
);\r
\r
/**\r
Remove the received packets if timeout occurs.\r
\r
- @param Event The event this notify function registered to.\r
- @param Context Pointer to the context data registered to the\r
+ @param[in] Event The event this notify function registered to.\r
+ @param[in] Context Pointer to the context data registered to the\r
event.\r
\r
**/\r
Poll to receive the packets from Snp. This function is either called by upperlayer\r
protocols/applications or the system poll timer notify mechanism.\r
\r
- @param Event The event this notify function registered to.\r
- @param Context Pointer to the context data registered to the\r
- event.\r
+ @param[in] Event The event this notify function registered to.\r
+ @param[in, out] Context Pointer to the context data registered to the event.\r
\r
**/\r
VOID\r
EFIAPI\r
MnpSystemPoll (\r
IN EFI_EVENT Event,\r
- IN VOID *Context\r
+ IN OUT VOID *Context\r
);\r
\r
/**\r
The GetModeData() function is used to read the current mode data (operational\r
parameters) from the MNP or the underlying SNP. \r
\r
- @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
- @param MnpConfigData Pointer to storage for MNP operational parameters. Type\r
- EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related\r
- Definitions" below.\r
- @param SnpModeData Pointer to storage for SNP operational parameters. This\r
- feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE\r
- is defined in the EFI_SIMPLE_NETWORK_PROTOCOL.\r
+ @param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+ @param[out] MnpConfigData Pointer to storage for MNP operational parameters. Type\r
+ EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related\r
+ Definitions" below.\r
+ @param[out] SnpModeData Pointer to storage for SNP operational parameters. This\r
+ feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE\r
+ is defined in the EFI_SIMPLE_NETWORK_PROTOCOL.\r
\r
@retval EFI_SUCCESS The operation completed successfully.\r
@retval EFI_INVALID_PARAMETER This is NULL.\r
@retval EFI_NOT_STARTED This MNP child driver instance has not been\r
configured. The default values are returned in\r
MnpConfigData if it is not NULL.\r
- @retval Other The mode data could not be read.\r
+ @retval Others The mode data could not be read.\r
\r
**/\r
EFI_STATUS\r
Note: Warning: Receive filter settings that overlap will consume extra\r
processor and/or DMA resources and degrade system and network performance.\r
\r
- @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
- @param MnpConfigData Pointer to configuration data that will be assigned\r
- to the MNP child driver instance. If NULL, the MNP\r
- child driver instance is reset to startup defaults\r
- and all pending transmit and receive requests are\r
- flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is\r
- defined in\r
- EFI_MANAGED_NETWORK_PROTOCOL.GetModeData().\r
+ @param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+ @param[in] MnpConfigData Pointer to configuration data that will be assigned\r
+ to the MNP child driver instance. If NULL, the MNP\r
+ child driver instance is reset to startup defaults\r
+ and all pending transmit and receive requests are\r
+ flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is\r
+ defined in EFI_MANAGED_NETWORK_PROTOCOL.GetModeData().\r
\r
@retval EFI_SUCCESS The operation completed successfully.\r
@retval EFI_INVALID_PARAMETER One or more of the following conditions is\r
@retval EFI_DEVICE_ERROR An unexpected network or system error\r
occurred. The MNP child driver instance has\r
been reset to startup defaults.\r
- @retval Other The MNP child driver instance has been reset to\r
+ @retval Others The MNP child driver instance has been reset to\r
startup defaults.\r
\r
**/\r
\r
The McastIpToMac() function translates an IP multicast address to a hardware\r
(MAC) multicast address. This function may be implemented by calling the\r
- underlying EFI_SIMPLE_NETWORK.MCastIpToMac() function, which may also be\r
+ underlying EFI_SIMPLE_NETWORK. MCastIpToMac() function, which may also be\r
unsupported in some MNP implementations.\r
\r
- @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
- @param Ipv6Flag Set to TRUE to if IpAddress is an IPv6 multicast address.\r
- Set to FALSE if IpAddress is an IPv4 multicast address.\r
- @param IpAddress Pointer to the multicast IP address (in network byte order)\r
- to convert.\r
- @param MacAddress Pointer to the resulting multicast MAC address. \r
+ @param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+ @param[in] Ipv6Flag Set to TRUE to if IpAddress is an IPv6 multicast address.\r
+ Set to FALSE if IpAddress is an IPv4 multicast address.\r
+ @param[in] IpAddress Pointer to the multicast IP address (in network byte\r
+ order) to convert.\r
+ @param[out] MacAddress Pointer to the resulting multicast MAC address. \r
\r
@retval EFI_SUCCESS The operation completed successfully.\r
@retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:\r
@retval EFI_UNSUPPORTED The requested feature is unsupported in this\r
MNP implementation.\r
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.\r
- @retval Other The address could not be converted.\r
+ @retval Others The address could not be converted.\r
**/\r
EFI_STATUS\r
EFIAPI\r
Management Protocol (IGMP) packets. If JoinFlag is FALSE and MacAddress is\r
NULL, then all joined groups are left.\r
\r
- @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
- @param JoinFlag Set to TRUE to join this multicast group.\r
- Set to FALSE to leave this multicast group.\r
- @param MacAddress Pointer to the multicast MAC group (address) to join or\r
- leave.\r
+ @param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+ @param[in] JoinFlag Set to TRUE to join this multicast group.\r
+ Set to FALSE to leave this multicast group.\r
+ @param[in] MacAddress Pointer to the multicast MAC group (address) to join or\r
+ leave.\r
\r
@retval EFI_SUCCESS The requested operation completed successfully.\r
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
startup defaults.\r
@retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP\r
implementation.\r
- @retval Other The requested operation could not be completed.\r
+ @retval Others The requested operation could not be completed.\r
The MNP multicast group settings are unchanged.\r
\r
**/\r
the underlying communications device and drivers.\r
\r
\r
- @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
- @param Token Pointer to a token associated with the transmit data\r
- descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN is\r
- defined in "Related Definitions" below.\r
+ @param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+ @param[in] Token Pointer to a token associated with the transmit data\r
+ descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN\r
+ is defined in "Related Definitions" below.\r
\r
@retval EFI_SUCCESS The transmit completion token was cached.\r
@retval EFI_NOT_STARTED This MNP child driver instance has not been\r
the asynchronous operation has completed, this function will not signal the\r
token and EFI_NOT_FOUND is returned.\r
\r
- @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
- @param Token Pointer to a token that has been issued by\r
- EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or\r
- EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all pending\r
- tokens are aborted.\r
+ @param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+ @param[in] Token Pointer to a token that has been issued by\r
+ EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or\r
+ EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all \r
+ pending tokens are aborted.\r
\r
@retval EFI_SUCCESS The asynchronous I/O request was aborted and\r
Token.Event was signaled. When Token is NULL,\r
updates the Token.Status and Token.RxData fields and the Token.Event is\r
signaled.\r
\r
- @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
- @param Token Pointer to a token associated with the receive\r
+ @param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+ @param[in] Token Pointer to a token associated with the receive\r
data descriptor. Type\r
EFI_MANAGED_NETWORK_COMPLETION_TOKEN is defined in\r
EFI_MANAGED_NETWORK_PROTOCOL.Transmit().\r
applications that are experiencing packet loss should try calling the Poll()\r
function more often.\r
\r
- @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+ @param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
\r
@retval EFI_SUCCESS Incoming or outgoing data was processed.\r
@retval EFI_NOT_STARTED This MNP child driver instance has not been\r
projects / mirror_edk2.git / blobdiff