RTLinux-GPL Ethernet Device Drivers

Controller

Adapter Name

Board IDs

82558

PRO/100+ PCI Adapter

668081-xxx, 689661-xxx

82558

PRO/100+ Management Adapter

691334-xxx, 701738-xxx, 721383-xxx

82558

PRO/100+ Dual Port Server Adapter

714303-xxx, 711269-xxx, A28276-xxx

82558

PRO/100+ PCI Server Adapter

710550-xxx

82550
82559

PRO/100 S Server Adapter

752438-xxx (82550)
A56831-xxx, A10563-xxx, A12171-xxx, A12321-xxx, A12320-xxx, A12170-xxx
748568-xxx (82559)
748565-xxx (82559)

82550
82559

PRO/100 S Desktop Adapter

751767-xxx (82550)
748592-xxx, A12167-xxx, A12318-xxx, A12317-xxx, A12165-xxx
748569-xxx (82559)

82559

PRO/100+ Server Adapter

729757-xxx

82559

PRO/100 S Management Adapter

748566-xxx, 748564-xxx

82550

PRO/100 S Dual Port Server Adapter

A56831-xxx

82551

PRO/100 M Desktop Adapter
PRO/100 S Advanced Management Adapter

A80897-xxx
747842-xxx, 745171-xxx

CNR

PRO/100 VE Desktop Adapter
PRO/100 VM Desktop Adapter

A10386-xxx, A10725-xxx, A23801-xxx, A19716-xxx
A14323-xxx, A19725-xxx, A23801-xxx, A22220-xxx, A23796-xxx

This drivers, despite the usual API, provide the standard POSIX API, i.e., the standard open(), close(), read(), write() and ioctl() calls. Except for the read() call, the other calls are used as usual.

The read() call has been implemented to provide the standard interface, although the way of using that interface by default is not the usual (the drivers can provide the usual way of interfacing them by modifying a macro... go on reading :): it implements the ZERO COPY technique. A normal read() call would need the user to pass a pointer to a previously reserved memory area and the driver would fill that area with data (this way of interfacing the read can be achieved by uncommenting the macro _NO_ZERO_COPY_API_ in the reddopts.h file) call. That means that the driver would have to perform a copy for each packet. In the implementation we provide, the driver saves the expense of that copy just by returning a pointer to the packet being hold in the internal buffers of the driver; this technique is usually named zero copy.

Now a description of the API of each call and an example using it will be shown. The examples are taken from the test program provided with REDD, which is a ping server. You can see the whole code here. Pay special attention to the read() call.

Next, an example of how to use the open() call with RTLinux drivers. In RTLinux, the open call MUST be called inside the init_module() function. Each driver will be located in a virtual location, such as /dev/, and will have a name, such as eth0, or rtl0 or whatever name. In the next example we'll open /dev/eth0 in blocking mode (0 does not mean blocking mode, blocking mode is set by default). The returned value, fd, is used to identify the device. A reference to fd will be used in the next examples.

      if((fd=open("/dev/eth0",0)) == -1){
        rtl_printf("ERROR OPENING /dev/eth0 in blocking mode\n");
        return -1;
      }

The driver can be opened in non-blocking mode by using the flag O_NONBLOCK as follows:

      if((fd=open("/dev/eth0",O_NONBLOCK)) == -1){
        rtl_printf("ERROR OPENING /dev/eth0 in non-blocking mode\n");
        return -1;
      }

SYNOPSIS: int close(int fd);

Next, an example of how to use the close() call with RTLinux drivers. If fd is the device we want to close, then this code closes the device referenced by fd.

      close(fd);

SYNOPSIS: int ioctl(int d, int request, ...);

The ioctl() call is used to set or to get parameters of the device. In the next example we'll show how to get the Ethernet card's MAC address by means of ioctl().

   unsigned char MAC[6];
 
   //Obtain the network interface's MAC address. 
   ioctl(fd, 2, (unsigned long) MAC);

SYNOPSIS: ssize_t read(int fd, void *buf, size_t count);

As said before, by default the read() call uses the ZERO COPY technique. Although the read()'s interface is standard, the way of using that interface has to be modified to implement the zero copy technique. Using the zero copy technique, in order to get a pointer to the driver's internal buffer, an indirection level is needed. To achieve this, a structure encapsulating a memory pointer is needed. The next structure is the one used in REDD:

   struct memory{
      void *mem;
   }

The next code shows how to interface the read call using the previous structure:

   struct memory receive_buffer;
   unsigned char *in_buf;
   int len;
 
   // Obtain the size of the packet and put it into the "len" variable
   len = read(fd,(void *) &receive_buffer,1536);

   //This implements the ZERO COPY technique. In one hand, instead of copying 
   //the buffer into the one passed by us the driver give us a pointer to the 
   //internal buffer, thus saving the expense of a copy. On the other hand, 
   //we should NOT modify that buffer.
   in_buf = (char *) receive_buffer.mem;

Programming this way the driver's interface, after performing the read() call, receive_buffer.mem will contain a pointer to the driver's internal buffer.

If you want to interface read() as usual and not to use the ZERO COPY API uncomment the define _NO_ZERO_COPY_API_ in the reddopts.h file. That will allow you to use the read() call as usual. Nex a code showing how to use the read() call in this mode (it is supposed that the driver has been opened in blocking mode):

   unsigned char in_buf[1536];
   int len;
 
   // Obtain the size of the packet and put it into the "len" variable
   len = read(fd,(void *) &in_buf,1536);

If the driver is opened in non-blocking mode (using the O_NONBLOCK flag), then the application must poll the driver to see if a packet has arrived. The next code shows how to use the read() call if the driver is opened in non-blocking mode:

   unsigned char in_buf[1536];
   int len;

   do{
       // Obtain the size of the packet and put it into the "len" variable
       len = read(fd,(void *) &in_buf,1536);
       usleep(10);
   }while(!len);

The usleep() call is necessary (although the time to sleep can vary). If not called, your machine will be blocked in the do-while loop until a packet arrives, and that can hang your machine.

For more information about the implementation of the drivers, please read the paper "Building Ethernet Drivers on RTLinux-GPL", downloadable in the download section.

This module requires parameters. Usage: insmod ping_{zc,posix}.o IP=ip_address; Example: insmod ping_{zc,posix}.o IP="162.58.0.1"; For more information type as root: modinfo ping_{zc,posix}.o;

REDD: RTLinux Ethernet Device Drivers