rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-23 10:48:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

Clean up and review of Networking User Guide.

Browse Source
This commit is contained in:
Chris Johns 2016-04-11 13:53:58 +10:00 committed by Amar Takhar
parent ea0777e4ee
commit b41203897a
9 changed files with 1112 additions and 1183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
networking/conf.py
View File

@ -3,10 +3,11 @@ sys.path.append(os.path.abspath('../common/'))
from conf import * from conf import *
version = '1.0' version = '4.11.0'
release = '5.0' release = '4.11.0'
project = "RTEMS Networking User Manual"
latex_documents = [ latex_documents = [
('index', 'networking.tex', u'RTEMS Networking Documentation', u'RTEMS Documentation Project', 'manual'), ('index', 'networking.tex', u'RTEMS Networking User Documentation', u'RTEMS Documentation Project', 'manual'),
] ]

172
networking/dec_21140.rst
View File

@ -6,20 +6,19 @@ DEC 21240 Driver Introduction
.. COMMENT: XXX add back in cross reference to list of boards. .. COMMENT: XXX add back in cross reference to list of boards.
One aim of our project is to port RTEMS on a standard PowerPC platform. One aim of our project is to port RTEMS on a standard PowerPC platform. To
To achieve it, we have chosen a Motorola MCP750 board. This board includes achieve it, we have chosen a Motorola MCP750 board. This board includes an
an Ethernet controller based on a DEC21140 chip. Because RTEMS has a Ethernet controller based on a DEC21140 chip. Because RTEMS has a TCP/IP stack,
TCP/IP stack, we will we will have to develop the DEC21140 related ethernet driver for the PowerPC
have to develop the DEC21140 related ethernet driver for the PowerPC port of port of RTEMS. As this controller is able to support 100Mbps network and as
RTEMS. As this controller is able to support 100Mbps network and as there is there is a lot of PCI card using this DEC chip, we have decided to first
a lot of PCI card using this DEC chip, we have decided to first
implement this driver on an Intel PC386 target to provide a solution for using implement this driver on an Intel PC386 target to provide a solution for using
RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in a
a second phase. second phase.
The aim of this document is to give some PCI board generalities and The aim of this document is to give some PCI board generalities and to explain
to explain the software architecture of the RTEMS driver. Finally, we will see the software architecture of the RTEMS driver. Finally, we will see what will
what will be done for ChorusOs and Netboot environment . be done for ChorusOs and Netboot environment .
Document Revision History Document Revision History
========================= =========================
@ -47,15 +46,15 @@ This chapter describes rapidely the PCI interface of this Ethernet controller.
The board we have chosen for our PC386 implementation is a D-Link DFE-500TX. The board we have chosen for our PC386 implementation is a D-Link DFE-500TX.
This is a dual-speed 10/100Mbps Ethernet PCI adapter with a DEC21140AF chip. This is a dual-speed 10/100Mbps Ethernet PCI adapter with a DEC21140AF chip.
Like other PCI devices, this board has a PCI device's header containing some Like other PCI devices, this board has a PCI device's header containing some
required configuration registers, as shown in the PCI Register Figure. required configuration registers, as shown in the PCI Register Figure. By
By reading reading or writing these registers, a driver can obtain information about the
or writing these registers, a driver can obtain information about the type of type of the board, the interrupt it uses, the mapping of the chip specific
the board, the interrupt it uses, the mapping of the chip specific registers, ... registers, ...
On Intel target, the chip specific registers can be accessed via 2 On Intel target, the chip specific registers can be accessed via 2 methods :
methods : I/O port access or PCI address mapped access. We have chosen to implement I/O port access or PCI address mapped access. We have chosen to implement the
the PCI address access to obtain compatible source code to the port the driver PCI address access to obtain compatible source code to the port the driver on a
on a PowerPC target. PowerPC target.
.. COMMENT: PCI Device's Configuration Header Space Format .. COMMENT: PCI Device's Configuration Header Space Format
@ -65,17 +64,16 @@ on a PowerPC target.
.. COMMENT: XXX add crossreference to PCI Register Figure .. COMMENT: XXX add crossreference to PCI Register Figure
On RTEMS, a PCI API exists. We have used it to configure the board. After initializing On RTEMS, a PCI API exists. We have used it to configure the board. After
this PCI module via the ``pci_initialize()`` function, we try to detect initializing this PCI module via the ``pci_initialize()`` function, we try to
the DEC21140 based ethernet board. This board is characterized by its Vendor detect the DEC21140 based ethernet board. This board is characterized by its
ID (0x1011) and its Device ID (0x0009). We give these arguments to the``pcib_find_by_deviceid`` Vendor ID (0x1011) and its Device ID (0x0009). We give these arguments to
function which returns , if the device is present, a pointer to the configuration the``pcib_find_by_deviceid`` function which returns , if the device is present,
header space (see PCI Registers Fgure). Once this operation performed, a pointer to the configuration header space (see PCI Registers Fgure). Once
the driver this operation performed, the driver is able to extract the information it
is able to extract the information it needs to configure the board internal needs to configure the board internal registers, like the interrupt line, the
registers, like the interrupt line, the base address,... The board internal base address,... The board internal registers will not be detailled here. You
registers will not be detailled here. You can find them in *DIGITAL can find them in *DIGITAL Semiconductor 21140A PCI Fast Ethernet LAN Controller
Semiconductor 21140A PCI Fast Ethernet LAN Controller
- Hardware Reference Manual*. - Hardware Reference Manual*.
.. COMMENT: fix citation .. COMMENT: fix citation
@ -89,16 +87,17 @@ host memory and the 2 threads launched at the initialization time.
Initialization phase Initialization phase
-------------------- --------------------
The DEC21140 Ethernet driver keeps the same software architecture than the other The DEC21140 Ethernet driver keeps the same software architecture than the
RTEMS ethernet drivers. The only API the programmer can use is the ``rtems_dec21140_driver_attach````(struct rtems_bsdnet_ifconfig \*config)`` function which other RTEMS ethernet drivers. The only API the programmer can use is the
detects the board and initializes the associated data structure (with registers ``rtems_dec21140_driver_attach(struct rtems_bsdnet_ifconfig *config)``
base address, entry points to low-level initialization function,...), if the function which detects the board and initializes the associated data structure
board is found. (with registers base address, entry points to low-level initialization
function,...), if the board is found.
Once the attach function executed, the driver initializes the DEC Once the attach function executed, the driver initializes the DEC chip. Then
chip. Then the driver connects an interrupt handler to the interrupt line driven the driver connects an interrupt handler to the interrupt line driven by the
by the Ethernet controller (the only interrupt which will be treated is the Ethernet controller (the only interrupt which will be treated is the receive
receive interrupt) and launches 2 threads : a receiver thread and a transmitter interrupt) and launches 2 threads : a receiver thread and a transmitter
thread. Then the driver waits for incoming frame to give to the protocol stack thread. Then the driver waits for incoming frame to give to the protocol stack
or outcoming frame to send on the physical link. or outcoming frame to send on the physical link.
@ -108,19 +107,18 @@ Memory Buffer
.. COMMENT: XXX add cross reference to Problem .. COMMENT: XXX add cross reference to Problem
This DEC chip uses the host memory to store the incoming Ethernet frames and This DEC chip uses the host memory to store the incoming Ethernet frames and
the descriptor of these frames. We have chosen to use 7 receive buffers and the descriptor of these frames. We have chosen to use 7 receive buffers and 1
1 transmit buffer to optimize memory allocation due to cache and paging problem transmit buffer to optimize memory allocation due to cache and paging problem
that will be explained in the section *Encountered Problems*. that will be explained in the section *Encountered Problems*.
To reference these buffers to the DEC chip we use a buffer descriptors To reference these buffers to the DEC chip we use a buffer descriptors
ring. The descriptor structure is defined in the Buffer Descriptor Figure. ring. The descriptor structure is defined in the Buffer Descriptor Figure.
Each descriptor Each descriptor can reference one or two memory buffers. We choose to use only
can reference one or two memory buffers. We choose to use only one buffer of one buffer of 1520 bytes per descriptor.
1520 bytes per descriptor.
The difference between a receive and a transmit buffer descriptor The difference between a receive and a transmit buffer descriptor is located in
is located in the status and control bits fields. We do not give details here, the status and control bits fields. We do not give details here, please refer
please refer to the \[DEC21140 Hardware Manual]. to the DEC21140 Hardware Manual.
.. COMMENT: Buffer Descriptor .. COMMENT: Buffer Descriptor
@ -132,12 +130,12 @@ Receiver Thread
--------------- ---------------
This thread is event driven. Each time a DEC PCI board interrupt occurs, the This thread is event driven. Each time a DEC PCI board interrupt occurs, the
handler checks if this is a receive interrupt and send an event "reception" handler checks if this is a receive interrupt and send an event "reception" to
to the receiver thread which looks into the entire buffer descriptors ring the the receiver thread which looks into the entire buffer descriptors ring the
ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs to
to host processor). Each valid incoming ethernet frame is sent to the protocol host processor). Each valid incoming ethernet frame is sent to the protocol
stack and the buffer descriptor is given back to the DEC board (the host processor stack and the buffer descriptor is given back to the DEC board (the host
reset bit OWN, which means descriptor belongs to 21140). processor reset bit OWN, which means descriptor belongs to 21140).
Transmitter Thread Transmitter Thread
------------------ ------------------
@ -151,47 +149,37 @@ Encountered Problems
==================== ====================
On Intel PC386 target, we were faced with a problem of memory cache management. On Intel PC386 target, we were faced with a problem of memory cache management.
Because the DEC chip uses the host memory to store the incoming frame and because Because the DEC chip uses the host memory to store the incoming frame and
the DEC21140 configuration registers are mapped into the PCI address space, because the DEC21140 configuration registers are mapped into the PCI address
we must ensure that the data read (or written) by the host processor are the space, we must ensure that the data read (or written) by the host processor are
ones written (or read) by the DEC21140 device in the host memory and not old the ones written (or read) by the DEC21140 device in the host memory and not
data stored in the cache memory. Therefore, we had to provide a way to manage old data stored in the cache memory. Therefore, we had to provide a way to
the cache. This module is described in the document *RTEMS manage the cache. This module is described in the document *RTEMS Cache
Cache Management For Intel*. On Intel, the Management For Intel*. On Intel, the memory region cache management is
memory region cache management is available only if the paging unit is enabled. available only if the paging unit is enabled. We have used this paging
We have used this paging mechanism, with 4Kb page. All the buffers allocated mechanism, with 4Kb page. All the buffers allocated to store the incoming or
to store the incoming or outcoming frames, buffer descriptor and also the PCI outcoming frames, buffer descriptor and also the PCI address space of the DEC
address space of the DEC board are located in a memory space with cache disable. board are located in a memory space with cache disable.
Concerning the buffers and their descriptors, we have tried to optimize Concerning the buffers and their descriptors, we have tried to optimize the
the memory space in term of allocated page. One buffer has 1520 bytes, one descriptor memory space in term of allocated page. One buffer has 1520 bytes, one
has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and for each, descriptor has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and
1 descriptor : (7+1)*(1520+16) = 12288 bytes = 12Kb = 3 entire pages. This for each, 1 descriptor : (7+1)*(1520+16) = 12288 bytes = 12Kb = 3 entire
allows not to lose too much memory or not to disable cache memory for a page pages. This allows not to lose too much memory or not to disable cache memory
which contains other data than buffer, which could decrease performance. for a page which contains other data than buffer, which could decrease
performance.
ChorusOs DEC Driver
===================
Because ChorusOs is used in several Canon CRF projects, we must provide such
a driver on this OS to ensure compatibility between the RTEMS and ChorusOs developments.
On ChorusOs, a DEC driver source code already exists but only for a PowerPC
target. We plan to port this code (which uses ChorusOs API) on Intel target.
This will allow us to have homogeneous developments. Moreover, the port of the
development performed with ChorusOs environment to RTEMS environment will be
easier for the developers.
Netboot DEC driver Netboot DEC driver
================== ==================
We use Netboot tool to load our development from a server to the target via We use Netboot tool to load our development from a server to the target via an
an ethernet network. Currently, this tool does not support the DEC board. We ethernet network. Currently, this tool does not support the DEC board. We plan
plan to port the DEC driver for the Netboot tool. to port the DEC driver for the Netboot tool.
But concerning the port of the DEC driver into Netboot, we are faced But concerning the port of the DEC driver into Netboot, we are faced with a
with a problem : in RTEMS environment, the DEC driver is interrupt or event problem: in RTEMS environment, the DEC driver is interrupt or event driven, in
driven, in Netboot environment, it must be used in polling mode. It means that Netboot environment, it must be used in polling mode. It means that we will
we will have to re-write some mechanisms of this driver. have to re-write some mechanisms of this driver.
List of Ethernet cards using the DEC chip List of Ethernet cards using the DEC chip
========================================= =========================================
@ -238,9 +226,7 @@ of adapters which support this driver :
Our DEC driver has not been tested with all these cards, only with the D-Link Our DEC driver has not been tested with all these cards, only with the D-Link
DFE500-TX. DFE500-TX.
- *[DEC21140 Hardware Manual] DIGITAL, *DIGITAL - DEC21140 Hardware Manual DIGITAL, DIGITAL Semiconductor 21140A PCI Fast
Semiconductor 21140A PCI Fast Ethernet LAN Controller - Hardware Ethernet LAN Controller - Hardware Reference Manual**.
Reference Manual**.
- *[99.TA.0021.M.ER]Emmanuel Raguet,*RTEMS Cache Management For Intel**. - *[99.TA.0021.M.ER]Emmanuel Raguet,*RTEMS Cache Management For Intel**.

