From 183369d86520e3880eec8ea306890e007cab7387 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 17 Dec 1998 18:15:39 +0000 Subject: Incorporated Jeff's suggestions. --- doc/bsp_howto/analog.t | 10 ++++++--- doc/bsp_howto/clock.t | 3 +++ doc/bsp_howto/console.t | 6 +++--- doc/bsp_howto/discrete.t | 8 +++++-- doc/bsp_howto/init.t | 15 ++++++++++---- doc/bsp_howto/linkcmds.t | 10 ++++----- doc/bsp_howto/makefiles.t | 29 ++++++++++++++++++++++++-- doc/bsp_howto/nvmem.t | 6 +++--- doc/bsp_howto/rtc.t | 3 ++- doc/bsp_howto/target.t | 19 +++++++++-------- doc/bsp_howto/timer.t | 2 +- doc/networking/driver.t | 53 +++++++++++++++++++++++++---------------------- 12 files changed, 106 insertions(+), 58 deletions(-) (limited to 'doc') diff --git a/doc/bsp_howto/analog.t b/doc/bsp_howto/analog.t index 34cee23f65..bb7532632a 100644 --- a/doc/bsp_howto/analog.t +++ b/doc/bsp_howto/analog.t @@ -80,7 +80,7 @@ in a known state. At system initialization, the analog driver's initialization entry point will be invoked. As part of initialization, the driver will perform -whatever board initializatin is required and then set all +whatever board initialization is required and then set all outputs to their configured initial state. The analog driver may register a device name for each DAC and ADC in @@ -158,6 +158,10 @@ for this device. This is one of the IOCTL functions supported by the I/O control device driver entry point. When this IOCTL function is invoked, -the last value written to the specified output word along with -a timestamp of when the last write was performed. +the following information is returned to the caller: + +@itemize @bullet +@item last value written to the specified DAC +@item timestamp of when the last write was performed +@end itemize diff --git a/doc/bsp_howto/clock.t b/doc/bsp_howto/clock.t index e6bd4f3cb0..f96bd5f411 100644 --- a/doc/bsp_howto/clock.t +++ b/doc/bsp_howto/clock.t @@ -19,6 +19,9 @@ The clock driver is located in the @code{clock} directory of the BSP. @section Clock Driver Global Variables +This section describes the global variables expected to be provided by +this driver. + @subsection Major and Minor Number The major and minor numbers of the clock driver are made available via diff --git a/doc/bsp_howto/console.t b/doc/bsp_howto/console.t index 0b94cede70..5c48e5399b 100644 --- a/doc/bsp_howto/console.t +++ b/doc/bsp_howto/console.t @@ -31,7 +31,7 @@ line, tabulations, etc.) recognition and processing, @end itemize -We may think that one need two serial drivers to deal with those two types +One may think that two serial drivers are needed to handle these two types of data, but Termios permits having only one driver. @section Termios @@ -90,7 +90,7 @@ Asynchronous Receiver-Transmitter, i.e. the serial chip): In polled mode, the processor blocks on sending/receiving characters. This mode is not the most efficient way to utilize the UART. But polled mode is usually necessary when one wants to print an -error message in the event of a fatal error such as al fatal error +error message in the event of a fatal error such as a fatal error in the BSP. This is also the simplest mode to program. Polled mode is generally preferred if the serial port is to be used primarily as a debug console. In a simple polled driver, @@ -124,7 +124,7 @@ before the first interrupt will occur. The following Figure shows how a Termios driven serial driver works: @example -This figure needs to be inserted in this document. +Figure not included in this draft @end example The following list describes the basic flow. diff --git a/doc/bsp_howto/discrete.t b/doc/bsp_howto/discrete.t index 8b0da7925d..a865912a81 100644 --- a/doc/bsp_howto/discrete.t +++ b/doc/bsp_howto/discrete.t @@ -178,6 +178,10 @@ output values. This is one of the IOCTL functions supported by the I/O control device driver entry point. When this IOCTL function is invoked, -the last value written to the specified output word along with -a timestamp of when the last write was performed. +the following information is returned to the caller: + +@itemize @bullet +@item last value written to the specified output word +@item timestamp of when the last write was performed +@end itemize diff --git a/doc/bsp_howto/init.t b/doc/bsp_howto/init.t index a0fcbda577..bf8b2c3990 100644 --- a/doc/bsp_howto/init.t +++ b/doc/bsp_howto/init.t @@ -95,6 +95,14 @@ to execute to complete the initialization sequence. The initial assembly language start code completes its execution by invoking the shared routine @code{boot_card()}. +The label (symbolic name) associated with the starting address of the +program is typically called @code{start}. The start object file +is the first object file linked into the program image so it is insured +that the start code is at offset 0 in the @code{.text} section. It is +the responsibility of the linker script in conjunction with the +compiler specifications file to put the start code in the correct location +in the application image. + @subsection boot_card() - Boot the Card The @code{boot_card()} is the first C code invoked. Most of the BSPs @@ -163,12 +171,11 @@ initialization hooks: @end itemize One of the most important functions performed by this routine -is determining where the RTEMS Executive Work Space is to be +is determining where the RTEMS Workspace is to be located in memory. All RTEMS objects and task stacks will be allocated from this Workspace. The RTEMS Workspace is distinct -from the application heap used for @code{malloc()}. - -Many BSPs place this area at the end of RAM although this is +from the application heap used for @code{malloc()}. Many BSPs +place the RTEMS Workspace area at the end of RAM although this is certainly not a requirement. After completing execution, this routine returns to the diff --git a/doc/bsp_howto/linkcmds.t b/doc/bsp_howto/linkcmds.t index 3bfb28b4be..22744dbadd 100644 --- a/doc/bsp_howto/linkcmds.t +++ b/doc/bsp_howto/linkcmds.t @@ -19,7 +19,7 @@ for the application will reside in memory. An embedded systems programmer must be much more aware of the placement of their executable image in memory than the average -"normal" programmer. A program destined to be embedded as well +applications programmer. A program destined to be embedded as well as the target system have some specific properties that must be taken into account. Embedded machines often mean average performances and small memory usage. It is the memory usage that concerns us @@ -43,9 +43,9 @@ or Flash. On the other hand, data processing occurs in RAM. This leads us to the structure of an embedded program. In rough terms, an embedded program is made of sections. It is the responsibility of the application programmer to place these sections in the appropriate -place in target memory. To make this clearer, if using COFF on the -Motorola m68k family of microprocessors, the following sections will -be present: +place in target memory. To make this clearer, if using the COFF +object file format on the Motorola m68k family of microprocessors, +the following sections will be present: @itemize @bullet @@ -417,6 +417,6 @@ this is done are not relevant. Step 3 shows the final executable image as it logically appears in the target's non-volatile program memory. The board initialization -code will copy the initialized data initial values (which are stored in +code will copy the ""copy of @code{.data} section" (which are stored in ROM) to their reserved location in RAM. diff --git a/doc/bsp_howto/makefiles.t b/doc/bsp_howto/makefiles.t index cf815f10a1..c607a0fbb5 100644 --- a/doc/bsp_howto/makefiles.t +++ b/doc/bsp_howto/makefiles.t @@ -8,6 +8,31 @@ @chapter Makefiles +This chapter discusses the Makefiles associated with a BSP. It does not +describe the process of configuring, building, and installing RTEMS. +This chapter will not provide detailed information about this process. +Nonetheless, it is important to remember that the general process consists +of three parts: + +@itemize @bullet +@item configure +@item build +@item install +@end itemize + +During the configure phase, a number of files are generated. These +generated files are tailored for the specific host/target combination +by the configure script. This set of files includes the Makefiles used +to actually compile and install RTEMS. + +During the build phase, the source files are compiled into object files +and libraries are built. + +During the install phase, the libraries, header files, and other support +files are copied to the BSP specific installation point. After installation +is successfully completed, the files generated by the configure and build +phases may be removed. + @section Makefiles Used During The BSP Building Process There is a file named @code{Makefile.in} in each directory of a BSP. @@ -88,8 +113,8 @@ components from the CPU dependent support code library. For example, this component may choose to use a default exception handler from the CPU dependent support code or provide its own. -This Makefile makes use of a neat construct in @b{GNU make} to pick -up the required components: +This Makefile makes use of the @code{foreach} construct in @b{GNU make} +to pick up the required components: @example BSP_PIECES=startup clock console timer diff --git a/doc/bsp_howto/nvmem.t b/doc/bsp_howto/nvmem.t index eda65f93a5..6ff9931b31 100644 --- a/doc/bsp_howto/nvmem.t +++ b/doc/bsp_howto/nvmem.t @@ -65,7 +65,7 @@ configuration table is typically an array of structures with each structure containing the information for a particular area of non-volatile memory. The following is a list of the type of information normally required -to configure each area of non-volatile memory +to configure each area of non-volatile memory. @table @b @item memory_type @@ -118,7 +118,7 @@ block. is the number of logical partitions within this area. @item Partitions -is the address of table that contains an entry to describe each +is the address of the table that contains an entry to describe each partition in this area. Fields within each element of this table are defined as follows: @@ -143,7 +143,7 @@ initialization entry point will be invoked. As part of initialization, the driver will perform whatever initializatin is required on each non-volatile memory area. -The discrete I/O driver may register devices name for memory +The discrete I/O driver may register device names for memory partitions of particular interest to the system. Normally this will be restricted to the device "/dev/nv_memory" to indicate the entire device driver. diff --git a/doc/bsp_howto/rtc.t b/doc/bsp_howto/rtc.t index 6134452dd7..b84c214258 100644 --- a/doc/bsp_howto/rtc.t +++ b/doc/bsp_howto/rtc.t @@ -89,7 +89,8 @@ generation had Vendor B's RTC chip, RTC_Table could contain information for both. The @code{deviceProbe} configured for Vendor A's RTC chip would need to return TRUE if the board was a first generation one. The @code{deviceProbe} -routines are very board dependent. +routines are very board dependent and must be provided by +the BSP. @section setRealTimeToRTEMS diff --git a/doc/bsp_howto/target.t b/doc/bsp_howto/target.t index a14f7d6a49..7ac719b692 100644 --- a/doc/bsp_howto/target.t +++ b/doc/bsp_howto/target.t @@ -54,11 +54,11 @@ and the peripherals actually placed on the board. @section Peripheral Dependent This class of code provides a reusable library of peripheral device -drivers which can be tailored easily to a particular board. This -reusable library provides software objects which correspond to standard -controllers. Just as the hardware engineer choose a standard controller -when designing a board, the goal of this library is to let the software -engineer do the same thing. +drivers which can be tailored easily to a particular board. The +libchip library is a collection of reusable software objects that +correspond to standard controllers. Just as the hardware engineer +chooses a standard controller when designing a board, the goal of +this library is to let the software engineer do the same thing. The source code for the reusable peripheral driver library may be found in the directory @code{c/src/lib/libchip}. The source code is further @@ -90,10 +90,11 @@ the existing BSP may not support this. If the BSP does not exist and the board's CPU model is supported, then examine the reusable chip library and existing BSPs for a close match. -This will help reduce the development effort required. It is often -possible to copy existing components in the reusable chip library or -device drivers from BSPs from different CPU families as the starting -point for a new device driver. +Other BSPs and libchip provide starting points for the development +of a new BSP. It is often possible to copy existing components in +the reusable chip library or device drivers from BSPs from different +CPU families as the starting point for a new device driver. +This will help reduce the development effort required. If the board's CPU family is supported but the particular CPU model on that board is not, then the RTEMS port to that CPU family will have to diff --git a/doc/bsp_howto/timer.t b/doc/bsp_howto/timer.t index 8794ea00ee..6a9642e941 100644 --- a/doc/bsp_howto/timer.t +++ b/doc/bsp_howto/timer.t @@ -15,7 +15,7 @@ bus cycles. This information can be very useful for determining precisely what pieces of code require optimization and to measure the impact of specific minor changes. -The gen68340 BSP also uses the TImer Driver to support a high performance +The gen68340 BSP also uses the Timer Driver to support a high performance mode of the on-CPU UART. @section Benchmark Timer diff --git a/doc/networking/driver.t b/doc/networking/driver.t index e7e5c4335b..f3223530e1 100644 --- a/doc/networking/driver.t +++ b/doc/networking/driver.t @@ -17,12 +17,12 @@ 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. +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 you need to be completely +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. @@ -34,7 +34,7 @@ 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 +outgoing packet from multiple fragments scattered in separate memory buffers? @item If the device uses DMA, is it capable of chaining multiple @@ -74,43 +74,43 @@ 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 +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}). -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. +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. -Your task must call this function immediately before +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 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 +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 *)} -Your task should call this function when it wishes to wait for an event. -This function releases the network semaphore, +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 Write your driver attach function +@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. @@ -185,7 +185,7 @@ the driver has been successfully configured and attached. -@section Write your driver start function. +@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 @@ -196,7 +196,8 @@ For many devices this function need only set the @code{IFF_OACTIVE} bit in the indicating that a packet is in the driver transmit queue. -@section Write your driver initialization function. +@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 @@ -212,11 +213,13 @@ 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. +Make sure multiple versions of the receive and transmit tasks are not accidentally +started. + +@section Write the Driver Transmit Task -@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 @@ -224,7 +227,7 @@ the @code{IFF_OACTIVE} bit in @code{if_flags} and block until another outgoing packet is queued. -@section Write your driver receive task. +@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} @@ -234,7 +237,7 @@ header and a pointer to an mbuf containing the packet itself. -@section Write your driver interrupt handler. +@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. @@ -243,7 +246,7 @@ network routines. -@section Write your driver ioctl function. +@section Write the Driver IOCTL Function This function handles ioctl requests directed at the device. The ioctl commands which must be handled are: @@ -275,9 +278,9 @@ Do nothing. -@section Write Your Driver Statistic-Printing Function +@section Write the 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 +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}. -- cgit v1.2.3