diff options
Diffstat (limited to 'doc/bsp_howto')
| -rw-r--r-- | doc/bsp_howto/Makefile | 152 | ||||
| -rw-r--r-- | doc/bsp_howto/Makefile.am | 118 | ||||
| -rw-r--r-- | doc/bsp_howto/network.t | 342 |
3 files changed, 460 insertions, 152 deletions
diff --git a/doc/bsp_howto/Makefile b/doc/bsp_howto/Makefile deleted file mode 100644 index 0e12e674b3..0000000000 --- a/doc/bsp_howto/Makefile +++ /dev/null @@ -1,152 +0,0 @@ -# -# COPYRIGHT (c) 1988-1999. -# On-Line Applications Research Corporation (OAR). -# All rights reserved. -# -# $Id$ -# - -PROJECT=bsp_howto - -include ../Make.config - -all: html info ps pdf - -dirs: - $(make-dirs) - -COMMON_FILES=../common/cpright.texi ../common/setup.texi - -GENERATED_FILES= \ - intro.texi target.texi makefiles.texi linkcmds.texi support.texi \ - adaintr.texi init.texi console.texi clock.texi timer.texi rtc.texi \ - nvmem.texi network.texi shmsupp.texi analog.texi discrete.texi - -FILES=$(PROJECT).texi $(GENERATED_FILES) - -INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*) - -info: dirs $(PROJECT) - #cp $(wildcard $(PROJECT) $(PROJECT)-*) $(INFO_INSTALL) - # cp $(PROJECT) $(INFO_INSTALL) - -$(PROJECT): $(FILES) - $(MAKEINFO) $(PROJECT).texi - -dvi: dirs $(PROJECT).dvi -ps: dirs $(PROJECT).ps -pdf: dirs $(PROJECT).pdf - -$(PROJECT).pdf: $(FILES) - $(TEXI2PDF) $(PROJECT).texi - cp $(PROJECT).pdf $(WWW_INSTALL)/$(PROJECT) - -$(PROJECT).ps: $(PROJECT).dvi - dvips -o $(PROJECT).ps $(PROJECT).dvi - cp $(PROJECT).ps $(WWW_INSTALL)/$(PROJECT) - -$(PROJECT).dvi: $(FILES) - $(TEXI2DVI) $(PROJECT).texi - cp $(PROJECT).dvi $(WWW_INSTALL)/$(PROJECT) - -html: dirs $(FILES) - -mkdir -p $(WWW_INSTALL)/$(PROJECT) - $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \ - $(PROJECT).texi - -clean: - rm -f *.o $(PROG) *.txt core $(PROJECT).pdf - rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) - rm -f $(PROJECT) $(PROJECT)-* $(GENERATED_FILES) - rm -f *.fixed _* network.t - -# -# Grab the chapter on writing a network device driver. -# -network.t: - ln -s ../networking/driver.t network.t - - -# -# Process Automatically Generated Files -# - -intro.texi: intro.t Makefile - $(BMENU) -p "Top" \ - -u "Top" \ - -n "Target Dependent Files" ${*}.t - -target.texi: target.t Makefile - $(BMENU) -p "Introduction" \ - -u "Top" \ - -n "Makefiles" ${*}.t - -makefiles.texi: makefiles.t Makefile - $(BMENU) -p "Target Dependent Files Board Support Package Structure" \ - -u "Top" \ - -n "Linker Script" ${*}.t - -linkcmds.texi: linkcmds.t Makefile - $(BMENU) -p "Makefiles Creating a New BSP Make Customization File" \ - -u "Top" \ - -n "Ada95 Interrupt Support" ${*}.t - -adaintr.texi: adaintr.t Makefile - $(BMENU) -p "Linker Script Initialized Data" \ - -u "Top" \ - -n "Miscellaneous Support Files" ${*}.t - -support.texi: support.t Makefile - $(BMENU) -p "Ada95 Interrupt Support Version Requirements" \ - -u "Top" \ - -n "" ${*}.t - -init.texi: init.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -console.texi: console.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -clock.texi: clock.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -timer.texi: timer.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -rtc.texi: rtc.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -nvmem.texi: nvmem.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -network.texi: network.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -shmsupp.texi: shmsupp.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -analog.texi: analog.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t - -discrete.texi: discrete.t Makefile - $(BMENU) -p "" \ - -u "Top" \ - -n "" ${*}.t diff --git a/doc/bsp_howto/Makefile.am b/doc/bsp_howto/Makefile.am new file mode 100644 index 0000000000..4657bbe873 --- /dev/null +++ b/doc/bsp_howto/Makefile.am @@ -0,0 +1,118 @@ +# +# COPYRIGHT (c) 1988-1999. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# +# $Id$ +# + +AUTOMAKE_OPTIONS = foreign + +PROJECT=bsp_howto + +include $(top_srcdir)/project.am + +COMMON_FILES=$(top_srcdir)/common/cpright.texi $(top_builddir)/common/setup.texi + +GENERATED_FILES= \ + intro.texi target.texi makefiles.texi linkcmds.texi support.texi \ + adaintr.texi init.texi console.texi clock.texi timer.texi rtc.texi \ + nvmem.texi network.texi shmsupp.texi analog.texi discrete.texi + +FILES= + +info_TEXINFOS = bsp_howto.texi +bsp_howto_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES) + +# +# Grab the chapter on writing a network device driver. +# +network.t: + ln -s ../networking/driver.t network.t + + +# +# Process Automatically Generated Files +# + +intro.texi: intro.t + $(BMENU) -p "Top" \ + -u "Top" \ + -n "Target Dependent Files" $< + +target.texi: target.t + $(BMENU) -p "Introduction" \ + -u "Top" \ + -n "Makefiles" $< + +makefiles.texi: makefiles.t + $(BMENU) -p "Target Dependent Files Board Support Package Structure" \ + -u "Top" \ + -n "Linker Script" $< + +linkcmds.texi: linkcmds.t + $(BMENU) -p "Makefiles Creating a New BSP Make Customization File" \ + -u "Top" \ + -n "Ada95 Interrupt Support" $< + +adaintr.texi: adaintr.t + $(BMENU) -p "Linker Script Initialized Data" \ + -u "Top" \ + -n "Miscellaneous Support Files" $< + +support.texi: support.t + $(BMENU) -p "Ada95 Interrupt Support Version Requirements" \ + -u "Top" \ + -n "" $< + +init.texi: init.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +console.texi: console.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +clock.texi: clock.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +timer.texi: timer.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +rtc.texi: rtc.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +nvmem.texi: nvmem.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +network.texi: network.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +shmsupp.texi: shmsupp.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +analog.texi: analog.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +discrete.texi: discrete.t + $(BMENU) -p "" \ + -u "Top" \ + -n "" $< + +EXTRA_DIST = *.t diff --git a/doc/bsp_howto/network.t b/doc/bsp_howto/network.t new file mode 100644 index 0000000000..c2fa4866f6 --- /dev/null +++ b/doc/bsp_howto/network.t @@ -0,0 +1,342 @@ +@c +@c Written by Eric Norum +@c +@c COPYRIGHT (c) 1988-1999. +@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. Having a copy of this driver at +hand when reading the following notes will help significantly. + +@section Learn about the network device + +Before starting to write the network driver become 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 +outgoing 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 the driver transmit and receive tasks, +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}). +The transmit and receive tasks must abide by this protocol. Be very +careful to avoid `deadly embraces' with the other network tasks. +A number of routines are provided to make it easier for the network +driver 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. +The network driver tasks 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 a network driver task has released the network semaphore to allow other +network-related tasks to run while the task blocks, then this function must +be called 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 *)} +The network driver 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 Network Driver Makefile + +Network drivers are considered part of the BSD network package and as such +are to be compiled with the appropriate flags. This can be accomplished by +adding @code{-D__INSIDE_RTEMS_BSD_TCPIP_STACK__} to the @code{command line}. +If the driver is inside the RTEMS source tree or is built using the +RTEMS application Makefiles, then adding the following line accomplishes +this: + +@example +DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__ +@end example + +This is equivalent to the following list of definitions. Early versions +of the RTEMS BSD network stack required that all of these be defined. + +@example +-D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \ + -DDIAGNOSTIC -DBOOTP_COMPAT +@end example + +Defining these macros tells the network header files that the driver +is to be compiled with extended visibility into the network stack. This +is in sharp contrast to applications that simply use the network stack. +Applications do not require this level of visibility and should stick +to the portable application level API. + +As a direct result of being logically internal to the network stack, +network drivers use the BSD memory allocation routines This means, +for example, that malloc takes three arguments. See the SONIC +device driver (@code{c/src/lib/libchip/network/sonic.c}) for an example +of this. Because of this, network drivers should not include +@code{<stdlib.h>}. Doing so will result in conflicting definitions +of @code{malloc()}. + +@b{Application level} code including network servers such as the FTP +daemon are @b{not} part of the BSD kernel network code and should not be +compiled with the BSD network flags. They should include +@code{<stdlib.h>} and not define the network stack visibility +macros. + +@section Write the 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 device name should +be obtained from the @code{name} entry in the configuration structure. + +@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}. The unit number should be +obtained from the `name' entry in the configuration structure. + +@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 + +RTEMS provides a function to parse the driver name in the +configuration structure into a device name and unit number. + +@example +int rtems_bsdnet_parse_driver_name ( + const struct rtems_bsdnet_ifconfig *config, + char **namep +); +@end example + +The function takes two arguments; a pointer to the configuration +structure and a pointer to a pointer to a character. The function +parses the configuration name entry, allocates memory for the driver +name, places the driver name in this memory, sets the second argument +to point to the name and returns the unit number. +On error, a message is printed and -1 is returned. + +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 the 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 the 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 multiple versions of the receive and transmit tasks are not accidentally +started. + + + +@section 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 +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 the 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 the 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 the 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 the Driver Statistic-Printing Function +This function should print the values of any statistic/diagnostic +counters the network driver may use. The driver ioctl function should call +the statistic-printing function when the ioctl command is +@code{SIO_RTEMS_SHOW_STATS}. + + |