RTSOCKWritten by Robert Kavaler (kavaler@innomedia.com)Copyright (C) 1998-2002, Innomedia, Inc.All rights reserved.Redistribution and use in source and binary forms, with or withoutmodification, are permitted provided that the following conditions aremet: Redistributions of source code must retain the above copyrightnotice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the abovecopyright notice, this list of conditions and the followingdisclaimer in the documentation and/or other materialsprovided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERSAND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIEDWARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF MERCHANTABILITY AND FITNESS FOR APARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALLTHE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FORANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITEDTO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;LOSS OF USE, DATA, OR PROFITS; OR BUSINESSINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OFLIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAYOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OFTHE POSSIBILITY OF SUCH DAMAGE.Update 7/20/02Rtsock now support rtlinux 3.1 and the 2.4.4 linux kernel.Update 6/17/02Added test/example code.  See test directory for details.Added new ioctl RTSOCK_IOCINTERFACE to interface to avoid passing opaque kernel pointer through user task.RTSOCK_IOCINTERFACE:  This interface replaces the RTSOCK_IOCGETSOCKADDRinterface.  To use the interface, each rtsock has a callback that will becalled when the RTSOCK_IOCINTERFACE ioctl call is made.  The callback has threeparameters: an opaque pointer passed with the callback register, a pointerto referenced linux "struct sock" and the args passed to the ioctl.  The firstarg is always the local file descriptor (i.e. fd integer) for the socket.This interface, therefore, allows the rtsock user to make an association between any user task data (i.e. parameters) and the underlying socket structure.  See the example for more information.Update 8/23/00Rtsock now supports 2.4 kernelsInitial Release 1/20/00Rtsock is an RTLinux interface to the Linux socket world.  Rtsock is not adevice driver for network cards.  Instead, packets flow through the Linux kernel using the standard Linux drivers, up/down the standard layer 2 and layer 3 protocols, and then packets are diverted into an RTLinux task.  Currently only UDP sockets are supported.The advantage of this approach over implementing a real-time ethernet driver is that all of the standard L2 and L3 protocols already implemented in the kernel are available to the real-time task.  Thus, all Linux routing protocols, ifconfigs, ARP, RARP, QoS, netfiltering and other packet level processes are applied to the real-time socket.  Of course, the disadvantage is that the delay through the Linux kernel is not fixed and therefore the packets generated in the real-time kernel will not come out of the kernel in "real-time" (i.e. with low jitter).  Thenagain, ethernet itself is not a low jitter medium.The RT interface to rtsock uses the standard Linux socket calls in user space and a non-standard interface in RT space.The API works as follows (this is an overview):Initialization:1.  The rtsock driver is loaded with modprobe or insmod.  It needs a mknod'd device (/dev/rtsock0-5) to communicate between the usertasks and the realtime tasks. 2.  The RT task wishing to use rtsock is loaded with modprobe or insmodand during initialization it must call rtsock_create with the minor device number (X) and other parameters. Each minor device (rtsock currently supports up to 6 minor devices) corresponds to a "pool" of sockets that are to be handled by a single RT "dequeue_skb" call.  Each pool also has a setof fixed length skb's that are allocated at initialization and replenished asthey are used.  The parameters fromRTmax_count and toRTmax_count define the size of the queues used to communicate between linux and rtlinux.  Themain constraint is that (fromRT + toRT) < 32000 (assuming max linux kmalloc is128K bytes).  The skbLength specified in the rtsock_create call is the lengthof layers 5 and above; an additional 16 + 60 + 8 bytes are included for layers2, 3 and 4 respectively.2. The user task opens "/dev/rtsockX" (fd).  This device is used to perform ioctls to manipulate sockets.  (Implementation note: the ioctls could have been added to the sockets themselves, but this would require modifying the kernel.)  The minor device number (X) forms the link between the usertask and the RT task.Next, on a per socket basis:1.  The user task creates a socket (s) and binds the socket as usual.  Eventhough only UDP packets are supported, currently the user must "connect" thesocket to the far end for rtsock to work.  Packets can be sent and receivedusing the standard Linux socket prior to and after redirecting the socketto rtsock.  These Linux packets can be sent using "sendto".2.  When the user task wishes to redirect the packet sequence tortsock it uses the sequence	long s1, s;	s1 = s; 	ioctl(fd, RTSOCK_IOCGETSOCKADDR, &s1);which returns a pointer (s1) that should be passed into the RT task.  Howthe pointer s1 gets to the RT task is not dealt with by rtsock.  Normally,RT tasks have a command queue that is processed by the RT task, and it is assumed that s1 will be passed using some command in that queue.3.  The RT task MUST reference count the socket pointer (s1) usingrtsock_reference_sock.  4.  The RT task can now allocate skb's using rtsock_alloc_skb, and send those skb's via the socket (s1) using rtsock_enqueue_skb.5.  The user task calls ioctl(fd, RTSOCK_IOCREDIRECTFD, &s) to redirect inputpackets to the rtsock.6.  The RT task can now receive packets from the rtsock using rtsock_dequeue_skb.  Rtsock_dequeue_skb actually receives ALL of the packetsfor a given rtsock (which may be multiple sockets).  In order to speedthe lookup of the socket pointer, the user_data field of the struct sockis modified by the real-time task to point to an internal data structure.7.  When done with a sock, the RT task must deferenece the socket (s1)using rtsock_dereference_sock.8.  The user task should close the socket (s1) only AFTER the socket is longerneeded by the RT task.9.  The user task can redirect the input packets back to the user task using ioctl(fd, RTSOCK_IOCRESETFD, &s).10.  Since ICMP messages are not redirected to the RT task, they are processedby the Linux stack and therefore the user task will receive the errors fora socket.  THIS IS A GOOD THING, as it allows the linux task to "manage" the socket and the RT task handle only the real-time packets.Manipulating packets in the RT task:An RT task can use the standard Linux "skb_put" call and similar calls tomanipulate/create packets. However, caution should taken to never underflowor overflow the skb.  Underflow and overflow will cause the RT task to callkmalloc to grow the packet, and that will in turn cause unpredicatable performance (and maybe crashing).  Thus the "__skb_put" version of the packetmanipulation routines should be used.Before an skb can be sent with "rsock_enqueue_sock" it must first be givenan "owner sock" using "skb_set_owner_w".  The owner sock is thesock onto which the skb is queued.Limitations:* Currently only UDP sockets can use the rtsock interface.* UDP packets are sent to the connected destination port only -- there is no equivalent to sendmsg.Applications for the rtsock interface:The main application for the rtsock interface is in situations that require real-time generation or consumption of standard UDP packets in an otherwiseasynchronous network.  One example is a time-tick that must be generated at a fixed rate to a large group of machines.  Another is for RTP sessions in a VoIP application, when the generator/consumer is a DSP or Video card runningwith a constant clock, but the network side is a standard ethernet.  In this case, a "jitter buffer" must be implemented in the real-time task.Installation:1. Unfortunately, in order to use rtsock the kernel must be patched minimally.A patch file is included for 2.2.14 and 2.4.0.  The patch is very simple:it exports one symbol.  2. Change the first line of the Makefile to reflect the proper location of the rtlinux source code for your system.  Then run "make" in this directory.  Theoutput file is rtsock.o3. The "make devs" to create the "/dev/rtsock0-5" devices.4. Run "insmod rtsock.o" to load the rtsock module.