Changeset febb47e in rtems

Timestamp:

11/19/98 16:59:38 (25 years ago)

Author:

Joel Sherrill <joel.sherrill@…>

Branches:

4.10, 4.11, 4.8, 4.9, 5, master

Children:

df4eb76e

Parents:

982e295e

Message:

Changed version string.

Added much new stuff to the POSIX User's Guide.

New chapters stuff shrunk.

Location:

doc

Files:

• Make.config (modified) (1 diff)
• bsp_howto/network.t (modified) (1 diff)
• common/setup.texi (modified) (1 diff)
• do_docs (modified) (1 diff)
• networking/Makefile (modified) (1 diff)
• networking/networking.texi (modified) (1 diff)
• posix_users/Makefile (modified) (3 diffs)
• posix_users/posix_users.texi (modified) (5 diffs)
• rtems_support.html (modified) (1 diff)

doc/Make.config

@@ -5 +5 @@
 #
 
-RTEMS_VERSION=4.0.0
+RTEMS_VERSION=19981119
 DOC_INSTALL_BASE=/usr1/tmp/rtemsdoc-$(RTEMS_VERSION)
 

doc/bsp_howto/network.t

@@ +1 @@
+@c
+@c  Written by Eric Norum
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@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}
+structure.
+
+@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
+
+@example
+rtems_id
+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
+@item SIOCGIFADDR
+@item SIOCSIFADDR
+If the device is an Ethernet interface these
+commands should be passed on to @code{ether_ioctl}.
+
+@item SIOCSIFFLAGS
+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
+@item IFF_RUNNING
+Stop the device.
+
+@item IFF_UP
+Start the device.
+
+@item IFF_UP|IFF_RUNNING
+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
+@code{SIO_RTEMS_SHOW_STATS}.
+
+

doc/common/setup.texi

@@ -11 +11 @@
 @c
 
-@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

doc/do_docs

@@ -14 +14 @@
 # Division by access level
 public_docs="user develenv networking posix_users started started_ada"
-support_docs="${supplements}"
+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

doc/networking/Makefile

@@ -50 +50 @@
         $(BMENU) -p "Preface" \
            -u "Top" \
-           -n "Writing RTEMS Network Device Drivers" ${*}.t
+           -n "Networking Driver" ${*}.t
 
 driver.texi: driver.t Makefile

doc/networking/networking.texi

@@ -77 +77 @@
 * Preface::
 * Network Task Structure and Data Flow::
-* Writing RTEMS Network Device Drivers::
+* Networking Driver::
 * Using Networking in an RTEMS Application::
 * Testing the Driver::

doc/posix_users/Makefile

@@ -7 +7 @@
 #
 
-PROJECT=posix_users
+PROJECT=posix_users_new
 DISTRIBUTION_LEVEL=public
 
@@ -19 +19 @@
 COMMON_FILES=../common/cpright.texi
 
-FILES= clock.texi cond.texi key.texi mutex.texi $(PROJECT).texi preface.texi \
-  sched.texi signal.texi thread.texi $(COMMON_FILES)
+GENERATED_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 \
+  $(COMMON_FILES) $(GENERATED_FILES)
 
 INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*)
 
-info: dirs $(PROJECT)
-        cp $(PROJECT) $(PROJECT)-* $(INFO_INSTALL)
-        #cp $(PROJECT) $(INFO_INSTALL)
+info: dirs $(FILES) $(PROJECT)
+#       cp $(PROJECT) $(PROJECT)-* $(INFO_INSTALL)
+        cp $(PROJECT) $(INFO_INSTALL)
 
-posix_users: $(FILES)
-        $(MAKEINFO) $(PROJECT).texi
+$(PROJECT): $(FILES)
+        $(MAKEINFO) posix_users.texi
 
 dvi: $(PROJECT).dvi
@@ -39 +46 @@
 
 $(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
         $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
-            $(PROJECT).texi
-
+            posix_users.texi
 
 clean:
         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)-* _*
+        rm -f $(PROJECT) $(PROJECT)-* _* $(GENERATED_FILES)
 
+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
+

doc/posix_users/posix_users.texi

@@ -1 +1 @@
 \input ../texinfo/texinfo   @c -*-texinfo-*-
 @c %**start of header
-@setfilename posix_users
+@setfilename posix_users_new
 @syncodeindex vr fn
 @synindex ky cp
@@ -40 +40 @@
 @c variable substitution info:
 @c
-@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 LANGUAGE C 
+@set STRUCTURE structure
+@set ROUTINE function
+@set OR |
+@set RPREFIX RTEMS_
+@set DIRPREFIX rtems_
 @c the language is @value{LANGUAGE}
 @c NOTE:  don't use underscore in the name
@@ -77 +86 @@
 
 @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 memorymgmt.texi
+@include sched.texi
+@include clock.texi
+@include message.texi
+@include thread.texi
 @include key.texi
-@include clock.texi
-@include sched.texi
+@include cancel.texi
 @ifinfo
 @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
@@ -92 +112 @@
 @menu
 * 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::
+* Memory Management Manager::
+* Scheduler Manager::
+* Clock Manager::
+* Message Passing Manager::
+* Thread Manager::
 * Key Manager::
-* Clock Manager::
-* Scheduler Manager::
+* Thread Cancellation Manager::
 * Command and Variable Index::
 * Concept Index::
@@ -109 +140 @@
 @c
 
-@node Command and Variable Index, Concept Index, sched_yield, Top
+@node Command and Variable Index, Concept Index, , Top
 @unnumbered Command and Variable Index
 

doc/rtems_support.html

@@ -20 +20 @@
     <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