IPC@CHIP® RTOS-LNX – API Documentation

Header image

Main page

Explanations and source code example for usage of the packet API

List of Packet API functions

The packet driver API provides transmission and reception of network packets separate from the RTOS TCPIP protocol, especially for the internal ethernet device. But it is also possible to use this functionality for user specific device drivers build with the Device Driver API.
This API provides the installation of user handlers for a specified device interface (e.g. the ethernet device). At its internal driver receive function the driver checks if the received packet has the same type than one of the installed handler types. It forwards the packet to the users packet application by executing a callback function, which is part of the handler installation. Therefore the user has to specify at his packet handler a specified packet type, e.g. the 16-Bit type field of an ethernet frame.

Two different types of packet handlers are supported:

Packet handlers must installed by calling the Packet API function pktSetAccessType( ).

The API function pktSetReceiveMode( ) is able to switch a device into the so-called promiscuous mode. If this mode is set, the device accepts physically all incoming packets. This feature is supported by the internal ethernet driver.

Please note: This API is not compatible to the Packet API of SC1x,SC1x3/SC2x due to the totally different architecture of the controllers.
Currently this API is focussed for the usage at the internal ethernet controller. It is not supported by the RTOS internal PPP devices. If the user wants to provide the functionality at own device driver application, the required functionality (e.g support of promiscuous mode or multicast addresses) must be implemented at his application.

The listed example code can be used as a template for own packet driver applications. It installs a packet type handler with 16-Bit packet type 0xF1F0 for the internal ethernet device.
The incoming packets are stored at a fixed ringbuffer and printed to stdout at main().

#include <stdio.h>
#include <string.h>
#include <clib.h>
#define MAX_PKTS 16 //Number of buffers at the receive ring
//Receive ring buffer definition
typedef struct tag_rx_buf{
int length;
// Prototypes
int myPktRecvCb(void * buffer, int length);
unsigned short myPktType = 0xF1F0; //Packet type
//The packet handler structure
PktHandle myPktHandle1=
{0, // Handler identifier number, filled in after execution.
myPktRecvCb, // Address of the receiver callback function
&myPktType, // Pointer to the packet type
sizeof(unsigned short) //Size of myPktType
//Receive buffer queue and read/write indices
tRxBuf myPktRcvBufs[MAX_PKTS];
unsigned short volatile rdIdx;
unsigned short volatile wrIdx;
EthPacketUnion myPktSendBuf;
//Broadcast MAC address
unsigned char bcastMAC[6]={0xFF,0xFF,0xFF,0xFF,0xFF,0xFF};
// int myPktRecvCb(void * buffer, int length)
// Callback function for receiving packets of the installed type
// executed by the device driver to handover the received packet to the user.
// The function must copy the packet into a buffer provided by the application,
// because the provided buffer content is no longer valid after the execution.
// This example uses a static ringbuffer with fixed sizes.
// Parameters: buffer packet storage
// length number of bytes at buffer
// Return: Return value is not used
int myPktRecvCb(void * buffer, int length)
unsigned short new_wrIdx;
//Store packets at ringbuffer
new_wrIdx = (wrIdx<(MAX_PKTS-1)) ? wrIdx+1 : 0;
if(new_wrIdx!=rdIdx) // buffer not full ?
return 0;
//No space left at ringBuffer
return -1;
// main()
// a) Install packet handler for type given by argument
// b) Sends a packet if the key ENTER was pressed
// c) Print headers of the received packets
int main(int argc, char *argv[])
int key;
void *devHandle;
int errorCode;
unsigned char chr='0';
printf("\r\nEthernet packet driver example, type: %04X",myPktType);
//Retrieve the device handle pointer of the ethernet
printf("\r\nError: Retrieving ethernet device handle pointer failed");
return 0;
//Install the handler
printf("\r\nError: Installing packet handler failed");
return 0;
//Init the send packet
printf("\r\nPress Enter for sending broadcast packets, (ESC exits)");
key = BIOS_getch() & 0x00FF;
printf("\r\nSending packet with data[0]: %02X",myPktSendBuf.packetstruct.data[0]);
printf("\r\nUser break");
//check ring buffer for incoming packets and print the packet
printf("\r\n\r\nBufIdx %08d Packet length %d\r\nDst: ",
printf(" Src: ");
printf(" Type: %04X",myPktRcvBufs[rdIdx].rcvBuf.packetstruct.type);
printf(" Data[0]: %02X",myPktRcvBufs[rdIdx].rcvBuf.packetstruct.data[0]);
//Set the read index pointer
rdIdx = (rdIdx<(MAX_PKTS-1)) ? rdIdx+1 : 0;
printf("\r\nExit application");
// All installed packet handlers will be automatically
// released at exit of the application

Top of page | Main page

Copyright © 2018 Beck IPC GmbH
Generated on Tue Jul 10 2018 14:54:14 by Doxygen 1.8.13