High speed Ethernet: The Packet Module

翻译注：本文主要讲述了如何使Kithara
RTS操作以太网数据收发，Packet模块是krts提供的用于直接操作以太网的模块，使用该模块无需开发网卡驱动即可操作网卡收发数据，可以适用于大多数网卡，如intel,realtek的网卡等。可以用于满足实时收发原始数据包的情况要求，如开发自定义的工业实时以太网等。原文是kithara
rts官方wiki的文档。

高速以太网：数据包模块

For industrial applications it is often necessary to operate the Ethernet
interface in real-time. The Packet Module can provide this.

The Packet Module allows the transport of any Ethernet packets, including IP
packets. It is also possible to use other basic protocols or raw Ethernet. In
any case, it is possible for the user to create a packet completely.

For higher protocols like UDP and TCP see the second part of this tutorial
(socket).

在工业应用中，通常需要实时的操作以太网接口。使用Packet模块可以实现这个功能。

该数据包模块允许传输任何以太网数据包，包括IP数据包。该模块也可以使用其他基本协议或原始以太网。在任何情况下，用户可以创建一个完整的数据包。

对于像UDP和TCP更高的协议，见本教程（socket）的第二部分。

Opening the Network Adapter

打开网络适配器

In order to communicate over an Ethernet network adapter, it must first be
opened using the functionKS_openAdapter. As parameters an adapter handle, an device
string, a receive pool length, a send pool length and flags are passed. After
the function call the adapter handle is written back to the
parameterphAdapter.

A valid device string can be found using the function KS_enumDevices.
The device is updated to the Kithara driver dynamically or can be assigned
permanent. For further details see How to look up for devices.

The amount of Ethernet packet memory that is made available for the receiving
and sending operation is given as the
parameters recvPoolLength and sendPoolLength. Later in this
tutorial the user requests Ethernet packet memory
with KS_requestPacket and releases the Ethernet packet memory
withKS_releasePacket.

为了与以太网网络适配器进行通信，首先必须先使用函数KS_openAdapter打开网络适配器，需要的参数有适配器句柄，设备字符串，接收池长度，发送池长度和标志位作为参数传入函数。在函数调用适配器后，句柄被写回到参数phAdapter
。
一个有效的设备字符串可以使用函数KS_enumDevices找到。设备可以通过Kithara驱动程序动态的更新，也可以被永久的分配。查看进一步详情，请参阅How to look upfor
devices。
数据发送和接收操作能够使用的以太网数据包的内存大小，由参数recvPoolLength和sendPoolLength给出。在这个教程后面，用户需要KS_requestPacket请求以太网数据包的内存，和KS_releasePacket释放以太网数据包内存。

Multiple options can be set using flags. For a complete list see KS_openAdapter.

The function KS_openAdapterEx can open an Ethernet
adapter, too. But additionally a connection handle can be passed. The connection
handle can either be a null-adapter, an adapter handle or a EoE slave
handle.

A null-adapter is an adapter without a physical interface. If an adapter
handle from a previous call ofKS_openAdapter(Ex) is passed, a network
bridge is created. If an EoE slave handle is passed, a network bridge to an EoE
slave is created.

使用标志位进行设置多个选项。请参阅KS_openAdapter函数说明了解详细信息 。

函数KS_openAdapterEx也可以打开一个以太网适配器，但可以多传递一个连接句柄。这个连接句柄可以是一个空的适配器，适配器句柄或EoE
从站句柄。
空适配器是一个没有物理接口的适配器。如果传入之前调用的KS_openAdapter函数得到适配器句柄，则网桥被创建。如果传入EoE从站句柄，一个EoE
从站网桥将被创建。

翻译注：使用该函数KS_openAdapterEx，可以建立windows网卡和kithara rts使用的网卡之间的桥梁

Closing the Network Adapter

关闭网络适配器

To close a network adapter the function KS_closeAdapter must be used.

使用 KS_closeAdapter 函数关闭网络适配器

Sending Packets

发送数据包

Before a packet can be sent, it is first requested from the send pool using
the function KS_requestPacket. As parameters an adapter handle, a packet
and flags are passed. After the function is called, a packet is returned in the
parameter ppPacket.

Per default a packet in raw IP mode is requested. With the
flag KSF_RAW_ETHERNET_PACKET a packet in raw Ethernet mode can be
requested. For an Ethernet frame the pointer which is delivered
in ppPacket is of the type KSMACHeader and for an IP frame it is of a type KSIPHeader.

As next step the packet is filled with the required content.

在一个数据包能被发送之前，首先使用函数KS_requestPacket向发送池请求。该函数需要的参数有适配器句柄，数据包和标志为作为函数参数传入。在函数调用之后，一个数据包返回到参数ppPacket。

