BIOS/UEFI基础——UEFI网络框架之MNP2

说明

之前已经写了关于MNP的基础部分，见下文：

BIOS/UEFI基础——UEFI网络框架之MNP

本文将详细介绍MNP中的各种接口以及它们的用法示例。

 

接口说明

先写下所有的接口：

///
/// The MNP is used by network applications (and drivers) to 
/// perform raw (unformatted) asynchronous network packet I/O.
///
struct _EFI_MANAGED_NETWORK_PROTOCOL {
  EFI_MANAGED_NETWORK_GET_MODE_DATA       GetModeData;
  EFI_MANAGED_NETWORK_CONFIGURE           Configure;
  EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC     McastIpToMac;
  EFI_MANAGED_NETWORK_GROUPS              Groups;
  EFI_MANAGED_NETWORK_TRANSMIT            Transmit;
  EFI_MANAGED_NETWORK_RECEIVE             Receive;
  EFI_MANAGED_NETWORK_CANCEL              Cancel;
  EFI_MANAGED_NETWORK_POLL                Poll;
};

它们的实现位于MnpMain.c中：

 

GetModeData

函数原型如下：

/**
  Returns the operational parameters for the current MNP child driver.

  @param  This          The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  @param  MnpConfigData The pointer to storage for MNP operational parameters.
  @param  SnpModeData   The pointer to storage for SNP operational parameters.

  @retval EFI_SUCCESS           The operation completed successfully.
  @retval EFI_INVALID_PARAMETER This is NULL.
  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
  @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured. The default
                                values are returned in MnpConfigData if it is not NULL.
  @retval Other                 The mode data could not be read.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_MANAGED_NETWORK_GET_MODE_DATA)(
  IN  EFI_MANAGED_NETWORK_PROTOCOL     *This,
  OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL,
  OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData    OPTIONAL
  );

用来获取MNP配置的参数(通过Configure()函数配置的)，会SNP的参数(通过SNP的GetStatus()函数获取)。

 

Configure

函数原型如下：

/**
  Sets or clears the operational parameters for the MNP child driver.

  @param  This          The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  @param  MnpConfigData The pointer to configuration data that will be assigned to the MNP
                        child driver instance. If NULL, the MNP child driver instance is
                        reset to startup defaults and all pending transmit and receive
                        requests are flushed.

  @retval EFI_SUCCESS           The operation completed successfully.
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  @retval EFI_OUT_OF_RESOURCES  Required system resources (usually memory) could not be
                                allocated.
  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this [MNP]
                                implementation.
  @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
  @retval Other                 The MNP child driver instance has been reset to startup defaults.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_MANAGED_NETWORK_CONFIGURE)(
  IN EFI_MANAGED_NETWORK_PROTOCOL     *This,
  IN EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL
  );

这个函数是MNP执行的起点，只有经过配置了，MNP才会开始运行。

在配置完成之后会设置Instance实例中的Configured成员，之后的操作，比如Receive()、Transmit()等都会去判断这个成员，来确定这个MNP实例是否在运行。

Configure()函数接收的参数的结构体如下：

typedef struct {
  ///
  /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
  /// from the MNP receive queue will be dropped if its receive timeout expires.
  ///
  UINT32     ReceivedQueueTimeoutValue;
  ///
  /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
  /// from the MNP transmit queue will be dropped if its receive timeout expires.
  ///
  UINT32     TransmitQueueTimeoutValue;
  ///
  /// Ethernet type II 16-bit protocol type in host byte order. Valid
  /// values are zero and 1,500 to 65,535.
  ///
  UINT16     ProtocolTypeFilter;
  ///
  /// Set to TRUE to receive packets that are sent to the network
  /// device MAC address. The startup default value is FALSE.
  ///
  BOOLEAN    EnableUnicastReceive;
  ///
  /// Set to TRUE to receive packets that are sent to any of the
  /// active multicast groups. The startup default value is FALSE.
  ///
  BOOLEAN    EnableMulticastReceive;
  ///
  /// Set to TRUE to receive packets that are sent to the network
  /// device broadcast address. The startup default value is FALSE.
  ///
  BOOLEAN    EnableBroadcastReceive;
  ///
  /// Set to TRUE to receive packets that are sent to any MAC address.
  /// The startup default value is FALSE.
  ///
  BOOLEAN    EnablePromiscuousReceive;
  ///
  /// Set to TRUE to drop queued packets when the configuration
  /// is changed. The startup default value is FALSE.
  ///
  BOOLEAN    FlushQueuesOnReset;
  ///
  /// Set to TRUE to timestamp all packets when they are received
  /// by the MNP. Note that timestamps may be unsupported in some
  /// MNP implementations. The startup default value is FALSE.
  ///
  BOOLEAN    EnableReceiveTimestamps;
  ///
  /// Set to TRUE to disable background polling in this MNP
  /// instance. Note that background polling may not be supported in
  /// all MNP implementations. The startup default value is FALSE,
  /// unless background polling is not supported.
  ///
  BOOLEAN    DisableBackgroundPolling;
} EFI_MANAGED_NETWORK_CONFIG_DATA;

默认的一个配置如下：

EFI_MANAGED_NETWORK_CONFIG_DATA mMnpDefaultConfigData = {
  10000000,
  10000000,
  0,
  FALSE,
  FALSE,
  FALSE,
  FALSE,
  FALSE,
  FALSE,
  FALSE
};

配置的最后会调用如下的函数：

    //
    // The instance is configured, start the Mnp.
    //
    Status = MnpStart (
              MnpServiceData,
              IsConfigUpdate,
              (BOOLEAN) !NewConfigData->DisableBackgroundPolling
              );

在MnpStart()函数中会有以下的操作：

1. 查看SNP是否正常运行，如果没有就会开启SNP；

2. 开启定时器，来处理接收数据和其它的一些事务。

这样网络算是正式运行起来了。

 

McastIpToMac

函数原型如下：

/**
  Translates an IP multicast address to a hardware (MAC) multicast address.

  @param  This       The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  @param  Ipv6Flag   Set to TRUE to if IpAddress is an IPv6 multicast address.
                     Set to FALSE if IpAddress is an IPv4 multicast address.
  @param  IpAddress  The pointer to the multicast IP address (in network byte order) to convert.
  @param  MacAddress The pointer to the resulting multicast MAC address.

  @retval EFI_SUCCESS           The operation completed successfully.
  @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
                                - This is NULL.
                                - IpAddress is NULL.
                                - *IpAddress is not a valid multicast IP address.
                                - MacAddress is NULL.
  @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
  @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
  @retval Other                 The address could not be converted.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC)(
  IN  EFI_MANAGED_NETWORK_PROTOCOL  *This,
  IN  BOOLEAN                       Ipv6Flag,
  IN  EFI_IP_ADDRESS                *IpAddress,
  OUT EFI_MAC_ADDRESS               *MacAddress
  );

这个函数没有需要特别说明的，就是一个从IP到MAC的转换。

因为对于多播来说，并没有特定的设备的MAC，因此就有了多播MAC的概念，它是通过IP转换得到的。

转换的规则也很简单，下面是IP4的转换示例：

 

Groups

函数原型如下：

/**
  Enables and disables receive filters for multicast address.

  @param  This       The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  @param  JoinFlag   Set to TRUE to join this multicast group.
                     Set to FALSE to leave this multicast group.
  @param  MacAddress The pointer to the multicast MAC group (address) to join or leave.

  @retval EFI_SUCCESS           The requested operation completed successfully.
  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
                                - This is NULL.
                                - JoinFlag is TRUE and MacAddress is NULL.
                                - *MacAddress is not a valid multicast MAC address.
  @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
  @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.
  @retval EFI_NOT_FOUND         The supplied multicast group is not joined.
  @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
  @retval Other                 The requested operation could not be completed.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_MANAGED_NETWORK_GROUPS)(
  IN EFI_MANAGED_NETWORK_PROTOCOL  *This,
  IN BOOLEAN                       JoinFlag,
  IN EFI_MAC_ADDRESS               *MacAddress  OPTIONAL
  );

这个函数用来设置多播过滤的。

最终也是调用了SNP的ReceiveFilters()函数来进行设置的。

 

Transmit

函数原型如下：

/**
  Places asynchronous outgoing data packets into the transmit queue.

  @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  @param  Token The pointer to a token associated with the transmit data descriptor.

  @retval EFI_SUCCESS           The transmit completion token was cached.
  @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  @retval EFI_ACCESS_DENIED     The transmit completion token is already in the transmit queue.
  @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
                                (usually memory).
  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
  @retval EFI_NOT_READY         The transmit request could not be queued because the transmit queue is full.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_MANAGED_NETWORK_TRANSMIT)(
  IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
  IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
  );

它的结构跟Receive()类似，都是带一个参数Token。

这个Token中包含需要传送的数据，通过MnpBuildTxPacket()来创建发送的包，然后通过MnpSyncSendPacket()来发送数据。

MnpSyncSendPacket()其实就是调用了SNP的Transmit()来发送数据，然后将执行的状态赋值给Token的Status成员，并触发Token中的Event。

Transmit()也会执行DispatchDpc()。

 

Receive

函数的原型如下：

/**
  Places an asynchronous receiving request into the receiving queue.

  @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  @param  Token The pointer to a token associated with the receive data descriptor.

  @retval EFI_SUCCESS           The receive completion token was cached.
  @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
                                - This is NULL.
                                - Token is NULL.
                                - Token.Event is NULL.
  @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
                                (usually memory).
  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
  @retval EFI_ACCESS_DENIED     The receive completion token was already in the receive queue.
  @retval EFI_NOT_READY         The receive request could not be queued because the receive queue is full.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_MANAGED_NETWORK_RECEIVE)(
  IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
  IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
  );

这里的参数Token已经在之前讲过。

上层的协议要使用MNP，就需要构建自己的Token，然后通过像Receive()这样的函数放到MNP的链表中。

Receive()函数首先会判断这个Token是否存在，如果存在就返回了；

之后通过NetMapInsertTail()将这个Token插入到MNP的Instance实例中，这个Instance实例是在CreateChild()的时候创建的；

如果没有出错，就调用MnpInstanceDeliverPacket()，这个函数会判断是否收到数据，如果收到了，就执行Signal当前Token中的Event；

最后是执行DispatchDpc()，这个函数在

BIOS/UEFI基础——UEFI网络框架之MNP

中已经介绍过，它会循环执行DPC Queue中的所有函数，这些被执行的函数通过QueueDpc()放到DPC Queue中，而QueueDpc()会在上层协议中调用，来注入一些上层协议，如ARP、IP、TCP等，会使用到的函数。

注意，在Receive()中会调用一次MnpInstanceDeliverPacket()和DispatchDpc()，表示了一个数据的立即处理，但是当前可能没有数据，所以这两个函数最重要的执行地点是在Poll()函数中。

另外，一个Token中的事件只会被触发一次，之后它会被移出RxTokenMap：

  //
  // Get the receive token from the RxTokenMap.
  //
  RxToken = NetMapRemoveHead (&Instance->RxTokenMap, NULL);

 

Cancel

函数原型如下：

/**
  Aborts an asynchronous transmit or receive request.

  @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  @param  Token The pointer to a token that has been issued by
                EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
                EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If
                NULL, all pending tokens are aborted.

  @retval  EFI_SUCCESS           The asynchronous I/O request was aborted and Token.Event
                                 was signaled. When Token is NULL, all pending requests were
                                 aborted and their events were signaled.
  @retval  EFI_NOT_STARTED       This MNP child driver instance has not been configured.
  @retval  EFI_INVALID_PARAMETER This is NULL.
  @retval  EFI_NOT_FOUND         When Token is not NULL, the asynchronous I/O request was
                                 not found in the transmit or receive queue. It has either completed
                                 or was not issued by Transmit() and Receive().

**/
typedef
EFI_STATUS
(EFIAPI *EFI_MANAGED_NETWORK_CANCEL)(
  IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
  IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token  OPTIONAL
  );

这里的Token表示的就是Receive()或者Transmit()送入的Token，这个参数也是可选的，如果为NULL表示的就是全部的Token都会被取消。

需要注意几点：

1. Cancel()会将Token中的Status置为EFI_ABORTED；

2. Token中的Event还是会被Signal，所以在事件的回调函数中可以根据状态是否为EFI_ABORTED来判断处理；

3. Cancel()也会调用DispatchDpc()；

 

Poll

函数原型如下：

/**
  Polls for incoming data packets and processes outgoing data packets.

  @param  This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.

  @retval EFI_SUCCESS      Incoming or outgoing data was processed.
  @retval EFI_NOT_STARTED  This MNP child driver instance has not been configured.
  @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
  @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider increasing
                           the polling rate.
  @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive queue.
                            Consider increasing the polling rate.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_MANAGED_NETWORK_POLL)(
  IN EFI_MANAGED_NETWORK_PROTOCOL    *This
  );

这个函数的作用在Receive()中已经提到，就是一个轮询，来处理数据。

 

示例

待补充。