diff options
authorJoel Sherrill <>1998-11-19 16:59:38 +0000
committerJoel Sherrill <>1998-11-19 16:59:38 +0000
commitfebb47e0710f5b77d2401ca520503c210429b6e1 (patch)
parent982e295e68493a2f26169f8e0b1111c539faabdd (diff)
Changed version string.
Added much new stuff to the POSIX User's Guide. New chapters stuff shrunk.
9 files changed, 447 insertions, 33 deletions
diff --git a/doc/Make.config b/doc/Make.config
index 2b7cab80b8..b694c59930 100644
--- a/doc/Make.config
+++ b/doc/Make.config
@@ -4,7 +4,7 @@
# $Id$
diff --git a/doc/bsp_howto/network.t b/doc/bsp_howto/network.t
index e69de29bb2..e7e5c4335b 100644
--- a/doc/bsp_howto/network.t
+++ b/doc/bsp_howto/network.t
@@ -0,0 +1,284 @@
+@c Written by Eric Norum
+@c COPYRIGHT (c) 1988-1998.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c $Id$
+@chapter Networking Driver
+@section 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
+@code{c/src/lib/libbsp/m68k/gen68360/network} directory in the RTEMS
+source code distribution. You should have a copy of this driver at
+hand when reading the following notes.
+@section Learn about the network device
+Before starting to write the network driver you need to be 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.
+@itemize @bullet
+@item 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?
+@item If the device uses DMA, is it capable of forming a single
+outtoing packet from multiple fragments scattered in separate
+memory buffers?
+@item If the device uses DMA, is it capable of chaining multiple
+outgoing packets, or does each outgoing packet require
+intervention by the driver?
+@item Does the device automatically pad short frames to the minimum
+64 bytes or does the driver have to supply the padding?
+@item Does the device automatically retry a transmission on detection
+of a collision?
+@item 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?
+@item 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?
+@item How is the device Ethernet address set? How is the device
+programmed to accept or reject broadcast and multicast packets?
+@item 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?
+@end itemize
+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.
+@section Understand the network scheduling conventions
+When writing code for your driver transmit and receive tasks you must
+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 (@code{rtems_bsdnet_semaphore}).
+Your transmit and receive tasks must abide by this protocol which means you must
+be careful to avoid `deadly embraces' with the other network tasks.
+A number of routines are provided to make it easier for your code
+to conform to the network task scheduling conventions.
+@itemize @bullet
+@item @code{void rtems_bsdnet_semaphore_release(void)}
+This function releases the network semaphore.
+Your task must call this function immediately before
+making any blocking RTEMS request.
+@item @code{void rtems_bsdnet_semaphore_obtain(void)}
+This function obtains the network semaphore.
+If your task has released the network semaphore to allow other
+network-related tasks to run while your task blocks you must call this
+function to reobtain the semaphore immediately after the return from the
+blocking RTEMS request.
+@item @code{rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set *)}
+Your task should call this function when it wishes to wait for an event.
+This function releases the network semaphore,
+calls @code{rtems_event_receive} to wait for the specified event
+or events and reobtains the semaphore.
+The value returned is the value returned by the @code{rtems_event_receive}.
+@end itemize
+@section Write your 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
+@code{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:
+@table @code
+@item ifp->if_softc
+Pointer to the device-dependent data. The first entry
+in the device-dependent data structure must be an @code{arpcom}
+@item ifp->if_name
+The name of the device. The network stack uses this string
+and the device number for device name lookups. The name should not
+contain digits as these will be assumed to be part of the unit number
+and not part of the device name.
+@item ifp->if_unit
+The device number. The network stack uses this number and the
+device name for device name lookups. For example, if
+@code{ifp->if_name} is @samp{scc}, and @code{ifp->if_unit} is @samp{1},
+the full device name would be @samp{scc1}.
+@item ifp->if_mtu
+The maximum transmission unit for the device. For Ethernet
+devices this value should almost always be 1500.
+@item ifp->if_flags
+The device flags. Ethernet devices should set the flags
+to @code{IFF_BROADCAST|IFF_SIMPLEX}, indicating that the
+device can broadcast packets to multiple destinations
+and does not receive and transmit at the same time.
+@item ifp->if_snd.ifq_maxlen
+The maximum length of the queue of packets waiting to be
+sent to the driver. This is normally set to @code{ifqmaxlen}.
+@item ifp->if_init
+The address of the driver initialization function.
+@item ifp->if_start
+The address of the driver start function.
+@item ifp->if_ioctl
+The address of the driver ioctl function.
+@item ifp->if_output
+The address of the output function. Ethernet devices
+should set this to @code{ether_output}.
+@end table
+Once the attach function has set up the above entries it must link the
+driver data structure onto the list of devices by
+calling @code{if_attach}. Ethernet devices should then
+call @code{ether_ifattach}. Both functions take a pointer to the
+device's @code{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.
+@section Write your 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 @code{IFF_OACTIVE} bit in the
+device's @code{if_flags} is not set.
+For many devices this function need only set the @code{IFF_OACTIVE} bit in the
+@code{if_flags} and send an event to the transmit task
+indicating that a packet is in the driver transmit queue.
+@section Write your driver initialization function.
+This function should initialize the device, attach to interrupt handler,
+and start the driver transmit and receive tasks. The function
+rtems_bsdnet_newproc (char *name,
+ int stacksize,
+ void(*entry)(void *),
+ void *arg);
+@end example
+should be used to start the driver tasks.
+Note that the network stack may call the driver initialization function more
+than once.
+Make sure you don't start multiple versions of the receive and transmit tasks.
+@section Write your 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 @code{IFF_OACTIVE} bit in @code{if_flags} and block until another outgoing
+packet is queued.
+@section Write your driver receive task.
+This task should block until a packet arrives from the device. If the
+device is an Ethernet interface the function @code{ether_input} should be called
+to forward the packet to the network stack. The arguments to @code{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.
+@section Write your 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.
+@section Write your driver ioctl function.
+This function handles ioctl requests directed at the device. The ioctl
+commands which must be handled are:
+@table @code
+If the device is an Ethernet interface these
+commands should be passed on to @code{ether_ioctl}.
+This command should be used to start or stop the device,
+depending on the state of the interface @code{IFF_UP} and
+@code{IFF_RUNNING} bits in @code{if_flags}:
+@table @code
+Stop the device.
+@item IFF_UP
+Start the device.
+Stop then start the device.
+@item 0
+Do nothing.
+@end table
+@end table
+@section Write Your Driver Statistic-Printing Function
+This function should print the values of any statistic/diagnostic
+counters your driver may use. The driver ioctl function should call
+the statistic-printing function when the ioctl command is
diff --git a/doc/common/setup.texi b/doc/common/setup.texi
index 8578a86ece..7e66f015f9 100644
--- a/doc/common/setup.texi
+++ b/doc/common/setup.texi
@@ -10,11 +10,11 @@
@c Set Variables
-@set RTEMS-RELEASE 4.0.0
-@set RTEMS-EDITION 4.0.0
-@set RTEMS-VERSION 4.0.0
-@set RTEMS-UPDATE-DATE October 27 1998
-@set RTEMS-UPDATE-MONTH October 1998
+@set RTEMS-RELEASE 19981119
+@set RTEMS-EDITION 19981119
+@set RTEMS-VERSION 19981119
+@set RTEMS-UPDATE-DATE November 19 1998
+@set RTEMS-UPDATE-MONTH November 1998
@c The following determines which set of the tables and figures we will use.
diff --git a/doc/do_docs b/doc/do_docs
index 548f8647a9..418454608b 100755
--- a/doc/do_docs
+++ b/doc/do_docs
@@ -13,10 +13,10 @@ supplements="supplements/hppa1_1 supplements/i386 \
# Division by access level
public_docs="user develenv networking posix_users started started_ada"
+support_docs="${supplements} bsp_howto"
partners_docs="posix1003.1 posix1003.1h"
oar_manuals="ada_user hwapi tools/texi2www \
- browseable_rtems posix_users_new bsp_howto"
+ browseable_rtems new_chapters"
# relnotes is obsolete
# posix_users manual left out until finished
diff --git a/doc/networking/Makefile b/doc/networking/Makefile
index 6f36ead921..c821c8425e 100644
--- a/doc/networking/Makefile
+++ b/doc/networking/Makefile
@@ -49,7 +49,7 @@ $(PROJECT).dvi: $(FILES)
networktasks.texi: networktasks.t Makefile
$(BMENU) -p "Preface" \
-u "Top" \
- -n "Writing RTEMS Network Device Drivers" ${*}.t
+ -n "Networking Driver" ${*}.t
driver.texi: driver.t Makefile
$(BMENU) -p "Network Task Structure and Data Flow" \
diff --git a/doc/networking/networking.texi b/doc/networking/networking.texi
index cefac1b00d..7378b779f7 100644
--- a/doc/networking/networking.texi
+++ b/doc/networking/networking.texi
@@ -76,7 +76,7 @@ This is the online version of the RTEMS Network Supplement.
* Preface::
* Network Task Structure and Data Flow::
-* Writing RTEMS Network Device Drivers::
+* Networking Driver::
* Using Networking in an RTEMS Application::
* Testing the Driver::
* Command and Variable Index::
diff --git a/doc/posix_users/Makefile b/doc/posix_users/Makefile
index fe57b61ea4..78e953b497 100644
--- a/doc/posix_users/Makefile
+++ b/doc/posix_users/Makefile
@@ -6,7 +6,7 @@
# $Id$
include ../Make.config
@@ -18,17 +18,24 @@ dirs:
-FILES= clock.texi cond.texi key.texi mutex.texi $(PROJECT).texi preface.texi \
- sched.texi signal.texi thread.texi $(COMMON_FILES)
+ cancel.texi clock.texi cond.texi \
+ cspecific.texi device.texi files.texi \
+ io.texi key.texi memorymgmt.texi message.texi mutex.texi procenv.texi \
+ process.texi sched.texi semaphores.texi signal.texi systemdb.texi \
+ thread.texi
+FILES= posix_users.texi preface.texi \
-info: dirs $(PROJECT)
+info: dirs $(FILES) $(PROJECT)
-posix_users: $(FILES)
+ $(MAKEINFO) posix_users.texi
dvi: $(PROJECT).dvi
ps: dirs $(PROJECT).ps
@@ -38,17 +45,107 @@ $(PROJECT).ps: $(PROJECT).dvi
$(PROJECT).dvi: $(FILES)
- $(TEXI2DVI) $(PROJECT).texi
+ $(TEXI2DVI) posix_users.texi
+ mv posix_users.dvi $(PROJECT).dvi
-html: dirs
+html: dirs $(FILES)
-mkdir -p $(WWW_INSTALL)/$(PROJECT)
-cd .. ; gmake headers
- $(PROJECT).texi
+ posix_users.texi
rm -f *.o $(PROG) *.txt core *.html
rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
- rm -f $(PROJECT) $(PROJECT)-* _*
+process.texi: process.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+procenv.texi: procenv.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+files.texi: files.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+thread.texi: thread.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+signal.texi: signal.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+mutex.texi: mutex.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+cond.texi: cond.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+key.texi: key.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+clock.texi: clock.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+sched.texi: sched.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+io.texi: io.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+device.texi: device.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+cspecific.texi: cspecific.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+semaphores.texi: semaphores.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+memorymgmt.texi: memorymgmt.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+message.texi: message.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+cancel.texi: cancel.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
+systemdb.texi: systemdb.t Makefile
+ $(BMENU) -p "" \
+ -u "Top" \
+ -n "" ${*}.t
diff --git a/doc/posix_users/posix_users.texi b/doc/posix_users/posix_users.texi
index 7686b2cb40..1d2485cef0 100644
--- a/doc/posix_users/posix_users.texi
+++ b/doc/posix_users/posix_users.texi
@@ -1,6 +1,6 @@
\input ../texinfo/texinfo @c -*-texinfo-*-
@c %**start of header
-@setfilename posix_users
+@setfilename posix_users_new
@syncodeindex vr fn
@synindex ky cp
@paragraphindent 0
@@ -39,7 +39,16 @@ END-INFO-DIR-ENTRY
@c variable substitution info:
-@c @set LANGUAGE C
+@c Note: At the moment we do not document the Ada interface but by building
+@c in the infrastructure Florist support should be simple to add.
+@set is-C
+@clear is-Ada
+@set STRUCTURE structure
+@set ROUTINE function
+@set OR |
+@set DIRPREFIX rtems_
@c the language is @value{LANGUAGE}
@c NOTE: don't use underscore in the name
@@ -76,28 +85,50 @@ END-INFO-DIR-ENTRY
@c The alternative is to rework a sentence to avoid this problem.
@include preface.texi
-@include thread.texi
+@include process.texi
@include signal.texi
+@include procenv.texi
+@include files.texi
+@include io.texi
+@include device.texi
+@include cspecific.texi
+@include systemdb.texi
+@include semaphores.texi
@include mutex.texi
@include cond.texi
-@include key.texi
-@include clock.texi
+@include memorymgmt.texi
@include sched.texi
+@include clock.texi
+@include message.texi
+@include thread.texi
+@include key.texi
+@include cancel.texi
@node Top, Preface, (dir), (dir)
-@top posix_users
+@top posix_users_new
This is the online version of the RTEMS POSIX API User's Guide
* Preface::
-* Thread Manager::
+* Process Creation and Execution Manager::
* Signal Manager::
+* Process Environment Manager::
+* Files and Directories Manager::
+* Input and Output Primitives Manager::
+* Device- and Class- Specific Functions Manager::
+* Language-Specific Services for the C Programming Language Manager::
+* System Databases Manager::
+* Semaphores Manager::
* Mutex Manager::
* Condition Variable Manager::
-* Key Manager::
-* Clock Manager::
+* Memory Management Manager::
* Scheduler Manager::
+* Clock Manager::
+* Message Passing Manager::
+* Thread Manager::
+* Key Manager::
+* Thread Cancellation Manager::
* Command and Variable Index::
* Concept Index::
@end menu
@@ -108,7 +139,7 @@ This is the online version of the RTEMS POSIX API User's Guide
@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
-@node Command and Variable Index, Concept Index, sched_yield, Top
+@node Command and Variable Index, Concept Index, , Top
@unnumbered Command and Variable Index
There are currently no Command and Variable Index entries.
diff --git a/doc/rtems_support.html b/doc/rtems_support.html
index 9318a3c506..ac2999e123 100644
--- a/doc/rtems_support.html
+++ b/doc/rtems_support.html
@@ -19,6 +19,8 @@
RTEMS POSIX API User's Guide</A>
<LI><A HREF="networking/index.html">
RTEMS Network Supplement</A>
+ <LI><A HREF="bsp_howto/index.html">
+ RTEMS BSP and Device Driver Development Guide</A>
<LI>CPU Supplements