README.RTNET

# Copyright (C) 2005-2017 The RTAI project
# This [file] is free software; the RTAI project
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.

                             RTnet Version 0.9.13
                             ====================

What is it?
-----------
This version of RTnet is a free software hard real-time network protocol stack
for RTAI real-time Linux extension. It makes use of standard Ethernet hardware
and supports several popular card chip sets, including Gigabit Ethernet.
Moreover, Ethernet-over-1394 support is available based on the RT-FireWire
protocol stack.

RTnet implements UDP/IP, TCP/IP (basic features), ICMP and ARP in a
deterministic way. It provides a POSIX socket API to real-time user space
processes and kernel modules. Access to nondeterministic media is managed by
the pluggable RTmac layer and the actual control discipline. As default for
Ethernet, a Time Division Multiple Access (TDMA) discipline is provided.


What are the requirements?
--------------------------
- Linux kernel 3.x onward
- RTAI 5.1 or better
- x86
- RealTek 8139, Intel 8255x (EtherExpress Pro 100), Intel PRO/1000 (e1000 and
  e1000e), DEC 21x4x-based (tulip), AMD PCnet32/PCnetPCI, VIA Rhine, NatSemi
  DP8381x, RTL8169 network adapter, MPC8260 FCC, MPC8xx SCC/FEC, or MPC5200
  on-chip controllers, SMSC LAN91C111 embedded controller, Intel 82575 (igb)
- CAUTION: On systems with > 4 GB RAM, currently only the following chipsets
  will work: RealTek 8139, Intel PRO/1000 PCI-E (e1000e, NOT e1000),
  Intel 82575 (igb). For other drivers, as a workaround, RAM usage can be
  limited to 4 GB by giving mem=4096M as boot parameter.
- For Ethernet-over-FireWire see rtfirewire.berlios.de
- For RT-WLAN: Ralink 2500


How to install it?
------------------
1. Install and test a suitable real-time Linux version
2. cd to a preferred directory (e.g. /usr/src)
3. tar xvjf <PATH-TO-RTNET-ARCHIVE>/rtnet-X.X.X.tar.bz2
4. cd rtnet
5. make menuconfig (run "make help" for further information)
   Set at least the real-time extension installation path and the path RTnet
   is to be installed to (called <PREFIX> from now on). You could also check
   other options if they fit your requirements. Help is available for each
   feature.
6. make
7. make install
   This will create the directories <PREFIX>/sbin with all configuration tools,
   <PREFIX>/modules containing all core modules, <PREFIX>/include with the
   required API header files, and <PREFIX>/etc with configuration files to be
   used with the rtnet startup script.
8. run "mknod /dev/rtnet c 10 240" on your target system to create the
   configuration interface device node. Alternatively, there is also an udev
   rules file available under tools/00-rtnet.rules.


How to test it?
---------------
1. Shutdown the network device which shall become part of the RT-network and
   remove its driver module (this also means that it must not be compiled
   into the kernel!)
2. Load required real-time modules, rtai_hal, rtai_sched, rtai_sem, rtai_rtdm.
3. Check <PREFIX>/etc/rtnet.conf and adapt at least the following parameters:
   RT_DRIVER, IPADDR, TDMA_MODE, TDMA_SLAVES.
4. Run <PREFIX>/sbin/rtnet start
5. Run rtping <remote-host> or run an example application
   (e.g. examples/rtai/simple(server-client))


Special notes
-------------
Starting the RTnet core manually (without RTmac):
  1. Load required componentes of the real-time Linux extension (see above)
  2. Load RTnet modules: rtnet (core), rtipv4 (IPv4 protocol + API), rtpacket
     (packet protocol + API), rt_loopback (rtlo loopback driver), rt_XXX
     (real-time NIC driver)
  3. Configure real-time NICs: rtifconfig rtethX up <IP>,
     rtifconfig rtlo up 127.0.0.1
  4. Add host routes to target nodes, either explicitly:
     rtroute add <target IP> <target hw-address> dev <local NIC>
     Or trigger an ARP handshake:
     rtroute solicit <target IP> dev <local NIC>


Contributors
------------
Ulrich Marx                             - core programming
<marx-at-fet.uni-hannover.de>
Nathan Gustavson                        - testing and bug fixing
Marc Kleine-Budde                       - RTmac, testing, bug fixing, autotools
<kleine-budde-at-gmx.de>
Jan Kiszka <jan.kiszka-at-web.de>       - project management, core programming
Wittawat Yamwong <wittawat-at-web.de>   - testing, documents
Hans-Peter Bock <rtnet-at-avaapgh.de>   - testing, bug fixing, rtdm-select
Mathias Koehrer                         - 3c59x-rt, rtnetproxy, testing,
<mathias_koehrer-at-yahoo.de>             bug fixing, ip fragmentation, e1000
Vinay Sridhara                          - ICMP support
<vinaysridhara-at-yahoo.com>
Erwin Rol <erwin-at-muffin.org>         - Ethereal plugin, rtnetproxy
Wolfgang Grandegger                     - MPC drivers, testing
<wg-at-denx.de>
Erik Buit                               - NatSemi driver
<e.buit-at-student.utwente.nl>
Yuchen Zhang                            - Ethernet-over-FireWire support
<yuchen623-at-gmail.com>
Klaus Keppler                           - RTL8169 gigabit driver
<klaus.keppler-at-informatik.stud.uni-erlangen.de>
Bill Vareka <bvareka-at-amsuper.com>    - joint-slots TDMA extension
Fabian Koch <me-at-tabascoeye.de>       - various improvements of the
                                          configuration interfaces and tools
Daniel Gregorek <dxg-at-gmx.de>         - RT-WLAN support, RT2500 driver
Jorge Almeida                           - SOCK_RAW for packet sockets and
<j-almeida@criticalsoftware.com>          ETH_P_ALL support
Yeoh Chun Yeow <yeohchunyeow@gmail.com>	- rt_at91_ether driver
Cristiano Mantovani <cristianomantovani@hotmail.com>,
Stefano Banzi                           - rt_macb driver
Gilles Chanteperdrix                    - NIC statistics, select() groundwork,
<gilles.chanteperdrix@xenomai.org>        various fixes and enhancements
... and more, see git logs!

Acknowledgements:
David Schleef                           - he wrote the original RTnet, some
                                          parts of this version are based on
                                          his code


RTnet is free software, and you are welcome to redistribute it under
the terms of the GNU General Public License unless otherwise stated. This
program comes with ABSOLUTELY NO WARRANTY. See "COPYING" and header files
rtnet.h and rtmac.h for details.