RTEMS Network User Manual (5.1).¶
Copyrights and License
This document is available under the Creative Commons Attribution-ShareAlike 4.0 International Public License.
The authors have used their best efforts in preparing this material. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. No warranty of any kind, expressed or implied, with regard to the software or the material contained in this document is provided. No liability arising out of the application or use of any product described in this document is assumed. The authors reserve the right to revise this material and to make changes from time to time in the content hereof without obligation to notify anyone of such revision or changes.
The RTEMS Project is hosted at https://www.rtems.org. Any inquiries concerning RTEMS, its related support components, or its documentation should be directed to the RTEMS Project community.
RTEMS Online Resources
Home | |
Documentation | |
Mailing Lists | |
Bug Reporting | |
Git Repositories | |
Developers |
1. Preface¶
This document describes the RTEMS specific parts of the FreeBSD TCP/IP stack. Much of this documentation was written by Eric Norum (eric@skatter.usask.ca) of the Saskatchewan Accelerator Laboratory who also ported the FreeBSD TCP/IP stack to RTEMS.
The following is a list of resources which should be useful in trying to understand Ethernet:
Charles Spurgeon’s Ethernet Web Site “This site provides extensive information about Ethernet (IEEE 802.3) local area network (LAN) technology. Including the original 10 Megabit per second (Mbps) system, the 100 Mbps Fast Ethernet system (802.3u), and the Gigabit Ethernet system (802.3z).” The URL is: (http://www.ethermanage.com/ethernet/ethernet.html)
TCP/IP Illustrated, Volume 1 : The Protocols by W. Richard Stevens (ISBN: 0201633469) This book provides detailed introduction to TCP/IP and includes diagnostic programs which are publicly available.
TCP/IP Illustrated, Volume 2 : The Implementation by W. Richard Stevens and Gary Wright (ISBN: 020163354X) This book focuses on implementation issues regarding TCP/IP. The treat for RTEMS users is that the implementation covered is the BSD stack with most of the source code described in detail.
UNIX Network Programming, Volume 1 : 2nd Edition by W. Richard Stevens (ISBN: 0-13-490012-X) This book describes how to write basic TCP/IP applications, again with primary focus on the BSD stack.
2. Network Task Structure and Data Flow¶
A schematic diagram of the tasks and message mbuf queues in a simple RTEMS networking application is shown in the following figure:
The transmit task for each network interface is normally blocked waiting for a packet to arrive in the transmit queue. Once a packet arrives, the transmit task may block waiting for an event from the transmit interrupt handler. The transmit interrupt handler sends an RTEMS event to the transmit task to indicate that transmit hardware resources have become available.
The receive task for each network interface is normally blocked waiting for an event from the receive interrupt handler. When this event is received the receive task reads the packet and forwards it to the network stack for subsequent processing by the network task.
The network task processes incoming packets and takes care of timed operations such as handling TCP timeouts and aging and removing routing table entries.
The ‘Network code’ contains routines which may run in the context of the user application tasks, the interface receive task or the network task. A network semaphore ensures that the data structures manipulated by the network code remain consistent.
3. Networking Driver¶
3.1. Introduction¶
This chapter is intended to provide an introduction to the procedure for writing RTEMS network device drivers. The example code is taken from the ‘Generic 68360’ network device driver. The source code for this driver is located in the bsps/m68k/gen68360/net directory in the RTEMS source code distribution. Having a copy of this driver at hand when reading the following notes will help significantly.
3.2. Learn about the network device¶
Before starting to write the network driver become completely familiar with the programmer’s view of the device. The following points list some of the details of the device that must be understood before a driver can be written.
Does the device use DMA to transfer packets to and from memory or does the processor have to copy packets to and from memory on the device?
If the device uses DMA, is it capable of forming a single outgoing packet from multiple fragments scattered in separate memory buffers?
If the device uses DMA, is it capable of chaining multiple outgoing packets, or does each outgoing packet require intervention by the driver?
Does the device automatically pad short frames to the minimum 64 bytes or does the driver have to supply the padding?
Does the device automatically retry a transmission on detection of a collision?
If the device uses DMA, is it capable of buffering multiple packets to memory, or does the receiver have to be restarted after the arrival of each packet?
How are packets that are too short, too long, or received with CRC errors handled? Does the device automatically continue reception or does the driver have to intervene?
How is the device Ethernet address set? How is the device programmed to accept or reject broadcast and multicast packets?
What interrupts does the device generate? Does it generate an interrupt for each incoming packet, or only for packets received without error? Does it generate an interrupt for each packet transmitted, or only when the transmit queue is empty? What happens when a transmit error is detected?
In addition, some controllers have specific questions regarding board specific configuration. For example, the SONIC Ethernet controller has a very configurable data bus interface. It can even be configured for sixteen and thirty-two bit data buses. This type of information should be obtained from the board vendor.
3.3. Understand the network scheduling conventions¶
When writing code for the driver transmit and receive tasks, take care to follow the network scheduling conventions. All tasks which are associated with networking share various data structures and resources. To ensure the consistency of these structures the tasks execute only when they hold the network semaphore (rtems_bsdnet_semaphore). The transmit and receive tasks must abide by this protocol. Be very careful to avoid ‘deadly embraces’ with the other network tasks. A number of routines are provided to make it easier for the network driver code to conform to the network task scheduling conventions.
void rtems_bsdnet_semaphore_release(void)This function releases the network semaphore. The network driver tasks must call this function immediately before making any blocking RTEMS request.void rtems_bsdnet_semaphore_obtain(void)This function obtains the network semaphore. If a network driver task has released the network semaphore to allow other network-related tasks to run while the task blocks, then this function must be called to reobtain the semaphore immediately after the return from the blocking RTEMS request.rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set *)The network driver task should call this function when it wishes to wait for an event. This function releases the network semaphore, callsrtems_event_receiveto wait for the specified event or events and reobtains the semaphore. The value returned is the value returned by thertems_event_receive.
3.4. Network Driver Makefile¶
Network drivers are considered part of the BSD network package and as such are to be compiled with the appropriate flags. This can be accomplished by adding -D__INSIDE_RTEMS_BSD_TCPIP_STACK__ to the command line. If the driver is inside the RTEMS source tree or is built using the RTEMS application Makefiles, then adding the following line accomplishes this:
DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__
This is equivalent to the following list of definitions. Early versions of the RTEMS BSD network stack required that all of these be defined.
-D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \
-DDIAGNOSTIC -DBOOTP_COMPAT
Defining these macros tells the network header files that the driver is to be compiled with extended visibility into the network stack. This is in sharp contrast to applications that simply use the network stack. Applications do not require this level of visibility and should stick to the portable application level API.
As a direct result of being logically internal to the network stack, network drivers use the BSD memory allocation routines This means, for example, that malloc takes three arguments. See the SONIC device driver (c/src/lib/libchip/network/sonic.c) for an example of this. Because of this, network drivers should not include <stdlib.h>. Doing so will result in conflicting definitions of malloc().
Application level code including network servers such as the FTP daemon are not part of the BSD kernel network code and should not be compiled with the BSD network flags. They should include <stdlib.h> and not define the network stack visibility macros.
3.5. Write the Driver Attach Function¶
The driver attach function is responsible for configuring the driver and making the connection between the network stack and the driver.
Driver attach functions take a pointer to an rtems_bsdnet_ifconfig structure as their only argument. and set the driver parameters based on the values in this structure. If an entry in the configuration structure is zero the attach function chooses an appropriate default value for that parameter.
The driver should then set up several fields in the ifnet structure in the device-dependent data structure supplied and maintained by the driver:
ifp->if_softcPointer to the device-dependent data. The first entry in the device-dependent data structure must be an
arpcomstructure.ifp->if_nameThe name of the device. The network stack uses this string and the device number for device name lookups. The device name should be obtained from the
nameentry in the configuration structure.ifp->if_unitThe device number. The network stack uses this number and the device name for device name lookups. For example, if
ifp->if_nameissccandifp->if_unitis1, the full device name would bescc1. The unit number should be obtained from the ‘name’ entry in the configuration structure.ifp->if_mtuThe maximum transmission unit for the device. For Ethernet devices this value should almost always be 1500.
ifp->if_flagsThe device flags. Ethernet devices should set the flags to
IFF_BROADCAST|IFF_SIMPLEX, indicating that the device can broadcast packets to multiple destinations and does not receive and transmit at the same time.ifp->if_snd.ifq_maxlenThe maximum length of the queue of packets waiting to be sent to the driver. This is normally set to
ifqmaxlen.ifp->if_initThe address of the driver initialization function.
ifp->if_startThe address of the driver start function.
ifp->if_ioctlThe address of the driver ioctl function.
ifp->if_outputThe address of the output function. Ethernet devices should set this to
ether_output.
RTEMS provides a function to parse the driver name in the configuration structure into a device name and unit number.
int rtems_bsdnet_parse_driver_name (
const struct rtems_bsdnet_ifconfig *config,
char **namep
);
The function takes two arguments; a pointer to the configuration structure and a pointer to a pointer to a character. The function parses the configuration name entry, allocates memory for the driver name, places the driver name in this memory, sets the second argument to point to the name and returns the unit number. On error, a message is printed and -1 is returned.
Once the attach function has set up the above entries it must link the driver data structure onto the list of devices by calling if_attach. Ethernet devices should then call ether_ifattach. Both functions take a pointer to the device’s ifnet structure as their only argument.
The attach function should return a non-zero value to indicate that the driver has been successfully configured and attached.
3.6. Write the Driver Start Function.¶
This function is called each time the network stack wants to start the transmitter. This occures whenever the network stack adds a packet to a device’s send queue and the IFF_OACTIVE bit in the device’s if_flags is not set.
For many devices this function need only set the IFF_OACTIVE bit in the if_flags and send an event to the transmit task indicating that a packet is in the driver transmit queue.
3.7. Write the Driver Initialization Function.¶
This function should initialize the device, attach to interrupt handler, and start the driver transmit and receive tasks. The function
rtems_id
rtems_bsdnet_newproc (char *name,
int stacksize,
void(*entry)(void *),
void *arg);
should be used to start the driver tasks.
Note that the network stack may call the driver initialization function more than once. Make sure multiple versions of the receive and transmit tasks are not accidentally started.
3.8. Write the Driver Transmit Task¶
This task is reponsible for removing packets from the driver send queue and sending them to the device. The task should block waiting for an event from the driver start function indicating that packets are waiting to be transmitted. When the transmit task has drained the driver send queue the task should clear the IFF_OACTIVE bit in if_flags and block until another outgoing packet is queued.
3.9. Write the Driver Receive Task¶
This task should block until a packet arrives from the device. If the device is an Ethernet interface the function ether_input should be called to forward the packet to the network stack. The arguments to ether_input are a pointer to the interface data structure, a pointer to the ethernet header and a pointer to an mbuf containing the packet itself.
3.10. Write the Driver Interrupt Handler¶
A typical interrupt handler will do nothing more than the hardware manipulation required to acknowledge the interrupt and send an RTEMS event to wake up the driver receive or transmit task waiting for the event. Network interface interrupt handlers must not make any calls to other network routines.
3.11. Write the Driver IOCTL Function¶
This function handles ioctl requests directed at the device. The ioctl commands which must be handled are:
SIOCGIFADDR
SIOCSIFADDRIf the device is an Ethernet interface these commands should be passed on to
ether_ioctl.SIOCSIFFLAGSThis command should be used to start or stop the device, depending on the state of the interface
IFF_UPandIFF_RUNNINGbits inif_flags:IFF_RUNNINGStop the device.
IFF_UPStart the device.
IFF_UP|IFF_RUNNINGStop then start the device.
0Do nothing.
3.12. Write the Driver Statistic-Printing Function¶
This function should print the values of any statistic/diagnostic counters the network driver may use. The driver ioctl function should call the statistic-printing function when the ioctl command is SIO_RTEMS_SHOW_STATS.
4. Using Networking in an RTEMS Application¶
4.1. Makefile changes¶
4.1.1. Including the required managers¶
The FreeBSD networking code requires several RTEMS managers in the application:
MANAGERS = io event semaphore
4.1.2. Increasing the size of the heap¶
The networking tasks allocate a lot of memory. For most applications the heap should be at least 256 kbytes. The amount of memory set aside for the heap can be adjusted by setting the CFLAGS_LD definition as shown below:
CFLAGS_LD += -Wl,--defsym -Wl,HeapSize=0x80000
This sets aside 512 kbytes of memory for the heap.
4.2. System Configuration¶
The networking tasks allocate some RTEMS objects. These must be accounted for in the application configuration table. The following lists the requirements.
- TASKS
One network task plus a receive and transmit task for each device.
- SEMAPHORES
One network semaphore plus one syslog mutex semaphore if the application uses openlog/syslog.
- EVENTS
The network stack uses
RTEMS_EVENT_24andRTEMS_EVENT_25. This has no effect on the application configuration, but application tasks which call the network functions should not use these events for other purposes.
4.3. Initialization¶
4.3.1. Additional include files¶
The source file which declares the network configuration structures and calls the network initialization function must include
#include <rtems/rtems_bsdnet.h>
4.3.2. Network Configuration¶
The network configuration is specified by declaring and initializing the rtems_bsdnet_config structure.
struct rtems_bsdnet_config {
/*
* This entry points to the head of the ifconfig chain.
*/
struct rtems_bsdnet_ifconfig *ifconfig;
/*
* This entry should be rtems_bsdnet_do_bootp if BOOTP
* is being used to configure the network, and NULL
* if BOOTP is not being used.
*/
void (*bootp)(void);
/*
* The remaining items can be initialized to 0, in
* which case the default value will be used.
*/
rtems_task_priority network_task_priority; /* 100 */
unsigned long mbuf_bytecount; /* 64 kbytes */
unsigned long mbuf_cluster_bytecount; /* 128 kbytes */
char *hostname; /* BOOTP */
char *domainname; /* BOOTP */
char *gateway; /* BOOTP */
char *log_host; /* BOOTP */
char *name_server[3]; /* BOOTP */
char *ntp_server[3]; /* BOOTP */
unsigned long sb_efficiency; /* 2 */
/* UDP TX: 9216 bytes */
unsigned long udp_tx_buf_size;
/* UDP RX: 40 * (1024 + sizeof(struct sockaddr_in)) */
unsigned long udp_rx_buf_size;
/* TCP TX: 16 * 1024 bytes */
unsigned long tcp_tx_buf_size;
/* TCP TX: 16 * 1024 bytes */
unsigned long tcp_rx_buf_size;
/* Default Network Tasks CPU Affinity */
#ifdef RTEMS_SMP
const cpu_set_t *network_task_cpuset;
size_t network_task_cpuset_size;
#endif
};
The structure entries are described in the following table. If your application uses BOOTP/DHCP to obtain network configuration information and if you are happy with the default values described below, you need to provide only the first two entries in this structure.
struct rtems_bsdnet_ifconfig *ifconfigA pointer to the first configuration structure of the first network device. This structure is described in the following section. You must provide a value for this entry since there is no default value for it.
void (*bootp)(void)This entry should be set to
rtems_bsdnet_do_bootpif your application by default uses the BOOTP/DHCP client protocol to obtain network configuration information. It should be set toNULLif your application does not use BOOTP/DHCP. You can also usertems_bsdnet_do_bootp_rootfsto have a set of standard files created with the information return by the BOOTP/DHCP protocol. The IP address is added to/etc/hostswith the host name and domain returned. If no host name or domain is returnedme.mydomainis used. The BOOTP/DHCP server’s address is also added to/etc/hosts. The domain name server listed in the BOOTP/DHCP information are added to/etc/resolv.conf. A``search`` record is also added if a domain is returned. The files are created if they do not exist. The defaultrtems_bsdnet_do_bootpandrtems_bsdnet_do_bootp_rootfshandlers will loop for-ever waiting for a BOOTP/DHCP server to respond. If an error is detected such as not valid interface or valid hardware address the target will reboot allowing any hardware reset to correct itself. You can provide your own custom handler which allows you to perform an initialization that meets your specific system requirements. For example you could try BOOTP/DHCP then enter a configuration tool if no server is found allowing the user to switch to a static configuration.int network_task_priorityThe priority at which the network task and network device receive and transmit tasks will run. If a value of 0 is specified the tasks will run at priority 100.
unsigned long mbuf_bytecountThe number of bytes to allocate from the heap for use as mbufs. If a value of 0 is specified, 64 kbytes will be allocated.
unsigned long mbuf_cluster_bytecountThe number of bytes to allocate from the heap for use as mbuf clusters. If a value of 0 is specified, 128 kbytes will be allocated.
char *hostnameThe host name of the system. If this, or any of the following, entries are
NULLthe value may be obtained from a BOOTP/DHCP server.char *domainnameThe name of the Internet domain to which the system belongs.
char *gatewayThe Internet host number of the network gateway machine, specified in ‘dotted decimal’ (
129.128.4.1) form.char *log_hostThe Internet host number of the machine to which
syslogmessages will be sent.char *name_server[3]The Internet host numbers of up to three machines to be used as Internet Domain Name Servers.
char *ntp_server[3]The Internet host numbers of up to three machines to be used as Network Time Protocol (NTP) Servers.
unsigned long sb_efficiencyThis is the first of five configuration parameters related to the amount of memory each socket may consume for buffers. The TCP/IP stack reserves buffers (e.g. mbufs) for each open socket. The TCP/IP stack has different limits for the transmit and receive buffers associated with each TCP and UDP socket. By tuning these parameters, the application developer can make trade-offs between memory consumption and performance. The default parameters favor performance over memory consumption. See http://www.rtems.org/ml/rtems-users/2004/february/msg00200.html for more details but note that after the RTEMS 4.8 release series, the
sb_efficiencydefault was changed from8to2. The user should also be aware of theSO_SNDBUFandSO_RCVBUFIO control operations. These can be used to specify the send and receive buffer sizes for a specific socket. There is no standard IO control to change thesb_efficiencyfactor. Thesb_efficiencyparameter is a buffering factor used in the implementation of the TCP/IP stack. The default is2which indicates double buffering. When allocating memory for each socket, this number is multiplied by the buffer sizes for that socket.unsigned long udp_tx_buf_sizeThis configuration parameter specifies the maximum amount of buffer memory which may be used for UDP sockets to transmit with. The default size is 9216 bytes which corresponds to the maximum datagram size.
unsigned long udp_rx_buf_sizeThis configuration parameter specifies the maximum amount of buffer memory which may be used for UDP sockets to receive into. The default size is the following length in bytes:
40 * (1024 + sizeof(struct sockaddr_in))unsigned long tcp_tx_buf_sizeThis configuration parameter specifies the maximum amount of buffer memory which may be used for TCP sockets to transmit with. The default size is sixteen kilobytes.
unsigned long tcp_rx_buf_sizeThis configuration parameter specifies the maximum amount of buffer memory which may be used for TCP sockets to receive into. The default size is sixteen kilobytes.
const cpu_set_t *network_task_cpusetThis configuration parameter specifies the CPU affinity of the network task. If set to
0the network task can be scheduled on any CPU. Only available in SMP configurations.size_t network_task_cpuset_sizeThis configuration parameter specifies the size of the
network_task_cpusetused. Only available in SMP configurations.
In addition, the following fields in the rtems_bsdnet_ifconfig are of interest.
- int port
The I/O port number (ex: 0x240) on which the external Ethernet can be accessed.
- int irno
The interrupt number of the external Ethernet controller.
- int bpar
The address of the shared memory on the external Ethernet controller.
4.3.3. Network device configuration¶
Network devices are specified and configured by declaring and initializing a struct rtems_bsdnet_ifconfig structure for each network device.
The structure entries are described in the following table. An application which uses a single network interface, gets network configuration information from a BOOTP/DHCP server, and uses the default values for all driver parameters needs to initialize only the first two entries in the structure.
char *nameThe full name of the network device. This name consists of the driver name and the unit number (e.g.
"scc1"). Thebsp.hinclude file usually definesRTEMS_BSP_NETWORK_DRIVER_NAMEas the name of the primary (or only) network driver.
int (*attach)(struct rtems_bsdnet_ifconfig *conf)
The address of the driver
attachfunction. The network initialization function calls this function to configure the driver and attach it to the network stack. Thebsp.hinclude file usually definesRTEMS_BSP_NETWORK_DRIVER_ATTACHas the name of the attach function of the primary (or only) network driver.
struct rtems_bsdnet_ifconfig *nextA pointer to the network device configuration structure for the next network interface, or
NULLif this is the configuration structure of the last network interface.char *ip_addressThe Internet address of the device, specified in ‘dotted decimal’ (
129.128.4.2) form, orNULLif the device configuration information is being obtained from a BOOTP/DHCP server.char *ip_netmaskThe Internet inetwork mask of the device, specified in ‘dotted decimal’ (
255.255.255.0) form, orNULLif the device configuration information is being obtained from a BOOTP/DHCP server.void *hardware_addressThe hardware address of the device, or
NULLif the driver is to obtain the hardware address in some other way (usually by reading it from the device or from the bootstrap ROM).int ignore_broadcastZero if the device is to accept broadcast packets, non-zero if the device is to ignore broadcast packets.
int mtuThe maximum transmission unit of the device, or zero if the driver is to choose a default value (typically 1500 for Ethernet devices).
int rbuf_countThe number of receive buffers to use, or zero if the driver is to choose a default value
int xbuf_countThe number of transmit buffers to use, or zero if the driver is to choose a default value Keep in mind that some network devices may use 4 or more transmit descriptors for a single transmit buffer.
A complete network configuration specification can be as simple as the one shown in the following example. This configuration uses a single network interface, gets network configuration information from a BOOTP/DHCP server, and uses the default values for all driver parameters.
static struct rtems_bsdnet_ifconfig netdriver_config = {
RTEMS_BSP_NETWORK_DRIVER_NAME,
RTEMS_BSP_NETWORK_DRIVER_ATTACH
};
struct rtems_bsdnet_config rtems_bsdnet_config = {
&netdriver_config,
rtems_bsdnet_do_bootp,
};
4.3.4. Network initialization¶
The networking tasks must be started before any network I/O operations can be performed. This is done by calling:
rtems_bsdnet_initialize_network ();
This function is declared in rtems/rtems_bsdnet.h. t returns 0 on success and -1 on failure with an error code in errno. It is not possible to undo the effects of a partial initialization, though, so the function can be called only once irregardless of the return code. Consequently, if the condition for the failure can be corrected, the system must be reset to permit another network initialization attempt.
4.4. Application Programming Interface¶
The RTEMS network package provides almost a complete set of BSD network services. The network functions work like their BSD counterparts with the following exceptions:
A given socket can be read or written by only one task at a time.
The
selectfunction only works for file descriptors associated with sockets.You must call
openlogbefore calling any of thesyslogfunctions.Some of the network functions are not thread-safe. For example the following functions return a pointer to a static buffer which remains valid only until the next call:
gethostbyaddrgethostbynameinet_ntoa(inet_ntopis thread-safe, though).The RTEMS network package gathers statistics.
Addition of a mechanism to “tap onto” an interface and monitor every packet received and transmitted.
Addition of
SO_SNDWAKEUPandSO_RCVWAKEUPsocket options.
Some of the new features are discussed in more detail in the following sections.
4.4.1. Network Statistics¶
There are a number of functions to print statistics gathered by the network stack. These function are declared in rtems/rtems_bsdnet.h.
rtems_bsdnet_show_if_statsDisplay statistics gathered by network interfaces.
rtems_bsdnet_show_ip_statsDisplay IP packet statistics.
rtems_bsdnet_show_icmp_statsDisplay ICMP packet statistics.
rtems_bsdnet_show_tcp_statsDisplay TCP packet statistics.
rtems_bsdnet_show_udp_statsDisplay UDP packet statistics.
rtems_bsdnet_show_mbuf_statsDisplay mbuf statistics.
rtems_bsdnet_show_inet_routesDisplay the routing table.
4.4.2. Tapping Into an Interface¶
RTEMS add two new ioctls to the BSD networking code, SIOCSIFTAP and SIOCGIFTAP. These may be used to set and get a tap function. The tap function will be called for every Ethernet packet received by the interface.
These are called like other interface ioctls, such as SIOCSIFADDR. When setting the tap function with SIOCSIFTAP, set the ifr_tap field of the ifreq struct to the tap function. When retrieving the tap function with SIOCGIFTAP, the current tap function will be returned in the ifr_tap field. To stop tapping packets, call SIOCSIFTAP with a ifr_tap field of 0.
The tap function is called like this:
int tap (struct ifnet *, struct ether_header *, struct mbuf *)
The tap function should return 1 if the packet was fully handled, in which case the caller will simply discard the mbuf. The tap function should return 0 if the packet should be passed up to the higher networking layers.
The tap function is called with the network semaphore locked. It must not make any calls on the application levels of the networking level itself. It is safe to call other non-networking RTEMS functions.
4.4.3. Socket Options¶
RTEMS adds two new SOL_SOCKET level options for setsockopt and getsockopt: SO_SNDWAKEUP and SO_RCVWAKEUP. For both, the option value should point to a sockwakeup structure. The sockwakeup structure has the following fields:
void (*sw_pfn) (struct socket *, caddr_t);
caddr_t sw_arg;
These options are used to set a callback function to be called when, for example, there is data available from the socket (SO_RCVWAKEUP) and when there is space available to accept data written to the socket (SO_SNDWAKEUP).
If setsockopt is called with the SO_RCVWAKEUP option, and the sw_pfn field is not zero, then when there is data available to be read from the socket, the function pointed to by the sw_pfn field will be called. A pointer to the socket structure will be passed as the first argument to the function. The sw_arg field set by the SO_RCVWAKEUP call will be passed as the second argument to the function.
If setsockopt is called with the SO_SNDWAKEUP function, and the sw_pfn field is not zero, then when there is space available to accept data written to the socket, the function pointed to by the sw_pfn field will be called. The arguments passed to the function will be as with SO_SNDWAKEUP.
When the function is called, the network semaphore will be locked and the callback function runs in the context of the networking task. The function must be careful not to call any networking functions. It is OK to call an RTEMS function; for example, it is OK to send an RTEMS event.
The purpose of these callback functions is to permit a more efficient alternative to the select call when dealing with a large number of sockets.
The callbacks are called by the same criteria that the select function uses for indicating “ready” sockets. In Stevens Unix Network Programming on page 153-154 in the section “Under what Conditions Is a Descriptor Ready?” you will find the definitive list of conditions for readable and writable that also determine when the functions are called.
When the number of received bytes equals or exceeds the socket receive buffer “low water mark” (default 1 byte) you get a readable callback. If there are 100 bytes in the receive buffer and you only read 1, you will not immediately get another callback. However, you will get another callback after you read the remaining 99 bytes and at least 1 more byte arrives. Using a non-blocking socket you should probably read until it produces error EWOULDBLOCK and then allow the readable callback to tell you when more data has arrived. (Condition 1.a.)
For sending, when the socket is connected and the free space becomes at or above the “low water mark” for the send buffer (default 4096 bytes) you will receive a writable callback. You don’t get continuous callbacks if you don’t write anything. Using a non-blocking write socket, you can then call write until it returns a value less than the amount of data requested to be sent or it produces error EWOULDBLOCK (indicating buffer full and no longer writable). When this happens you can try the write again, but it is often better to go do other things and let the writable callback tell you when space is available to send again. You only get a writable callback when the free space transitions to above the “low water mark” and not every time you write to a non-full send buffer. (Condition 2.a.)
The remaining conditions enumerated by Stevens handle the fact that sockets become readable and/or writable when connects, disconnects and errors occur, not just when data is received or sent. For example, when a server “listening” socket becomes readable it indicates that a client has connected and accept can be called without blocking, not that network data was received (Condition 1.c).
4.4.4. Adding an IP Alias¶
The following code snippet adds an IP alias:
void addAlias(const char *pName, const char *pAddr, const char *pMask)
{
struct ifaliasreq aliasreq;
struct sockaddr_in *in;
/* initialize alias request */
memset(&aliasreq, 0, sizeof(aliasreq));
sprintf(aliasreq.ifra_name, pName);
/* initialize alias address */
in = (struct sockaddr_in *)&aliasreq.ifra_addr;
in->sin_family = AF_INET;
in->sin_len = sizeof(aliasreq.ifra_addr);
in->sin_addr.s_addr = inet_addr(pAddr);
/* initialize alias mask */
in = (struct sockaddr_in *)&aliasreq.ifra_mask;
in->sin_family = AF_INET;
in->sin_len = sizeof(aliasreq.ifra_mask);
in->sin_addr.s_addr = inet_addr(pMask);
/* call to setup the alias */
rtems_bsdnet_ifconfig(pName, SIOCAIFADDR, &aliasreq);
}
Thanks to Mike Seirs <mailto:mikes@poliac.com> for this example code.
4.4.5. Adding a Default Route¶
The function provided in this section is functionally equivalent to the command route add default gw yyy.yyy.yyy.yyy:
void mon_ifconfig(int argc, char *argv[], unsigned32 command_arg, bool verbose)
{
struct sockaddr_in ipaddr;
struct sockaddr_in dstaddr;
struct sockaddr_in netmask;
struct sockaddr_in broadcast;
char *iface;
int f_ip = 0;
int f_ptp = 0;
int f_netmask = 0;
int f_up = 0;
int f_down = 0;
int f_bcast = 0;
int cur_idx;
int rc;
int flags;
bzero((void*) &ipaddr, sizeof(ipaddr));
bzero((void*) &dstaddr, sizeof(dstaddr));
bzero((void*) &netmask, sizeof(netmask));
bzero((void*) &broadcast, sizeof(broadcast));
ipaddr.sin_len = sizeof(ipaddr);
ipaddr.sin_family = AF_INET;
dstaddr.sin_len = sizeof(dstaddr);
dstaddr.sin_family = AF_INET;
netmask.sin_len = sizeof(netmask);
netmask.sin_family = AF_INET;
broadcast.sin_len = sizeof(broadcast);
broadcast.sin_family = AF_INET;
cur_idx = 0;
if (argc <= 1) {
/* display all interfaces */
iface = NULL;
cur_idx += 1;
} else {
iface = argv[1];
if (isdigit(*argv[2])) {
if (inet_pton(AF_INET, argv[2], &ipaddr.sin_addr) < 0) {
printf(