55
networking/index.rst
View File

@ -1,36 +1,35 @@
======================== .. highlight:: c
RTEMS Network Supplement
========================
COPYRIGHT (c) 1988 - 2015.
On-Line Applications Research Corporation (OAR). ===================================
RTEMS |version| Network User Manual
===================================
The authors have used their best efforts in preparing | COPYRIGHT (c) 1988 - 2015.
this material. These efforts include the development, research, | On-Line Applications Research Corporation (OAR).
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 http://www.rtems.org. Any The authors have used their best efforts in preparing this material. These
inquiries concerning RTEMS, its related support components, or its efforts include the development, research, and testing of the theories and
documentation should be directed to the Community Project hosted athttp://www.rtems.org. 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.
Any inquiries for commercial services including training, support, custom The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning
development, application development assistance should be directed tohttp://www.rtems.com. RTEMS, its related support components, or its documentation should be directed
to the Community Project hosted at http://www.rtems.org/.
.. topic:: RTEMS Online Resources
Table of Contents ================ =============================
----------------- Home https://www.rtems.org/
Developers https://devel.rtems.org/
.. toctree:: Documentation https://docs.rtems.org/
Bug Reporting https://devel.rtems.org/query
preface Mailing Lists https://lists.rtems.org/
Git Repositories https://git.rtems.org/
================ =============================
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 3
@ -45,7 +44,5 @@ Table of Contents
dec_21140 dec_21140
command command
* :ref:`genindex` * :ref:`genindex`
* :ref:`search` * :ref:`search`

