Ethernet Debug Sharing Procedures

Article
06/30/2006

The VBridge library acts as a MAC layer bridging the kernel's Ethernet debug traffic and the TCP/IP and Winsock application traffic. It should be linked into Nk.exe. The VBridge library communicates with the VMini miniport driver through kernel IOCTLs. For more information about these IOCTLs, see VMINI IOCTLs.

Note Including Vbridge.lib in Nk.exe will cost around 30 KB of memory to be reserved for VBridge operation.

To include the VBridge library in the OS image

Include VBridge.lib in \Kernel\Buildexe\...\Sources.

Add support for VMini.dll to Ethdbg.h and include it in the source file containing the OEMIoControl function. The following code example shows how to add the support for VMini.dll to Ethdbg.h.

case IOCTL_VBRIDGE_GET_TX_PACKET:
  return VBridgeUGetOneTxPacket((PUCHAR *)lpOutBuf, nInBufSize);

case IOCTL_VBRIDGE_GET_TX_PACKET_COMPLETE:
  VBridgeUGetOneTxPacketComplete((PUCHAR)lpInBuf, nInBufSize);
  return TRUE;

case IOCTL_VBRIDGE_GET_RX_PACKET:
  return VBridgeUGetOneRxPacket((PUCHAR *)lpOutBuf, lpBytesReturned);

case IOCTL_VBRIDGE_GET_RX_PACKET_COMPLETE:
  VBridgeUGetOneRxPacketComplete((PUCHAR)lpInBuf);
  return TRUE;

case IOCTL_VBRIDGE_GET_ETHERNET_MAC:
  VBridgeUGetEDBGMac((PBYTE)lpOutBuf);
  return TRUE;

case IOCTL_VBRIDGE_WILD_CARD:
  return VBridgeUWildCard(
    lpInBuf,
    nInBufSize,
    lpOutBuf,
    nOutBufSize,
    lpBytesReturned);

case IOCTL_VBRIDGE_CURRENT_PACKET_FILTER:
  // Check whether the filter setting has been implemented and then 
  // inform VBridge of the new filtering. 
  if (OEMEthCurrentPacketFilter((PDWORD)lpInBuf))
  {
    VBridgeUCurrentPacketFilter((PDWORD)lpInBuf);
    return TRUE;
  }
  return FALSE;

case IOCTL_VBRIDGE_802_3_MULTICAST_LIST:
  if (OEMEthMulticastList((PUCHAR)lpInBuf, nInBufSize))
    return TRUE;
  return FALSE;

case IOCTL_VBRIDGE_SHARED_ETHERNET:
  // This kernel supports a shared Ethernet port.
  return TRUE;

Call the VBridgeInit function in the OEMEthInit function.
Call the VBridgeKSetLocalMacAddress function in the OEMEthInit function to inform VBridge of the media access control address of the underlying Ethernet hardware.

Add the following ProcessVMiniSend function shown in the following code example. This function is called in the OEMEthGetFrame and OEMEthSendFrame functions.

void
ProcessVMiniSend(void)
{
  PBYTE   pVMiniData;
  DWORD   dwVMiniDataLength;
  // Handle the filter if necessary.
  if (bNewFilter && pfnCurrentPacketFilter)
  {
    bNewFilter = FALSE;
    pfnCurrentPacketFilter(dwFilter);
  }

  // Consume all the client packets.
  while (
        VBridgeKGetOneTxBuffer(&pVMiniData,&dwVMiniDataLength) == TRUE)
  {
    pfnEDbgSendFrame (pVMiniData, dwVMiniDataLength);
    VBridgeKGetOneTxBufferComplete(pVMiniData);
  }
} // ProcessVMiniSend()

Modify the OEMEthISR function. Replace pfnXXXwith the platform's appropriate function call to its Ethernet library, as shown in the following code sample.
```
DWORD
OEMEthISR()
{
#if IMGSHAREETH
  ProcessVMiniSend();
#endif
  return (pfnEDbgGetPendingInts());
}
```
For more information, see %_WINCEROOT%\Platform\CEPC. This platform demonstrates how to use the environment variable IMGSHAREETH flag to enable and disable Ethernet sharing.

Use the following code sample in the OEMEthGetFrame function.