每个在原始IP模式下的默认数据包被请求。通过标志位KSF_RAW_ETHERNET_PACKET下，在原始以太网模式下的数据包可以被请求。对于以太网帧由ppPacket传递的指针是KSMACHeader类型，而对于一个IP帧它是一种KSIPHeader类型。在下一步，数据包可以填上需要的内容。

Then the packet can be sent using the function KS_sendPacket. As parameters an adapter handle, a packet, a
packet size and flags are passed. The packet size equals to the size in bytes of
the frame including header. Per default raw IP mode is used. With the
flag KSF_RAW_ETHERNET_PACKET the mode can be switched to raw
Ethernet.

Using flags one of four packet priorities can be
set: KSF_PRIO_NORMAL, KSF_PRIO_LOW, KSF_PRIO_LOWER,KSF_PRIO_LOWEST.

然后该数据包可以使用函数KS_sendPacket发送。需要的参数包括适配器句柄，数据包，数据包大小和标志位作为函数参数传入。数据包的大小等于帧中包括包头的字节大小。每个默认原始IP模式被使用。通过标志位KSF_RAW_ETHERNET_PACKET原始IP模式可以被切换到原始以太网。
使用标志位可以设置数据包四种优先级中的一种：
KSF_PRIO_NORMAL ， KSF_PRIO_LOW ， KSF_PRIO_LOWER ， KSF_PRIO_LOWEST 。

翻译注：这四个有优先级分别对应着，一般优先级，低优先级，较低优先级和最低优先级。

Receiving Packets

接收数据包

There are 2 options for receiving packets:

1. Cyclically check with KS_recvPacket if a packet is ready to be
   collected.


2. Installing a Packet Receive Handler.

有两种方式接收数据包，翻译注：一种是轮询的方式，一种是采用事件触发的中断机制

1、用KS_recvPacket函数周期性进行检测是否有数据包准备好被接收。

2、安装一个数据包接收事件触发的回调函数。

In both cases the data can be analyzed and then given back to the receive
pool with KS_releasePacket. Both methods are mutual exclusive, i.e. you
can either use KS_recvPacket or install a receive handler.

The function KS_recvPacket has an adapter handle, a packet and
flags as parameters. If KS_recvPacket is called but no packet is ready
to be collected the error KSERROR_NO_DATA_AVAILABLE is returned.

For an Ethernet frame the pointer which is delivered in ppPacket is
of the type KSMACHeader and for an IP frame it is of a type KSIPHeader.

If receiving IP frames, the flag KSF_CHECK_IP_CHECKSUM can be used
to check automatically whether the IP checksum is correct.

The function KS_releasePacket release a packet to the receive pool
after it was processed. As parameters an adapter handle, a packet and flags are
passed. This function must be called to ensure that memory resources are
released.

这两种情况下数据都会被分析，然后通过KS_releasePacket函数被接收池接收。这两种方法是相互排斥的，即你只能使用KS_recvPacket函数或安装接收处理程序中的一种。KS_recvPacket函数有适配器句柄，数据包，标志这三个参数。如果调用KS_recvPacket函数而没有可以接收的数据包，则会返回KSERROR_NO_DATA_AVAILABLE错误。

对于以太网帧，从ppPacket接收的指针是KSMACHeader类型，而对于Ip帧是KSIPHeader类型。

函数KS_releasePacket在数据包传输之后释放数据包。适配器句柄、数据包和标志为作为参数传入。这个函数必须被调用以确保内存被释放。

Getting the Adapter State

The function KS_getAdapterState gets the state of an Ethernet
adapter. As parameters an adapter handle, a structure KSAdapterState and flags are passed.

Be sure to initialize the structure member structSize to the actual
size of the structure KSAdapterStatebefore calling the function. After the
call of KS_getAdapterState the structure is filled with information
about sent and received packets.

得到适配器状态

函数KS_getAdapterState得到以太网适配器的状态。适配器句柄、结构KSAdapterState和标志位作为参数传入。

在调用函数前，要确保用真实的数组大小初始化KSAdapterState结构的成员structSize，在调用函数
KS_getAdapterState后结构被填入发送和接受数据包的信息。

Executing Adapter Commands

The function KS_execAdapterCommand executes a specific command on an
adapter. As parameters an adapter handle, a command, an optional parameter and
flags are passed.

A description of the specific commands can be found in
the API documentation ofKS_execAdapterCommand. Information on how the
optional parameter pParam or flags must be set can be found there,
too.

If e.g. a IP configuration should be set, the
command KS_PACKET_SET_IP_CONFIG can be used. The optional
parameter pParam is set to the structure KSIPConfig.

执行适配器命令