91
networking/network_servers.rst
View File

@ -1,16 +1,18 @@
.. COMMENT: RTEMS Remote Debugger Server Specifications
.. COMMENT: Written by: Emmanuel Raguet <raguet@crf.canon.fr>
Network Servers Network Servers
############### ###############
RTEMS FTP Daemon RTEMS FTP Daemon
================ ================
The RTEMS FTPD is a complete file transfer protocol (FTP) daemon The RTEMS FTPD is a complete file transfer protocol (FTP) daemon which can
which can store, retrieve, and manipulate files on the local store, retrieve, and manipulate files on the local filesystem. In addition,
filesystem. In addition, the RTEMS FTPD provides "hooks" the RTEMS FTPD provides "hooks" which are actions performed on received data.
which are actions performed on received data. Hooks are useful Hooks are useful in situations where a destination file is not necessarily
in situations where a destination file is not necessarily appropriate or in cases when a formal device driver has not yet been
appropriate or in cases when a formal device driver has not yet implemented.
been implemented.
This server was implemented and documented by Jake Janovetz This server was implemented and documented by Jake Janovetz
(janovetz@tempest.ece.uiuc.edu). (janovetz@tempest.ece.uiuc.edu).
@ -19,61 +21,63 @@ Configuration Parameters
------------------------ ------------------------
The configuration structure for FTPD is as follows: The configuration structure for FTPD is as follows:
.. code:: c
.. code-block:: c
struct rtems_ftpd_configuration struct rtems_ftpd_configuration
{ {
rtems_task_priority priority; /* FTPD task priority \*/ rtems_task_priority priority; /* FTPD task priority */
unsigned long max_hook_filesize; /* Maximum buffersize \*/ unsigned long max_hook_filesize; /* Maximum buffersize */
/* for hooks \*/ /* for hooks */
int port; /* Well-known port \*/ int port; /* Well-known port */
struct rtems_ftpd_hook \*hooks; /* List of hooks \*/ struct rtems_ftpd_hook *hooks; /* List of hooks */
}; };
The FTPD task priority is specified with ``priority``. Because The FTPD task priority is specified with ``priority``. Because hooks are not
hooks are not saved as files, the received data is placed in an saved as files, the received data is placed in an allocated buffer.
allocated buffer. ``max_hook_filesize`` specifies the maximum ``max_hook_filesize`` specifies the maximum size of this buffer. Finally,
size of this buffer. Finally, ``hooks`` is a pointer to the ``hooks`` is a pointer to the configured hooks structure.
configured hooks structure.
Initializing FTPD (Starting the daemon) Initializing FTPD (Starting the daemon)
--------------------------------------- ---------------------------------------
Starting FTPD is done with a call to ``rtems_initialize_ftpd()``. Starting FTPD is done with a call to ``rtems_initialize_ftpd()``. The
The configuration structure must be provided in the application configuration structure must be provided in the application source code.
source code. Example hooks structure and configuration structure Example hooks structure and configuration structure folllow.
folllow.
.. code:: c .. code-block:: c
struct rtems_ftpd_hook ftp_hooks[] = struct rtems_ftpd_hook ftp_hooks[] =
{ {
{"untar", Untar_FromMemory}, {"untar", Untar_FromMemory},
{NULL, NULL} {NULL, NULL}
};
struct rtems_ftpd_configuration rtems_ftpd_configuration =
{
40, /* FTPD task priority \*/
512*1024, /* Maximum hook 'file' size \*/
0, /* Use default port \*/
ftp_hooks /* Local ftp hooks \*/
}; };
Specifying 0 for the well-known port causes FTPD to use the struct rtems_ftpd_configuration rtems_ftpd_configuration =
UNIX standard FTPD port (21). {
40, /* FTPD task priority */
512*1024, /* Maximum hook 'file' size */
0, /* Use default port */
ftp_hooks /* Local ftp hooks */
};
Specifying 0 for the well-known port causes FTPD to use the UNIX standard FTPD
port (21).
Using Hooks Using Hooks
----------- -----------
In the example above, one hook was installed. The hook causes In the example above, one hook was installed. The hook causes FTPD to call the
FTPD to call the function ``Untar_FromMemory`` when the function ``Untar_FromMemory`` when the user sends data to the file ``untar``.
user sends data to the file ``untar``. The prototype for The prototype for the ``untar`` hook (and hooks, in general) is:
the ``untar`` hook (and hooks, in general) is:
.. code:: c
int Untar_FromMemory(unsigned char \*tar_buf, unsigned long size); .. code-block:: c
int Untar_FromMemory(unsigned char *tar_buf, unsigned long size);
An example FTP transcript which exercises this hook is: An example FTP transcript which exercises this hook is:
.. code:: c
.. code-block:: shell
220 RTEMS FTP server (Version 1.0-JWJ) ready. 220 RTEMS FTP server (Version 1.0-JWJ) ready.
Name (dcomm0:janovetz): John Galt Name (dcomm0:janovetz): John Galt
@ -102,8 +106,3 @@ An example FTP transcript which exercises this hook is:
226 Transfer complete. 226 Transfer complete.
ftp> quit ftp> quit
221 Goodbye. 221 Goodbye.
.. COMMENT: RTEMS Remote Debugger Server Specifications
.. COMMENT: Written by: Emmanuel Raguet <raguet@crf.canon.fr>

50
networking/network_task_structure.rst
View File

@ -1,38 +1,32 @@
.. COMMENT: Written by Eric Norum
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Network Task Structure and Data Flow Network Task Structure and Data Flow
#################################### ####################################
A schematic diagram of the tasks and message *mbuf* queues in a A schematic diagram of the tasks and message *mbuf* queues in a simple RTEMS
simple RTEMS networking application is shown in the following networking application is shown in the following figure:
figure:
.. image:: images/networkflow.jpg .. image:: images/networkflow.jpg
The transmit task for each network interface is normally blocked waiting The transmit task for each network interface is normally blocked waiting for a
for a packet to arrive in the transmit queue. Once a packet arrives, the packet to arrive in the transmit queue. Once a packet arrives, the transmit
transmit task may block waiting for an event from the transmit interrupt task may block waiting for an event from the transmit interrupt handler. The
handler. The transmit interrupt handler sends an RTEMS event to the transmit transmit interrupt handler sends an RTEMS event to the transmit task to
task to indicate that transmit hardware resources have become available. indicate that transmit hardware resources have become available.
The receive task for each network interface is normally blocked waiting The receive task for each network interface is normally blocked waiting for an
for an event from the receive interrupt handler. When this event is received event from the receive interrupt handler. When this event is received the
the receive task reads the packet and forwards it to the network stack receive task reads the packet and forwards it to the network stack for
for subsequent processing by the network task. subsequent processing by the network task.
The network task processes incoming packets and takes care of The network task processes incoming packets and takes care of timed operations
timed operations such as handling TCP timeouts and such as handling TCP timeouts and aging and removing routing table entries.
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.
.. COMMENT: Written by Eric Norum
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
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.

364
networking/networking_driver.rst
View File