BOOL
OEMEthGetFrame(
              BYTE *pData,       // OUT - Receives frame data
              UINT16 *pwLength)  // IN  - Length of Rx buffer
                                 // OUT - Number of bytes received
{

#if IMGSHAREETH
  BOOL    bStatus;
  BOOL    bTaken;

    ProcessVMiniSend();

  while (1)
  {
    bStatus  = pfnEDbgGetFrame(pData, pwLength);
      if (bStatus)
      {
        VBridgeKIndicateOneRxBuffer(pData, *pwLength, FALSE, &bTaken);
        if (!bTaken)
          return bStatus;
      }
      else
        break;
  }

  return (FALSE);
#else

  return (pfnEDbgGetFrame(pData, pwLength));

#endif
}

Use the following code sample in the OEMEthSendFrame function.

BOOL
OEMEthSendFrame(
               BYTE *pData,     // IN - Data buffer
               DWORD dwLength)  // IN - Length of buffer 
{
  int retries = 0;
  while ( retries++ < 4 ) {
    if ( !pfnEDbgSendFrame(pData, dwLength) )
    {

#if IMGSHAREETH
      ProcessVMiniSend();
#endif

      return (TRUE);
    }
    else
      EdbgOutputDebugString(
                           "!OEMEthSendFrame failure,
                           retry %u\n",retries);
    }
    return (FALSE);
}

Optional support for FILTERING and MULTICASTING can be implemented for the platform by using the IOCTL_VBRIDGE_CURRENT_PACKET_FILTER and IOCTL_VBRIDGE_802_3_MULTICAST_LIST functions. To view sample implementations of these functions, see %_WINCEROOT%\Platform\Cepc\Halether.c.

Note Without these functions, VMINI will function but will not provide multicast support for Winsock applications.
Insert the following code sample in the function OEMInterruptEnable.
```
if(idInt == SYSINTR_VMINI)
{
  RETAILMSG (
            1,
            (TEXT("Accepting VMini interrupt enable request.\r\n")) );
  return (TRUE);
}
```
SYSINTR_VMINI is defined as SYSINTR_DEVICES + 7. Verify that your platform does not use the SYSINTR_DEVICES + 7 slot.

For information about complete sample implementations, see %_WINCEROOT%\Platform\<PlatformName>\Kernel\Hal\Halether.c.

To enable the VMini virtual adapter

Read %_WINCEROOT%\Public\Common\Oak\Drivers\Ethdbg\Vbridge\Readme.txt.
Include VMini.dll in the OS image.

Update the registry to support VMini.dll. When the appropriate environment variable settings are set — !BSP_NOSHAREETH, !IMGNOSHAREETH, and SYSGEN_SHELL for IABASE or SYSGEN_TCPIP for HLBASE — the following registry settings that support VMini.dll will be included.

[HKEY_LOCAL_MACHINE\Comm\Tcpip\Linkage]
    "Bind"=multi_sz:"VMINI1"
[HKEY_LOCAL_MACHINE\Comm\VMini]
    "DisplayName"="Null Ethernet Miniport Driver"
    "Group"="NDIS"
    "ImagePath"="VMini.dll"
[HKEY_LOCAL_MACHINE\Comm\VMini\Linkage]
    "Route"=multi_sz:"VMINI1"
[HKEY_LOCAL_MACHINE\Comm\VMINI1]
    "DisplayName"="Null Ethernet Miniport Driver"
    "Group"="NDIS"
    "ImagePath"="VMini.dll"
[HKEY_LOCAL_MACHINE\Comm\VMINI1\Parms]
    "BusNumber"=dword:0
    "BusType"=dword:05
    "Interrupt"=dword:05
    "IOAddress"=dword:0300
[HKEY_LOCAL_MACHINE\Comm\VMINI1\Parms\TcpIp]
    "EnableDHCP"=dword:1
    ;This should be MULTI_SZ
    "DefaultGateway"=""
    ;Use zero as the broadcast address (or 255.255.255.255)
    "UseZeroBroadcast"=dword:0
    ;This should be MULTI_SZ, the IP address list
    "IpAddress"="0.0.0.0"
    ;This should be MULTI_SZ, the subnet masks for the IP addresses above
    "Subnetmask"="0.0.0.0"
    ;DHCP will keep retrying
    "DhcpMaxRetry"=dword:ffffffff
    ;INIT delay, RFC2131 recommends 10 seconds
    "DhcpInitDelayInterval"=dword:2710
    ;Number of retries before the dialogue box comes up
    "DhcpRetryDialogue"=dword:ffffffff
[HKEY_LOCAL_MACHINE\Comm\VMINI1\Parms]
    "DefaultGateway"=dword:1
    "DefaultLineStatus"=dword:1

For multicast, VMini assumes that the adapter has 8 entries for the multicast address list.

Partager via

See Also

Ressources supplémentaires