Changeset febb47e in rtems


Ignore:
Timestamp:
Nov 19, 1998, 4:59:38 PM (21 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 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:
9 edited

Legend:

Unmodified
Added
Removed
  • doc/Make.config

    r982e295e rfebb47e  
    55#
    66
    7 RTEMS_VERSION=4.0.0
     7RTEMS_VERSION=19981119
    88DOC_INSTALL_BASE=/usr1/tmp/rtemsdoc-$(RTEMS_VERSION)
    99
  • doc/bsp_howto/network.t

    r982e295e rfebb47e  
     1@c
     2@c  Written by Eric Norum
     3@c
     4@c  COPYRIGHT (c) 1988-1998.
     5@c  On-Line Applications Research Corporation (OAR).
     6@c  All rights reserved.
     7@c
     8@c  $Id$
     9@c
     10
     11@chapter Networking Driver
     12
     13@section Introduction
     14
     15This chapter is intended to provide an introduction to the
     16procedure for writing RTEMS network device drivers.
     17The example code is taken from the `Generic 68360' network device
     18driver.  The source code for this driver is located in the
     19@code{c/src/lib/libbsp/m68k/gen68360/network} directory in the RTEMS
     20source code distribution.  You should have a copy of this driver at
     21hand when reading the following notes.
     22
     23@section Learn about the network device
     24
     25Before starting to write the network driver you need to be completely
     26familiar with the programmer's view of the device.
     27The following points list some of the details of the
     28device that must be understood before a driver can be written.
     29
     30@itemize @bullet
     31
     32@item Does the device use DMA to transfer packets to and from
     33memory or does the processor have to
     34copy packets to and from memory on the device?
     35
     36@item If the device uses DMA, is it capable of forming a single
     37outtoing packet from multiple fragments scattered in separate
     38memory buffers?
     39
     40@item If the device uses DMA, is it capable of chaining multiple
     41outgoing packets, or does each outgoing packet require
     42intervention by the driver?
     43
     44@item Does the device automatically pad short frames to the minimum
     4564 bytes or does the driver have to supply the padding?
     46
     47@item Does the device automatically retry a transmission on detection
     48of a collision?
     49
     50@item If the device uses DMA, is it capable of buffering multiple
     51packets to memory, or does the receiver have to be restarted
     52after the arrival of each packet?
     53
     54@item How are packets that are too short, too long, or received with
     55CRC errors handled?  Does the device automatically continue
     56reception or does the driver have to intervene?
     57
     58@item How is the device Ethernet address set?  How is the device
     59programmed to accept or reject broadcast and multicast packets?
     60
     61@item What interrupts does the device generate?  Does it generate an
     62interrupt for each incoming packet, or only for packets received
     63without error?  Does it generate an interrupt for each packet
     64transmitted, or only when the transmit queue is empty?  What
     65happens when a transmit error is detected?
     66
     67@end itemize
     68
     69In addition, some controllers have specific questions regarding
     70board specific configuration.  For example, the SONIC Ethernet
     71controller has a very configurable data bus interface.  It can
     72even be configured for sixteen and thirty-two bit data buses.  This
     73type of information should be obtained from the board vendor.
     74
     75@section Understand the network scheduling conventions
     76
     77When writing code for your driver transmit and receive tasks you must
     78take care to follow the network scheduling conventions.  All tasks
     79which are associated with networking share various
     80data structures and resources.  To ensure the consistency
     81of these structures the tasks
     82execute only when they hold the network semaphore (@code{rtems_bsdnet_semaphore}).
     83Your transmit and receive tasks must abide by this protocol which means you must
     84be careful to avoid `deadly embraces' with the other network tasks.
     85A number of routines are provided to make it easier for your code
     86to conform to the network task scheduling conventions.
     87
     88@itemize @bullet
     89
     90@item @code{void rtems_bsdnet_semaphore_release(void)}
     91
     92This function releases the network semaphore.
     93Your task must call this function immediately before
     94making any blocking RTEMS request.
     95
     96@item @code{void rtems_bsdnet_semaphore_obtain(void)}
     97
     98This function obtains the network semaphore.
     99If your task has released the network semaphore to allow other
     100network-related tasks to run while your task blocks you must call this
     101function to reobtain the semaphore immediately after the return from the
     102blocking RTEMS request.
     103
     104@item @code{rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set *)}
     105Your task should call this function when it wishes to wait for an event.
     106This function releases the network semaphore,
     107calls @code{rtems_event_receive} to wait for the specified event
     108or events and reobtains the semaphore.
     109The value returned is the value returned by the @code{rtems_event_receive}.
     110
     111@end itemize
     112
     113@section Write your driver attach function
     114The driver attach function is responsible for configuring the driver
     115and making the connection between the network stack
     116and the driver.
     117
     118Driver attach functions take a pointer to an
     119@code{rtems_bsdnet_ifconfig} structure as their only argument.
     120and set the driver parameters based on the
     121values in this structure.  If an entry in the configuration
     122structure is zero the attach function chooses an
     123appropriate default value for that parameter.
     124
     125
     126The driver should then set up several fields in the ifnet structure
     127in the device-dependent data structure supplied and maintained by the driver:
     128
     129@table @code
     130@item ifp->if_softc
     131Pointer to the device-dependent data.  The first entry
     132in the device-dependent data structure must be an @code{arpcom}
     133structure.
     134
     135@item ifp->if_name
     136The name of the device.  The network stack uses this string
     137and the device number for device name lookups.  The name should not
     138contain digits as these will be assumed to be part of the unit number
     139and not part of the device name.
     140
     141
     142@item ifp->if_unit
     143The device number.  The network stack uses this number and the
     144device name for device name lookups.  For example, if
     145@code{ifp->if_name} is @samp{scc}, and @code{ifp->if_unit} is @samp{1},
     146the full device name would be @samp{scc1}.
     147
     148@item ifp->if_mtu
     149The maximum transmission unit for the device.  For Ethernet
     150devices this value should almost always be 1500.
     151
     152@item ifp->if_flags
     153The device flags.  Ethernet devices should set the flags
     154to @code{IFF_BROADCAST|IFF_SIMPLEX}, indicating that the
     155device can broadcast packets to multiple destinations
     156and does not receive and transmit at the same time.
     157
     158@item ifp->if_snd.ifq_maxlen
     159The maximum length of the queue of packets waiting to be
     160sent to the driver.  This is normally set to @code{ifqmaxlen}.
     161
     162@item ifp->if_init
     163The address of the driver initialization function.
     164
     165@item ifp->if_start
     166The address of the driver start function.
     167
     168@item ifp->if_ioctl
     169The address of the driver ioctl function.
     170
     171@item ifp->if_output
     172The address of the output function.  Ethernet devices
     173should set this to @code{ether_output}.
     174@end table
     175
     176Once the attach function  has set up the above entries it must link the
     177driver data structure onto the list of devices by
     178calling @code{if_attach}.  Ethernet devices should then
     179call @code{ether_ifattach}.  Both functions take a pointer to the
     180device's @code{ifnet} structure as their only argument.
     181
     182The attach function should return a non-zero value to indicate that
     183the driver has been successfully configured and attached.
     184
     185
     186
     187
     188@section Write your driver start function.
     189This function is called each time the network stack wants to start the
     190transmitter.  This occures whenever the network stack adds a packet
     191to a device's send queue and the @code{IFF_OACTIVE} bit in the
     192device's @code{if_flags} is not set.
     193
     194For many devices this function need only set the @code{IFF_OACTIVE} bit in the
     195@code{if_flags} and send an event to the transmit task
     196indicating that a packet is in the driver transmit queue.
     197
     198
     199@section Write your driver initialization function.
     200This function should initialize the device, attach to interrupt handler,
     201and start the driver transmit and receive tasks.  The function
     202
     203@example
     204rtems_id
     205rtems_bsdnet_newproc (char *name,
     206                      int stacksize,
     207                      void(*entry)(void *),
     208                      void *arg);
     209@end example
     210
     211should be used to start the driver tasks.
     212
     213Note that the network stack may call the driver initialization function more
     214than once.
     215Make sure you don't start multiple versions of the receive and transmit tasks.
     216
     217
     218
     219@section Write your driver transmit task.
     220This 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
     221driver start function indicating that packets are waiting to be transmitted.
     222When the transmit task has drained the driver send queue the task should clear
     223the @code{IFF_OACTIVE} bit in @code{if_flags} and block until another outgoing
     224packet is queued.
     225
     226
     227@section Write your driver receive task.
     228This task should block until a packet arrives from the device.  If the
     229device is an Ethernet interface the function @code{ether_input} should be called
     230to forward the packet to the network stack.   The arguments to @code{ether_input}
     231are a pointer to the interface data structure, a pointer to the ethernet
     232header and a pointer to an mbuf containing the packet itself.
     233
     234
     235
     236
     237@section Write your driver interrupt handler.
     238A typical interrupt handler will do nothing more than the hardware
     239manipulation required to acknowledge the interrupt and send an RTEMS event
     240to wake up the driver receive or transmit task waiting for the event.
     241Network interface interrupt handlers must not make any calls to other
     242network routines.
     243
     244
     245
     246@section Write your driver ioctl function.
     247This function handles ioctl requests directed at the device.  The ioctl
     248commands which must be handled are:
     249
     250@table @code
     251@item SIOCGIFADDR
     252@item SIOCSIFADDR
     253If the device is an Ethernet interface these
     254commands should be passed on to @code{ether_ioctl}.
     255
     256@item SIOCSIFFLAGS
     257This command should be used to start or stop the device,
     258depending on the state of the interface @code{IFF_UP} and
     259@code{IFF_RUNNING} bits in @code{if_flags}:
     260@table @code
     261@item IFF_RUNNING
     262Stop the device.
     263
     264@item IFF_UP
     265Start the device.
     266
     267@item IFF_UP|IFF_RUNNING
     268Stop then start the device.
     269
     270@item 0
     271Do nothing.
     272
     273@end table
     274@end table
     275
     276
     277
     278@section Write Your Driver Statistic-Printing Function
     279This function should print the values of any statistic/diagnostic
     280counters your driver may use.  The driver ioctl function should call
     281the statistic-printing function when the ioctl command is
     282@code{SIO_RTEMS_SHOW_STATS}.
     283
     284
  • doc/common/setup.texi

    r982e295e rfebb47e  
    1111@c
    1212
    13 @set RTEMS-RELEASE 4.0.0
    14 @set RTEMS-EDITION 4.0.0
    15 @set RTEMS-VERSION 4.0.0
    16 @set RTEMS-UPDATE-DATE October 27 1998
    17 @set RTEMS-UPDATE-MONTH October 1998
     13@set RTEMS-RELEASE 19981119
     14@set RTEMS-EDITION 19981119
     15@set RTEMS-VERSION 19981119
     16@set RTEMS-UPDATE-DATE November 19 1998
     17@set RTEMS-UPDATE-MONTH November 1998
    1818
    1919@c
  • doc/do_docs

    r982e295e rfebb47e  
    1414# Division by access level
    1515public_docs="user develenv networking posix_users started started_ada"
    16 support_docs="${supplements}"
     16support_docs="${supplements} bsp_howto"
    1717partners_docs="posix1003.1 posix1003.1h"
    1818oar_manuals="ada_user hwapi tools/texi2www \
    19   browseable_rtems posix_users_new bsp_howto"
     19  browseable_rtems new_chapters"
    2020
    2121# relnotes  is obsolete
  • doc/networking/Makefile

    r982e295e rfebb47e  
    5050        $(BMENU) -p "Preface" \
    5151           -u "Top" \
    52            -n "Writing RTEMS Network Device Drivers" ${*}.t
     52           -n "Networking Driver" ${*}.t
    5353
    5454driver.texi: driver.t Makefile
  • doc/networking/networking.texi

    r982e295e rfebb47e  
    7777* Preface::
    7878* Network Task Structure and Data Flow::
    79 * Writing RTEMS Network Device Drivers::
     79* Networking Driver::
    8080* Using Networking in an RTEMS Application::
    8181* Testing the Driver::
  • doc/posix_users/Makefile

    r982e295e rfebb47e  
    77#
    88
    9 PROJECT=posix_users
     9PROJECT=posix_users_new
    1010DISTRIBUTION_LEVEL=public
    1111
     
    1919COMMON_FILES=../common/cpright.texi
    2020
    21 FILES= clock.texi cond.texi key.texi mutex.texi $(PROJECT).texi preface.texi \
    22   sched.texi signal.texi thread.texi $(COMMON_FILES)
     21GENERATED_FILES= \
     22   cancel.texi clock.texi cond.texi \
     23   cspecific.texi device.texi files.texi \
     24   io.texi key.texi memorymgmt.texi message.texi mutex.texi procenv.texi \
     25   process.texi sched.texi semaphores.texi signal.texi systemdb.texi \
     26   thread.texi
     27
     28FILES= posix_users.texi preface.texi \
     29  $(COMMON_FILES) $(GENERATED_FILES)
    2330
    2431INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*)
    2532
    26 info: dirs $(PROJECT)
    27         cp $(PROJECT) $(PROJECT)-* $(INFO_INSTALL)
    28         #cp $(PROJECT) $(INFO_INSTALL)
     33info: dirs $(FILES) $(PROJECT)
     34#       cp $(PROJECT) $(PROJECT)-* $(INFO_INSTALL)
     35        cp $(PROJECT) $(INFO_INSTALL)
    2936
    30 posix_users: $(FILES)
    31         $(MAKEINFO) $(PROJECT).texi
     37$(PROJECT): $(FILES)
     38        $(MAKEINFO) posix_users.texi
    3239
    3340dvi: $(PROJECT).dvi
     
    3946
    4047$(PROJECT).dvi: $(FILES)
    41         $(TEXI2DVI) $(PROJECT).texi
     48        $(TEXI2DVI) posix_users.texi
     49        mv posix_users.dvi $(PROJECT).dvi
    4250
    43 html: dirs
     51html: dirs $(FILES)
    4452        -mkdir -p $(WWW_INSTALL)/$(PROJECT)
    4553        -cd .. ; gmake headers
    4654        $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
    47             $(PROJECT).texi
    48 
     55            posix_users.texi
    4956
    5057clean:
    5158        rm -f *.o $(PROG) *.txt core *.html
    5259        rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
    53         rm -f $(PROJECT) $(PROJECT)-* _*
     60        rm -f $(PROJECT) $(PROJECT)-* _* $(GENERATED_FILES)
    5461
     62process.texi: process.t Makefile
     63         $(BMENU) -p "" \
     64            -u "Top" \
     65            -n "" ${*}.t
     66
     67procenv.texi: procenv.t Makefile
     68         $(BMENU) -p "" \
     69            -u "Top" \
     70            -n "" ${*}.t
     71
     72files.texi: files.t Makefile
     73         $(BMENU) -p "" \
     74            -u "Top" \
     75            -n "" ${*}.t
     76
     77thread.texi: thread.t Makefile
     78         $(BMENU) -p "" \
     79            -u "Top" \
     80            -n "" ${*}.t
     81
     82signal.texi: signal.t Makefile
     83         $(BMENU) -p "" \
     84            -u "Top" \
     85            -n "" ${*}.t
     86
     87mutex.texi: mutex.t Makefile
     88         $(BMENU) -p "" \
     89            -u "Top" \
     90            -n "" ${*}.t
     91
     92cond.texi: cond.t Makefile
     93         $(BMENU) -p "" \
     94            -u "Top" \
     95            -n "" ${*}.t
     96
     97key.texi: key.t Makefile
     98         $(BMENU) -p "" \
     99            -u "Top" \
     100            -n "" ${*}.t
     101
     102clock.texi: clock.t Makefile
     103         $(BMENU) -p "" \
     104            -u "Top" \
     105            -n "" ${*}.t
     106
     107sched.texi: sched.t Makefile
     108         $(BMENU) -p "" \
     109            -u "Top" \
     110            -n "" ${*}.t
     111
     112io.texi: io.t Makefile
     113         $(BMENU) -p "" \
     114            -u "Top" \
     115            -n "" ${*}.t
     116
     117device.texi: device.t Makefile
     118         $(BMENU) -p "" \
     119            -u "Top" \
     120            -n "" ${*}.t
     121
     122cspecific.texi: cspecific.t Makefile
     123         $(BMENU) -p "" \
     124            -u "Top" \
     125            -n "" ${*}.t
     126
     127semaphores.texi: semaphores.t Makefile
     128         $(BMENU) -p "" \
     129            -u "Top" \
     130            -n "" ${*}.t
     131
     132memorymgmt.texi: memorymgmt.t Makefile
     133         $(BMENU) -p "" \
     134            -u "Top" \
     135            -n "" ${*}.t
     136
     137message.texi: message.t Makefile
     138         $(BMENU) -p "" \
     139            -u "Top" \
     140            -n "" ${*}.t
     141
     142cancel.texi: cancel.t Makefile
     143         $(BMENU) -p "" \
     144            -u "Top" \
     145            -n "" ${*}.t
     146
     147systemdb.texi: systemdb.t Makefile
     148         $(BMENU) -p "" \
     149            -u "Top" \
     150            -n "" ${*}.t
     151
  • doc/posix_users/posix_users.texi

    r982e295e rfebb47e  
    11\input ../texinfo/texinfo   @c -*-texinfo-*-
    22@c %**start of header
    3 @setfilename posix_users
     3@setfilename posix_users_new
    44@syncodeindex vr fn
    55@synindex ky cp
     
    4040@c variable substitution info:
    4141@c
    42 @c @set LANGUAGE C
     42@c Note: At the moment we do not document the Ada interface but by building
     43@c       in the infrastructure Florist support should be simple to add.
     44@set is-C
     45@clear is-Ada
     46@set LANGUAGE C
     47@set STRUCTURE structure
     48@set ROUTINE function
     49@set OR |
     50@set RPREFIX RTEMS_
     51@set DIRPREFIX rtems_
    4352@c the language is @value{LANGUAGE}
    4453@c NOTE:  don't use underscore in the name
     
    7786
    7887@include preface.texi
    79 @include thread.texi
     88@include process.texi
    8089@include signal.texi
     90@include procenv.texi
     91@include files.texi
     92@include io.texi
     93@include device.texi
     94@include cspecific.texi
     95@include systemdb.texi
     96@include semaphores.texi
    8197@include mutex.texi
    8298@include cond.texi
     99@include memorymgmt.texi
     100@include sched.texi
     101@include clock.texi
     102@include message.texi
     103@include thread.texi
    83104@include key.texi
    84 @include clock.texi
    85 @include sched.texi
     105@include cancel.texi
    86106@ifinfo
    87107@node Top, Preface, (dir), (dir)
    88 @top posix_users
     108@top posix_users_new
    89109
    90110This is the online version of the RTEMS POSIX API User's Guide
     
    92112@menu
    93113* Preface::
    94 * Thread Manager::
     114* Process Creation and Execution Manager::
    95115* Signal Manager::
     116* Process Environment Manager::
     117* Files and Directories Manager::
     118* Input and Output Primitives Manager::
     119* Device- and Class- Specific Functions Manager::
     120* Language-Specific Services for the C Programming Language Manager::
     121* System Databases Manager::
     122* Semaphores Manager::
    96123* Mutex Manager::
    97124* Condition Variable Manager::
     125* Memory Management Manager::
     126* Scheduler Manager::
     127* Clock Manager::
     128* Message Passing Manager::
     129* Thread Manager::
    98130* Key Manager::
    99 * Clock Manager::
    100 * Scheduler Manager::
     131* Thread Cancellation Manager::
    101132* Command and Variable Index::
    102133* Concept Index::
     
    109140@c
    110141
    111 @node Command and Variable Index, Concept Index, sched_yield, Top
     142@node Command and Variable Index, Concept Index, , Top
    112143@unnumbered Command and Variable Index
    113144
  • doc/rtems_support.html

    r982e295e rfebb47e  
    2020    <LI><A HREF="networking/index.html">
    2121        RTEMS Network Supplement</A>
     22    <LI><A HREF="bsp_howto/index.html">
     23        RTEMS BSP and Device Driver Development Guide</A>
    2224
    2325<LI>CPU Supplements
Note: See TracChangeset for help on using the changeset viewer.