@ -1,182 +1,177 @@
.. COMMENT: Written by Eric Norum
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Networking Driver Networking Driver
################# #################
Introduction Introduction
============ ============
This chapter is intended to provide an introduction to the This chapter is intended to provide an introduction to the procedure for
procedure for writing RTEMS network device drivers. writing RTEMS network device drivers. The example code is taken from the
The example code is taken from the 'Generic 68360' network device 'Generic 68360' network device driver. The source code for this driver is
driver. The source code for this driver is located in the``c/src/lib/libbsp/m68k/gen68360/network`` directory in the RTEMS located in the :file:`c/src/lib/libbsp/m68k/gen68360/network` directory in the
source code distribution. Having a copy of this driver at RTEMS source code distribution. Having a copy of this driver at hand when
hand when reading the following notes will help significantly. reading the following notes will help significantly.
Learn about the network device Learn about the network device
============================== ==============================
Before starting to write the network driver become completely Before starting to write the network driver become completely familiar with the
familiar with the programmer's view of the device. programmer's view of the device. The following points list some of the details
The following points list some of the details of the of the device that must be understood before a driver can be written.
device that must be understood before a driver can be written.
- Does the device use DMA to transfer packets to and from - Does the device use DMA to transfer packets to and from memory or does the
memory or does the processor have to processor have to copy packets to and from memory on the device?
copy packets to and from memory on the device?
- If the device uses DMA, is it capable of forming a single - If the device uses DMA, is it capable of forming a single outgoing packet
outgoing packet from multiple fragments scattered in separate from multiple fragments scattered in separate memory buffers?
memory buffers?
- If the device uses DMA, is it capable of chaining multiple - If the device uses DMA, is it capable of chaining multiple outgoing packets,
outgoing packets, or does each outgoing packet require or does each outgoing packet require intervention by the driver?
intervention by the driver?
- Does the device automatically pad short frames to the minimum - Does the device automatically pad short frames to the minimum 64 bytes or
64 bytes or does the driver have to supply the padding? does the driver have to supply the padding?
- Does the device automatically retry a transmission on detection - Does the device automatically retry a transmission on detection of a
of a collision? collision?
- If the device uses DMA, is it capable of buffering multiple - If the device uses DMA, is it capable of buffering multiple packets to
packets to memory, or does the receiver have to be restarted memory, or does the receiver have to be restarted after the arrival of each
after the arrival of each packet? packet?
- How are packets that are too short, too long, or received with - How are packets that are too short, too long, or received with CRC errors
CRC errors handled? Does the device automatically continue handled? Does the device automatically continue reception or does the driver
reception or does the driver have to intervene? have to intervene?
- How is the device Ethernet address set? How is the device - How is the device Ethernet address set? How is the device programmed to
programmed to accept or reject broadcast and multicast packets? accept or reject broadcast and multicast packets?
- What interrupts does the device generate? Does it generate an - What interrupts does the device generate? Does it generate an interrupt for
interrupt for each incoming packet, or only for packets received each incoming packet, or only for packets received without error? Does it
without error? Does it generate an interrupt for each packet generate an interrupt for each packet transmitted, or only when the transmit
transmitted, or only when the transmit queue is empty? What queue is empty? What happens when a transmit error is detected?
happens when a transmit error is detected?
In addition, some controllers have specific questions regarding In addition, some controllers have specific questions regarding board specific
board specific configuration. For example, the SONIC Ethernet configuration. For example, the SONIC Ethernet controller has a very
controller has a very configurable data bus interface. It can configurable data bus interface. It can even be configured for sixteen and
even be configured for sixteen and thirty-two bit data buses. This thirty-two bit data buses. This type of information should be obtained from
type of information should be obtained from the board vendor. the board vendor.
Understand the network scheduling conventions Understand the network scheduling conventions
============================================= =============================================
When writing code for the driver transmit and receive tasks, When writing code for the driver transmit and receive tasks, take care to
take care to follow the network scheduling conventions. All tasks follow the network scheduling conventions. All tasks which are associated with
which are associated with networking share various networking share various data structures and resources. To ensure the
data structures and resources. To ensure the consistency consistency of these structures the tasks execute only when they hold the
of these structures the tasks network semaphore (``rtems_bsdnet_semaphore``). The transmit and receive tasks
execute only when they hold the network semaphore (``rtems_bsdnet_semaphore``). must abide by this protocol. Be very careful to avoid 'deadly embraces' with
The transmit and receive tasks must abide by this protocol. Be very the other network tasks. A number of routines are provided to make it easier
careful to avoid 'deadly embraces' with the other network tasks. for the network driver code to conform to the network task scheduling
A number of routines are provided to make it easier for the network conventions.
driver code to conform to the network task scheduling conventions.
- ``void rtems_bsdnet_semaphore_release(void)`` - ``void rtems_bsdnet_semaphore_release(void)``
This function releases the network semaphore. This function releases the network semaphore. The network driver tasks must
The network driver tasks must call this function immediately before call this function immediately before making any blocking RTEMS request.
making any blocking RTEMS request.
- ``void rtems_bsdnet_semaphore_obtain(void)`` - ``void rtems_bsdnet_semaphore_obtain(void)``
This function obtains the network semaphore. This function obtains the network semaphore. If a network driver task has
If a network driver task has released the network semaphore to allow other released the network semaphore to allow other network-related tasks to run
network-related tasks to run while the task blocks, then this function must while the task blocks, then this function must be called to reobtain the
be called to reobtain the semaphore immediately after the return from the semaphore immediately after the return from the blocking RTEMS request.
blocking RTEMS request.
- ``rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set \*)`` - ``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 The network driver task should call this function when it wishes to wait for
for an event. This function releases the network semaphore, an event. This function releases the network semaphore, calls
calls ``rtems_event_receive`` to wait for the specified event ``rtems_event_receive`` to wait for the specified event or events and
or events and reobtains the semaphore. reobtains the semaphore. The value returned is the value returned by the
The value returned is the value returned by the ``rtems_event_receive``. ``rtems_event_receive``.
Network Driver Makefile Network Driver Makefile
======================= =======================
Network drivers are considered part of the BSD network package and as such Network drivers are considered part of the BSD network package and as such are
are to be compiled with the appropriate flags. This can be accomplished by to be compiled with the appropriate flags. This can be accomplished by adding
adding ``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``command line``. ``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``command line``. If the driver
If the driver is inside the RTEMS source tree or is built using the is inside the RTEMS source tree or is built using the RTEMS application
RTEMS application Makefiles, then adding the following line accomplishes Makefiles, then adding the following line accomplishes this:
this:
.. code:: c .. code-block:: c
DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__ DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__
This is equivalent to the following list of definitions. Early versions This is equivalent to the following list of definitions. Early versions of the
of the RTEMS BSD network stack required that all of these be defined. RTEMS BSD network stack required that all of these be defined.
.. code:: c .. code-block:: c
-D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \\ -D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \
-DDIAGNOSTIC -DBOOTP_COMPAT -DDIAGNOSTIC -DBOOTP_COMPAT
Defining these macros tells the network header files that the driver Defining these macros tells the network header files that the driver is to be
is to be compiled with extended visibility into the network stack. This compiled with extended visibility into the network stack. This is in sharp
is in sharp contrast to applications that simply use the network stack. contrast to applications that simply use the network stack. Applications do
Applications do not require this level of visibility and should stick not require this level of visibility and should stick to the portable
to the portable application level API. application level API.
As a direct result of being logically internal to the network stack, As a direct result of being logically internal to the network stack, network
network drivers use the BSD memory allocation routines This means, drivers use the BSD memory allocation routines This means, for example, that
for example, that malloc takes three arguments. See the SONIC malloc takes three arguments. See the SONIC device driver
device driver (``c/src/lib/libchip/network/sonic.c``) for an example (:file:`c/src/lib/libchip/network/sonic.c`) for an example of this. Because of
of this. Because of this, network drivers should not include``<stdlib.h>``. Doing so will result in conflicting definitions this, network drivers should not include ``<stdlib.h>``. Doing so will result
of ``malloc()``. in conflicting definitions of ``malloc()``.
*Application level* code including network servers such as the FTP *Application level* code including network servers such as the FTP daemon are
daemon are *not* part of the BSD kernel network code and should not be *not* part of the BSD kernel network code and should not be compiled with the
compiled with the BSD network flags. They should include``<stdlib.h>`` and not define the network stack visibility BSD network flags. They should include ``<stdlib.h>`` and not define the
macros. network stack visibility macros.
Write the Driver Attach Function Write the Driver Attach Function
================================ ================================
The driver attach function is responsible for configuring the driver The driver attach function is responsible for configuring the driver and making
and making the connection between the network stack the connection between the network stack and the driver.
and the driver.
Driver attach functions take a pointer to an``rtems_bsdnet_ifconfig`` structure as their only argument. Driver attach functions take a pointer to an ``rtems_bsdnet_ifconfig``
and set the driver parameters based on the structure as their only argument. and set the driver parameters based on the
values in this structure. If an entry in the configuration values in this structure. If an entry in the configuration structure is zero
structure is zero the attach function chooses an the attach function chooses an appropriate default value for that parameter.
appropriate default value for that parameter.
The driver should then set up several fields in the ifnet structure The driver should then set up several fields in the ifnet structure in the
in the device-dependent data structure supplied and maintained by the driver: device-dependent data structure supplied and maintained by the driver:
``ifp->if_softc`` ``ifp->if_softc``
Pointer to the device-dependent data. The first entry Pointer to the device-dependent data. The first entry in the
in the device-dependent data structure must be an ``arpcom`` device-dependent data structure must be an ``arpcom`` structure.
structure.
``ifp->if_name`` ``ifp->if_name``
The name of the device. The network stack uses this string The name of the device. The network stack uses this string and the device
and the device number for device name lookups. The device name should number for device name lookups. The device name should be obtained from
be obtained from the ``name`` entry in the configuration structure. the ``name`` entry in the configuration structure.
``ifp->if_unit`` ``ifp->if_unit``
The device number. The network stack uses this number and the The device number. The network stack uses this number and the device name
device name for device name lookups. For example, if``ifp->if_name`` is '``scc``' and ``ifp->if_unit`` is '``1``', for device name lookups. For example, if ``ifp->if_name`` is ``scc`` and
the full device name would be '``scc1``'. The unit number should be ``ifp->if_unit`` is ``1``, the full device name would be ``scc1``. The
obtained from the 'name' entry in the configuration structure. unit number should be obtained from the 'name' entry in the configuration
structure.
``ifp->if_mtu`` ``ifp->if_mtu``
The maximum transmission unit for the device. For Ethernet The maximum transmission unit for the device. For Ethernet devices this
devices this value should almost always be 1500. value should almost always be 1500.
``ifp->if_flags`` ``ifp->if_flags``
The device flags. Ethernet devices should set the flags The device flags. Ethernet devices should set the flags to
to ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the device can broadcast
device can broadcast packets to multiple destinations packets to multiple destinations and does not receive and transmit at the
and does not receive and transmit at the same time. same time.
``ifp->if_snd.ifq_maxlen`` ``ifp->if_snd.ifq_maxlen``
The maximum length of the queue of packets waiting to be The maximum length of the queue of packets waiting to be sent to the
sent to the driver. This is normally set to ``ifqmaxlen``. driver. This is normally set to ``ifqmaxlen``.
``ifp->if_init`` ``ifp->if_init``
The address of the driver initialization function. The address of the driver initialization function.
@ -188,91 +183,91 @@ in the device-dependent data structure supplied and maintained by the driver:
The address of the driver ioctl function. The address of the driver ioctl function.
``ifp->if_output`` ``ifp->if_output``
The address of the output function. Ethernet devices The address of the output function. Ethernet devices should set this to
should set this to ``ether_output``. ``ether_output``.
RTEMS provides a function to parse the driver name in the RTEMS provides a function to parse the driver name in the configuration
configuration structure into a device name and unit number. structure into a device name and unit number.
.. code:: c
.. code-block:: c
int rtems_bsdnet_parse_driver_name ( int rtems_bsdnet_parse_driver_name (
const struct rtems_bsdnet_ifconfig \*config, const struct rtems_bsdnet_ifconfig *config,
char \**namep char **namep
); );
The function takes two arguments; a pointer to the configuration The function takes two arguments; a pointer to the configuration structure and
structure and a pointer to a pointer to a character. The function a pointer to a pointer to a character. The function parses the configuration
parses the configuration name entry, allocates memory for the driver name entry, allocates memory for the driver name, places the driver name in
name, places the driver name in this memory, sets the second argument this memory, sets the second argument to point to the name and returns the unit
to point to the name and returns the unit number. number. On error, a message is printed and ``-1`` is returned.
On error, a message is printed and -1 is returned.
Once the attach function has set up the above entries it must link the Once the attach function has set up the above entries it must link the driver
driver data structure onto the list of devices by data structure onto the list of devices by calling ``if_attach``. Ethernet
calling ``if_attach``. Ethernet devices should then devices should then call ``ether_ifattach``. Both functions take a pointer to
call ``ether_ifattach``. Both functions take a pointer to the the device's ``ifnet`` structure as their only argument.
device's ``ifnet`` structure as their only argument.
The attach function should return a non-zero value to indicate that The attach function should return a non-zero value to indicate that the driver
the driver has been successfully configured and attached. has been successfully configured and attached.
Write the Driver Start Function. Write the Driver Start Function.
================================ ================================
This function is called each time the network stack wants to start the This function is called each time the network stack wants to start the
transmitter. This occures whenever the network stack adds a packet transmitter. This occures whenever the network stack adds a packet to a
to a device's send queue and the ``IFF_OACTIVE`` bit in the device's send queue and the ``IFF_OACTIVE`` bit in the device's ``if_flags`` is
device's ``if_flags`` is not set. 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 For many devices this function need only set the ``IFF_OACTIVE`` bit in the
indicating that a packet is in the driver transmit queue. ``if_flags`` and send an event to the transmit task indicating that a packet is
in the driver transmit queue.
Write the Driver Initialization Function. Write the Driver Initialization Function.
========================================= =========================================
This function should initialize the device, attach to interrupt handler, This function should initialize the device, attach to interrupt handler, and
and start the driver transmit and receive tasks. The function start the driver transmit and receive tasks. The function
.. code:: c
.. code-block:: c
rtems_id rtems_id
rtems_bsdnet_newproc (char \*name, rtems_bsdnet_newproc (char *name,
int stacksize, int stacksize,
void(\*entry)(void \*), void(*entry)(void *),
void \*arg); void *arg);
should be used to start the driver tasks. should be used to start the driver tasks.
Note that the network stack may call the driver initialization function more Note that the network stack may call the driver initialization function more
than once. than once. Make sure multiple versions of the receive and transmit tasks are
Make sure multiple versions of the receive and transmit tasks are not accidentally not accidentally started.
started.
Write the Driver Transmit Task 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 This task is reponsible for removing packets from the driver send queue and
driver start function indicating that packets are waiting to be transmitted. sending them to the device. The task should block waiting for an event from
When the transmit task has drained the driver send queue the task should clear the driver start function indicating that packets are waiting to be
the ``IFF_OACTIVE`` bit in ``if_flags`` and block until another outgoing transmitted. When the transmit task has drained the driver send queue the task
packet is queued. should clear the ``IFF_OACTIVE`` bit in ``if_flags`` and block until another
outgoing packet is queued.
Write the Driver Receive Task Write the Driver Receive Task
============================= =============================
This task should block until a packet arrives from the device. If the This task should block until a packet arrives from the device. If the device
device is an Ethernet interface the function ``ether_input`` should be called is an Ethernet interface the function ``ether_input`` should be called to
to forward the packet to the network stack. The arguments to ``ether_input`` forward the packet to the network stack. The arguments to ``ether_input`` are
are a pointer to the interface data structure, a pointer to the ethernet a pointer to the interface data structure, a pointer to the ethernet header and
header and a pointer to an mbuf containing the packet itself. a pointer to an mbuf containing the packet itself.
Write the Driver Interrupt Handler Write the Driver Interrupt Handler
================================== ==================================
A typical interrupt handler will do nothing more than the hardware A typical interrupt handler will do nothing more than the hardware manipulation
manipulation required to acknowledge the interrupt and send an RTEMS event required to acknowledge the interrupt and send an RTEMS event to wake up the
to wake up the driver receive or transmit task waiting for the event. driver receive or transmit task waiting for the event. Network interface
Network interface interrupt handlers must not make any calls to other interrupt handlers must not make any calls to other network routines.
network routines.
Write the Driver IOCTL Function Write the Driver IOCTL Function
=============================== ===============================
@ -283,43 +278,28 @@ commands which must be handled are:
``SIOCGIFADDR`` ``SIOCGIFADDR``
``SIOCSIFADDR`` ``SIOCSIFADDR``
If the device is an Ethernet interface these commands should be passed on
If the device is an Ethernet interface these to ``ether_ioctl``.
commands should be passed on to ``ether_ioctl``.
``SIOCSIFFLAGS`` ``SIOCSIFFLAGS``
This command should be used to start or stop the device, depending on the
This command should be used to start or stop the device, state of the interface ``IFF_UP`` and ``IFF_RUNNING`` bits in ``if_flags``:
depending on the state of the interface ``IFF_UP`` and``IFF_RUNNING`` bits in ``if_flags``:
``IFF_RUNNING`` ``IFF_RUNNING``
Stop the device. Stop the device.
``IFF_UP`` ``IFF_UP``
Start the device. Start the device.
``IFF_UP|IFF_RUNNING`` ``IFF_UP|IFF_RUNNING``
Stop then start the device. Stop then start the device.
``0`` ``0``
Do nothing. Do nothing.
Write the Driver Statistic-Printing Function Write the Driver Statistic-Printing Function
============================================ ============================================
This function should print the values of any statistic/diagnostic This function should print the values of any statistic/diagnostic counters the
counters the network driver may use. The driver ioctl function should call network driver may use. The driver ioctl function should call the
the statistic-printing function when the ioctl command is``SIO_RTEMS_SHOW_STATS``. statistic-printing function when the ioctl command is ``SIO_RTEMS_SHOW_STATS``.
.. COMMENT: Written by Eric Norum
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

