Incorporated Jeff's suggestions.

2026-09-20 22:14:29 +08:00 · 1998-12-17 18:15:39 +00:00
parent a54541d8e3
commit 183369d865
12 changed files with 106 additions and 58 deletions
@@ -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

@@ -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 
@@ -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.
@@ -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

@@ -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
@@ -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. 

@@ -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
@@ -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.
@@ -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

@@ -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
@@ -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
@@ -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 your driver transmit task.
+@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
@@ -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}.