函数KS_execAdapterCommand执行适配器上的特定的命令。适配器句柄、命令、一个可选参数和标志位作为参数传入。

关于特殊的命令的描述可以在API文件中找到，对于关于KS_execAdapterCommand的可选参数pParam
和标志位如何设定.的信息也可以在那里找到。

如果是e.g则必须配置IP，可以会用命令KS_PACKET_SET_IP_CONFIG 。可选参数pParam被设置到结构KSIPConfig中。

Installing a Handler

To install a packet handler the function KS_installPacketHandler can be used.

As parameters an adapter handle, an event code, a callback handle and flags
are passed. With the event code the type of the handler is specified.

For the event
code KS_PACKET_RECV and KS_PACKET_LINK_CHANGE are possible
to implement a packet receive handler and a link change handler. The first
handler is called if a packet is ready for receiving and the second handler is
called if the link status changed.

The code that should be executed when the handler is called is passed as a
callback handle (see Creating callbacks). For different event codes special
context structures are passed to the callback function in the context parameter.
A list can be found in the API documentation of the function KS_installPacketHandler.

For a KS_PACKET_RECV event code the corresponding context structure
is PacketUserContext.

If null/NULL/NIL is entered as a callback handle then the handler is
uninstalled again.

安装处理函数

可以使用函数KS_installPacketHandler安装数据包处理程序。

一个适配器句柄，一个事件号，一个回调句柄和标志位需要作为函数参数传入。每个处理程序的类型，通过事件号区别开。

对于该事件代码KS_PACKET_RECV和KS_PACKET_LINK_CHANGE都可以实现数据包接收处理程序和一个链接更改处理程序。如果一个数据包准备好接收则第一个处理程序被调用，如果链路状态变化则第二处理程序被调用。

当处理程序被调用时，需要执行的代码是通过回调句柄传回的（请参阅Creatingcallbacks）。对于不同的事件代码不同的背景结构被传到回调函数的背景参数里。列表可以在API文档中的KS_installPacketHandler函数中找到。
对于KS_PACKET_RECV事件代码对应的上下文结构是PacketUserContext。
如果null/NULL/NIL传到回调句柄，处理程序将再次卸载。

Installing a Packet Receive Handler

First we implement a callback routine that is executed when the handler is
called. A receive callback gets the structure PacketUserContext from the parameter pContext. The
field pPacketSys of the structurePacketUserContext contains the
packet with access on kernel-level. The packet can be analyzed an given back to
the receive pool using the function KS_releasePacket.

安装数据包接收处理程序
首先，当处理程序被调用时，我们实现一个已经执行的回调例程。一个接收回调从参数PacketUserContext得到结构PacketUserContext。该structurePacketUserContext的pPacketSys领域包含在内核级访问数据包。通过使用KS_releasePacket函数，该数据包可以被分析和反馈到接收池。

1. static Error __stdcall _recvCallBack(void* pArgs, void* pContext) {


2. PacketUserContext* pUserContext = (PacketUserContext*)pContext;


3. KSMACHeader* pMacHeader = (KSMACHeader*)(pUserContext->pPacketSys);


4. Error ksError;
5. if (pMacHeader->typeOrLength == KS_htons(USER_ETHERTYPE)) {


6. // analyze packet


7. }
8. ksError = KS_releasePacket(


9. hAdapter,                 // Adapter handle


10. pUserContext->pPacketSys, // Pointer to packet


11. KSF_RAW_ETHERNET_PACKET); // Flags


12. if (ksError != KS_OK)


13. return ksError;
14. return KS_OK;


15. }

As next step a callback is created calling the function KS_createCallBack with
flag KSF_DIRECT_EXEC for execution on kernel-level in real-time
context. The receive packet handler is installed using the functionKS_installPacketHandler with an event
code KS_PACKET_RECV.

下一个步骤，通过标志位KSF_DIRECT_EXEC在实时下执行内核级，调用函数KS_createCallBack创建回调。该接收数据包处理程序是通过使用带事件代码的KS_installPacketHandler函数安装的。

1. KSHandle hCallBack;


2. ksError = KS_createCallBack(


3. &hCallBack,              // Address of callback handle


4. _recvCallBack,          // Callback routine


5. NULL,                   // Reference parameter to callback


6. KSF_DIRECT_EXEC,        // Flags, here kernel-level


7. //   in real-time context


8. 0);                     // Priority
9. ksError = KS_installPacketHandler(


10. hAdapter,             // Adapter handle


11. KS_PACKET_RECV,       // Event code


12. hCallBack,            // Callback handle


13. KSF_RAW_ETHERNET_PACKET); // Flags

高速实时以太网----Kithara RTS,布布扣,bubuko.com