49
networking/preface.rst
View File

@ -1,45 +1,38 @@
======= .. COMMENT: Written by Eric Norum
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Preface Preface
======= #######
This document describes the RTEMS specific parts of the FreeBSD TCP/IP This document describes the RTEMS specific parts of the FreeBSD TCP/IP stack.
stack. Much of this documentation was written by Eric Norum Much of this documentation was written by Eric Norum (eric@skatter.usask.ca) of
(eric@skatter.usask.ca) the Saskatchewan Accelerator Laboratory who also ported the FreeBSD TCP/IP
of the Saskatchewan Accelerator Laboratory stack to RTEMS.
who also ported the FreeBSD TCP/IP stack to RTEMS.
The following is a list of resources which should be useful in trying The following is a list of resources which should be useful in trying to
to understand Ethernet: understand Ethernet:
- *Charles Spurgeon's Ethernet Web Site* - *Charles Spurgeon's Ethernet Web Site*
"This site provides extensive information about Ethernet "This site provides extensive information about Ethernet (IEEE 802.3) local
(IEEE 802.3) local area network (LAN) technology. Including area network (LAN) technology. Including the original 10 Megabit per second
the original 10 Megabit per second (Mbps) system, the 100 Mbps (Mbps) system, the 100 Mbps Fast Ethernet system (802.3u), and the Gigabit
Fast Ethernet system (802.3u), and the Gigabit Ethernet system (802.3z)." Ethernet system (802.3z)." The URL is:
The URL is:
(http://www.ethermanage.com/ethernet/ethernet.html) (http://www.ethermanage.com/ethernet/ethernet.html)
- *TCP/IP Illustrated, Volume 1 : The Protocols* by - *TCP/IP Illustrated, Volume 1 : The Protocols*
by W. Richard Stevens (ISBN: 0201633469) by W. Richard Stevens (ISBN: 0201633469)
This book provides detailed introduction to TCP/IP and includes diagnostic This book provides detailed introduction to TCP/IP and includes diagnostic
programs which are publicly available. programs which are publicly available.
- *TCP/IP Illustrated, Volume 2 : The Implementation* by W. Richard - *TCP/IP Illustrated, Volume 2 : The Implementation*
Stevens and Gary Wright (ISBN: 020163354X) by W. Richard Stevens and Gary Wright (ISBN: 020163354X)
This book focuses on implementation issues regarding TCP/IP. The This book focuses on implementation issues regarding TCP/IP. The
treat for RTEMS users is that the implementation covered is the BSD treat for RTEMS users is that the implementation covered is the BSD
stack with most of the source code described in detail. stack with most of the source code described in detail.
- *UNIX Network Programming, Volume 1 : 2nd Edition* by W. Richard - *UNIX Network Programming, Volume 1 : 2nd Edition*
Stevens (ISBN: 0-13-490012-X) by W. Richard Stevens (ISBN: 0-13-490012-X)
This book describes how to write basic TCP/IP applications, again with primary This book describes how to write basic TCP/IP applications, again with primary
focus on the BSD stack. focus on the BSD stack.
.. COMMENT: Written by Eric Norum
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

283
networking/testing_the_driver.rst
View File

@ -1,3 +1,8 @@
.. COMMENT: Text Written by Jake Janovetz
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Testing the Driver Testing the Driver
################## ##################
@ -6,89 +11,84 @@ Preliminary Setup
The network used to test the driver should include at least: The network used to test the driver should include at least:
- The hardware on which the driver is to run. - The hardware on which the driver is to run. It makes testing much easier if
It makes testing much easier if you can run a debugger to control you can run a debugger to control the operation of the target machine.
the operation of the target machine.
- An Ethernet network analyzer or a workstation with an - An Ethernet network analyzer or a workstation with an 'Ethernet snoop'
'Ethernet snoop' program such as ``ethersnoop`` or``tcpdump``. program such as ``ethersnoop`` or ``tcpdump``.
- A workstation. - A workstation.
During early debug, you should consider putting the target, workstation, During early debug, you should consider putting the target, workstation, and
and snooper on a small network by themselves. This offers a few snooper on a small network by themselves. This offers a few advantages:
advantages:
- There is less traffic to look at on the snooper and for the target - There is less traffic to look at on the snooper and for the target to process
to process while bringing the driver up. while bringing the driver up.
- Any serious errors will impact only your small network not a building - Any serious errors will impact only your small network not a building or
or campus network. You want to avoid causing any unnecessary problems. campus network. You want to avoid causing any unnecessary problems.
- Test traffic is easier to repeatably generate. - Test traffic is easier to repeatably generate.
- Performance measurements are not impacted by other systems on - Performance measurements are not impacted by other systems on the network.
the network.
Debug Output Debug Output
============ ============
There are a number of sources of debug output that can be enabled There are a number of sources of debug output that can be enabled to aid in
to aid in tracing the behavior of the network stack. The following tracing the behavior of the network stack. The following is a list of them:
is a list of them:
- mbuf activity - mbuf activity
There are commented out calls to ``printf`` in the file``sys/mbuf.h`` in the network stack code. Uncommenting There are commented out calls to ``printf`` in the file ``sys/mbuf.h`` in the
these lines results in output when mbuf's are allocated network stack code. Uncommenting these lines results in output when mbuf's
and freed. This is very useful for finding memory leaks. are allocated and freed. This is very useful for finding memory leaks.
- TX and RX queuing - TX and RX queuing
There are commented out calls to ``printf`` in the file``net/if.h`` in the network stack code. Uncommenting There are commented out calls to ``printf`` in the file ``net/if.h`` in the
these lines results in output when packets are placed network stack code. Uncommenting these lines results in output when packets
on or removed from one of the transmit or receive packet are placed on or removed from one of the transmit or receive packet queues.
queues. These queues can be viewed as the boundary line These queues can be viewed as the boundary line between a device driver and
between a device driver and the network stack. If the the network stack. If the network stack is enqueuing packets to be
network stack is enqueuing packets to be transmitted that transmitted that the device driver is not dequeuing, then that is indicative
the device driver is not dequeuing, then that is indicative of a problem in the transmit side of the device driver. Conversely, if the
of a problem in the transmit side of the device driver. device driver is enqueueing packets as it receives them (via a call to
Conversely, if the device driver is enqueueing packets ``ether_input``) and they are not being dequeued by the network stack, then
as it receives them (via a call to ``ether_input``) and there is a problem. This situation would likely indicate that the network
they are not being dequeued by the network stack, server task is not running.
then there is a problem. This situation would likely indicate
that the network server task is not running.
- TCP state transitions - TCP state transitions
In the unlikely event that one would actually want to see
TCP state transitions, the ``TCPDEBUG`` macro can be defined In the unlikely event that one would actually want to see TCP state
in the file ``opt_tcpdebug.h``. This results in the routine``tcp_trace()`` being called by the network stack and transitions, the ``TCPDEBUG`` macro can be defined in the file
the state transitions logged into the ``tcp_debug`` data ``opt_tcpdebug.h``. This results in the routine ``tcp_trace()`` being called
structure. If the variable ``tcpconsdebug`` in the file``netinet/tcp_debug.c`` is set to 1, then the state transitions by the network stack and the state transitions logged into the ``tcp_debug``
will also be printed to the console. data structure. If the variable ``tcpconsdebug`` in the file
``netinet/tcp_debug.c`` is set to ``1``, then the state transitions will also
be printed to the console.
Monitor Commands Monitor Commands
================ ================
There are a number of command available in the shell / monitor There are a number of command available in the shell / monitor to aid in
to aid in tracing the behavior of the network stack. The following tracing the behavior of the network stack. The following is a list of them:
is a list of them:
- ``inet`` - ``inet``
This command shows the current routing information for the TCP/IP stack. Following is an This command shows the current routing information for the TCP/IP
example showing the output of this command. stack. Following is an example showing the output of this command.
.. code:: c .. code-block:: shell
Destination Gateway/Mask/Hw Flags Refs Use Expire Interface Destination Gateway/Mask/Hw Flags Refs Use Expire Interface
10.0.0.0 255.0.0.0 U 0 0 17 smc1 10.0.0.0 255.0.0.0 U 0 0 17 smc1
127.0.0.1 127.0.0.1 UH 0 0 0 lo0 127.0.0.1 127.0.0.1 UH 0 0 0 lo0
In this example, there is only one network interface with an IP address of 10.8.1.1. This In this example, there is only one network interface with an IP address of
link is currently not up. 10.8.1.1. This link is currently not up. Two routes that are shown are the
Two routes that are shown are the default routes for the Ethernet interface (10.0.0.0) and the default routes for the Ethernet interface (10.0.0.0) and the loopback
loopback interface (127.0.0.1). interface (127.0.0.1). Since the stack comes from BSD, this command is very
Since the stack comes from BSD, this command is very similar to the netstat command. For more similar to the netstat command. For more details on the network routing
details on the network routing please look the following please look the following URL:
URL: (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html) (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html)
For a quick reference to the flags, see the table below: For a quick reference to the flags, see the table below:
'``U``' '``U``'
@ -98,43 +98,44 @@ is a list of them:
Host: The route destination is a single host. Host: The route destination is a single host.
'``G``' '``G``'
Gateway: Send anything for this destination on to this remote system, which Gateway: Send anything for this destination on to this remote system,
will figure out from there where to send it. which will figure out from there where to send it.
'``S``' '``S``'
Static: This route was configured manually, not automatically generated by the Static: This route was configured manually, not automatically generated
system. by the system.
'``C``' '``C``'
Clone: Generates a new route based upon this route for machines we connect Clone: Generates a new route based upon this route for machines we
to. This type of route is normally used for local networks. connect to. This type of route is normally used for local networks.
'``W``' '``W``'
WasCloned: Indicated a route that was auto-configured based upon a local area WasCloned: Indicated a route that was auto-configured based upon a local
network (Clone) route. area network (Clone) route.
'``L``' '``L``'
Link: Route involves references to Ethernet hardware. Link: Route involves references to Ethernet hardware.
- ``mbuf`` - ``mbuf``
This command shows the current MBUF statistics. An example of the command is
shown below:
This command shows the current MBUF statistics. An example of the command is shown below: .. code-block:: shell
.. code:: c
************ MBUF STATISTICS \************ ************ MBUF STATISTICS \************
mbufs:4096 clusters: 256 free: 241 mbufs:4096 clusters: 256 free: 241
drops: 0 waits: 0 drains: 0 drops: 0 waits: 0 drains: 0
free:4080 data:16 header:0 socket:0 free:4080 data:16 header:0 socket:0
pcb:0 rtable:0 htable:0 atable:0 pcb:0 rtable:0 htable:0 atable:0
soname:0 soopts:0 ftable:0 rights:0 soname:0 soopts:0 ftable:0 rights:0
ifaddr:0 control:0 oobdata:0 ifaddr:0 control:0 oobdata:0
- ``if`` - ``if``
This command shows the current statistics for your Ethernet driver as long as
the ioctl hook ``SIO_RTEMS_SHOW_STATS`` has been implemented. Below is an
example:
This command shows the current statistics for your Ethernet driver as long as the ioctl hook``SIO_RTEMS_SHOW_STATS`` has been implemented. Below is an example: .. code-block:: shell
.. code:: c
************ INTERFACE STATISTICS \************ ************ INTERFACE STATISTICS \************
\***** smc1 \***** \***** smc1 \*****
@ -144,11 +145,11 @@ is a list of them:
Send queue limit:50 length:0 Dropped:0 Send queue limit:50 length:0 Dropped:0
SMC91C111 RTEMS driver A0.01 11/03/2002 Ian Caddy (ianc@microsol.iinet.net.au) SMC91C111 RTEMS driver A0.01 11/03/2002 Ian Caddy (ianc@microsol.iinet.net.au)
Rx Interrupts:0 Not First:0 Not Last:0 Rx Interrupts:0 Not First:0 Not Last:0
Giant:0 Runt:0 Non-octet:0 Giant:0 Runt:0 Non-octet:0
Bad CRC:0 Overrun:0 Collision:0 Bad CRC:0 Overrun:0 Collision:0
Tx Interrupts:2 Deferred:0 Missed Hearbeat:0 Tx Interrupts:2 Deferred:0 Missed Hearbeat:0
No Carrier:0 Retransmit Limit:0 Late Collision:0 No Carrier:0 Retransmit Limit:0 Late Collision:0
Underrun:0 Raw output wait:0 Coalesced:0 Underrun:0 Raw output wait:0 Coalesced:0
Coalesce failed:0 Retries:0 Coalesce failed:0 Retries:0
\***** lo0 \***** \***** lo0 \*****
Address:127.0.0.1 Net mask:255.0.0.0 Address:127.0.0.1 Net mask:255.0.0.0
@ -176,15 +177,12 @@ The network demonstration program ``netdemo`` may be used for these tests.
- Start with ``RTEMS_USE_BOOTP`` not defined. - Start with ``RTEMS_USE_BOOTP`` not defined.
- Edit ``networkconfig.h`` to configure the driver - Edit ``networkconfig.h`` to configure the driver with an explicit Ethernet
with an and Internet address and with reception of broadcast packets disabled: Verify
explicit Ethernet and Internet address and with reception of that the program continues to run once the driver has been attached.
broadcast packets disabled:
Verify that the program continues to run once the driver has been attached.
- Issue a '``u``' command to send UDP - Issue a '``u``' command to send UDP packets to the 'discard' port. Verify
packets to the 'discard' port. that the packets appear on the network.
Verify that the packets appear on the network.
- Issue a '``s``' command to print the network and driver statistics. - Issue a '``s``' command to print the network and driver statistics.
@ -193,124 +191,109 @@ The network demonstration program ``netdemo`` may be used for these tests.
- On that same workstation try to 'ping' the target system. - On that same workstation try to 'ping' the target system.
Verify that the ICMP echo request and reply packets appear on the net. Verify that the ICMP echo request and reply packets appear on the net.
- Remove the static route to the target system. - Remove the static route to the target system. Modify ``networkconfig.h`` to
Modify ``networkconfig.h`` to attach the driver attach the driver with reception of broadcast packets enabled. Try to 'ping'
with reception of broadcast packets enabled. the target system again. Verify that ARP request/reply and ICMP echo
Try to 'ping' the target system again. request/reply packets appear on the net.
Verify that ARP request/reply and ICMP echo request/reply packets appear
on the net.
- Issue a '``t``' command to send TCP - Issue a '``t``' command to send TCP packets to the 'discard' port. Verify
packets to the 'discard' port. that the packets appear on the network.
Verify that the packets appear on the network.
- Issue a '``s``' command to print the network and driver statistics. - Issue a '``s``' command to print the network and driver statistics.
- Verify that you can telnet to ports 24742 - Verify that you can telnet to ports 24742 and 24743 on the target system from
and 24743 on the target system from one or more one or more workstations on your network.
workstations on your network.
BOOTP/DHCP operation BOOTP/DHCP operation
==================== ====================
Set up a BOOTP/DHCP server on the network. Set up a BOOTP/DHCP server on the network. Set define ``RTEMS USE_BOOT`` in
Set define ``RTEMS USE_BOOT`` in ``networkconfig.h``. ``networkconfig.h``. Run the ``netdemo`` test program. Verify that the target
Run the ``netdemo`` test program. system configures itself from the BOOTP/DHCP server and that all the above
Verify that the target system configures itself from the BOOTP/DHCP server and tests succeed.
that all the above tests succeed.
Stress Tests Stress Tests
============ ============
Once the driver passes the tests described in the previous section it should Once the driver passes the tests described in the previous section it should be
be subjected to conditions which exercise it more subjected to conditions which exercise it more thoroughly and which test its
thoroughly and which test its error handling routines. error handling routines.
Giant packets Giant packets
------------- -------------
- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to - Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to a smaller value,
a smaller value, say 514. say 514.
- 'Ping' the driver from another workstation and verify - 'Ping' the driver from another workstation and verify that frames larger than
that frames larger than 514 bytes are correctly rejected. 514 bytes are correctly rejected.
- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` restored to 1518. - Recompile the driver with ``MAXIMUM_FRAME_SIZE`` restored to 1518.
Resource Exhaustion Resource Exhaustion
------------------- -------------------
- Edit ``networkconfig.h`` - Edit ``networkconfig.h`` so that the driver is configured with just two
so that the driver is configured with just two receive and transmit descriptors. receive and transmit descriptors.
- Compile and run the ``netdemo`` program. - Compile and run the ``netdemo`` program.
- Verify that the program operates properly and that you can - Verify that the program operates properly and that you can still telnet to
still telnet to both the ports. both the ports.
- Display the driver statistics (Console '``s``' command or telnet - Display the driver statistics (Console '``s``' command or telnet 'control-G'
'control-G' character) and verify that: character) and verify that:
# The number of transmit interrupts is non-zero. #. The number of transmit interrupts is non-zero. This indicates that all
This indicates that all transmit descriptors have been in use at some time. transmit descriptors have been in use at some time.
# The number of missed packets is non-zero. #. The number of missed packets is non-zero. This indicates that all receive
This indicates that all receive descriptors have been in use at some time. descriptors have been in use at some time.
Cable Faults Cable Faults
------------ ------------
- Run the ``netdemo`` program. - Run the ``netdemo`` program.
- Issue a '``u``' console command to make the target machine transmit - Issue a '``u``' console command to make the target machine transmit a bunch
a bunch of UDP packets. of UDP packets.
- While the packets are being transmitted, disconnect and reconnect the - While the packets are being transmitted, disconnect and reconnect the network
network cable. cable.
- Display the network statistics and verify that the driver has - Display the network statistics and verify that the driver has detected the
detected the loss of carrier. loss of carrier.
- Verify that you can still telnet to both ports on the target machine. - Verify that you can still telnet to both ports on the target machine.
Throughput Throughput
---------- ----------
Run the ``ttcp`` network benchmark program. Run the ``ttcp`` network benchmark program. Transfer large amounts of data
Transfer large amounts of data (100's of megabytes) to and from the target (100's of megabytes) to and from the target system.
system.
The procedure for testing throughput from a host to an RTEMS target The procedure for testing throughput from a host to an RTEMS target is as
is as follows: follows:
# Download and start the ttcp program on the Target. #. Download and start the ttcp program on the Target.
# In response to the ``ttcp`` prompt, enter ``-s -r``. The #. In response to the ``ttcp`` prompt, enter ``-s -r``. The meaning of these
meaning of these flags is described in the ``ttcp.1`` manual page flags is described in the ``ttcp.1`` manual page found in the ``ttcp_orig``
found in the ``ttcp_orig`` subdirectory. subdirectory.
# On the host run ``ttcp -s -t <<insert the hostname or IP address of the Target here>>`` #. On the host run ``ttcp -s -t <<insert the hostname or IP address of the Target here>>``
The procedure for testing throughput from an RTEMS target The procedure for testing throughput from an RTEMS target to a Host is as
to a Host is as follows: follows:
# On the host run ``ttcp -s -r``. #. On the host run ``ttcp -s -r``.
# Download and start the ttcp program on the Target. #. Download and start the ttcp program on the Target.
# In response to the ``ttcp`` prompt, enter ``-s -t <<insert the hostname or IP address of the Target here>>``. You need to type the #. In response to the ``ttcp`` prompt, enter ``-s -t <<insert the hostname or
IP address of the host unless your Target is talking to your Domain Name IP address of the Target here>>``. You need to type the IP address of the
Server. host unless your Target is talking to your Domain Name Server.
To change the number of buffers, the buffer size, etc. you just add the
extra flags to the ``-t`` machine as specified in the ``ttcp.1``
manual page found in the ``ttcp_orig`` subdirectory.
.. COMMENT: Text Written by Jake Janovetz
.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
To change the number of buffers, the buffer size, etc. you just add the extra
flags to the ``-t`` machine as specified in the ``ttcp.1`` manual page found in
the ``ttcp_orig`` subdirectory.

1222
networking/using_networking_rtems_app.rst
View File

File diff suppressed because it is too large Load Diff