Changeset 6d7a4d2 – RTEMS Project

bsp_howto/ada95_interrupt.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Ada95 Interrupt Support
 …
 ============
 This chapter describes what is required to enable Ada interrupt
 and error exception handling when using GNAT over RTEMS.
+This chapter describes what is required to enable Ada interrupt and error
+exception handling when using GNAT over RTEMS.
+The GNAT Ada95 interrupt support RTEMS was developed by
+Jiri Gaisler <jgais@ws.estec.esa.nl> who also wrote this
+chapter.
+The GNAT Ada95 interrupt support RTEMS was developed by Jiri Gaisler
+<jgais@ws.estec.esa.nl> who also wrote this chapter.
 Mapping Interrupts to POSIX Signals
 ===================================
 In Ada95, interrupts can be attached with the interrupt_attach pragma.
+For most systems, the gnat run-time will use POSIX signal to implement
+the interrupt handling, mapping one signal per interrupt. For interrupts
+to be propagated to the attached Ada handler, the corresponding signal
 must be raised when the interrupt occurs.
+In Ada95, interrupts can be attached with the interrupt_attach pragma.  For
+most systems, the gnat run-time will use POSIX signal to implement the
+interrupt handling, mapping one signal per interrupt. For interrupts to be
+propagated to the attached Ada handler, the corresponding signal must be raised
+when the interrupt occurs.
+The same mechanism is used to generate Ada error exceptions.
+Three error exceptions are defined: program, constraint and storage
+error. These are generated by raising the predefined signals: SIGILL,
+SIGFPE and SIGSEGV. These signals should be raised when a spurious
+or erroneous trap occurs.
+The same mechanism is used to generate Ada error exceptions.  Three error
+exceptions are defined: program, constraint and storage error. These are
+generated by raising the predefined signals: SIGILL, SIGFPE and SIGSEGV. These
+signals should be raised when a spurious or erroneous trap occurs.
 To enable gnat interrupt and error exception support for a particular
 BSP, the following has to be done:
+To enable gnat interrupt and error exception support for a particular BSP, the
+following has to be done:
+# Write an interrupt/trap handler that will raise the corresponding
   signal depending on the interrupt/trap number.
+- Write an interrupt/trap handler that will raise the corresponding signal
+  depending on the interrupt/trap number.
+# Install the interrupt handler for all interrupts/traps that will be
   handled by gnat (including spurious).
+- Install the interrupt handler for all interrupts/traps that will be handled
+  by gnat (including spurious).
+# At startup, gnat calls ``__gnat_install_handler()``. The BSP
   must provide this function which installs the interrupt/trap handlers.
+- At startup, gnat calls ``__gnat_install_handler()``. The BSP must provide
+  this function which installs the interrupt/trap handlers.
+Which CPU-interrupt will generate which signal is implementation
+defined. There are 32 POSIX signals (1 - 32), and all except the
+three error signals (SIGILL, SIGFPE and SIGSEGV) can be used. I
+would suggest to use the upper 16 (17 - 32) which do not
+have an assigned POSIX name.
+Which CPU-interrupt will generate which signal is implementation defined. There
+are 32 POSIX signals (1 - 32), and all except the three error signals (SIGILL,
+SIGFPE and SIGSEGV) can be used. I would suggest to use the upper 16 (17 - 32)
+which do not have an assigned POSIX name.
 Note that the pragma interrupt_attach will only bind a signal
 to a particular Ada handler - it will not unmask the
 interrupt or do any other things to enable it. This have to be
 done separately, typically by writing various device register.
+Note that the pragma interrupt_attach will only bind a signal to a particular
+Ada handler - it will not unmask the interrupt or do any other things to enable
+it. This have to be done separately, typically by writing various device
+register.
 Example Ada95 Interrupt Program
 ===============================
+An example program (``irq_test``) is included in the
+Ada examples package to show how interrupts can be handled
+in Ada95. Note that generation of the test interrupt
+(``irqforce.c``) is BSP specific and must be edited.
+An example program (``irq_test``) is included in the Ada examples package to
+show how interrupts can be handled in Ada95. Note that generation of the test
+interrupt (``irqforce.c``) is BSP specific and must be edited.
+NOTE: The ``irq_test`` example was written for the SPARC/ERC32
+BSP.
+.. note::
+   The ``irq_test`` example was written for the SPARC/ERC32 BSP.
 Version Requirements
 ====================
 With RTEMS 4.0, a patch was required to psignal.c in RTEMS
+sources (to correct a bug associated to the default action of
 signals 15-32).   The SPARC/ERC32 RTEMS BSP includes the``gnatsupp`` subdirectory that can be used as an example
+With RTEMS 4.0, a patch was required to psignal.c in RTEMS sources (to correct
+a bug associated to the default action of signals 15-32).  The SPARC/ERC32
+RTEMS BSP includes the``gnatsupp`` subdirectory that can be used as an example
 for other BSPs.
+With GNAT 3.11p, a patch is required for ``a-init.c`` to invoke
+the BSP specific routine that installs the exception handlers.
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+With GNAT 3.11p, a patch is required for ``a-init.c`` to invoke the BSP
+specific routine that installs the exception handlers.

bsp_howto/analog.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Analog Driver
 #############
+The Analog driver is responsible for providing an
+interface to Digital to Analog Converters (DACs) and
+Analog to Digital Converters (ADCs).  The capabilities provided
+by this class of device driver are:
+The Analog driver is responsible for providing an interface to Digital to
+Analog Converters (DACs) and Analog to Digital Converters (ADCs).  The
+capabilities provided by this class of device driver are:
 - Initialize an Analog Board
 …
 - Reinitialize DACS
 Most analog devices are found on I/O cards that support multiple
 DACs or ADCs on a single card.
+Most analog devices are found on I/O cards that support multiple DACs or ADCs
+on a single card.
+There are currently no analog device drivers included in the
+RTEMS source tree.  The information provided in this chapter
+is based on drivers developed for applications using RTEMS.
+It is hoped that this driver model information can form the
+basis for a standard analog driver model that can be supported
+in future RTEMS distribution.
+There are currently no analog device drivers included in the RTEMS source tree.
+The information provided in this chapter is based on drivers developed for
+applications using RTEMS.  It is hoped that this driver model information can
+form the basis for a standard analog driver model that can be supported in
+future RTEMS distribution.
 Major and Minor Numbers
 =======================
 The *major* number of a device driver is its index in the
 RTEMS Device Address Table.
+The ``major`` number of a device driver is its index in the RTEMS Device
+Address Table.
+A *minor* number is associated with each device instance
+managed by a particular device driver.  An RTEMS minor number
+is an ``unsigned32`` entity.  Convention calls for
+dividing the bits in the minor number down into categories
+A ``minor`` number is associated with each device instance managed by a
+particular device driver.  An RTEMS minor number is an ``unsigned32`` entity.
+Convention calls for dividing the bits in the minor number down into categories
 like the following:
 - *board* - indicates the board a particular device is located on
+- ``board`` - indicates the board a particular device is located on
 - *port* - indicates the particular device on a board.
+- ``port`` - indicates the particular device on a board.
 From the above, it should be clear that a single device driver
+can support multiple copies of the same board in a single system.
 The minor number is used to distinguish the devices.
+From the above, it should be clear that a single device driver can support
+multiple copies of the same board in a single system.  The minor number is used
+to distinguish the devices.
 Analog Driver Configuration
 ===========================
+There is not a standard analog driver configuration table but some
+fields are common across different drivers.  The analog driver
+configuration table is typically an array of structures with each
+structure containing the information for a particular board.
+The following is a list of the type of information normally required
+to configure an analog board:
+There is not a standard analog driver configuration table but some fields are
+common across different drivers.  The analog driver configuration table is
+typically an array of structures with each structure containing the information
+for a particular board.  The following is a list of the type of information
+normally required to configure an analog board:
+*board_offset*
+``board_offset``
     is the base address of a board.
+*DAC_initial_values*
     is an array of the voltages that should be written to each DAC
     during initialization.  This allows the driver to start the board
     in a known state.
+``DAC_initial_values``
+    is an array of the voltages that should be written to each DAC during
+    initialization.  This allows the driver to start the board in a known
+    state.
 Initialize an Analog Board
 ==========================
 At system initialization, the analog driver's initialization entry point
+will be invoked.  As part of initialization, the driver will perform
 whatever board initialization is required and then set all
 outputs to their configured initial state.
+At system initialization, the analog driver's initialization entry point will
+be invoked.  As part of initialization, the driver will perform 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
 the system.
+The analog driver may register a device name for each DAC and ADC in the
+system.
 Open a Particular Analog
 …
 With some drivers, it may be necessary to allocate memory when a particular
 device is opened.  If that is the case, then this is often the place
 to do this operation.
+device is opened.  If that is the case, then this is often the place to do this
+operation.
 Close a Particular Analog
 …
 With some drivers, it may be necessary to allocate memory when a particular
 device is opened.  If that is the case, then this is the place
 where that memory should be deallocated.
+device is opened.  If that is the case, then this is the place where that
+memory should be deallocated.
 Read from a Particular Analog
 =============================
 This corresponds to the driver read call.  After validating the minor
+number and arguments, this call reads the indicated device.  Most analog
+devices store the last value written to a DAC.  Since DACs are output
+only devices, saving the last written value gives the appearance that
 DACs can be read from also.  If the device is an ADC, then it is sampled.
+This corresponds to the driver read call.  After validating the minor number
+and arguments, this call reads the indicated device.  Most analog devices store
+the last value written to a DAC.  Since DACs are output only devices, saving
+the last written value gives the appearance that DACs can be read from also.
+If the device is an ADC, then it is sampled.
+*NOTE:* Many boards have multiple analog inputs but only one ADC.  On
+these boards, it will be necessary to provide some type of mutual exclusion
+during reads.  On these boards, there is a MUX which must be switched
+before sampling the ADC.  After the MUX is switched, the driver must
+delay some short period of time (usually microseconds) before the
+signal is stable and can be sampled.  To make matters worse, some ADCs
+cannot respond to wide voltage swings in a single sample.  On these
+ADCs, one must do two samples when the voltage swing is too large.
+On a practical basis, this means that the driver usually ends up
+double sampling the ADC on these systems.
+.. note::
+The value returned is a single precision floating point number
+representing the voltage read.  This value is stored in the``argument_block`` passed in to the call.  By returning the
+voltage, the caller is freed from having to know the number of
+bits in the analog and board dependent conversion algorithm.
+   Many boards have multiple analog inputs but only one ADC.  On these boards,
+   it will be necessary to provide some type of mutual exclusion during reads.
+   On these boards, there is a MUX which must be switched before sampling the
+   ADC.  After the MUX is switched, the driver must delay some short period of
+   time (usually microseconds) before the signal is stable and can be sampled.
+   To make matters worse, some ADCs cannot respond to wide voltage swings in a
+   single sample.  On these ADCs, one must do two samples when the voltage
+   swing is too large.  On a practical basis, this means that the driver
+   usually ends up double sampling the ADC on these systems.
+The value returned is a single precision floating point number representing the
+voltage read.  This value is stored in the ``argument_block`` passed in to the
+call.  By returning the voltage, the caller is freed from having to know the
+number of bits in the analog and board dependent conversion algorithm.
 Write to a Particular Analog
 ============================
 This corresponds to the driver write call.  After validating the minor
 number and arguments, this call writes the indicated device.  If the
 specified device is an ADC, then an error is usually returned.
+This corresponds to the driver write call.  After validating the minor number
+and arguments, this call writes the indicated device.  If the specified device
+is an ADC, then an error is usually returned.
+The value written is a single precision floating point number
+representing the voltage to be written to the specified DAC.
+This value is stored in the ``argument_block`` passed in to the
+call.  By passing the voltage to the device driver, the caller is
+freed from having to know the number of bits in the analog
+and board dependent conversion algorithm.
+The value written is a single precision floating point number representing the
+voltage to be written to the specified DAC.  This value is stored in the
+``argument_block`` passed in to the call.  By passing the voltage to the device
+driver, the caller is freed from having to know the number of bits in the
+analog and board dependent conversion algorithm.
 Reset DACs
 ==========
 This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
 all of the DACs are written to 0.0 volts.
+This is one of the IOCTL functions supported by the I/O control device driver
+entry point.  When this IOCTL function is invoked, all of the DACs are written
+to 0.0 volts.
 Reinitialize DACS
 =================
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+all of the DACs are written with the initial value configured
+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, all of the DACs are written
+with the initial value configured for this device.
 Get Last Written 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 following information is returned to the caller:
+This is one of the IOCTL functions supported by the I/O control device driver
+entry point.  When this IOCTL function is invoked, the following information is
+returned to the caller:
 - last value written to the specified DAC
 - timestamp of when the last write was performed
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-.. COMMENT: All rights reserved.

bsp_howto/ata.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 ATA Driver
 …
 ============
 ATA driver provides generic interface to an ATA device. ATA driver is
+hardware independent implementation of ATA standard defined in working draft
+"AT Attachment Interface with Extensions (ATA-2)" X3T10/0948D revision 4c,
 March 18, 1996. ATA Driver based on IDE Controller Driver and may be used for
+ATA driver provides generic interface to an ATA device. ATA driver is hardware
+independent implementation of ATA standard defined in working draft "AT
+Attachment Interface with Extensions (ATA-2)" X3T10/0948D revision 4c, March
+, 1996. ATA Driver based on IDE Controller Driver and may be used for
 computer systems with single IDE controller and with multiple as well. Although
 current implementation has several restrictions detailed below ATA driver
 …
 - Only PIO mode is supported but both poll and interrupt driven
+The reference implementation for ATA driver can be found in``cpukit/libblock/src/ata.c``.
+The reference implementation for ATA driver can be found in
+``cpukit/libblock/src/ata.c``.
 Initialization
 …
 The ``ata_initialize`` routine is responsible for ATA driver
 initialization. The main goal of the initialization is to detect and
+register in the system all ATA devices attached to IDE controllers
 successfully initialized by the IDE Controller driver.
+initialization. The main goal of the initialization is to detect and register
+in the system all ATA devices attached to IDE controllers successfully
+initialized by the IDE Controller driver.
 In the implementation of the driver, the following actions are performed:
+.. code:: c
+.. code-block:: c
     rtems_device_driver ata_initialize(
     rtems_device_major_number  major,
     rtems_device_minor_number  minor,
     void                      \*arg
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor,
+      void                      *arg
+    )
+    {
+    initialize internal ATA driver data structure
+    for each IDE controller successfully initialized by the IDE Controller
+    driver
+    if the controller is interrupt driven
+    set up interrupt handler
+    obtain information about ATA devices attached to the controller
+    with help of EXECUTE DEVICE DIAGNOSTIC command
+    for each ATA device detected on the controller
+    obtain device parameters with help of DEVICE IDENTIFY command
+    register new ATA device as new block device in the system
+      initialize internal ATA driver data structure
+      for each IDE controller successfully initialized by the IDE Controller driver
+        if the controller is interrupt driven
+          set up interrupt handler
+        obtain information about ATA devices attached to the controller
+        with help of EXECUTE DEVICE DIAGNOSTIC command
+        for each ATA device detected on the controller
+          obtain device parameters with help of DEVICE IDENTIFY command
+          register new ATA device as new block device in the system
+    }
 …
 (see libblock library description). Device names are formed based on IDE
 controller minor number device is attached to and device number on the
+controller (0 - Master, 1 - Slave). In current implementation 64 minor
+numbers are reserved for each ATA device which allows to support up to 63
+logical partitions per device.
+.. code:: c
+controller (0 - Master, 1 - Slave). In current implementation 64 minor numbers
+are reserved for each ATA device which allows to support up to 63 logical
+partitions per device.
+    controller minor    device number    device name    ata device minor
+                  0             hda                0
+                  1             hdb               64
+                  0             hdc              128
+                  1             hdd              172
+    ...                ...            ...
+================ ============= =========== ================
+controller minor device number device name ata device minor
+================ ============= =========== ================
+                0             hda         0
+                1             hdb         64
+                0             hdc         128
+                1             hdd         172
+...              ...           ...         ...
+================ ============= =========== ================
 ATA Driver Architecture
 …
 ----------------------------------------
+ATA driver works with ATA requests. ATA request is described by the
+following structure:
+.. code:: c
+ATA driver works with ATA requests. ATA request is described by the following
+structure:
+    /* ATA request \*/
+.. code-block:: c
+    /* ATA request */
     typedef struct ata_req_s {
+    Chain_Node        link;   /* link in requests chain \*/
+    char              type;   /* request type \*/
+    ata_registers_t   regs;   /* ATA command \*/
+    uint32_t          cnt;    /* Number of sectors to be exchanged \*/
+    uint32_t          cbuf;   /* number of current buffer from breq in use \*/
+    uint32_t          pos;    /* current position in 'cbuf' \*/
+    blkdev_request   \*breq;   /* blkdev_request which corresponds to the
+    * ata request
+    \*/
+    rtems_id          sema;   /* semaphore which is used if synchronous
+    * processing of the ata request is required
+    \*/
+    rtems_status_code status; /* status of ata request processing \*/
+    int               error;  /* error code \*/
+      Chain_Node        link;   /* link in requests chain */
+      char              type;   /* request type */
+      ata_registers_t   regs;   /* ATA command */
+      uint32_t          cnt;    /* Number of sectors to be exchanged */
+      uint32_t          cbuf;   /* number of current buffer from breq in use */
+      uint32_t          pos;    /* current position in 'cbuf' */
+      blkdev_request   *breq;   /* blkdev_request which corresponds to the ata request */
+      rtems_id          sema;   /* semaphore which is used if synchronous
+                                 * processing of the ata request is required */
+      rtems_status_code status; /* status of ata request processing */
+      int               error;  /* error code */
     } ata_req_t;
+ATA driver supports separate ATA requests queues for each IDE
+controller (one queue per controller). The following structure contains
+information about controller's queue and devices attached to the controller:
+.. code:: c
+ATA driver supports separate ATA requests queues for each IDE controller (one
+queue per controller). The following structure contains information about
+controller's queue and devices attached to the controller:
+.. code-block:: c
     /*
     * This structure describes controller state, devices configuration on the
     * controller and chain of ATA requests to the controller.
     \*/
+     * This structure describes controller state, devices configuration on the
+     * controller and chain of ATA requests to the controller.
+    */
     typedef struct ata_ide_ctrl_s {
     bool          present;   /* controller state \*/
     ata_dev_t     device[2]; /* ata devices description \*/
     Chain_Control reqs;      /* requests chain \*/
+      bool          present;   /* controller state */
+      ata_dev_t     device[2]; /* ata devices description */
+      Chain_Control reqs;      /* requests chain */
     } ata_ide_ctrl_t;
+Driver uses array of the structures indexed by the controllers minor
+number.
+Driver uses array of the structures indexed by the controllers minor number.
 The following structure allows to map an ATA device to the pair (IDE
+controller minor number device is attached to, device number
+on the controller):
 .. code:: c
+The following structure allows to map an ATA device to the pair (IDE controller
+minor number device is attached to, device number on the controller):
+.. code-block:: c
     /*
     * Mapping of rtems ATA devices to the following pairs:
     * (IDE controller number served the device, device number on the controller)
     \*/
+     * Mapping of rtems ATA devices to the following pairs:
+     * (IDE controller number served the device, device number on the controller)
+    */
     typedef struct ata_ide_dev_s {
     int ctrl_minor;/* minor number of IDE controller serves rtems ATA device \*/
     int device;    /* device number on IDE controller (0 or 1) \*/
+      int ctrl_minor;/* minor number of IDE controller serves rtems ATA device */
+      int device;    /* device number on IDE controller (0 or 1) */
     } ata_ide_dev_t;
+Driver uses array of the structures indexed by the ATA devices minor
+number.
+Driver uses array of the structures indexed by the ATA devices minor number.
 ATA driver defines the following internal events:
-.. code:: c
+    /* ATA driver events \*/
+.. code-block:: c
+    /* ATA driver events */
     typedef enum ata_msg_type_s {
     ATA_MSG_GEN_EVT = 1,     /* general event \*/
     ATA_MSG_SUCCESS_EVT,     /* success event \*/
     ATA_MSG_ERROR_EVT,       /* error event \*/
     ATA_MSG_PROCESS_NEXT_EVT /* process next ata request event \*/
+      ATA_MSG_GEN_EVT = 1,     /* general event */
+      ATA_MSG_SUCCESS_EVT,     /* success event */
+      ATA_MSG_ERROR_EVT,       /* error event */
+      ATA_MSG_PROCESS_NEXT_EVT /* process next ata request event */
     } ata_msg_type_t;
 …
 All ATA driver functionality is available via ATA driver ioctl. Current
 implementation supports only two ioctls: BLKIO_REQUEST and
+ATAIO_SET_MULTIPLE_MODE. Each ATA driver ioctl() call generates an
+ATA request which is appended to the appropriate controller queue depending
+on ATA device the request belongs to. If appended request is single request in
 the controller's queue then ATA driver event is generated.
+implementation supports only two ioctls: ``BLKIO_REQUEST`` and
+``ATAIO_SET_MULTIPLE_MODE``. Each ATA driver ``ioctl()`` call generates an ATA
+request which is appended to the appropriate controller queue depending on ATA
+device the request belongs to. If appended request is single request in the
+controller's queue then ATA driver event is generated.
 ATA driver task which manages queue of ATA driver events is core of ATA
+driver. In current driver version queue of ATA driver events implemented
+as RTEMS message queue. Each message contains event type, IDE controller
+minor number on which event happened and error if an error occurred. Events
+may be generated either by ATA driver ioctl call or by ATA driver task itself.
+Each time ATA driver task receives an event it gets controller minor number
+from event, takes first ATA request from controller queue and processes it
+depending on request and event types. An ATA request processing may also
+includes sending of several events. If ATA request processing is finished
+the ATA request is removed from the controller queue. Note, that in current
+implementation maximum one event per controller may be queued at any moment
+of the time.
+driver. In current driver version queue of ATA driver events implemented as
+RTEMS message queue. Each message contains event type, IDE controller minor
+number on which event happened and error if an error occurred. Events may be
+generated either by ATA driver ioctl call or by ATA driver task itself.  Each
+time ATA driver task receives an event it gets controller minor number from
+event, takes first ATA request from controller queue and processes it depending
+on request and event types. An ATA request processing may also includes sending
+of several events. If ATA request processing is finished the ATA request is
+removed from the controller queue. Note, that in current implementation maximum
+one event per controller may be queued at any moment of the time.
 (This part seems not very clear, hope I rewrite it soon)
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-.. COMMENT: All rights reserved.

bsp_howto/clock.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Clock Driver
 …
 system.
+- A steady time basis to the kernel, so that the RTEMS primitives that need
+  a clock tick work properly.  See the *Clock Manager* chapter of the*RTEMS Application C User's Guide* for more details.
+- An optional time counter to generate timestamps of the uptime and wall
+  clock time.
+- A steady time basis to the kernel, so that the RTEMS primitives that need a
+  clock tick work properly.  See the *Clock Manager* chapter of the *RTEMS
+  Application C User's Guide* for more details.
+- An optional time counter to generate timestamps of the uptime and wall clock
+  time.
 The clock driver is usually located in the :file:`clock` directory of the BSP.
+Clock drivers should use the :dfn:`Clock Driver Shell` available via the:file:`clockdrv_shell.h` include file.
+Clock drivers should use the :dfn:`Clock Driver Shell` available via the
+:file:`clockdrv_shell.h` include file.
 Clock Driver Shell
 …
 functions, defines and macros for the :dfn:`Clock Driver Shell` which are
 explained here step by step.  A clock driver file looks in general like this.
+.. code:: c
+.. code-block:: c
     /*
     * A section with functions, defines and macros to provide hardware specific
     * functions for the Clock Driver Shell.
     \*/
+     * A section with functions, defines and macros to provide hardware specific
+     * functions for the Clock Driver Shell.
+     */
     #include "../../../shared/clockdrv_shell.h"
 …
 - The most basic clock driver provides only a periodic interrupt service
   routine which calls ``rtems_clock_tick()``.  The interval is determined by
   the application configuration via ``#define
   CONFIGURE_MICROSECONDS_PER_TICK`` and can be obtained via``rtems_configuration_get_microseconds_per_tick()``.  The timestamp
   resolution is limited to the clock tick interval.
+  the application configuration via ``#define CONFIGURE_MICROSECONDS_PER_TICK``
+  and can be obtained via ``rtems_configuration_get_microseconds_per_tick()``.
+  The timestamp resolution is limited to the clock tick interval.
 - In case the hardware lacks support for a free running counter, then the
 …
 ~~~~~~~~~~~~~~~~~~~~~~~
 .. code:: c
+.. code-block:: c
     static void some_support_initialize_hardware( void )
+    {
+    /* Initialize hardware \*/
+    }
+    #define Clock_driver_support_initialize_hardware() \\
+    some_support_initialize_hardware()
+    /* Indicate that this clock driver lacks a proper timecounter in hardware \*/
+      /* Initialize hardware */
+    }
+    #define Clock_driver_support_initialize_hardware() \
+              some_support_initialize_hardware()
+    /* Indicate that this clock driver lacks a proper timecounter in hardware */
     #define CLOCK_DRIVER_USE_DUMMY_TIMECOUNTER
     #include "../../../shared/clockdrv_shell.h"
 …
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. code:: c
+.. code-block:: c
     #include <rtems/timecounter.h>
     static rtems_timecounter_simple some_tc;
+    static uint32_t some_tc_get( rtems_timecounter_simple \*tc )
+    {
+    return some.counter;
+    }
+    static bool some_tc_is_pending( rtems_timecounter_simple \*tc )
+    {
+    return some.is_pending;
+    }
+    static uint32_t some_tc_get_timecount( struct timecounter \*tc )
+    {
+    return rtems_timecounter_simple_downcounter_get(
+    tc,
+    some_tc_get,
+    some_tc_is_pending
+    );
+    }
+    static uint32_t some_tc_get( rtems_timecounter_simple *tc )
+    {
+      return some.counter;
+    }
+    static bool some_tc_is_pending( rtems_timecounter_simple *tc )
+    {
+      return some.is_pending;
+    }
+    static uint32_t some_tc_get_timecount( struct timecounter *tc )
+    {
+      return rtems_timecounter_simple_downcounter_get(
+        tc,
+        some_tc_get,
+        some_tc_is_pending
+      );
+    }
     static void some_tc_tick( void )
+    {
+    rtems_timecounter_simple_downcounter_tick( &some_tc, some_tc_get );
+    }
+      rtems_timecounter_simple_downcounter_tick( &some_tc, some_tc_get );
+    }
     static void some_support_initialize_hardware( void )
+    {
+    uint32_t frequency = 123456;
+    uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
+    uint32_t timecounter_ticks_per_clock_tick =
+    ( frequency * us_per_tick ) / 1000000;
+    /* Initialize hardware \*/
+    rtems_timecounter_simple_install(
+    &some_tc,
+    frequency,
+    timecounter_ticks_per_clock_tick,
+    some_tc_get_timecount
+    );
+    }
+    #define Clock_driver_support_initialize_hardware() \\
+    some_support_initialize_hardware()
+    #define Clock_driver_timecounter_tick() \\
+    some_tc_tick()
+      uint32_t frequency = 123456;
+      uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
+      uint32_t timecounter_ticks_per_clock_tick =
+                             ( frequency * us_per_tick ) / 1000000;
+      /* Initialize hardware */
+      rtems_timecounter_simple_install(
+        &some_tc,
+        frequency,
+        timecounter_ticks_per_clock_tick,
+        some_tc_get_timecount
+      );
+    }
+    #define Clock_driver_support_initialize_hardware() \
+              some_support_initialize_hardware()
+    #define Clock_driver_timecounter_tick() \
+              some_tc_tick()
     #include "../../../shared/clockdrv_shell.h"
 …
 valid timestamps.  The hardware must provide a periodic interrupt to service
 the clock tick and a free running counter for the timecounter.  The free
+running counter must have a power of two period.  The ``tc_counter_mask``
+must be initialized to the free running counter period minus one, e.g. for a
+-bit counter this is 0xffffffff.  The ``tc_get_timecount`` function must
+return the current counter value (the counter values must increase, so if the
+counter counts down, a conversion is necessary).  Use``RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER`` for the ``tc_quality``.  Set``tc_frequency`` to the frequency of the free running counter in Hz.  All
+other fields of the ``struct timecounter`` must be zero initialized.
+Install the initialized timecounter via ``rtems_timecounter_install()``.
+.. code:: c
+running counter must have a power of two period.  The ``tc_counter_mask`` must
+be initialized to the free running counter period minus one, e.g. for a 32-bit
+counter this is 0xffffffff.  The ``tc_get_timecount`` function must return the
+current counter value (the counter values must increase, so if the counter
+counts down, a conversion is necessary).  Use
+``RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER`` for the ``tc_quality``.  Set
+``tc_frequency`` to the frequency of the free running counter in Hz.  All other
+fields of the ``struct timecounter`` must be zero initialized.  Install the
+initialized timecounter via ``rtems_timecounter_install()``.
+.. code-block:: c
     #include <rtems/timecounter.h>
     static struct timecounter some_tc;
+    static uint32_t some_tc_get_timecount( struct timecounter \*tc )
+    {
+    some.free_running_counter;
+    }
+    static uint32_t some_tc_get_timecount( struct timecounter *tc )
+    {
+      some.free_running_counter;
+    }
     static void some_support_initialize_hardware( void )
+    {
+    uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
+    uint32_t frequency = 123456;
+    /*
+    * The multiplication must be done in 64-bit arithmetic to avoid an integer
+    * overflow on targets with a high enough counter frequency.
+    \*/
+    uint32_t interval = (uint32_t) ( ( frequency * us_per_tick ) / 1000000 );
+    /*
+    * Initialize hardware and set up a periodic interrupt for the configuration
+    * based interval.
+    \*/
+    some_tc.tc_get_timecount = some_tc_get_timecount;
+    some_tc.tc_counter_mask = 0xffffffff;
+    some_tc.tc_frequency = frequency;
+    some_tc.tc_quality = RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER;
+    rtems_timecounter_install( &some_tc );
+    }
+    #define Clock_driver_support_initialize_hardware() \\
+    some_support_initialize_hardware()
+      uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
+      uint32_t frequency = 123456;
+      /*
+       * The multiplication must be done in 64-bit arithmetic to avoid an integer
+       * overflow on targets with a high enough counter frequency.
+       */
+      uint32_t interval = (uint32_t) ( ( frequency * us_per_tick ) / 1000000 );
+      /*
+       * Initialize hardware and set up a periodic interrupt for the configuration
+       * based interval.
+       */
+      some_tc.tc_get_timecount = some_tc_get_timecount;
+      some_tc.tc_counter_mask = 0xffffffff;
+      some_tc.tc_frequency = frequency;
+      some_tc.tc_quality = RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER;
+      rtems_timecounter_install( &some_tc );
+    }
+    #define Clock_driver_support_initialize_hardware() \
+              some_support_initialize_hardware()
     #include "../../../shared/clockdrv_shell.h"
 …
 The clock driver must provide a function to install the clock tick interrupt
 service routine via ``Clock_driver_support_install_isr()``.
+.. code:: c
+.. code-block:: c
     #include <bsp/irq.h>
     #include <bsp/fatal.h>
     static void some_support_install_isr( rtems_interrupt_handler isr )
+    {
+    rtems_status_code sc;
+    sc = rtems_interrupt_handler_install(
+    SOME_IRQ,
+    "Clock",
+    RTEMS_INTERRUPT_UNIQUE,
+    isr,
+    NULL
+    );
+    if ( sc != RTEMS_SUCCESSFUL ) {
+    bsp_fatal( SOME_FATAL_IRQ_INSTALL );
+    }
+    }
+    #define Clock_driver_support_install_isr( isr, old ) \\
+    some_support_install_isr( isr )
+      rtems_status_code sc;
+      sc = rtems_interrupt_handler_install(
+        SOME_IRQ,
+        "Clock",
+        RTEMS_INTERRUPT_UNIQUE,
+        isr,
+        NULL
+      );
+      if ( sc != RTEMS_SUCCESSFUL ) {
+        bsp_fatal( SOME_FATAL_IRQ_INSTALL );
+      }
+    }
+    #define Clock_driver_support_install_isr( isr, old ) \
+              some_support_install_isr( isr )
     #include "../../../shared/clockdrv_shell.h"
 …
 ---------------
+The hardware specific support at tick is specified by``Clock_driver_support_at_tick()``.
+.. code:: c
+The hardware specific support at tick is specified by
+``Clock_driver_support_at_tick()``.
+.. code-block:: c
     static void some_support_at_tick( void )
+    {
+    /* Clear interrupt \*/
+    }
+    #define Clock_driver_support_at_tick() \\
+    some_support_at_tick()
+      /* Clear interrupt */
+    }
+    #define Clock_driver_support_at_tick() \
+              some_support_at_tick()
     #include "../../../shared/clockdrv_shell.h"
 …
 The :dfn:`Clock Driver Shell` provides the routine ``Clock_exit()`` that is
+scheduled to be run during system shutdown via the ``atexit()`` routine.
+The hardware specific shutdown support is specified by``Clock_driver_support_shutdown_hardware()`` which is used by``Clock_exit()``.  It should disable the clock tick source if it was
+enabled.  This can be used to prevent clock ticks after the system is shutdown.
+.. code:: c
+scheduled to be run during system shutdown via the ``atexit()`` routine.  The
+hardware specific shutdown support is specified by
+``Clock_driver_support_shutdown_hardware()`` which is used by ``Clock_exit()``.
+It should disable the clock tick source if it was enabled.  This can be used to
+prevent clock ticks after the system is shutdown.
+.. code-block:: c
     static void some_support_shutdown_hardware( void )
+    {
+    /* Shutdown hardware \*/
+    }
+    #define Clock_driver_support_shutdown_hardware() \\
+    some_support_shutdown_hardware()
+      /* Shutdown hardware */
+    }
+    #define Clock_driver_support_shutdown_hardware() \
+              some_support_shutdown_hardware()
     #include "../../../shared/clockdrv_shell.h"
 …
 due to a limited range of the hardware timer), then this can be specified with
 the optional ``#define CLOCK_DRIVER_ISRS_PER_TICK`` and ``#define
+CLOCK_DRIVER_ISRS_PER_TICK_VALUE`` defines.  This is currently used only for x86
+and it hopefully remains that way.
+.. code:: c
+    /* Enable multiple clock driver ticks per clock tick \*/
+CLOCK_DRIVER_ISRS_PER_TICK_VALUE`` defines.  This is currently used only for
+x86 and it hopefully remains that way.
+.. code-block:: c
+    /* Enable multiple clock driver ticks per clock tick */
     #define CLOCK_DRIVER_ISRS_PER_TICK 1
+    /* Specifiy the clock driver ticks per clock tick value \*/
+    /* Specifiy the clock driver ticks per clock tick value */
     #define CLOCK_DRIVER_ISRS_PER_TICK_VALUE 123
     #include "../../../shared/clockdrv_shell.h"
 …
 This information is valuable when debugging a system.  This variable is
 declared as follows:
+.. code:: c
+.. code-block:: c
     volatile uint32_t Clock_driver_ticks;
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-.. COMMENT: All rights reserved.

bsp_howto/conf.py

-                      r54514fe
+                      r6d7a4d2
 from conf import *
+version = '1.0'
+release = '5.0'
+version = '4.11.0'
+release = '4.11.0'
+project = "RTEMS BSP and Device Driver Development Guide"
 latex_documents = [
         ('index', 'bsp_howto.tex', u'RTEMS BSP Howto Documentation', u'RTEMS Documentation Project', 'manual'),
+        ('index', 'bsp_howto.tex', u'RTEMS BSP and Device Driver Development Guide', u'RTEMS Documentation Project', 'manual'),
+]

bsp_howto/console.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Console Driver
 …
 ============
+This chapter describes the operation of a console driver using
+the RTEMS POSIX Termios support.  Traditionally RTEMS has referred
+to all serial device drivers as console device drivers.  A
+console driver can be used to do raw data processing in addition
+to the "normal" standard input and output device functions required
+of a console.
+The serial driver may be called as the consequence of a C Library
+call such as ``printf`` or ``scanf`` or directly via the``read`` or ``write`` system calls.
+This chapter describes the operation of a console driver using the RTEMS POSIX
+Termios support.  Traditionally RTEMS has referred to all serial device drivers
+as console device drivers.  A console driver can be used to do raw data
+processing in addition to the "normal" standard input and output device
+functions required of a console.
+The serial driver may be called as the consequence of a C Library call such as
+``printf`` or ``scanf`` or directly via the``read`` or ``write`` system calls.
 There are two main functioning modes:
 - console: formatted input/output, with special characters (end of
   line, tabulations, etc.) recognition and processing,
+- console: formatted input/output, with special characters (end of line,
+  tabulations, etc.) recognition and processing,
 - raw: permits raw data processing.
 One may think that two serial drivers are needed to handle these two types
 of data, but Termios permits having only one driver.
+One may think that two serial drivers are needed to handle these two types of
+data, but Termios permits having only one driver.
 Termios
 =======
 Termios is a standard for terminal management, included in the POSIX
+.1b standard.  As part of the POSIX and Open Group Single UNIX
+Specification, is commonly provided on UNIX implementations.  The
+Open Group has the termios portion of the POSIX standard online
+at http://opengroup.org/onlinepubs/007908775/xbd/termios.html.
+The requirements for the ``<termios.h>`` file are also provided
 and are at http://opengroup.org/onlinepubs/007908775/xsh/termios.h.html.
+Termios is a standard for terminal management, included in the POSIX 1003.1b
+standard.  As part of the POSIX and Open Group Single UNIX Specification, is
+commonly provided on UNIX implementations.  The Open Group has the termios
+portion of the POSIX standard online at
+http://opengroup.org/onlinepubs/007908775/xbd/termios.html.  The requirements
+for the ``<termios.h>`` file are also provided and are at
+http://opengroup.org/onlinepubs/007908775/xsh/termios.h.html.
 Having RTEMS support for Termios is beneficial because:
+- from the user's side because it provides standard primitive operations
+  to access the terminal and change configuration settings.  These operations
+  are the same under UNIX and RTEMS.
+- from the BSP developer's side because it frees the
+  developer from dealing with buffer states and mutual exclusions on them.
+  Early RTEMS console device drivers also did their own special
+  character processing.
+- from the user's side because it provides standard primitive operations to
+  access the terminal and change configuration settings.  These operations are
+  the same under UNIX and RTEMS.
+- from the BSP developer's side because it frees the developer from dealing
+  with buffer states and mutual exclusions on them.  Early RTEMS console device
+  drivers also did their own special character processing.
 - it is part of an internationally recognized standard.
 …
 - raw and console handling,
+- blocking or non-blocking characters receive, with or without
+  Timeout.
+At this time, RTEMS documentation does not include a thorough discussion
+of the Termios functionality.  For more information on Termios,
+type ``man termios`` on a Unix box or point a web browser
+athttp://www.freebsd.org/cgi/man.cgi.
+- blocking or non-blocking characters receive, with or without Timeout.
+At this time, RTEMS documentation does not include a thorough discussion of the
+Termios functionality.  For more information on Termios, type ``man termios``
+on a Unix box or point a web browser athttp://www.freebsd.org/cgi/man.cgi.
 Driver Functioning Modes
 …
 - task driven mode
+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 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,
+the software will continuously check the status of the UART when
+it is reading or writing to the UART.  Termios improves on this
+by delaying the caller for 1 clock tick between successive checks
+of the UART on a read operation.
+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 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, the software
+will continuously check the status of the UART when it is reading or writing to
+the UART.  Termios improves on this by delaying the caller for 1 clock tick
+between successive checks of the UART on a read operation.
 In interrupt driven mode, the processor does not block on sending/receiving
+characters.  Data is buffered between the interrupt service routine
+and application code.  Two buffers are used to insulate the application
+from the relative slowness of the serial device.  One of the buffers is
+used for incoming characters, while the other is used for outgoing characters.
+An interrupt is raised when a character is received by the UART.
+The interrupt subroutine places the incoming character at the end
+of the input buffer.  When an application asks for input,
+the characters at the front of the buffer are returned.
+When the application prints to the serial device, the outgoing characters
+are placed at the end of the output buffer.  The driver will place
+one or more characters in the UART (the exact number depends on the UART)
+An interrupt will be raised when all the characters have been transmitted.
+The interrupt service routine has to send the characters
+remaining in the output buffer the same way.   When the transmitting side
+of the UART is idle, it is typically necessary to prime the transmitter
+before the first interrupt will occur.
+characters.  Data is buffered between the interrupt service routine and
+application code.  Two buffers are used to insulate the application from the
+relative slowness of the serial device.  One of the buffers is used for
+incoming characters, while the other is used for outgoing characters.
+An interrupt is raised when a character is received by the UART.  The interrupt
+subroutine places the incoming character at the end of the input buffer.  When
+an application asks for input, the characters at the front of the buffer are
+returned.
+When the application prints to the serial device, the outgoing characters are
+placed at the end of the output buffer.  The driver will place one or more
+characters in the UART (the exact number depends on the UART) An interrupt will
+be raised when all the characters have been transmitted.  The interrupt service
+routine has to send the characters remaining in the output buffer the same way.
+When the transmitting side of the UART is idle, it is typically necessary to
+prime the transmitter before the first interrupt will occur.
 The task driven mode is similar to interrupt driven mode, but the actual data
 …
 ==================================
 The following Figure shows how a Termios driven serial driver works:
 Figure not included in ASCII version
+The following Figure shows how a Termios driven serial driver works: Figure not
+included in ASCII version
 The following list describes the basic flow.
+- the application programmer uses standard C library call (printf,
+  scanf, read, write, etc.),
+- C library (ctx.g. RedHat (formerly Cygnus) Newlib) calls
+  the RTEMS system call interface.  This code can be found in the:file:`cpukit/libcsupport/src` directory.
+- the application programmer uses standard C library call (printf, scanf, read,
+  write, etc.),
+- C library (ctx.g. RedHat (formerly Cygnus) Newlib) calls the RTEMS system
+  call interface.  This code can be found in the:file:`cpukit/libcsupport/src`
+  directory.
 - Glue code calls the serial driver entry routines.
 …
 functions are deprecated:
+- ``rtems_termios_open()`` - use ``rtems_termios_device_open()`` in
+  combination with ``rtems_termios_device_install()`` instead.
+- ``rtems_termios_close()`` - use ``rtems_termios_device_close()``
+  instead.
+- ``rtems_termios_open()`` - use ``rtems_termios_device_open()`` in combination
+  with ``rtems_termios_device_install()`` instead.
+- ``rtems_termios_close()`` - use ``rtems_termios_device_close()`` instead.
 This manual describes the new API.  A new console driver should consist of
 three parts.
+# The basic console driver functions using the Termios support.  Add this
   the BSPs Makefile.am:
+  .. code:: c
+- The basic console driver functions using the Termios support.  Add this the
+  BSPs Makefile.am:
+.. code-block:: makefile
       [...]
       libbsp_a_SOURCES += ../../shared/console-termios.c
       \[...]
+# A general serial module specific low-level driver providing the handler
   table for the Termios ``rtems_termios_device_install()`` function.  This
   low-level driver could be used for more than one BSP.
+# A BSP specific initialization routine ``console_initialize()``, that
   calls ``rtems_termios_device_install()`` providing a low-level driver
   context for each installed device.
+      [...]
+- A general serial module specific low-level driver providing the handler table
+  for the Termios ``rtems_termios_device_install()`` function.  This low-level
+  driver could be used for more than one BSP.
+- A BSP specific initialization routine ``console_initialize()``, that calls
+  ``rtems_termios_device_install()`` providing a low-level driver context for
+  each installed device.
 You need to provide a device handler structure for the Termios device
 …
 If you want to use polled IO it should look like the following.  Termios must
 be told the addresses of the handler that are to be used for simple character
+IO, i.e. pointers to the ``my_driver_poll_read()`` and``my_driver_poll_write()`` functions described later in `Termios and Polled IO`_.
+.. code:: c
+IO, i.e. pointers to the ``my_driver_poll_read()`` and
+``my_driver_poll_write()`` functions described later in `Termios and Polled
+IO`_.
+.. code-block:: c
     const rtems_termios_handler my_driver_handler_polled = {
     .first_open = my_driver_first_open,
     .last_close = my_driver_last_close,
     .poll_read = my_driver_poll_read,
     .write = my_driver_poll_write,
     .set_attributes = my_driver_set_attributes,
     .stop_remote_tx = NULL,
     .start_remote_tx = NULL,
     .mode = TERMIOS_POLLED
+      .first_open = my_driver_first_open,
+      .last_close = my_driver_last_close,
+      .poll_read = my_driver_poll_read,
+      .write = my_driver_poll_write,
+      .set_attributes = my_driver_set_attributes,
+      .stop_remote_tx = NULL,
+      .start_remote_tx = NULL,
+      .mode = TERMIOS_POLLED
+    }
 …
 handler to be passed to Termios.  Indeed a ``console_read()`` call returns the
 contents of Termios input buffer.  This buffer is filled in the driver
+interrupt subroutine, see also `Termios and Interrupt Driven IO`_.  The driver
+is responsible for providing a pointer to the``my_driver_interrupt_write()`` function.
+.. code:: c
+interrupt subroutine, see also `Termios and Interrupt Driven IO`_.  The driver
+is responsible for providing a pointer to the``my_driver_interrupt_write()``
+function.
+.. code-block:: c
     const rtems_termios_handler my_driver_handler_interrupt = {
     .first_open = my_driver_first_open,
     .last_close = my_driver_last_close,
     .poll_read = NULL,
     .write = my_driver_interrupt_write,
     .set_attributes = my_driver_set_attributes,
     .stopRemoteTx = NULL,
     .stop_remote_tx = NULL,
     .start_remote_tx = NULL,
     .mode = TERMIOS_IRQ_DRIVEN
+      .first_open = my_driver_first_open,
+      .last_close = my_driver_last_close,
+      .poll_read = NULL,
+      .write = my_driver_interrupt_write,
+      .set_attributes = my_driver_set_attributes,
+      .stopRemoteTx = NULL,
+      .stop_remote_tx = NULL,
+      .start_remote_tx = NULL,
+      .mode = TERMIOS_IRQ_DRIVEN
     };
+You can also provide hander for remote transmission control.  This
+is not covered in this manual, so they are set to ``NULL`` in the above
+examples.
+You can also provide hander for remote transmission control.  This is not
+covered in this manual, so they are set to ``NULL`` in the above examples.
 The low-level driver should provide a data structure for its device context.
+The initialization routine must provide a context for each installed device via``rtems_termios_device_install()``.  For simplicity of the console
+initialization example the device name is also present.  Her is an example header file.
+.. code:: c
+The initialization routine must provide a context for each installed device via
+``rtems_termios_device_install()``.  For simplicity of the console
+initialization example the device name is also present.  Here is an example
+header file.
+.. code-block:: c
     #ifndef MY_DRIVER_H
     #define MY_DRIVER_H
     #include <rtems/termiostypes.h>
     #include <some-chip-header.h>
     /* Low-level driver specific data structure \*/
     typedef struct {
     rtems_termios_device_context base;
     const char \*device_name;
     volatile module_register_block \*regs;
     /* More stuff \*/
+      rtems_termios_device_context base;
+      const char \*device_name;
+      volatile module_register_block \*regs;
+      /* More stuff \*/
     } my_driver_context;
     extern const rtems_termios_handler my_driver_handler_polled;
     extern const rtems_termios_handler my_driver_handler_interrupt;
     #endif /* MY_DRIVER_H \*/
 Termios and Polled IO
 …
 The ``my_driver_poll_write()`` routine is responsible for writing ``n``
 characters from ``buf`` to the serial device specified by ``tty``.
+.. code:: c
+.. code-block:: c
     static void my_driver_poll_write(
     rtems_termios_device_context \*base,
     const char                   \*buf,
     size_t                        n
+    )
+    {
     my_driver_context \*ctx = (my_driver_context \*) base;
     size_t i;
     /* Write \*/
     for (i = 0; i < n; ++i) {
     my_driver_write_char(ctx, buf[i]);
+    }
+      rtems_termios_device_context *base,
+      const char                   *buf,
+      size_t                        n
+    )
+    {
+      my_driver_context *ctx = (my_driver_context *) base;
+      size_t i;
+      /* Write */
+      for (i = 0; i < n; ++i) {
+        my_driver_write_char(ctx, buf[i]);
+      }
+    }
 …
 character from the serial device specified by ``tty``.  If no character is
 available, then the routine should return minus one.
+.. code:: c
+    static int my_driver_poll_read(rtems_termios_device_context \*base)
+    {
+    my_driver_context \*ctx = (my_driver_context \*) base;
+    /* Check if a character is available \*/
+    if (my_driver_can_read_char(ctx)) {
+    /* Return the character \*/
+    return my_driver_read_char(ctx);
+    } else {
+    /* Return an error status \*/
+    return -1;
+    }
+.. code-block:: c
+    static int my_driver_poll_read(rtems_termios_device_context *base)
+    {
+      my_driver_context *ctx = (my_driver_context *) base;
+      /* Check if a character is available */
+      if (my_driver_can_read_char(ctx)) {
+        /* Return the character */
+        return my_driver_read_char(ctx);
+      } else {
+        /* Return an error status */
+        return -1;
+      }
+    }
 …
 In the simplest case, the ``my_driver_interrupt_handler()`` will have to check
 the status of the UART and determine what caused the interrupt.  The following
+describes the operation of an ``my_driver_interrupt_handler`` which has to
+do this:
+.. code:: c
+describes the operation of an ``my_driver_interrupt_handler`` which has to do
+this:
+.. code-block:: c
     static void my_driver_interrupt_handler(
+    rtems_vector_number  vector,
+    void                \*arg
+    )
+    {
+    rtems_termios_tty \*tty = arg;
+    my_driver_context \*ctx = rtems_termios_get_device_context(tty);
+    char buf[N];
+    size_t n;
+    /*
+    * Check if we have received something.  The function reads the
+    * received characters from the device and stores them in the
+    * buffer.  It returns the number of read characters.
+    \*/
+    n = my_driver_read_received_chars(ctx, buf, N);
+    if (n > 0) {
+    /* Hand the data over to the Termios infrastructure \*/
+    rtems_termios_enqueue_raw_characters(tty, buf, n);
+    }
+    /*
+    * Check if we have something transmitted.  The functions returns
+    * the number of transmitted characters since the last write to the
+    * device.
+    \*/
+    n = my_driver_transmitted_chars(ctx);
+    if (n > 0) {
+    /*
+    * Notify Termios that we have transmitted some characters.  It
+    * will call now the interrupt write function if more characters
+    * are ready for transmission.
+    \*/
+    rtems_termios_dequeue_characters(tty, n);
+    }
+      rtems_vector_number  vector,
+      void                *arg
+    )
+    {
+      rtems_termios_tty *tty = arg;
+      my_driver_context *ctx = rtems_termios_get_device_context(tty);
+      char buf[N];
+      size_t n;
+      /*
+       * Check if we have received something.  The function reads the
+       * received characters from the device and stores them in the
+       * buffer.  It returns the number of read characters.
+       */
+      n = my_driver_read_received_chars(ctx, buf, N);
+      if (n > 0) {
+        /* Hand the data over to the Termios infrastructure */
+        rtems_termios_enqueue_raw_characters(tty, buf, n);
+      }
+      /*
+       * Check if we have something transmitted.  The functions returns
+       * the number of transmitted characters since the last write to the
+       * device.
+       */
+      n = my_driver_transmitted_chars(ctx);
+      if (n > 0) {
+        /*
+         * Notify Termios that we have transmitted some characters.  It
+         * will call now the interrupt write function if more characters
+         * are ready for transmission.
+         */
+        rtems_termios_dequeue_characters(tty, n);
+      }
+    }
 The ``my_driver_interrupt_write()`` function is responsible for telling the
 device that the ``n`` characters at ``buf`` are to be transmitted.  It
+the value ``n`` is zero to indicate that no more characters are to send.
+The driver can disable the transmit interrupts now.  This routine is invoked
+either from task context with disabled interrupts to start a new transmission
 process with exactly one character in case of an idle output state or from the
+device that the ``n`` characters at ``buf`` are to be transmitted.  It the
+value ``n`` is zero to indicate that no more characters are to send.  The
+driver can disable the transmit interrupts now.  This routine is invoked either
+from task context with disabled interrupts to start a new transmission process
+with exactly one character in case of an idle output state or from the
 interrupt handler to refill the transmitter.  If the routine is invoked to
 start the transmit process the output state will become busy and Termios starts
 …
 able to fill the transmit buffer you will end up with one interrupt per
 character.
+.. code:: c
+.. code-block:: c
     static void my_driver_interrupt_write(
+    rtems_termios_device_context  \*base,
+    const char                    \*buf,
+    size_t                         n
+    )
+    {
+    my_driver_context \*ctx = (my_driver_context \*) base;
+    /*
+    * Tell the device to transmit some characters from buf (less than
+    * or equal to n).  When the device is finished it should raise an
+    * interrupt.  The interrupt handler will notify Termios that these
+    * characters have been transmitted and this may trigger this write
+    * function again.  You may have to store the number of outstanding
+    * characters in the device data structure.
+    \*/
+    /*
+    * Termios will set n to zero to indicate that the transmitter is
+    * now inactive.  The output buffer is empty in this case.  The
+    * driver may disable the transmit interrupts now.
+    \*/
+      rtems_termios_device_context  *base,
+      const char                    *buf,
+      size_t                         n
+    )
+    {
+      my_driver_context *ctx = (my_driver_context *) base;
+      /*
+       * Tell the device to transmit some characters from buf (less than
+       * or equal to n).  When the device is finished it should raise an
+       * interrupt.  The interrupt handler will notify Termios that these
+       * characters have been transmitted and this may trigger this write
+       * function again.  You may have to store the number of outstanding
+       * characters in the device data structure.
+       */
+      /*
+       * Termios will set n to zero to indicate that the transmitter is
+       * now inactive.  The output buffer is empty in this case.  The
+       * driver may disable the transmit interrupts now.
+       */
+    }
 …
 The ``console_initialize()`` function may look like this:
+.. code:: c
+.. code-block:: c
     #include <my-driver.h>
 …
     #include <bsp.h>
     #include <bsp/fatal.h>
+    static my_driver_context driver_context_table[M] = { /* Some values \*/ };
+    static my_driver_context driver_context_table[M] = { /* Some values */ };
     rtems_device_driver console_initialize(
+    rtems_device_major_number  major,
+    rtems_device_minor_number  minor,
+    void                      \*arg
+    )
+    {
+    rtems_status_code sc;
+    #ifdef SOME_BSP_USE_INTERRUPTS
+    const rtems_termios_handler \*handler = &my_driver_handler_interrupt;
+    #else
+    const rtems_termios_handler \*handler = &my_driver_handler_polled;
+    #endif
+    /*
+    * Initialize the Termios infrastructure.  If Termios has already
+    * been initialized by another device driver, then this call will
+    * have no effect.
+    \*/
+    rtems_termios_initialize();
+    /* Initialize each device \*/
+    for (
+    minor = 0;
+    minor < RTEMS_ARRAY_SIZE(driver_context_table);
+    ++minor
+    ) {
+    my_driver_context \*ctx = &driver_context_table[minor];
+    /*
+    * Install this device in the file system and Termios.  In order
+    * to use the console (i.e. being able to do printf, scanf etc.
+    * on stdin, stdout and stderr), one device must be registered as
+    * "/dev/console" (CONSOLE_DEVICE_NAME).
+    \*/
+    sc = rtems_termios_device_install(
+    ctx->device_name,
+    major,
+    minor,
+    handler,
+    NULL,
+    ctx
+    );
+    if (sc != RTEMS_SUCCESSFUL) {
+    bsp_fatal(SOME_BSP_FATAL_CONSOLE_DEVICE_INSTALL);
+    }
+    }
+    return RTEMS_SUCCESSFUL;
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor,
+      void                      *arg
+    )
+    {
+      rtems_status_code sc;
+      #ifdef SOME_BSP_USE_INTERRUPTS
+        const rtems_termios_handler *handler = &my_driver_handler_interrupt;
+      #else
+        const rtems_termios_handler *handler = &my_driver_handler_polled;
+      #endif
+      /*
+       * Initialize the Termios infrastructure.  If Termios has already
+       * been initialized by another device driver, then this call will
+       * have no effect.
+       */
+      rtems_termios_initialize();
+      /* Initialize each device */
+      for (
+        minor = 0;
+        minor < RTEMS_ARRAY_SIZE(driver_context_table);
+        ++minor
+      ) {
+        my_driver_context *ctx = &driver_context_table[minor];
+        /*
+         * Install this device in the file system and Termios.  In order
+         * to use the console (i.e. being able to do printf, scanf etc.
+         * on stdin, stdout and stderr), one device must be registered as
+         * "/dev/console" (CONSOLE_DEVICE_NAME).
+         */
+        sc = rtems_termios_device_install(
+          ctx->device_name,
+          major,
+          minor,
+          handler,
+          NULL,
+          ctx
+        );
+        if (sc != RTEMS_SUCCESSFUL) {
+          bsp_fatal(SOME_BSP_FATAL_CONSOLE_DEVICE_INSTALL);
+        }
+      }
+      return RTEMS_SUCCESSFUL;
+    }
 …
 -----------------------
+The ``console_open()`` function provided by :file:`console-termios.c` is
+called whenever a serial device is opened.  The device registered as``"/dev/console"`` (``CONSOLE_DEVICE_NAME``) is opened automatically
+during RTEMS initialization.  For instance, if UART channel 2 is registered as``"/dev/tty1"``, the ``console_open()`` entry point will be called as the
+The ``console_open()`` function provided by :file:`console-termios.c` is called
+whenever a serial device is opened.  The device registered as
+``"/dev/console"`` (``CONSOLE_DEVICE_NAME``) is opened automatically during
+RTEMS initialization.  For instance, if UART channel 2 is registered as
+``"/dev/tty1"``, the ``console_open()`` entry point will be called as the
 result of an ``fopen("/dev/tty1", mode)`` in the application.
+During the first open of the device Termios will call the``my_driver_first_open()`` handler.
+.. code:: c
+During the first open of the device Termios will call the
+``my_driver_first_open()`` handler.
+.. code-block:: c
     static bool my_driver_first_open(
+    rtems_termios_tty             \*tty,
+    rtems_termios_device_context  \*base,
+    struct termios                \*term,
+    rtems_libio_open_close_args_t \*args
+    )
+    {
+    my_driver_context \*ctx = (my_driver_context \*) base;
+    rtems_status_code sc;
+    bool ok;
+    /*
+    * You may add some initialization code here.
+    \*/
+    /*
+    * Sets the initial baud rate.  This should be set to the value of
+    * the boot loader.  This function accepts only exact Termios baud
+    * values.
+    \*/
+    sc = rtems_termios_set_initial_baud(tty, MY_DRIVER_BAUD_RATE);
+    if (sc != RTEMS_SUCCESSFUL) {
+    /* Not a valid Termios baud \*/
+    }
+    /*
+    * Alternatively you can set the best baud.
+    \*/
+    rtems_termios_set_best_baud(term, MY_DRIVER_BAUD_RATE);
+    /*
+    * To propagate the initial Termios attributes to the device use
+    * this.
+    \*/
+    ok = my_driver_set_attributes(base, term);
+    if (!ok) {
+    /* This is bad \*/
+    }
+    /*
+    * Return true to indicate a successful set attributes, and false
+    * otherwise.
+    \*/
+    return true;
+      rtems_termios_tty             *tty,
+      rtems_termios_device_context  *base,
+      struct termios                *term,
+      rtems_libio_open_close_args_t *args
+    )
+    {
+      my_driver_context *ctx = (my_driver_context *) base;
+      rtems_status_code sc;
+      bool ok;
+      /*
+       * You may add some initialization code here.
+       */
+      /*
+       * Sets the initial baud rate.  This should be set to the value of
+       * the boot loader.  This function accepts only exact Termios baud
+       * values.
+       */
+      sc = rtems_termios_set_initial_baud(tty, MY_DRIVER_BAUD_RATE);
+      if (sc != RTEMS_SUCCESSFUL) {
+        /* Not a valid Termios baud */
+      }
+      /*
+       * Alternatively you can set the best baud.
+       */
+      rtems_termios_set_best_baud(term, MY_DRIVER_BAUD_RATE);
+      /*
+       * To propagate the initial Termios attributes to the device use
+       * this.
+      */
+      ok = my_driver_set_attributes(base, term);
+      if (!ok) {
+        /* This is bad */
+      }
+      /*
+       * Return true to indicate a successful set attributes, and false
+       * otherwise.
+       */
+      return true;
+    }
 …
 Termios will call the ``my_driver_last_close()`` handler if the last close
 happens on the device.
+.. code:: c
+.. code-block:: c
     static void my_driver_last_close(
+    rtems_termios_tty             \*tty,
+    rtems_termios_device_context  \*base,
+    rtems_libio_open_close_args_t \*args
+    )
+    {
+    my_driver_context \*ctx = (my_driver_context \*) base;
+    /*
+    * The driver may do some cleanup here.
+    \*/
+      rtems_termios_tty             *tty,
+      rtems_termios_device_context  *base,
+      rtems_libio_open_close_args_t *args
+    )
+    {
+      my_driver_context *ctx = (my_driver_context *) base;
+      /*
+       * The driver may do some cleanup here.
+      */
+    }
 …
 -------------------------------
 The ``console_control()`` provided by :file:`console-termios.c` is invoked
+when the line parameters for a particular serial device are to be changed.
 This entry point corresponds to the device driver IO control entry point.
+The ``console_control()`` provided by :file:`console-termios.c` is invoked when
+the line parameters for a particular serial device are to be changed.  This
+entry point corresponds to the device driver IO control entry point.
 The application writer is able to control the serial line configuration with
 Termios calls (such as the ``ioctl()`` command, see the Termios
+documentation for more details).  If the driver is to support dynamic
+configuration, then it must have the ``console_control()`` piece of code.
+Basically ``ioctl()`` commands call ``console_control()`` with the serial
 line configuration in a Termios defined data structure.
+Termios calls (such as the ``ioctl()`` command, see the Termios documentation
+for more details).  If the driver is to support dynamic configuration, then it
+must have the ``console_control()`` piece of code.  Basically ``ioctl()``
+commands call ``console_control()`` with the serial line configuration in a
+Termios defined data structure.
 The driver is responsible for reinitializing the device with the correct
 settings.  For this purpose Termios calls the ``my_driver_set_attributes()``
 handler.
+.. code:: c
+.. code-block:: c
     static bool my_driver_set_attributes(
+    rtems_termios_device_context \*base,
+    const struct termios         \*term
+    )
+    {
+    my_driver_context \*ctx = (my_driver_context \*) base;
+    /*
+    * Inspect the termios data structure and configure the device
+    * appropriately.  The driver should only be concerned with the
+    * parts of the structure that specify hardware setting for the
+    * communications channel such as baud, character size, etc.
+    \*/
+    /*
+    * Return true to indicate a successful set attributes, and false
+    * otherwise.
+    \*/
+    return true;
+    }
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+      rtems_termios_device_context *base,
+      const struct termios         *term
+    )
+    {
+      my_driver_context *ctx = (my_driver_context *) base;
+      /*
+       * Inspect the termios data structure and configure the device
+       * appropriately.  The driver should only be concerned with the
+       * parts of the structure that specify hardware setting for the
+       * communications channel such as baud, character size, etc.
+       */
+      /*
+       * Return true to indicate a successful set attributes, and false
+       * otherwise.
+       */
+      return true;
+    }

bsp_howto/discrete.rst

-                      r54514fe
+                      r6d7a4d2
 ###############
+The Discrete driver is responsible for providing an
+interface to Discrete Input/Outputs.  The capabilities provided
+by this class of device driver are:
+The Discrete driver is responsible for providing an interface to Discrete
+Input/Outputs.  The capabilities provided by this class of device driver are:
 - Initialize a Discrete I/O Board
 …
 - Reinitialize DACS
 Most discrete I/O devices are found on I/O cards that support many
+bits of discrete I/O on a single card.  This driver model is centered
 on the notion of reading bitfields from the card.
+Most discrete I/O devices are found on I/O cards that support many bits of
+discrete I/O on a single card.  This driver model is centered on the notion of
+reading bitfields from the card.
+There are currently no discrete I/O device drivers included in the
+RTEMS source tree.  The information provided in this chapter
+is based on drivers developed for applications using RTEMS.
+It is hoped that this driver model information can form the
+discrete I/O driver model that can be supported in future RTEMS
+There are currently no discrete I/O device drivers included in the RTEMS source
+tree.  The information provided in this chapter is based on drivers developed
+for applications using RTEMS.  It is hoped that this driver model information
+can form the discrete I/O driver model that can be supported in future RTEMS
 distribution.
 …
 =======================
 The *major* number of a device driver is its index in the
 RTEMS Device Address Table.
+The ``major`` number of a device driver is its index in the RTEMS Device
+Address Table.
+A *minor* number is associated with each device instance
+managed by a particular device driver.  An RTEMS minor number
+is an ``unsigned32`` entity.  Convention calls for
+dividing the bits in the minor number down into categories
+that specify a particular bitfield.  This results in categories
+like the following:
+A ``minor`` number is associated with each device instance managed by a
+particular device driver.  An RTEMS minor number is an ``unsigned32`` entity.
+Convention calls for dividing the bits in the minor number down into categories
+that specify a particular bitfield.  This results in categories like the
+following:
 - *board* - indicates the board a particular bitfield is located on
+- ``board`` - indicates the board a particular bitfield is located on
 - *word* - indicates the particular word of discrete bits the
   bitfield is located within
+- ``word`` - indicates the particular word of discrete bits the bitfield is
+  located within
 - *start* - indicates the starting bit of the bitfield
+- ``start`` - indicates the starting bit of the bitfield
 - *width* - indicates the width of the bitfield
+- ``width`` - indicates the width of the bitfield
 From the above, it should be clear that a single device driver
+can support multiple copies of the same board in a single system.
 The minor number is used to distinguish the devices.
+From the above, it should be clear that a single device driver can support
+multiple copies of the same board in a single system.  The minor number is used
+to distinguish the devices.
 By providing a way to easily access a particular bitfield from
+the device driver, the application is insulated with knowing how
 to mask fields in and out of a discrete I/O.
+By providing a way to easily access a particular bitfield from the device
+driver, the application is insulated with knowing how to mask fields in and out
+of a discrete I/O.
 Discrete I/O Driver Configuration
 =================================
+There is not a standard discrete I/O driver configuration table but some
+fields are common across different drivers.  The discrete I/O driver
+configuration table is typically an array of structures with each
+structure containing the information for a particular board.
+The following is a list of the type of information normally required
+to configure an discrete I/O board:
+There is not a standard discrete I/O driver configuration table but some fields
+are common across different drivers.  The discrete I/O driver configuration
+table is typically an array of structures with each structure containing the
+information for a particular board.  The following is a list of the type of
+information normally required to configure an discrete I/O board:
+*board_offset*
+``board_offset``
     is the base address of a board.
+*relay_initial_values*
     is an array of the values that should be written to each output
     word on the board during initialization.  This allows the driver
     to start with the board's output  in a known state.
+``relay_initial_values``
+    is an array of the values that should be written to each output word on the
+    board during initialization.  This allows the driver to start with the
+    board's output in a known state.
 Initialize a Discrete I/O Board
 …
 At system initialization, the discrete I/O 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
 outputs to their configured initial state.
+will be invoked.  As part of initialization, the driver will perform whatever
+board initializatin is required and then set all outputs to their configured
+initial state.
 The discrete I/O driver may register a device name for bitfields of
+particular interest to the system.  Normally this will be restricted
 to the names of each word and, if the driver supports it, an "all words".
+The discrete I/O driver may register a device name for bitfields of particular
+interest to the system.  Normally this will be restricted to the names of each
+word and, if the driver supports it, an "all words".
 Open a Particular Discrete Bitfield
 …
 With some drivers, it may be necessary to allocate memory when a particular
 device is opened.  If that is the case, then this is often the place
 to do this operation.
+device is opened.  If that is the case, then this is often the place to do this
+operation.
 Close a Particular Discrete Bitfield
 …
 With some drivers, it may be necessary to allocate memory when a particular
 device is opened.  If that is the case, then this is the place
 where that memory should be deallocated.
+device is opened.  If that is the case, then this is the place where that
+memory should be deallocated.
 Read from a Particular Discrete Bitfield
 ========================================
+This corresponds to the driver read call.  After validating the minor
+number and arguments, this call reads the indicated bitfield.  A
+discrete I/O devices may have to store the last value written to
+a discrete output.  If the bitfield is output only, saving the last
+written value gives the appearance that it can be read from also.
+If the bitfield is input, then it is sampled.
+This corresponds to the driver read call.  After validating the minor number
+and arguments, this call reads the indicated bitfield.  A discrete I/O devices
+may have to store the last value written to a discrete output.  If the bitfield
+is output only, saving the last written value gives the appearance that it can
+be read from also.  If the bitfield is input, then it is sampled.
+*NOTE:* Many discrete inputs have a tendency to bounce.  The application
+may have to take account for bounces.
+.. note::
+The value returned is an ``unsigned32`` number
 representing the bitfield read.  This value is stored in the``argument_block`` passed in to the call.
+   Many discrete inputs have a tendency to bounce.  The application may have to
+   take account for bounces.
+*NOTE:* Some discrete I/O drivers have a special minor number
+used to access all discrete I/O bits on the board.  If this special
+minor is used, then the area pointed to by ``argument_block`` must
+be the correct size.
+The value returned is an ``unsigned32`` number representing the bitfield read.
+This value is stored in the ``argument_block`` passed in to the call.
+.. note::
+   Some discrete I/O drivers have a special minor number used to access all
+   discrete I/O bits on the board.  If this special minor is used, then the
+   area pointed to by ``argument_block`` must be the correct size.
 Write to a Particular Discrete Bitfield
 =======================================
 This corresponds to the driver write call.  After validating the minor
 number and arguments, this call writes the indicated device.  If the
 specified device is an ADC, then an error is usually returned.
+This corresponds to the driver write call.  After validating the minor number
+and arguments, this call writes the indicated device.  If the specified device
+is an ADC, then an error is usually returned.
 The value written is an ``unsigned32`` number
+representing the value to be written to the specified
 bitfield.  This value is stored in the``argument_block`` passed in to the call.
+The value written is an ``unsigned32`` number representing the value to be
+written to the specified bitfield.  This value is stored in the
+``argument_block`` passed in to the call.
+*NOTE:* Some discrete I/O drivers have a special minor number
+used to access all discrete I/O bits on the board.  If this special
+minor is used, then the area pointed to by ``argument_block`` must
+be the correct size.
+.. note::
+   Some discrete I/O drivers have a special minor number used to access all
+   discrete I/O bits on the board.  If this special minor is used, then the
+   area pointed to by ``argument_block`` must be the correct size.
 Disable Discrete Outputs
 ========================
 This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
 the discrete outputs are disabled.
+This is one of the IOCTL functions supported by the I/O control device driver
+entry point.  When this IOCTL function is invoked, the discrete outputs are
+disabled.
+*NOTE:* It may not be possible to disable/enable discrete output on all
+discrete I/O boards.
+.. note::
+   It may not be possible to disable/enable discrete output on all discrete I/O
+   boards.
 Enable Discrete Outputs
 =======================
 This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
 the discrete outputs are enabled.
+This is one of the IOCTL functions supported by the I/O control device driver
+entry point.  When this IOCTL function is invoked, the discrete outputs are
+enabled.
+*NOTE:* It may not be possible to disable/enable discrete output on all
+discrete I/O boards.
+.. note::
+    It may not be possible to disable/enable discrete output on all discrete
+    I/O boards.
 Reinitialize Outputs
 ====================
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+the discrete outputs are rewritten with the configured initial
+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 discrete outputs are
+rewritten with the configured initial output values.
 Get Last Written 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 following information is returned to the caller:
+This is one of the IOCTL functions supported by the I/O control device driver
+entry point.  When this IOCTL function is invoked, the following information is
+returned to the caller:
 - last value written to the specified output word
 - timestamp of when the last write was performed

bsp_howto/frame_buffer.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Frame Buffer Driver
 ###################
+In this chapter, we present the basic functionality implemented by a
+frame buffer driver: ``frame_buffer_initialize()``, ``frame_buffer_open()``,``frame_buffer_close()``, ``frame_buffer_read()``, ``frame_buffer_write()``
+and ``frame_buffer_control()``.
+In this chapter, we present the basic functionality implemented by a frame
+buffer driver:
+- ``frame_buffer_initialize()``
+- ``frame_buffer_open()``
+- ``frame_buffer_close()``
+- ``frame_buffer_read()``
+- ``frame_buffer_write()``
+- ``frame_buffer_control()``
 Introduction
 …
 The purpose of the frame buffer driver is to provide an abstraction for
+graphics hardware.
+By using the frame buffer interface, an application can display graphics
+without knowing anything about the low-level details of interfacing to a
+particular graphics adapter. The parameters governing the mapping of
+memory to displayed pixels (planar or linear, bit depth, etc) is still
+implementation-specific, but device-independent methods are provided to
+graphics hardware.  By using the frame buffer interface, an application can
+display graphics without knowing anything about the low-level details of
+interfacing to a particular graphics adapter. The parameters governing the
+mapping of memory to displayed pixels (planar or linear, bit depth, etc) is
+still implementation-specific, but device-independent methods are provided to
 determine and potentially modify these parameters.
+The frame buffer driver is commonly located in the ``console``
+directory of the BSP and registered by the name */dev/fb0*.
+Additional frame buffers (if available) are named */dev/fb1*,*/dev/fb2*, etc.
+To work with the frame buffer, the following operation sequence is used:``open()``, ``ioctls()`` to get the frame buffer info, ``read()`` and/or``write()``, and ``close()``.
+The frame buffer driver is commonly located in the ``console`` directory of the
+BSP and registered by the name :file:`/dev/fb0`.  Additional frame buffers (if
+available) are named :file:`/dev/fb1*,*/dev/fb2`, etc.
+To work with the frame buffer, the following operation sequence is
+used:``open()``, ``ioctls()`` to get the frame buffer info, ``read()``
+and/or ``write()``, and ``close()``.
 Driver Function Overview
 …
 The driver initialization is called once during the RTEMS initialization
 process and returns RTEMS_SUCCESSFUL when the device driver is successfully
 initialized. During the initialization, a name is assigned to the frame
+buffer device.  If the graphics hardware supports console text output,
+as is the case with the pc386 VGA hardware, initialization into graphics
 mode may be deferred until the device is ``open()`` ed.
+process and returns ``RTEMS_SUCCESSFUL`` when the device driver is successfully
+initialized. During the initialization, a name is assigned to the frame buffer
+device.  If the graphics hardware supports console text output, as is the case
+with the pc386 VGA hardware, initialization into graphics mode may be deferred
+until the device is ``open()`` ed.
 The ``frame_buffer_initialize()`` function may look like this:
 .. code:: c
+.. code-block:: c
     rtems_device_driver frame_buffer_initialize(
+    rtems_device_major_number  major,
+    rtems_device_minor_number  minor,
+    void                      \*arg)
+    {
+    rtems_status_code status;
+    printk( "frame buffer driver initializing..\\n" );
+    /*
+    * Register the device
+    \*/
+    status = rtems_io_register_name("/dev/fb0", major, 0);
+    if (status != RTEMS_SUCCESSFUL)
+    {
+    printk("Error registering frame buffer device!\\n");
+    rtems_fatal_error_occurred( status );
+    }
+    /*
+    * graphics hardware initialization goes here for non-console
+    * devices
+    \*/
+    return RTEMS_SUCCESSFUL;
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor,
+      void                      *arg)
+    {
+      rtems_status_code status;
+      printk( "frame buffer driver initializing..\n" );
+      /*
+       * Register the device
+       */
+      status = rtems_io_register_name("/dev/fb0", major, 0);
+      if (status != RTEMS_SUCCESSFUL)
+      {
+        printk("Error registering frame buffer device!\n");
+        rtems_fatal_error_occurred( status );
+      }
+      /*
+       * graphics hardware initialization goes here for non-console
+       * devices
+       */
+      return RTEMS_SUCCESSFUL;
+    }
 …
 -------------------------------
+The ``frame_buffer_open()`` function is called whenever a frame buffer device is opened.
+If the frame buffer is registered as "/dev/fb0", the ``frame_buffer_open`` entry point
+will be called as the result of an  ``open("/dev/fb0", mode)`` in the application.
+Thread safety of the frame buffer driver is implementation-dependent.
+The VGA driver shown below uses a mutex to prevent multiple open()
+operations of the frame buffer device.
+The ``frame_buffer_open()`` function returns RTEMS_SUCCESSFUL when the device driver
+is successfully opened, and RTEMS_UNSATISFIED if the device is already open:
+.. code:: c
+The ``frame_buffer_open()`` function is called whenever a frame buffer device
+is opened.  If the frame buffer is registered as :file:`/dev/fb0`, the
+``frame_buffer_open`` entry point will be called as the result of an
+``open("/dev/fb0", mode)`` in the application.
+Thread safety of the frame buffer driver is implementation-dependent.  The VGA
+driver shown below uses a mutex to prevent multiple open() operations of the
+frame buffer device.
+The ``frame_buffer_open()`` function returns ``RTEMS_SUCCESSFUL`` when the
+device driver is successfully opened, and ``RTEMS_UNSATISFIED`` if the device
+is already open:
+.. code-block:: c
     rtems_device_driver frame_buffer_close(
+    rtems_device_major_number  major,
+    rtems_device_minor_number  minor,
+    void                      \*arg
+    )
+    {
+    if (pthread_mutex_unlock(&mutex) == 0){
+    /* restore previous state.  for VGA this means return to text mode.
+    * leave out if graphics hardware has been initialized in
+    * frame_buffer_initialize() \*/
+    ega_hwterm();
+    printk( "FBVGA close called.\\n" );
+    return RTEMS_SUCCESSFUL;
+    }
+    return RTEMS_UNSATISFIED;
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor,
+      void                      *arg
+    )
+    {
+      if (pthread_mutex_unlock(&mutex) == 0) {
+        /* restore previous state.  for VGA this means return to text mode.
+         * leave out if graphics hardware has been initialized in
+         * frame_buffer_initialize()
+         */
+        ega_hwterm();
+        printk( "FBVGA close called.\n" );
+        return RTEMS_SUCCESSFUL;
+      }
+      return RTEMS_UNSATISFIED;
+    }
 …
 -------------------------------
+The ``frame_buffer_close()`` is invoked when the frame buffer device
+is closed.  It frees up any resources allocated in``frame_buffer_open()``, and should restore previous hardware state.
+The entry point corresponds to the device driver close entry point.
+Returns RTEMS_SUCCESSFUL when the device driver is successfully closed:
+.. code:: c
+The ``frame_buffer_close()`` is invoked when the frame buffer device is closed.
+It frees up any resources allocated in ``frame_buffer_open()``, and should
+restore previous hardware state.  The entry point corresponds to the device
+driver close entry point.
+Returns ``RTEMS_SUCCESSFUL`` when the device driver is successfully closed:
+.. code-block:: c
     rtems_device_driver frame_buffer_close(
+    rtems_device_major_number  major,
+    rtems_device_minor_number  minor,
+    void                      \*arg)
+    {
+    pthread_mutex_unlock(&mutex);
+    /* TODO check mutex return value, RTEMS_UNSATISFIED if it failed.  we
+    * don't want to unconditionally call ega_hwterm()... \*/
+    /* restore previous state.  for VGA this means return to text mode.
+    * leave out if graphics hardware has been initialized in
+    * frame_buffer_initialize() \*/
+    ega_hwterm();
+    printk( "frame buffer close called.\\n" );
+    return RTEMS_SUCCESSFUL;
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor,
+      void                      *arg)
+    {
+      pthread_mutex_unlock(&mutex);
+      /* TODO check mutex return value, RTEMS_UNSATISFIED if it failed.  we
+       * don't want to unconditionally call ega_hwterm()... */
+      /* restore previous state.  for VGA this means return to text mode.
+       * leave out if graphics hardware has been initialized in
+       * frame_buffer_initialize() */
+      ega_hwterm();
+      printk( "frame buffer close called.\n" );
+      return RTEMS_SUCCESSFUL;
+    }
 …
 ------------------------------------
+The ``frame_buffer_read()`` is invoked from a ``read()`` operation
+on the frame buffer device.
+Read functions should allow normal and partial reading at the end of frame buffer memory.
+This method returns RTEMS_SUCCESSFUL when the device is successfully read from:
+.. code:: c
+The ``frame_buffer_read()`` is invoked from a ``read()`` operation on the frame
+buffer device.  Read functions should allow normal and partial reading at the
+end of frame buffer memory.  This method returns ``RTEMS_SUCCESSFUL`` when the
+device is successfully read from:
+.. code-block:: c
     rtems_device_driver frame_buffer_read(
+    rtems_device_major_number  major,
+    rtems_device_minor_number  minor,
+    void                      \*arg
+    )
+    {
+    rtems_libio_rw_args_t \*rw_args = (rtems_libio_rw_args_t \*)arg;
+    rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count;
+    memcpy(rw_args->buffer, (const void \*) (fb_fix.smem_start + rw_args->offset), rw_args->bytes_moved);
+    return RTEMS_SUCCESSFUL;
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor,
+      void                      *arg
+    )
+    {
+      rtems_libio_rw_args_t *rw_args = (rtems_libio_rw_args_t *)arg;
+      rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ?
+                               (fb_fix.smem_len - rw_args->offset) : rw_args->count;
+      memcpy(rw_args->buffer,
+             (const void *) (fb_fix.smem_start + rw_args->offset),
+             rw_args->bytes_moved);
+      return RTEMS_SUCCESSFUL;
+    }
 …
 ----------------------------------
+The ``frame_buffer_write()`` is invoked from a ``write()``
+operation on the frame buffer device.
+The frame buffer write function is similar to the read function, and
+should handle similar cases involving partial writes.
+This method returns RTEMS_SUCCESSFUL when the device is successfully
+The ``frame_buffer_write()`` is invoked from a ``write()`` operation on the
+frame buffer device.  The frame buffer write function is similar to the read
+function, and should handle similar cases involving partial writes.
+This method returns ``RTEMS_SUCCESSFUL`` when the device is successfully
 written to:
+.. code:: c
+.. code-block:: c
     rtems_device_driver frame_buffer_write(
+    rtems_device_major_number  major,
+    rtems_device_minor_number  minor,
+    void                      \*arg
+    )
+    {
+    rtems_libio_rw_args_t \*rw_args = (rtems_libio_rw_args_t \*)arg;
+    rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count;
+    memcpy( (void \*) (fb_fix.smem_start + rw_args->offset), rw_args->buffer, rw_args->bytes_moved);
+    return RTEMS_SUCCESSFUL;
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor,
+      void                      *arg
+    )
+    {
+      rtems_libio_rw_args_t *rw_args = (rtems_libio_rw_args_t *)arg;
+      rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ?
+                               (fb_fix.smem_len - rw_args->offset) : rw_args->count;
+      memcpy((void *) (fb_fix.smem_start + rw_args->offset),
+             rw_args->buffer,
+             rw_args->bytes_moved);
+      return RTEMS_SUCCESSFUL;
+    }
 …
 -----------------------
 The frame buffer driver allows several ioctls, partially compatible with
+the Linux kernel,
+to obtain information about the hardware.
 All ``ioctl()`` operations on the frame buffer device invoke``frame_buffer_control()``.
+The frame buffer driver allows several ioctls, partially compatible with the
+Linux kernel, to obtain information about the hardware.
+All ``ioctl()`` operations on the frame buffer device invoke
+``frame_buffer_control()``.
 Ioctls supported:
 …
 - ioctl to set and get palette.
 .. code:: c
+.. code-block:: c
     rtems_device_driver frame_buffer_control(
+    rtems_device_major_number  major,
+    rtems_device_minor_number  minor,
+    void                      \*arg
+    )
+    {
+    rtems_libio_ioctl_args_t \*args = arg;
+    printk( "FBVGA ioctl called, cmd=%x\\n", args->command  );
+    switch( args->command ) {
+    case FBIOGET_FSCREENINFO:
+    args->ioctl_return =  get_fix_screen_info( ( struct fb_fix_screeninfo * ) args->buffer );
+    break;
+    case FBIOGET_VSCREENINFO:
+    args->ioctl_return =  get_var_screen_info( ( struct fb_var_screeninfo * ) args->buffer );
+    break;
+    case FBIOPUT_VSCREENINFO:
+    /* not implemented yet*/
+    args->ioctl_return = -1;
+    return RTEMS_UNSATISFIED;
+    case FBIOGETCMAP:
+    args->ioctl_return =  get_palette( ( struct fb_cmap * ) args->buffer );
+    break;
+    case FBIOPUTCMAP:
+    args->ioctl_return =  set_palette( ( struct fb_cmap * ) args->buffer );
+    break;
+    default:
+    args->ioctl_return = 0;
+    break;
+    }
+    return RTEMS_SUCCESSFUL;
+    }
+See ``rtems/fb.h`` for more information on the list of ioctls and
+data structures they work with.
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor,
+      void                      *arg
+    )
+    {
+      rtems_libio_ioctl_args_t *args = arg;
+      printk( "FBVGA ioctl called, cmd=%x\n", args->command  );
+      switch( args->command ) {
+        case FBIOGET_FSCREENINFO:
+          args->ioctl_return =  get_fix_screen_info( ( struct fb_fix_screeninfo * ) args->buffer );
+          break;
+        case FBIOGET_VSCREENINFO:
+          args->ioctl_return =  get_var_screen_info( ( struct fb_var_screeninfo * ) args->buffer );
+          break;
+        case FBIOPUT_VSCREENINFO:
+          /* not implemented yet*/
+          args->ioctl_return = -1;
+          return RTEMS_UNSATISFIED;
+        case FBIOGETCMAP:
+          args->ioctl_return =  get_palette( ( struct fb_cmap * ) args->buffer );
+          break;
+        case FBIOPUTCMAP:
+          args->ioctl_return =  set_palette( ( struct fb_cmap * ) args->buffer );
+          break;
+        default:
+          args->ioctl_return = 0;
+          break;
+      }
+      return RTEMS_SUCCESSFUL;
+    }
+See ``rtems/fb.h`` for more information on the list of ioctls and data
+structures they work with.

bsp_howto/ide_controller.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 IDE Controller Driver
 …
 ============
+The IDE Controller driver is responsible for providing an
+interface to an IDE Controller.  The capabilities provided by this
+driver are:
+The IDE Controller driver is responsible for providing an interface to an IDE
+Controller.  The capabilities provided by this driver are:
 - Read IDE Controller register
 …
 - Write data block through IDE Controller Data Register
 The reference implementation for an IDE Controller driver can
+be found in ``$RTEMS_SRC_ROOT/c/src/libchip/ide``. This driver
+is based on the libchip concept and allows to work with any of the IDE
+Controller chips simply by appropriate configuration of BSP. Drivers for a
+particular IDE Controller chips locate in the following directories: drivers
+for well-known IDE Controller chips locate into``$RTEMS_SRC_ROOT/c/src/libchip/ide``, drivers for IDE Controller chips
+integrated with CPU locate into``$RTEMS_SRC_ROOT/c/src/lib/libcpu/myCPU`` and
+drivers for custom IDE Controller chips (for example, implemented on FPGA)
+locate into ``$RTEMS_SRC_ROOT/c/src/lib/libbsp/myBSP``.
+There is a README file in these directories for each supported
+IDE Controller chip. Each of these README explains how to configure a BSP
 for that particular IDE Controller chip.
+The reference implementation for an IDE Controller driver can be found in
+``$RTEMS_SRC_ROOT/c/src/libchip/ide``. This driver is based on the libchip
+concept and allows to work with any of the IDE Controller chips simply by
+appropriate configuration of BSP. Drivers for a particular IDE Controller chips
+locate in the following directories: drivers for well-known IDE Controller
+chips locate into ``$RTEMS_SRC_ROOT/c/src/libchip/ide``, drivers for IDE
+Controller chips integrated with CPU locate into
+``$RTEMS_SRC_ROOT/c/src/lib/libcpu/myCPU`` and drivers for custom IDE
+Controller chips (for example, implemented on FPGA) locate into
+``$RTEMS_SRC_ROOT/c/src/lib/libbsp/myBSP``.  There is a README file in these
+directories for each supported IDE Controller chip. Each of these README
+explains how to configure a BSP for that particular IDE Controller chip.
 Initialization
 ==============
+IDE Controller chips used by a BSP are statically configured into``IDE_Controller_Table``. The ``ide_controller_initialize`` routine is
+IDE Controller chips used by a BSP are statically configured into
+``IDE_Controller_Table``. The ``ide_controller_initialize`` routine is
 responsible for initialization of all configured IDE controller chips.
 Initialization order of the chips based on the order the chips are defined in
 the ``IDE_Controller_Table``.
+The following actions are performed by the IDE Controller driver
+initialization routine:
+.. code:: c
+The following actions are performed by the IDE Controller driver initialization
+routine:
+.. code-block:: c
     rtems_device_driver ide_controller_initialize(
     rtems_device_major_number  major,
     rtems_device_minor_number  minor_arg,
     void                      \*arg
+      rtems_device_major_number  major,
+      rtems_device_minor_number  minor_arg,
+      void                      *arg
+    )
+    {
     for each IDE Controller chip configured in IDE_Controller_Table
     if (BSP dependent probe(if exists) AND device probe for this IDE chip
     indicates it is present)
     perform initialization of the particular chip
     register device with configured name for this chip
+      for each IDE Controller chip configured in IDE_Controller_Table
+        if (BSP dependent probe(if exists) AND device probe for this IDE chip
+            indicates it is present)
+          perform initialization of the particular chip
+          register device with configured name for this chip
+    }
 …
 Controller chip register. IDE Controller chip is selected via the minor
 number. This routine is not allowed to be called from an application.
-.. code:: c
+    void ide_controller_read_register(rtems_device_minor_number minor,
+    unsigned32 reg, unsigned32 \*value)
+.. code-block:: c
+    void ide_controller_read_register(
+      rtems_device_minor_number  minor,
+      unsigned32                 reg,
+      unsigned32                *value
+    )
+    {
+    get IDE Controller chip configuration information from
+    IDE_Controller_Table by minor number
+    invoke read register routine for the chip
+      get IDE Controller chip configuration information from
+      IDE_Controller_Table by minor number
+      invoke read register routine for the chip
+    }
 …
 register with specified value. IDE Controller chip is selected via the minor
 number. This routine is not allowed to be called from an application.
-.. code:: c
+    void ide_controller_write_register(rtems_device_minor_number minor,
+    unsigned32 reg, unsigned32 value)
+.. code-block:: c
+    void ide_controller_write_register(
+      rtems_device_minor_number minor,
+      unsigned32                reg,
+      unsigned32                value
+    )
+    {
+    get IDE Controller chip configuration information from
+    IDE_Controller_Table by minor number
+    invoke write register routine for the chip
+      get IDE Controller chip configuration information from
+      IDE_Controller_Table by minor number
+      invoke write register routine for the chip
+    }
 …
 ====================================================
+The ``ide_controller_read_data_block`` provides multiple consequent read
+of the IDE Controller Data Register. IDE Controller chip is selected via the
+minor number. The same functionality may be achieved via separate multiple
+calls of ``ide_controller_read_register`` routine but``ide_controller_read_data_block`` allows to escape functions call
+overhead. This routine is not allowed to be called from an application.
+.. code:: c
+The ``ide_controller_read_data_block`` provides multiple consequent read of the
+IDE Controller Data Register. IDE Controller chip is selected via the minor
+number. The same functionality may be achieved via separate multiple calls of
+``ide_controller_read_register`` routine but ``ide_controller_read_data_block``
+allows to escape functions call overhead. This routine is not allowed to be
+called from an application.
+.. code-block:: c
     void ide_controller_read_data_block(
     rtems_device_minor_number  minor,
     unsigned16                 block_size,
     blkdev_sg_buffer          \*bufs,
     uint32_t                  \*cbuf,
     uint32_t                  \*pos
+      rtems_device_minor_number  minor,
+      unsigned16                 block_size,
+      blkdev_sg_buffer          *bufs,
+      uint32_t                  *cbuf,
+      uint32_t                  *pos
+    )
+    {
+    get IDE Controller chip configuration information from
+    IDE_Controller_Table by minor number
+    invoke read data block routine for the chip
+      get IDE Controller chip configuration information from
+      IDE_Controller_Table by minor number
+      invoke read data block routine for the chip
+    }
 …
 =====================================================
+The ``ide_controller_write_data_block`` provides multiple consequent write
+into the IDE Controller Data Register. IDE Controller chip is selected via the
+minor number. The same functionality may be achieved via separate multiple
+calls of ``ide_controller_write_register`` routine but``ide_controller_write_data_block`` allows to escape functions call
+The ``ide_controller_write_data_block`` provides multiple consequent write into
+the IDE Controller Data Register. IDE Controller chip is selected via the minor
+number. The same functionality may be achieved via separate multiple calls of
+``ide_controller_write_register`` routine but
+``ide_controller_write_data_block`` allows to escape functions call
 overhead. This routine is not allowed to be called from an application.
+.. code:: c
+.. code-block:: c
     void ide_controller_write_data_block(
     rtems_device_minor_number  minor,
     unsigned16                 block_size,
     blkdev_sg_buffer          \*bufs,
     uint32_t                  \*cbuf,
     uint32_t                  \*pos
+      rtems_device_minor_number  minor,
+      unsigned16                 block_size,
+      blkdev_sg_buffer          *bufs,
+      uint32_t                  *cbuf,
+      uint32_t                  *pos
+    )
+    {
+    get IDE Controller chip configuration information from
+    IDE_Controller_Table by minor number
+    invoke write data block routine for the chip
+      get IDE Controller chip configuration information from
+      IDE_Controller_Table by minor number
+      invoke write data block routine for the chip
+    }
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-.. COMMENT: All rights reserved.

bsp_howto/index.rst

-                      r54514fe
+                      r6d7a4d2
 =======================================
+COPYRIGHT (c) 1988 - 2015.
+BSP and Device Driver Development Guide
+---------------------------------------
+On-Line Applications Research Corporation (OAR).
+ | COPYRIGHT (c) 1988 - 2015.
+ | On-Line Applications Research Corporation (OAR).
+The authors have used their best efforts in preparing
+this material.  These efforts include the development, research,
+and testing of the theories and programs to determine their
+effectiveness.  No warranty of any kind, expressed or implied,
+with regard to the software or the material contained in this
+document is provided.  No liability arising out of the
+application or use of any product described in this document is
+assumed.  The authors reserve the right to revise this material
+and to make changes from time to time in the content hereof
+without obligation to notify anyone of such revision or changes.
+The authors have used their best efforts in preparing this material.  These
+efforts include the development, research, and testing of the theories and
+programs to determine their effectiveness.  No warranty of any kind, expressed
+or implied, with regard to the software or the material contained in this
+document is provided.  No liability arising out of the application or use of
+any product described in this document is assumed.  The authors reserve the
+right to revise this material and to make changes from time to time in the
+content hereof without obligation to notify anyone of such revision or changes.
 The RTEMS Project is hosted at http://www.rtems.org.  Any
+inquiries concerning RTEMS, its related support components, or its
 documentation should be directed to the Community Project hosted athttp://www.rtems.org.
+The RTEMS Project is hosted at http://www.rtems.org.  Any inquiries concerning
+RTEMS, its related support components, or its documentation should be directed
+to the Community Project hosted at http://www.rtems.org.
+Any inquiries for commercial services including training, support, custom
+development, application development assistance should be directed tohttp://www.rtems.com.
+.. topic:: RTEMS Online Resources
+Table of Contents
+-----------------
+.. toctree::
+        preface
+  ================  =============================
+  Home              https://www.rtems.org/
+  Developers        https://devel.rtems.org/
+  Documentation     https://docs.rtems.org/
+  Bug Reporting     https://devel.rtems.org/query
+  Mailing Lists     https://lists.rtems.org/
+  Git Repositories  https://git.rtems.org/
+  ================  =============================
 .. toctree::
 …
         :numbered:
+        preface
         target_dependant_files
         makefiles
 …
         command
 *       :ref:`genindex`
 *       :ref:`search`

bsp_howto/initilization_code.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Initialization Code
 …
 The initialization code is the first piece of code executed when there's a
 reset/reboot. Its purpose is to initialize the board for the application.
+This chapter contains a narrative description of the initialization
+process followed by a description of each of the files and routines
+commonly found in the BSP related to initialization.  The remainder of
+this chapter covers special issues which require attention such
 as interrupt vector table and chip select initialization.
+reset/reboot. Its purpose is to initialize the board for the application.  This
+chapter contains a narrative description of the initialization process followed
+by a description of each of the files and routines commonly found in the BSP
+related to initialization.  The remainder of this chapter covers special issues
+which require attention such as interrupt vector table and chip select
+initialization.
 Most of the examples in this chapter will be based on the SPARC/ERC32 and
 m68k/gen68340 BSP initialization code.  Like most BSPs, the initialization
+for these BSP is divided into two subdirectories under the BSP source
+directory.  The BSP source code for these BSPs is in the following
+directories:
+m68k/gen68340 BSP initialization code.  Like most BSPs, the initialization for
+these BSP is divided into two subdirectories under the BSP source directory.
+The BSP source code for these BSPs is in the following directories:
 .. code:: c
 …
     c/src/lib/libbsp/sparc/erc32
+Both BSPs contain startup code written in assembly language and C.
+The gen68340 BSP has its early initialization start code in the``start340`` subdirectory and its C startup code in the ``startup``
+directory.  In the ``start340`` directory are two source files.
+The file ``startfor340only.s`` is the simpler of these files as it only
+has initialization code for a MC68340 board.  The file ``start340.s``
+contains initialization for a 68349 based board as well.
+Similarly, the ERC32 BSP has startup code written in assembly language
+and C.  However, this BSP shares this code with other SPARC BSPs.
+Thus the ``Makefile.am`` explicitly references the following files
+for this functionality.
+Both BSPs contain startup code written in assembly language and C.  The
+gen68340 BSP has its early initialization start code in the ``start340``
+subdirectory and its C startup code in the ``startup`` directory.  In the
+``start340`` directory are two source files.  The file ``startfor340only.s`` is
+the simpler of these files as it only has initialization code for a MC68340
+board.  The file ``start340.s`` contains initialization for a 68349 based board
+as well.
+Similarly, the ERC32 BSP has startup code written in assembly language and C.
+However, this BSP shares this code with other SPARC BSPs.  Thus the
+``Makefile.am`` explicitly references the following files for this
+functionality.
 .. code:: c
     ../../sparc/shared/start.S
+*NOTE:* In most BSPs, the directory named ``start340`` in the
+gen68340 BSP would be simply named ``start`` or start followed by a
+BSP designation.
+.. note::
+   In most BSPs, the directory named ``start340`` in the gen68340 BSP would be
+   simply named ``start`` or start followed by a BSP designation.
 Required Global Variables
 =========================
+Although not strictly part of initialization, there are a few global
+variables assumed to exist by reusable device drivers.  These global
+variables should only defined by the BSP when using one of these device
+drivers.
+The BSP author probably should be aware of the ``Configuration``
+Table structure generated by ``<rtems/confdefs.h>`` during debug but
+should not explicitly reference it in the source code.  There are helper
+routines provided by RTEMS to access individual fields.
+Although not strictly part of initialization, there are a few global variables
+assumed to exist by reusable device drivers.  These global variables should
+only defined by the BSP when using one of these device drivers.
+The BSP author probably should be aware of the ``Configuration`` Table
+structure generated by ``<rtems/confdefs.h>`` during debug but should not
+explicitly reference it in the source code.  There are helper routines provided
+by RTEMS to access individual fields.
 In older RTEMS versions, the BSP included a number of required global
 variables.  We have made every attempt to eliminate these in the interest
 of simplicity.
+variables.  We have made every attempt to eliminate these in the interest of
+simplicity.
 Board Initialization
 ====================
+This section describes the steps an application goes through from the
+time the first BSP code is executed until the first application task
+executes.  The following figure illustrates the program flow during
+this sequence:
+IMAGE NOT AVAILABLE IN ASCII VERSION
+The above figure illustrates the flow from assembly language start code
+to the shared ``bootcard.c`` framework then through the C Library,
+RTEMS, device driver initialization phases, and the context switch
+to the first application task.  After this, the application executes
+until it calls ``exit``, ``rtems_shutdown_executive``, or some
+other normal termination initiating routine and a fatal system state is
+reached.  The optional ``bsp_fatal_extension`` initial extension can perform
+BSP specific system termination.
+The routines invoked during this will be discussed and their location
+in the RTEMS source tree pointed out as we discuss each.
+This section describes the steps an application goes through from the time the
+first BSP code is executed until the first application task executes.
+The initialization flows from assembly language start code to the shared
+``bootcard.c`` framework then through the C Library, RTEMS, device driver
+initialization phases, and the context switch to the first application task.
+After this, the application executes until it calls ``exit``,
+``rtems_shutdown_executive``, or some other normal termination initiating
+routine and a fatal system state is reached.  The optional
+``bsp_fatal_extension`` initial extension can perform BSP specific system
+termination.
+The routines invoked during this will be discussed and their location in the
+RTEMS source tree pointed out as we discuss each.
 Start Code - Assembly Language Initialization
 ---------------------------------------------
 The assembly language code in the directory ``start`` is the first part
+of the application to execute.  It is responsible for initializing the
 processor and board enough to execute the rest of the BSP.  This includes:
+The assembly language code in the directory ``start`` is the first part of the
+application to execute.  It is responsible for initializing the processor and
+board enough to execute the rest of the BSP.  This includes:
 - initializing the stack
 …
 - copy the initialized data from ROM to RAM
+The general rule of thumb is that the start code in assembly should
+do the minimum necessary to allow C code to execute to complete the
+initialization sequence.
+The initial assembly language start code completes its execution by
+invoking the shared routine ``boot_card()``.
+The label (symbolic name) associated with the starting address of the
+program is typically called ``start``.  The start object file is the
+first object file linked into the program image so it is ensured that
+the start code is at offset 0 in the ``.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.
+The general rule of thumb is that the start code in assembly should do the
+minimum necessary to allow C code to execute to complete the initialization
+sequence.
+The initial assembly language start code completes its execution by invoking
+the shared routine ``boot_card()``.
+The label (symbolic name) associated with the starting address of the program
+is typically called ``start``.  The start object file is the first object file
+linked into the program image so it is ensured that the start code is at offset
+in the ``.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.
 boot_card() - Boot the Card
 ---------------------------
+The ``boot_card()`` is the first C code invoked.  This file is the
+core component in the RTEMS BSP Initialization Framework and provides
+the proper sequencing of initialization steps for the BSP, RTEMS and
+device drivers. All BSPs use the same shared version of ``boot_card()``
+which is located in the following file:
+The ``boot_card()`` is the first C code invoked.  This file is the core
+component in the RTEMS BSP Initialization Framework and provides the proper
+sequencing of initialization steps for the BSP, RTEMS and device drivers. All
+BSPs use the same shared version of ``boot_card()`` which is located in the
+following file:
 .. code:: c
 …
   for later use by the application.
+- It invokes the BSP specific routine ``bsp_work_area_initialize()``
+  which is supposed to initialize the RTEMS Workspace and the C Program Heap.
+  Usually the default implementation in``c/src/lib/libbsp/shared/bspgetworkarea.c`` should be sufficient.  Custom
+  implementations can use ``bsp_work_area_initialize_default()`` or``bsp_work_area_initialize_with_table()`` available as inline functions from``#include <bsp/bootcard.h>``.
+- It invokes the BSP specific routine ``bsp_start()`` which is
+  written in C and thus able to perform more advanced initialization.
+  Often MMU, bus and interrupt controller initialization occurs here.  Since the
+  RTEMS Workspace and the C Program Heap was already initialized by``bsp_work_area_initialize()``, this routine may use ``malloc()``, etc.
+- It invokes the RTEMS directive``rtems_initialize_data_structures()`` to initialize the RTEMS
+  executive to a state where objects can be created but tasking is not
+  enabled.
+- It invokes the BSP specific routine ``bsp_libc_init()`` to initialize
+  the C Library.  Usually the default implementation in``c/src/lib/libbsp/shared/bsplibc.c`` should be sufficient.
+- It invokes the RTEMS directive``rtems_initialize_before_drivers()`` to initialize the MPCI Server
+  thread in a multiprocessor configuration and execute API specific
+  extensions.
+- It invokes the BSP specific routine ``bsp_predriver_hook``. For
+  most BSPs, the implementation of this routine does nothing.
+- It invokes the RTEMS directive``rtems_initialize_device_drivers()`` to initialize the statically
+  configured set of device drivers in the order they were specified in
+  the Configuration Table.
+- It invokes the BSP specific routine ``bsp_work_area_initialize()`` which is
+  supposed to initialize the RTEMS Workspace and the C Program Heap.  Usually
+  the default implementation in ``c/src/lib/libbsp/shared/bspgetworkarea.c``
+  should be sufficient.  Custom implementations can use
+  ``bsp_work_area_initialize_default()`` or
+  ``bsp_work_area_initialize_with_table()`` available as inline functions
+  from``#include <bsp/bootcard.h>``.
+- It invokes the BSP specific routine ``bsp_start()`` which is written in C and
+  thus able to perform more advanced initialization.  Often MMU, bus and
+  interrupt controller initialization occurs here.  Since the RTEMS Workspace
+  and the C Program Heap was already initialized by
+  ``bsp_work_area_initialize()``, this routine may use ``malloc()``, etc.
+- It invokes the RTEMS directive ``rtems_initialize_data_structures()`` to
+  initialize the RTEMS executive to a state where objects can be created but
+  tasking is not enabled.
+- It invokes the BSP specific routine ``bsp_libc_init()`` to initialize the C
+  Library.  Usually the default implementation in
+  ``c/src/lib/libbsp/shared/bsplibc.c`` should be sufficient.
+- It invokes the RTEMS directive ``rtems_initialize_before_drivers()`` to
+  initialize the MPCI Server thread in a multiprocessor configuration and
+  execute API specific extensions.
+- It invokes the BSP specific routine ``bsp_predriver_hook``. For most BSPs,
+  the implementation of this routine does nothing.
+- It invokes the RTEMS directive ``rtems_initialize_device_drivers()`` to
+  initialize the statically configured set of device drivers in the order they
+  were specified in the Configuration Table.
 - It invokes the BSP specific routine ``bsp_postdriver_hook``. For
 …
   for the BSP to insert BSP specific code into the initialization sequence.
 - It invokes the RTEMS directive``rtems_initialize_start_multitasking()``
   which initiates multitasking and performs a context switch to the
   first user application task and may enable interrupts as a side-effect of
   that context switch.  The context switch saves the executing context.  The
   application runs now.  The directive rtems_shutdown_executive() will return
   to the saved context.  The exit() function will use this directive.
   After a return to the saved context a fatal system state is reached.  The
   fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
   passed to rtems_shutdown_executive().
   The enabling of interrupts during the first context switch is often the source
   for fatal errors during BSP development because the BSP did not clear and/or
   disable all interrupt sources and a spurious interrupt will occur.
   When in the context of the first task but before its body has been
   entered, any C++ Global Constructors will be invoked.
+- It invokes the RTEMS directive ``rtems_initialize_start_multitasking()``
+  which initiates multitasking and performs a context switch to the first user
+  application task and may enable interrupts as a side-effect of that context
+  switch.  The context switch saves the executing context.  The application
+  runs now.  The directive ``rtems_shutdown_executive()`` will return to the
+  saved context.  The ``exit()`` function will use this directive.  After a
+  return to the saved context a fatal system state is reached.  The fatal
+  source is ``RTEMS_FATAL_SOURCE_EXIT`` with a fatal code set to the value
+  passed to rtems_shutdown_executive().  The enabling of interrupts during the
+  first context switch is often the source for fatal errors during BSP
+  development because the BSP did not clear and/or disable all interrupt
+  sources and a spurious interrupt will occur.  When in the context of the
+  first task but before its body has been entered, any C++ Global Constructors
+  will be invoked.
 That's it.  We just went through the entire sequence.
 …
 C Program Heap and RTEMS Workspace commonly referred to as the work areas.
 Many BSPs place the work areas at the end of RAM although this is certainly not
+a requirement.  Usually the default implementation in:file:`c/src/lib/libbsp/shared/bspgetworkarea.c` should be sufficient.  Custom
+implementations can use ``bsp_work_area_initialize_default()`` or``bsp_work_area_initialize_with_table()`` available as inline functions from``#include <bsp/bootcard.h>``.
+a requirement.  Usually the default implementation
+in:file:`c/src/lib/libbsp/shared/bspgetworkarea.c` should be sufficient.
+Custom implementations can use ``bsp_work_area_initialize_default()``
+or``bsp_work_area_initialize_with_table()`` available as inline functions from
+``#include <bsp/bootcard.h>``.
 bsp_start() - BSP Specific Initialization
 …
 This is the second BSP specific C routine to execute during system
 initialization.  It is called right after ``bsp_work_area_initialize()``.
 The ``bsp_start()`` routine often performs required fundamental hardware
+initialization.  It is called right after ``bsp_work_area_initialize()``.  The
+``bsp_start()`` routine often performs required fundamental hardware
 initialization such as setting bus controller registers that do not have a
 direct impact on whether or not C code can execute.  The interrupt controllers
 …
 After completing execution, this routine returns to the ``boot_card()``
+routine.  In case of errors, the initialization should be terminated via``bsp_fatal()``.
+routine.  In case of errors, the initialization should be terminated via
+``bsp_fatal()``.
 bsp_predriver_hook() - BSP Specific Predriver Hook
 --------------------------------------------------
 The ``bsp_predriver_hook()`` method is the BSP specific routine that is
 invoked immediately before the the device drivers are initialized. RTEMS
 initialization is complete but interrupts and tasking are disabled.
 The BSP may use the shared version of this routine which is empty.
 Most BSPs do not provide a specific implementation of this callback.
+The ``bsp_predriver_hook()`` method is the BSP specific routine that is invoked
+immediately before the the device drivers are initialized. RTEMS initialization
+is complete but interrupts and tasking are disabled.
+The BSP may use the shared version of this routine which is empty.  Most BSPs
+do not provide a specific implementation of this callback.
 Device Driver Initialization
 ----------------------------
 At this point in the initialization sequence, the initialization
+routines for all of the device drivers specified in the Device
+Driver Table are invoked.  The initialization routines are invoked
 in the order they appear in the Device Driver Table.
 The Driver Address Table is part of the RTEMS Configuration Table. It
 defines device drivers entry points (initialization, open, close, read,
 write, and control). For more information about this table, please
 refer to the *Configuring a System* chapter in the*RTEMS Application C User's Guide*.
 The RTEMS initialization procedure calls the initialization function for
+every driver defined in the RTEMS Configuration Table (this allows
 one to include only the drivers needed by the application).
+At this point in the initialization sequence, the initialization routines for
+all of the device drivers specified in the Device Driver Table are invoked.
+The initialization routines are invoked in the order they appear in the Device
+Driver Table.
+The Driver Address Table is part of the RTEMS Configuration Table. It defines
+device drivers entry points (initialization, open, close, read, write, and
+control). For more information about this table, please refer to the
+*Configuring a System* chapter in the *RTEMS Application C User's Guide*.
+The RTEMS initialization procedure calls the initialization function for every
+driver defined in the RTEMS Configuration Table (this allows one to include
+only the drivers needed by the application).
 All these primitives have a major and a minor number as arguments:
 …
 - the major number refers to the driver type,
+- the minor number is used to control two peripherals with the same
+  driver (for instance, we define only one major number for the serial
+  driver, but two minor numbers for channel A and B if there are two
+  channels in the UART).
+- the minor number is used to control two peripherals with the same driver (for
+  instance, we define only one major number for the serial driver, but two
+  minor numbers for channel A and B if there are two channels in the UART).
 RTEMS Postdriver Callback
 -------------------------
+The ``bsp_postdriver_hook()`` BSP specific routine is invoked
+immediately after the the device drivers and MPCI are initialized.
+Interrupts and tasking are disabled.
+Most BSPs use the shared implementation of this routine which is responsible for opening the device ``/dev/console`` for standard input, output and error if the application has configured the Console Device Driver.  This file is located at:
+The ``bsp_postdriver_hook()`` BSP specific routine is invoked immediately after
+the the device drivers and MPCI are initialized.  Interrupts and tasking are
+disabled.
+Most BSPs use the shared implementation of this routine which is responsible
+for opening the device ``/dev/console`` for standard input, output and error if
+the application has configured the Console Device Driver.  This file is located
+at:
 .. code:: c
 …
 ==========================
+The Interrupt Vector Table is called different things on different
+processor families but the basic functionality is the same.  Each
+entry in the Table corresponds to the handler routine for a particular
+interrupt source.  When an interrupt from that source occurs, the
+specified handler routine is invoked.  Some context information is
+saved by the processor automatically when this happens.  RTEMS saves
+enough context information so that an interrupt service routine
+can be implemented in a high level language.
+On some processors, the Interrupt Vector Table is at a fixed address.  If
+this address is in RAM, then usually the BSP only has to initialize
+it to contain pointers to default handlers.  If the table is in ROM,
+then the application developer will have to take special steps to
+fill in the table.
+If the base address of the Interrupt Vector Table can be dynamically
+changed to an arbitrary address, then the RTEMS port to that processor
+family will usually allocate its own table and install it.  For example,
+on some members of the Motorola MC68xxx family, the Vector Base Register
+(``vbr``) contains this base address.
+The Interrupt Vector Table is called different things on different processor
+families but the basic functionality is the same.  Each entry in the Table
+corresponds to the handler routine for a particular interrupt source.  When an
+interrupt from that source occurs, the specified handler routine is invoked.
+Some context information is saved by the processor automatically when this
+happens.  RTEMS saves enough context information so that an interrupt service
+routine can be implemented in a high level language.
+On some processors, the Interrupt Vector Table is at a fixed address.  If this
+address is in RAM, then usually the BSP only has to initialize it to contain
+pointers to default handlers.  If the table is in ROM, then the application
+developer will have to take special steps to fill in the table.
+If the base address of the Interrupt Vector Table can be dynamically changed to
+an arbitrary address, then the RTEMS port to that processor family will usually
+allocate its own table and install it.  For example, on some members of the
+Motorola MC68xxx family, the Vector Base Register (``vbr``) contains this base
+address.
 Interrupt Vector Table on the gen68340 BSP
 ------------------------------------------
+The gen68340 BSP provides a default Interrupt Vector Table in the
+file ``$BSP_ROOT/start340/start340.s``.  After the ``entry``
+label is the definition of space reserved for the table of
+interrupts vectors.  This space is assigned the symbolic name
+of ``__uhoh`` in the ``gen68340`` BSP.
+At ``__uhoh`` label is the default interrupt handler routine. This
+routine is only called when an unexpected interrupts is raised.  One can
+add their own routine there (in that case there's a call to a routine -
+$BSP_ROOT/startup/dumpanic.c - that prints which address caused the
+interrupt and the contents of the registers, stack, etc.), but this should
+not return.
+The gen68340 BSP provides a default Interrupt Vector Table in the file
+``$BSP_ROOT/start340/start340.s``.  After the ``entry`` label is the definition
+of space reserved for the table of interrupts vectors.  This space is assigned
+the symbolic name of ``__uhoh`` in the ``gen68340`` BSP.
+At ``__uhoh`` label is the default interrupt handler routine. This routine is
+only called when an unexpected interrupts is raised.  One can add their own
+routine there (in that case there's a call to a routine -
+$BSP_ROOT/startup/dumpanic.c - that prints which address caused the interrupt
+and the contents of the registers, stack, etc.), but this should not return.
 Chip Select Initialization
 ==========================
 When the microprocessor accesses a memory area, address decoding is
+handled by an address decoder, so that the microprocessor knows which
 memory chip(s) to access.   The following figure illustrates this:
 .. code:: c
+When the microprocessor accesses a memory area, address decoding is handled by
+an address decoder, so that the microprocessor knows which memory chip(s) to
+access.  The following figure illustrates this:
+.. code::
     +-------------------+
     ------------|                   |
     ------------|                   \|------------
     ------------|      Address      \|------------
     ------------|      Decoder      \|------------
     ------------|                   \|------------
+    ------------|                   |------------
+    ------------|      Address      |------------
+    ------------|      Decoder      |------------
+    ------------|                   |------------
     ------------|                   |
     +-------------------+
     CPU Bus                           Chip Select
+The Chip Select registers must be programmed such that they match
+the ``linkcmds`` settings. In the gen68340 BSP, ROM and RAM
+addresses can be found in both the ``linkcmds`` and initialization
+code, but this is not a great way to do this.  It is better to
+define addresses in the linker script.
+The Chip Select registers must be programmed such that they match the
+``linkcmds`` settings. In the gen68340 BSP, ROM and RAM addresses can be found
+in both the ``linkcmds`` and initialization code, but this is not a great way
+to do this.  It is better to define addresses in the linker script.
 Integrated Processor Registers Initialization
 =============================================
 The CPUs used in many embedded systems are highly complex devices
+with multiple peripherals on the CPU itself.  For these devices,
+there are always some specific integrated processor registers
+that must be initialized.  Refer to the processors' manuals for
 details on these registers and be VERY careful programming them.
+The CPUs used in many embedded systems are highly complex devices with multiple
+peripherals on the CPU itself.  For these devices, there are always some
+specific integrated processor registers that must be initialized.  Refer to the
+processors' manuals for details on these registers and be VERY careful
+programming them.
 Data Section Recopy
 ===================
+The next initialization part can be found in``$BSP340_ROOT/start340/init68340.c``. First the Interrupt
+Vector Table is copied into RAM, then the data section recopy is initiated
+(_CopyDataClearBSSAndStart in ``$BSP340_ROOT/start340/startfor340only.s``).
+The next initialization part can be found in
+``$BSP340_ROOT/start340/init68340.c``. First the Interrupt Vector Table is
+copied into RAM, then the data section recopy is initiated
+(``_CopyDataClearBSSAndStart`` in ``$BSP340_ROOT/start340/startfor340only.s``).
 This code performs the following actions:
+- copies the .data section from ROM to its location reserved in RAM
+  (see `Initialized Data`_ for more details about this copy),
+- clear ``.bss`` section (all the non-initialized
+  data will take value 0).
+- copies the .data section from ROM to its location reserved in RAM (see
+  `Initialized Data`_ for more details about this copy),
+- clear ``.bss`` section (all the non-initialized data will take value 0).
 The RTEMS Configuration Table
 =============================
+The RTEMS configuration table contains the maximum number of objects RTEMS
+can handle during the application (e.g. maximum number of tasks,
+semaphores, etc.). It's used to allocate the size for the RTEMS inner data
+structures.
+The RTEMS configuration table is application dependent, which means that
+one has to provide one per application. It is usually defined by defining
+macros and including the header file ``<rtems/confdefs.h>``.  In simple
+applications such as the tests provided with RTEMS, it is commonly found
+in the main module of the application.  For more complex applications,
+it may be in a file by itself.
+The header file ``<rtems/confdefs.h>`` defines a constant table
+named ``Configuration``.  With RTEMS 4.8 and older, it was accepted
+practice for the BSP to copy this table into a modifiable copy named``BSP_Configuration``.  This copy of the table was modified to define
+the base address of the RTEMS Executive Workspace as well as to reflect
+any BSP and device driver requirements not automatically handled by the
+application.  In 4.9 and newer, we have eliminated the BSP copies of the
+configuration tables and are making efforts to make the configuration
+information generated by ``<rtems/confdefs.h>`` constant and read only.
+For more information on the RTEMS Configuration Table, refer to the*RTEMS Application C User's Guide*.
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+The RTEMS configuration table contains the maximum number of objects RTEMS can
+handle during the application (e.g. maximum number of tasks, semaphores,
+etc.). It's used to allocate the size for the RTEMS inner data structures.
+The RTEMS configuration table is application dependent, which means that one
+has to provide one per application. It is usually defined by defining macros
+and including the header file ``<rtems/confdefs.h>``.  In simple applications
+such as the tests provided with RTEMS, it is commonly found in the main module
+of the application.  For more complex applications, it may be in a file by
+itself.
+The header file ``<rtems/confdefs.h>`` defines a constant table named
+``Configuration``.  With RTEMS 4.8 and older, it was accepted practice for the
+BSP to copy this table into a modifiable copy named ``BSP_Configuration``.
+This copy of the table was modified to define the base address of the RTEMS
+Executive Workspace as well as to reflect any BSP and device driver
+requirements not automatically handled by the application.  In 4.9 and newer,
+we have eliminated the BSP copies of the configuration tables and are making
+efforts to make the configuration information generated by
+``<rtems/confdefs.h>`` constant and read only.
+For more information on the RTEMS Configuration Table, refer to the *RTEMS
+Application C User's Guide*.

bsp_howto/linker_script.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2011.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Linker Script
 …
 The ``linkcmds`` file is a script which is passed to the linker at linking
+time.  This file describes the memory configuration of the board as needed
+to link the program.  Specifically it specifies where the code and data
+for the application will reside in memory.
+The format of the linker script is defined by the GNU Loader ``ld``
+which is included as a component of the GNU Binary Utilities.  If you
+are using GNU/Linux, then you probably have the documentation installed
+already and are using these same tools configured for *native* use.
+Please visit the Binutils project http://sourceware.org/binutils/
+if you need more information.
+time.  This file describes the memory configuration of the board as needed to
+link the program.  Specifically it specifies where the code and data for the
+application will reside in memory.
+The format of the linker script is defined by the GNU Loader ``ld`` which is
+included as a component of the GNU Binary Utilities.  If you are using
+GNU/Linux, then you probably have the documentation installed already and are
+using these same tools configured for *native* use.  Please visit the Binutils
+project http://sourceware.org/binutils/ if you need more information.
 Program Sections
 ================
+An embedded systems programmer must be much more aware of the
+placement of their executable image in memory than the average
+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
+when examining the linker command file.
+An embedded systems programmer must be much more aware of the placement of
+their executable image in memory than the average 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 when examining the linker command file.
 Two types of memories have to be distinguished:
 …
 - ROM - non-volatile but read only
+Even though RAM and ROM can be found in every personal computer,
+one generally doesn't care about them.  In a personal computer,
+a program is nearly always stored on disk and executed in RAM.  Things
+are a bit different for embedded targets: the target will execute the
+program each time it is rebooted or switched on.   The application
+program is stored in non-volatile memory such as ROM, PROM, EEPROM,
+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 the COFF
+object file format on the Motorola m68k family of microprocessors,
+the following sections will be present:
+- *code (``.text``) section*:
+  is the program's code and it should not be modified.
+  This section may be placed in ROM.
+- *non-initialized data (``.bss``) section*:
+Even though RAM and ROM can be found in every personal computer, one generally
+doesn't care about them.  In a personal computer, a program is nearly always
+stored on disk and executed in RAM.  Things are a bit different for embedded
+targets: the target will execute the program each time it is rebooted or
+switched on.  The application program is stored in non-volatile memory such as
+ROM, PROM, EEPROM, 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 the COFF object file format on
+the Motorola m68k family of microprocessors, the following sections will be
+present:
+- code (``.text``) section:
+  is the program's code and it should not be modified.  This section may be
+  placed in ROM.
+- non-initialized data (``.bss``) section:
   holds uninitialized variables of the program. It can stay in RAM.
+- *initialized data (``.data``) section*:
+  holds the initialized program data which may be modified during the
+  program's life.  This means they have to be in RAM.
+  On the other hand, these variables must be set to predefined values, and
+  those predefined values have to be stored in ROM.
+*NOTE:* Many programs and support libraries unknowingly assume that the``.bss`` section and, possibly, the application heap are initialized
+to zero at program start.  This is not required by the ISO/ANSI C Standard
+but is such a common requirement that most BSPs do this.
+That brings us up to the notion of the image of an executable: it consists
+of the set of the sections that together constitute the application.
+- initialized data (``.data``) section:
+  holds the initialized program data which may be modified during the program's
+  life.  This means they have to be in RAM.  On the other hand, these variables
+  must be set to predefined values, and those predefined values have to be
+  stored in ROM.
+.. note::
+   Many programs and support libraries unknowingly assume that the ``.bss``
+   section and, possibly, the application heap are initialized to zero at
+   program start.  This is not required by the ISO/ANSI C Standard but is such
+   a common requirement that most BSPs do this.
+That brings us up to the notion of the image of an executable: it consists of
+the set of the sections that together constitute the application.
 Image of an Executable
 ======================
+As a program executable has many sections (note that the user can define
+their own, and that compilers define theirs without any notice), one has to
+specify the placement of each section as well as the type of memory
+(RAM or ROM) the sections will be placed into.
+For instance, a program compiled for a Personal Computer will see all the
+sections to go to RAM, while a program destined to be embedded will see
+some of his sections going into the ROM.
+The connection between a section and where that section is loaded into
+memory is made at link time.  One has to let the linker know where
+the different sections are to be placed once they are in memory.
+The following example shows a simple layout of program sections.  With
+some object formats, there are many more sections but the basic
+layout is conceptually similar.
+.. code:: c
+    +-----------------+-------------+
+    |     .text       |  RAM or ROM |
+    +-----------------+-------------+
+    |     .data       |  RAM        |
+    +-----------------+-------------+
+    |     .bss        |  RAM        |
+    +-----------------+-------------+
+As a program executable has many sections (note that the user can define their
+own, and that compilers define theirs without any notice), one has to specify
+the placement of each section as well as the type of memory (RAM or ROM) the
+sections will be placed into.  For instance, a program compiled for a Personal
+Computer will see all the sections to go to RAM, while a program destined to be
+embedded will see some of his sections going into the ROM.
+The connection between a section and where that section is loaded into memory
+is made at link time.  One has to let the linker know where the different
+sections are to be placed once they are in memory.
+The following example shows a simple layout of program sections.  With some
+object formats, there are many more sections but the basic layout is
+conceptually similar.
+============ =============
+.text        RAM or ROM
+.data        RAM
+.bss         RAM
+============ =============
 Example Linker Command Script
 …
 The GNU linker has a command language to specify the image format.  This
 command language can be quite complicated but most of what is required
+can be learned by careful examination of a well-documented example.
+The following is a heavily commented version of the linker script
+used with the the ``gen68340`` BSP  This file can be found at
+$BSP340_ROOT/startup/linkcmds.
+command language can be quite complicated but most of what is required can be
+learned by careful examination of a well-documented example.  The following is
+a heavily commented version of the linker script used with the the ``gen68340``
+BSP This file can be found at $BSP340_ROOT/startup/linkcmds.
 .. code:: c
     /*
     *  Specify that the output is to be coff-m68k regardless of what the
     *  native object format is.
     \*/
+     *  Specify that the output is to be coff-m68k regardless of what the
+     *  native object format is.
+     */
     OUTPUT_FORMAT(coff-m68k)
     /*
     *  Set the amount of RAM on the target board.
+    *
     *  NOTE: The default may be overridden by passing an argument to ld.
     \*/
+     *  Set the amount of RAM on the target board.
+     *
+     *  NOTE: The default may be overridden by passing an argument to ld.
+     */
     RamSize = DEFINED(RamSize) ? RamSize : 4M;
     /*
     *  Set the amount of RAM to be used for the application heap.  Objects
     *  allocated using malloc() come from this area.  Having a tight heap
     *  size is somewhat difficult and multiple attempts to squeeze it may
     *  be needed reducing memory usage is important.  If all objects are
     *  allocated from the heap at system initialization time, this eases
     *  the sizing of the application heap.
+    *
     *  NOTE 1: The default may be overridden by passing an argument to ld.
+    *
     *  NOTE 2: The TCP/IP stack requires additional memory in the Heap.
+    *
     *  NOTE 3: The GNAT/RTEMS run-time requires additional memory in
     *  the Heap.
     \*/
+     *  Set the amount of RAM to be used for the application heap.  Objects
+     *  allocated using malloc() come from this area.  Having a tight heap
+     *  size is somewhat difficult and multiple attempts to squeeze it may
+     *  be needed reducing memory usage is important.  If all objects are
+     *  allocated from the heap at system initialization time, this eases
+     *  the sizing of the application heap.
+     *
+     *  NOTE 1: The default may be overridden by passing an argument to ld.
+     *
+     *  NOTE 2: The TCP/IP stack requires additional memory in the Heap.
+     *
+     *  NOTE 3: The GNAT/RTEMS run-time requires additional memory in
+     *  the Heap.
+     */
     HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
     /*
     *  Set the size of the starting stack used during BSP initialization
     *  until first task switch.  After that point, task stacks allocated
     *  by RTEMS are used.
+    *
     *  NOTE: The default may be overridden by passing an argument to ld.
     \*/
+     *  Set the size of the starting stack used during BSP initialization
+     *  until first task switch.  After that point, task stacks allocated
+     *  by RTEMS are used.
+     *
+     *  NOTE: The default may be overridden by passing an argument to ld.
+     */
     StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
     /*
     *  Starting addresses and length of RAM and ROM.
+    *
     *  The addresses must be valid addresses on the board.  The
     *  Chip Selects should be initialized such that the code addresses
     *  are valid.
     \*/
+     *  Starting addresses and length of RAM and ROM.
+     *
+     *  The addresses must be valid addresses on the board.  The
+     *  Chip Selects should be initialized such that the code addresses
+     *  are valid.
+     */
     MEMORY {
     ram : ORIGIN = 0x10000000, LENGTH = 4M
 …
+    }
     /*
     *  This is for the network driver.  See the Networking documentation
     *  for more details.
     \*/
+     *  This is for the network driver.  See the Networking documentation
+     *  for more details.
+     */
     ETHERNET_ADDRESS =
     DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
     /*
     *  The following defines the order in which the sections should go.
     *  It also defines a number of variables which can be used by the
     *  application program.
+    *
     *  NOTE: Each variable appears with 1 or 2 leading underscores to
     *        ensure that the variable is accessible from C code with a
     *        single underscore.  Some object formats automatically add
     *        a leading underscore to all C global symbols.
     \*/
+     *  The following defines the order in which the sections should go.
+     *  It also defines a number of variables which can be used by the
+     *  application program.
+     *
+     *  NOTE: Each variable appears with 1 or 2 leading underscores to
+     *        ensure that the variable is accessible from C code with a
+     *        single underscore.  Some object formats automatically add
+     *        a leading underscore to all C global symbols.
+     */
     SECTIONS {
     /*
     *  Make the RomBase variable available to the application.
     \*/
+     *  Make the RomBase variable available to the application.
+     */
     _RamSize = RamSize;
     __RamSize = RamSize;
     /*
     *  Boot PROM  - Set the RomBase variable to the start of the ROM.
     \*/
+     *  Boot PROM  - Set the RomBase variable to the start of the ROM.
+     */
     rom : {
     _RomBase = .;
     __RomBase = .;
+      _RomBase = .;
+      __RomBase = .;
     } >rom
     /*
     * Dynamic RAM - set the RamBase variable to the start of the RAM.
     \*/
+     * Dynamic RAM - set the RamBase variable to the start of the RAM.
+     */
     ram : {
     _RamBase = .;
     __RamBase = .;
     } >ram
     /*
     *  Text (code) goes into ROM
     \*/
+      _RamBase = .;
+      __RamBase = .;
+    } >ram
+    /*
+     *  Text (code) goes into ROM
+     */
     .text : {
     /*
     *  Create a symbol for each object (.o).
     \*/
     CREATE_OBJECT_SYMBOLS
     /*
     *  Put all the object files code sections here.
     \*/
     \*(.text)
     . = ALIGN (16);      /*  go to a 16-byte boundary \*/
     /*
     *  C++ constructors and destructors
+    *
     *  NOTE:  See the CROSSGCC mailing-list FAQ for
     *         more details about the "\[......]".
     \*/
     __CTOR_LIST__ = .;
     \[......]
     __DTOR_END__ = .;
     /*
     *  Declares where the .text section ends.
     \*/
     etext = .;
     _etext = .;
+      /*
+       *  Create a symbol for each object (.o).
+       */
+      CREATE_OBJECT_SYMBOLS
+      /*
+       *  Put all the object files code sections here.
+       */
+      *(.text)
+      . = ALIGN (16);      /*  go to a 16-byte boundary */
+      /*
+       *  C++ constructors and destructors
+       *
+       *  NOTE:  See the CROSSGCC mailing-list FAQ for
+       *         more details about the "\[......]".
+       */
+      __CTOR_LIST__ = .;
+       [......]
+      __DTOR_END__ = .;
+      /*
+       *  Declares where the .text section ends.
+       */
+      etext = .;
+     _etext = .;
     } >rom
     /*
     *  Exception Handler Frame section
     \*/
+     *  Exception Handler Frame section
+     */
     .eh_fram : {
     . = ALIGN (16);
     \*(.eh_fram)
     } >ram
     /*
     *  GCC Exception section
     \*/
+      . = ALIGN (16);
+      *(.eh_fram)
+    } >ram
+    /*
+     *  GCC Exception section
+     */
     .gcc_exc : {
     . = ALIGN (16);
     \*(.gcc_exc)
     } >ram
     /*
     *  Special variable to let application get to the dual-ported
     *  memory.
     \*/
+      . = ALIGN (16);
+      *(.gcc_exc)
+    } >ram
+    /*
+     *  Special variable to let application get to the dual-ported
+     *  memory.
+     */
     dpram : {
     m340 = .;
     _m340 = .;
     . += (8 * 1024);
     } >ram
     /*
     *  Initialized Data section goes in RAM
     \*/
+      m340 = .;
+      _m340 = .;
+      . += (8 * 1024);
+    } >ram
+    /*
+     *  Initialized Data section goes in RAM
+     */
     .data : {
     copy_start = .;
     \*(.data)
     . = ALIGN (16);
     _edata = .;
     copy_end = .;
     } >ram
     /*
     *  Uninitialized Data section goes in ROM
     \*/
+      copy_start = .;
+      *(.data)
+      . = ALIGN (16);
+      _edata = .;
+      copy_end = .;
+    } >ram
+    /*
+     *  Uninitialized Data section goes in ROM
+     */
     .bss : {
+    /*
+    *  M68K specific: Reserve some room for the Vector Table
+    *  (256 vectors of 4 bytes).
+    \*/
+    M68Kvec = .;
+    _M68Kvec = .;
+    . += (256 * 4);
+    /*
+    *  Start of memory to zero out at initialization time.
+    \*/
+    clear_start = .;
+    /*
+    *  Put all the object files uninitialized data sections
+    *  here.
+    \*/
+    \*(.bss)
+    \*(COMMON)
+    . = ALIGN (16);
+    _end = .;
+    /*
+    *  Start of the Application Heap
+    \*/
+    _HeapStart = .;
+    __HeapStart = .;
+    . += HeapSize;
+    /*
+    *  The Starting Stack goes after the Application Heap.
+    *  M68K stack grows down so start at high address.
+    \*/
+    . += StackSize;
+    . = ALIGN (16);
+    stack_init = .;
+    clear_end = .;
+    /*
+    *  The RTEMS Executive Workspace goes here.  RTEMS
+    *  allocates tasks, stacks, semaphores, etc. from this
+    *  memory.
+    \*/
+    _WorkspaceBase = .;
+    __WorkspaceBase = .;
+    } >ram
+    }
+      /*
+      *  M68K specific: Reserve some room for the Vector Table
+      *  (256 vectors of 4 bytes).
+      */
+      M68Kvec = .;
+      _M68Kvec = .;
+      . += (256 * 4);
+      /*
+      *  Start of memory to zero out at initialization time.
+      */
+      clear_start = .;
+      /*
+       *  Put all the object files uninitialized data sections
+       *  here.
+       */
+      *(.bss)
+      *(COMMON)
+      . = ALIGN (16);
+      _end = .;
+      /*
+       *  Start of the Application Heap
+       */
+      _HeapStart = .;
+      __HeapStart = .;
+      . += HeapSize;
+      /*
+      *  The Starting Stack goes after the Application Heap.
+      *  M68K stack grows down so start at high address.
+      */
+      . += StackSize;
+      . = ALIGN (16);
+      stack_init = .;
+      clear_end = .;
+      /*
+      *  The RTEMS Executive Workspace goes here.  RTEMS
+      *  allocates tasks, stacks, semaphores, etc. from this
+      *  memory.
+      */
+      _WorkspaceBase = .;
+      __WorkspaceBase = .;
+    } >ram
 Initialized Data
 ================
+Now there's a problem with the initialized data: the ``.data`` section
+has to be in RAM as this data may be modified during the program execution.
+But how will the values be initialized at boot time?
+One approach is to place the entire program image in RAM and reload
+the image in its entirety each time the program is run.  This is fine
+for use in a debug environment where a high-speed connection is available
+between the development host computer and the target.  But even in this
+environment, it is cumbersome.
+The solution is to place a copy of the initialized data in a separate
+area of memory and copy it into the proper location each time the
+program is started.  It is common practice to place a copy of the initialized ``.data`` section at the end of the code (``.text``) section
+in ROM when building a PROM image. The GNU tool ``objcopy``
+can be used for this purpose.
+Now there's a problem with the initialized data: the ``.data`` section has to
+be in RAM as this data may be modified during the program execution.  But how
+will the values be initialized at boot time?
+One approach is to place the entire program image in RAM and reload the image
+in its entirety each time the program is run.  This is fine for use in a debug
+environment where a high-speed connection is available between the development
+host computer and the target.  But even in this environment, it is cumbersome.
+The solution is to place a copy of the initialized data in a separate area of
+memory and copy it into the proper location each time the program is started.
+It is common practice to place a copy of the initialized ``.data`` section at
+the end of the code (``.text``) section in ROM when building a PROM image. The
+GNU tool ``objcopy`` can be used for this purpose.
 The following figure illustrates the steps a linked program goes through
 to become a downloadable image.
++--------------+-----+--------------------+--------------------------+
 | .data    RAM |     | .data          RAM |                          |
 +--------------+     +--------------------+                          |
+| .bss     RAM |     | .bss           RAM |                          |
++--------------+     +--------------------+-----+--------------------+
+| .text    ROM |     | .text          ROM |     |     .text          |
++--------------+-----+---------+----------+-----+--------------------+
+| copy of .data  ROM |         | copy of .data  |                    |
++--------------------+---------+----------------+--------------------+
+|  Step 1            |Step 2                       Step 3            |
++--------------------+--------------------------+--------------------+
++--------------+------+--------------------------+--------------------+
+| .data (RAM)  |      | .data (RAM)              |                    |
++--------------+      +--------------------------+                    |
+| .bss (RAM)   |      | .bss (RAM)               |                    |
++--------------+      +--------------------------+--------------------+
+| .text (ROM)  |      | .text (ROM)              | .text              |
++--------------+------+---------+----------+-----+--------------------+
+| copy of .data (ROM) |         | copy of .data  |                    |
++---------------------+---------+----------------+--------------------+
+|  Step 1             | Step 2                   | Step 3             |
++---------------------+--------------------------+--------------------+
 In Step 1, the program is linked together using the BSP linker script.
+In Step 2, a copy is made of the ``.data`` section and placed
+after the ``.text`` section so it can be placed in PROM.  This step
+is done after the linking time.  There is an example
+of doing this in the file $RTEMS_ROOT/make/custom/gen68340.cfg:
+.. code:: c
+In Step 2, a copy is made of the ``.data`` section and placed after the
+``.text`` section so it can be placed in PROM.  This step is done after the
+linking time.  There is an example of doing this in the file
+$RTEMS_ROOT/make/custom/gen68340.cfg:
+.. code-block:: shell
     # make a PROM image using objcopy
+    m68k-rtems-objcopy \\
+    --adjust-section-vma .data= \\
+    \`m68k-rtems-objdump --section-headers \\
+    $(basename $@).exe \\
+    | awk '\[...]` \\
+    m68k-rtems-objcopy --adjust-section-vma \
+    .data=`m68k-rtems-objdump --section-headers $(basename $@).exe | awk '[...]'` \
     $(basename $@).exe
+NOTE: The address of the "copy of ``.data`` section" is
+created by extracting the last address in the ``.text``
+section with an ``awk`` script.  The details of how
+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 ""copy of ``.data`` section" (which are stored in
+ROM) to their reserved location in RAM.
+.. COMMENT: COPYRIGHT (c) 1988-2011.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+.. note::
+   The address of the "copy of ``.data`` section" is created by extracting the
+   last address in the ``.text`` section with an ``awk`` script.  The details
+   of how 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
+""copy of ``.data`` section" (which are stored in ROM) to their reserved
+location in RAM.

bsp_howto/makefiles.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 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 four phases as shown here:
+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 four phases as
+shown here:
 - .. code:: c
+- ``bootstrap``
+      bootstrap
+- ``configure``
 - .. code:: c
+- ``build``
+      configure
+- ``install``
+- .. code:: c
+During the bootstrap phase, you are using the ``configure.ac`` and
+``Makefile.am`` files as input to GNU autoconf and automake to generate a
+variety of files.  This is done by running the ``bootstrap`` script found at
+the top of the RTEMS source tree.
+      build
+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.
+- .. code:: c
+During the build phase, the source files are compiled into object files and
+libraries are built.
+      install
+During the bootstrap phase, you are using the ``configure.ac`` and``Makefile.am`` files as input to GNU autoconf and automake to
+generate a variety of files.  This is done by running the ``bootstrap``
+script found at the top of the RTEMS source tree.
+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.
+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.
 Makefiles Used During The BSP Building Process
 ==============================================
+RTEMS uses the *GNU automake* and *GNU autoconf* automatic
+configuration package.  Consequently, there are a number of
+automatically generated files in each directory in the RTEMS
+source tree.  The ``bootstrap`` script found in the top level
+directory of the RTEMS source tree is executed to produce the
+automatically generated files.  That script must be run from
+a directory with a ``configure.ac`` file in it.  The ``bootstrap``
+command is usually invoked in one of the following manners:
+RTEMS uses the *GNU automake* and *GNU autoconf* automatic configuration
+package.  Consequently, there are a number of automatically generated files in
+each directory in the RTEMS source tree.  The ``bootstrap`` script found in the
+top level directory of the RTEMS source tree is executed to produce the
+automatically generated files.  That script must be run from a directory with a
+``configure.ac`` file in it.  The ``bootstrap`` command is usually invoked in
+one of the following manners:
 - ``bootstrap`` to regenerate all files that are generated by
   autoconf and automake.
+- ``bootstrap`` to regenerate all files that are generated by autoconf and
+  automake.
+- ``bootstrap -c`` to remove all files generated by autoconf and
+  automake.
+- ``bootstrap -c`` to remove all files generated by autoconf and automake.
 - ``bootstrap -p`` to regenerate ``preinstall.am`` files.
 There is a file named ``Makefile.am`` in each directory of
+a BSP.  This file is used by *automake* to produce the file named``Makefile.in`` which is also found in each directory of a BSP.
+When modifying a ``Makefile.am``, you can probably find examples of
 anything you need to do in one of the BSPs.
+There is a file named ``Makefile.am`` in each directory of a BSP.  This file is
+used by *automake* to produce the file named ``Makefile.in`` which is also
+found in each directory of a BSP.  When modifying a ``Makefile.am``, you can
+probably find examples of anything you need to do in one of the BSPs.
+The configure process specializes the ``Makefile.in`` files at the time that RTEMS
+is configured for a specific development host and target.  Makefiles
+are automatically generated from the ``Makefile.in`` files.  It is
+necessary for the BSP developer to provide the ``Makefile.am``
+files and generate the ``Makefile.in`` files.  Most of the
+time, it is possible to copy the ``Makefile.am`` from another
+similar directory and edit it.
+The configure process specializes the ``Makefile.in`` files at the time that
+RTEMS is configured for a specific development host and target.  Makefiles are
+automatically generated from the ``Makefile.in`` files.  It is necessary for
+the BSP developer to provide the ``Makefile.am`` files and generate the
+``Makefile.in`` files.  Most of the time, it is possible to copy the
+``Makefile.am`` from another similar directory and edit it.
 The ``Makefile`` files generated are processed when configuring
 and building RTEMS for a given BSP.
+The ``Makefile`` files generated are processed when configuring and building
+RTEMS for a given BSP.
 The BSP developer is responsible for generating ``Makefile.am``
+files which properly build all the files associated with their BSP.
+Most BSPs will only have a single ``Makefile.am`` which details
+the set of source files to build to compose the BSP support library
 along with the set of include files that are to be installed.
+The BSP developer is responsible for generating ``Makefile.am`` files which
+properly build all the files associated with their BSP.  Most BSPs will only
+have a single ``Makefile.am`` which details the set of source files to build to
+compose the BSP support library along with the set of include files that are to
+be installed.
+This single ``Makefile.am`` at the top of the BSP tree specifies
+the set of header files to install.  This fragment from the SPARC/ERC32
+BSP results in four header files being installed.
+.. code:: c
+This single ``Makefile.am`` at the top of the BSP tree specifies the set of
+header files to install.  This fragment from the SPARC/ERC32 BSP results in
+four header files being installed.
+.. code-block:: makefile
     include_HEADERS = include/bsp.h
 …
     include_HEADERS += include/coverhd.h
+When adding new include files, you will be adding to the set of``include_HEADERS``.  When you finish editing the ``Makefile.am``
+file, do not forget to run ``bootstrap -p`` to regenerate the``preinstall.am``.
+When adding new include files, you will be adding to the set of
+``include_HEADERS``.  When you finish editing the ``Makefile.am`` file, do not
+forget to run ``bootstrap -p`` to regenerate the ``preinstall.am``.
+The ``Makefile.am`` also specifies which source files to build.
+By convention, logical components within the BSP each assign their
+source files to a unique variable.  These variables which define
+the source files are collected into a single variable which instructs
+the GNU autotools that we are building ``libbsp.a``.  This fragment
+from the SPARC/ERC32 BSP shows how the startup related, miscellaneous
+support code, and the console device driver source is managed
+in the ``Makefile.am``.
+.. code:: c
+The ``Makefile.am`` also specifies which source files to build.  By convention,
+logical components within the BSP each assign their source files to a unique
+variable.  These variables which define the source files are collected into a
+single variable which instructs the GNU autotools that we are building
+``libbsp.a``.  This fragment from the SPARC/ERC32 BSP shows how the startup
+related, miscellaneous support code, and the console device driver source is
+managed in the ``Makefile.am``.
+    startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \\
+    ../../shared/bsppredriverhook.c \\
+    ../../shared/bsppost.c ../../sparc/shared/bspstart.c \\
+    ../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \\
+.. code-block:: makefile
+    startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \
+    ../../shared/bsppredriverhook.c \
+    ../../shared/bsppost.c ../../sparc/shared/bspstart.c \
+    ../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \
     startup/spurious.c startup/erc32mec.c startup/boardinit.S
     clock_SOURCES = clock/ckinit.c
 …
     libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
+When adding new files to an existing directory, do not forget to add
+the new files to the list of files to be built in the corresponding``XXX_SOURCES`` variable in the ``Makefile.am`` and run``bootstrap``.
+When adding new files to an existing directory, do not forget to add the new
+files to the list of files to be built in the corresponding ``XXX_SOURCES``
+variable in the ``Makefile.am`` and run``bootstrap``.
+Some BSPs use code that is built in ``libcpu``.  If you BSP does
+this, then you will need to make sure the objects are pulled into your
+BSP library.  The following from the SPARC/ERC32 BSP pulls in the cache,
+register window management and system call support code from the directory
+corresponding to its ``RTEMS_CPU`` model.
+.. code:: c
+Some BSPs use code that is built in ``libcpu``.  If you BSP does this, then you
+will need to make sure the objects are pulled into your BSP library.  The
+following from the SPARC/ERC32 BSP pulls in the cache, register window
+management and system call support code from the directory corresponding to its
+``RTEMS_CPU`` model.
+    libbsp_a_LIBADD  = ../../../libcpu/@RTEMS_CPU@/cache.rel \\
+    ../../../libcpu/@RTEMS_CPU@/reg_win.rel \\
+.. code-block:: makefile
+    libbsp_a_LIBADD  = ../../../libcpu/@RTEMS_CPU@/cache.rel \
+    ../../../libcpu/@RTEMS_CPU@/reg_win.rel \
     ../../../libcpu/@RTEMS_CPU@/syscall.rel
+*NOTE:* The ``Makefile.am`` files are ONLY processed by``bootstrap`` and the resulting ``Makefile.in`` files are only
+processed during the configure process of a RTEMS build. Therefore,
+when developing a BSP and adding a new file to a ``Makefile.am``,
+the already generated ``Makefile`` will not automatically
+include the new references unless you configured RTEMS with the``--enable-maintainer-mode`` option.  Otherwise, the new file not
+being be taken into account!
+.. note:
+The ``Makefile.am`` files are ONLY processed by ``bootstrap`` and the resulting
+``Makefile.in`` files are only processed during the configure process of a
+RTEMS build. Therefore, when developing a BSP and adding a new file to a
+``Makefile.am``, the already generated ``Makefile`` will not automatically
+include the new references unless you configured RTEMS with the
+``--enable-maintainer-mode`` option.  Otherwise, the new file will not being be
+taken into account!
 Creating a New BSP Make Customization File
 ==========================================
+When building a BSP or an application using that BSP, it is necessary
+to tailor the compilation arguments to account for compiler flags, use
+custom linker scripts, include the RTEMS libraries, etc..  The BSP
+must be built using this information.  Later, once the BSP is installed
+with the toolset, this same information must be used when building the
+application.  So a BSP must include a build configuration file.  The
+configuration file is ``make/custom/BSP.cfg``.
+When building a BSP or an application using that BSP, it is necessary to tailor
+the compilation arguments to account for compiler flags, use custom linker
+scripts, include the RTEMS libraries, etc..  The BSP must be built using this
+information.  Later, once the BSP is installed with the toolset, this same
+information must be used when building the application.  So a BSP must include
+a build configuration file.  The configuration file is ``make/custom/BSP.cfg``.
+The configuration file is taken into account when building one's
+application using the RTEMS template Makefiles (``make/templates``).
+These application template Makefiles have been included with the
+RTEMS source distribution since the early 1990's.  However there is
+a desire in the RTEMS user community to move all provided examples to
+GNU autoconf. They are included in the 4.9 release series and used for
+all examples provided with RTEMS. There is no definite time table for
+obsoleting them.  You are free to use these but be warned they have
+fallen out of favor with many in the RTEMS community and may disappear
+in the future.
+The configuration file is taken into account when building one's application
+using the RTEMS template Makefiles (``make/templates``).  These application
+template Makefiles have been included with the RTEMS source distribution since
+the early 1990's.  However there is a desire in the RTEMS user community to
+move all provided examples to GNU autoconf. They are included in the 4.9
+release series and used for all examples provided with RTEMS. There is no
+definite time table for obsoleting them.  You are free to use these but be
+warned they have fallen out of favor with many in the RTEMS community and may
+disappear in the future.
+The following is a slightly shortened version of the make customization
+file for the gen68340 BSP.  The original source for this file can be
+found in the ``make/custom`` directory.
+.. code:: c
+The following is a slightly shortened version of the make customization file
+for the gen68340 BSP.  The original source for this file can be found in the
+``make/custom`` directory.
+.. code-block:: makefile
     # The RTEMS CPU Family and Model
 …
     CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
+The make customization files have generally grown simpler and simpler
+with each RTEMS release.  Beginning in the 4.9 release series, the rules
+for linking an RTEMS application are shared by all BSPs.  Only BSPs which
+need to perform a transformation from linked ELF file to a downloadable
+format have any additional actions for program link time. In 4.8 and
+older, every BSP specified the "make executable" or ``make-exe``
+rule and duplicated the same actions.
+The make customization files have generally grown simpler and simpler with each
+RTEMS release.  Beginning in the 4.9 release series, the rules for linking an
+RTEMS application are shared by all BSPs.  Only BSPs which need to perform a
+transformation from linked ELF file to a downloadable format have any
+additional actions for program link time. In 4.8 and older, every BSP specified
+the "make executable" or ``make-exe`` rule and duplicated the same actions.
+It is generally easier to copy a ``make/custom`` file from a
+BSP similar to the one being developed.
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+It is generally easier to copy a ``make/custom`` file from a BSP similar to the
+one being developed.

bsp_howto/miscellanous_support.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Miscellaneous Support Files
 …
 ================================
 The file ``bsp_specs`` defines the start files and libraries
+that are always used with this BSP.  The format of this file
+is admittedly cryptic and this document will make no attempt
+to explain it completely.  Below is the ``bsp_specs``
+file from the PowerPC psim BSP:
 .. code:: c
+The file ``bsp_specs`` defines the start files and libraries that are always
+used with this BSP.  The format of this file is admittedly cryptic and this
+document will make no attempt to explain it completely.  Below is the
+``bsp_specs`` file from the PowerPC psim BSP:
+.. code-block:: c
     %rename endfile old_endfile
     %rename startfile old_startfile
     %rename link old_link
     \*startfile:
     %{!qrtems: %(old_startfile)} \\
+    *startfile:
+    %{!qrtems: %(old_startfile)} \
     %{!nostdlib: %{qrtems: ecrti%O%s rtems_crti%O%s crtbegin.o%s start.o%s}}
     \*link:
+    *link:
     %{!qrtems: %(old_link)} %{qrtems: -Qy -dp -Bstatic -e _start -u __vectors}
     \*endfile:
+    *endfile:
     %{!qrtems: %(old_endfile)} %{qrtems: crtend.o%s ecrtn.o%s}
+The first section of this file renames the built-in definition of
+some specification variables so they can be augmented without
+embedded their original definition.  The subsequent sections
+specify what behavior is expected when the ``-qrtems`` option is specified.
+The ``*startfile`` section specifies that the BSP specific file``start.o`` will be used instead of ``crt0.o``.  In addition,
+various EABI support files (``ecrti.o`` etc.) will be linked in with
+the executable.
+The ``*link`` section adds some arguments to the linker when it is
+invoked by GCC to link an application for this BSP.
+The format of this file is specific to the GNU Compiler Suite.  The
+argument used to override and extend the compiler built-in specifications
+is available in all recent GCC versions.  The ``-specs`` option is
+present in all ``egcs`` distributions and ``gcc`` distributions
+starting with version 2.8.0.
+The first section of this file renames the built-in definition of some
+specification variables so they can be augmented without embedded their
+original definition.  The subsequent sections specify what behavior is expected
+when the ``-qrtems`` option is specified.
+The ``*startfile`` section specifies that the BSP specific file ``start.o``
+will be used instead of ``crt0.o``.  In addition, various EABI support files
+(``ecrti.o`` etc.) will be linked in with the executable.
+The ``*link`` section adds some arguments to the linker when it is invoked by
+GCC to link an application for this BSP.
+The format of this file is specific to the GNU Compiler Suite.  The argument
+used to override and extend the compiler built-in specifications is available
+in all recent GCC versions.  The ``-specs`` option is present in all ``egcs``
+distributions and ``gcc`` distributions starting with version 2.8.0.
 README Files
 ============
+Most BSPs provide one or more ``README`` files.  Generally, there
+is a ``README`` file at the top of the BSP source.  This file
+describes the board and its hardware configuration, provides vendor
+information, local configuration information, information on downloading
+code to the board, debugging, etc..  The intent of this
+file is to help someone begin to use the BSP faster.
+A ``README`` file in a BSP subdirectory typically explains something
+about the contents of that subdirectory in greater detail.  For example,
+it may list the documentation available for a particular peripheral
+controller and how to obtain that documentation.  It may also explain some
+particularly cryptic part of the software in that directory or provide
+rationale on the implementation.
+Most BSPs provide one or more ``README`` files.  Generally, there is a
+``README`` file at the top of the BSP source.  This file describes the board
+and its hardware configuration, provides vendor information, local
+configuration information, information on downloading code to the board,
+debugging, etc..  The intent of this file is to help someone begin to use the
+BSP faster.
+A ``README`` file in a BSP subdirectory typically explains something about the
+contents of that subdirectory in greater detail.  For example, it may list the
+documentation available for a particular peripheral controller and how to
+obtain that documentation.  It may also explain some particularly cryptic part
+of the software in that directory or provide rationale on the implementation.
 times
 =====
 This file contains the results of the RTEMS Timing Test Suite.  It is
+in a standard format so that results from one BSP can be easily compared
 with those of another target board.
+This file contains the results of the RTEMS Timing Test Suite.  It is in a
+standard format so that results from one BSP can be easily compared with those
+of another target board.
 If a BSP supports multiple variants, then there may be multiple ``times``
 …
 ==================
 Some BSPs provide additional tools that aid in using the target board.
+These tools run on the development host and are built as part of building
+the BSP.  Most common is a script to automate running the RTEMS Test Suites
 on the BSP.  Examples of this include:
+Some BSPs provide additional tools that aid in using the target board.  These
+tools run on the development host and are built as part of building the BSP.
+Most common is a script to automate running the RTEMS Test Suites on the BSP.
+Examples of this include:
 - ``powerpc/psim`` includes scripts to ease use of the simulator
+- ``m68k/mvme162`` includes a utility to download across the
+  VMEbus into target memory if the host is a VMEbus board in the same
+  chasis.
+- ``m68k/mvme162`` includes a utility to download across the VMEbus into target
+  memory if the host is a VMEbus board in the same chasis.
 bsp.h Include File
 ==================
+The file ``include/bsp.h`` contains prototypes and definitions
+specific to this board.  Every BSP is required to provide a ``bsp.h``.
+The best approach to writing a ``bsp.h`` is copying an existing one
+as a starting point.
+Many ``bsp.h`` files provide prototypes of variables defined
+in the linker script (``linkcmds``).
+The file ``include/bsp.h`` contains prototypes and definitions specific to this
+board.  Every BSP is required to provide a ``bsp.h``.  The best approach to
+writing a ``bsp.h`` is copying an existing one as a starting point.
+Many ``bsp.h`` files provide prototypes of variables defined in the linker
+script (``linkcmds``).
 tm27.h Include File
 ===================
+The ``tm27`` test from the RTEMS Timing Test Suite is designed to measure the length of time required to vector to and return from an interrupt handler. This test requires some help from the BSP to know how to cause and manipulate the interrupt source used for this measurement.  The following is a list of these:
+The ``tm27`` test from the RTEMS Timing Test Suite is designed to measure the
+length of time required to vector to and return from an interrupt handler. This
+test requires some help from the BSP to know how to cause and manipulate the
+interrupt source used for this measurement.  The following is a list of these:
 - ``MUST_WAIT_FOR_INTERRUPT`` - modifies behavior of ``tm27``.
+- ``Install_tm27_vector`` - installs the interrupt service
+  routine for the Interrupt Benchmark Test (``tm27``).
+- ``Cause_tm27_intr`` - generates the interrupt source
+  used in the Interrupt Benchmark Test (``tm27``).
+- ``Clear_tm27_intr`` - clears the interrupt source
+  used in the Interrupt Benchmark Test (``tm27``).
+- ``Lower_tm27_intr`` - lowers the interrupt mask so the
+  interrupt source used in the Interrupt Benchmark Test (``tm27``)
+  can generate a nested interrupt.
+All members of the Timing Test Suite are designed to run *WITHOUT*
+the Clock Device Driver installed.  This increases the predictability
+of the tests' execution as well as avoids occassionally including the
+overhead of a clock tick interrupt in the time reported.  Because of
+this it is sometimes possible to use the clock tick interrupt source
+as the source of this test interrupt.  On other architectures, it is
+possible to directly force an interrupt to occur.
+- ``Install_tm27_vector`` - installs the interrupt service routine for the
+  Interrupt Benchmark Test (``tm27``).
+- ``Cause_tm27_intr`` - generates the interrupt source used in the Interrupt
+  Benchmark Test (``tm27``).
+- ``Clear_tm27_intr`` - clears the interrupt source used in the Interrupt
+  Benchmark Test (``tm27``).
+- ``Lower_tm27_intr`` - lowers the interrupt mask so the interrupt source used
+  in the Interrupt Benchmark Test (``tm27``) can generate a nested interrupt.
+All members of the Timing Test Suite are designed to run *WITHOUT* the Clock
+Device Driver installed.  This increases the predictability of the tests'
+execution as well as avoids occassionally including the overhead of a clock
+tick interrupt in the time reported.  Because of this it is sometimes possible
+to use the clock tick interrupt source as the source of this test interrupt.
+On other architectures, it is possible to directly force an interrupt to occur.
 Calling Overhead File
 =====================
 The file ``include/coverhd.h`` contains the overhead associated
+with invoking each directive.  This overhead consists of the execution
+time required to package the parameters as well as to execute the "jump to
+subroutine" and "return from subroutine" sequence.  The intent of this
+file is to help separate the calling overhead from the actual execution
+time of a directive.  This file is only used by the tests in the
+RTEMS Timing Test Suite.
+The numbers in this file are obtained by running the "Timer Overhead"``tmoverhd`` test.  The numbers in this file may be 0 and no
+overhead is subtracted from the directive execution times reported by
+the Timing Suite.
+There is a shared implementation of ``coverhd.h`` which sets all of
 the overhead constants to 0.  On faster processors, this is usually the
+best alternative for the BSP as the calling overhead is extremely small.
+This file is located at:
+The file ``include/coverhd.h`` contains the overhead associated with invoking
+each directive.  This overhead consists of the execution time required to
+package the parameters as well as to execute the "jump to subroutine" and
+"return from subroutine" sequence.  The intent of this file is to help separate
+the calling overhead from the actual execution time of a directive.  This file
+is only used by the tests in the RTEMS Timing Test Suite.
+The numbers in this file are obtained by running the "Timer
+Overhead"``tmoverhd`` test.  The numbers in this file may be 0 and no overhead
+is subtracted from the directive execution times reported by the Timing Suite.
+There is a shared implementation of ``coverhd.h`` which sets all of the
+overhead constants to 0.  On faster processors, this is usually the best
+alternative for the BSP as the calling overhead is extremely small.  This file
+is located at:
 .. code:: c
 …
 =====================
+Although nearly all BSPs give all possible memory to the C Program Heap
+at initialization, it is possible for a BSP to configure the initial
+size of the heap small and let it grow on demand.  If the BSP wants
+to dynamically extend the heap used by the C Library memory allocation
+routines (i.e. ``malloc`` family), then the``sbrk`` routine must
+be functional.  The following is the prototype for this routine:
+Although nearly all BSPs give all possible memory to the C Program Heap at
+initialization, it is possible for a BSP to configure the initial size of the
+heap small and let it grow on demand.  If the BSP wants to dynamically extend
+the heap used by the C Library memory allocation routines (i.e. ``malloc``
+family), then the``sbrk`` routine must be functional.  The following is the
+prototype for this routine:
 .. code:: c
     void * sbrk(size_t increment)
+The ``increment`` amount is based upon the ``sbrk_amount``
+parameter passed to the ``bsp_libc_init`` during system initialization... index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
+If your BSP does not want to support dynamic heap extension, then you do not have to do anything special.  However, if you want to support ``sbrk``, you must provide an implementation of this method and define ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` in ``bsp.h``.  This informs ``rtems/confdefs.h`` to configure the Malloc Family Extensions which support ``sbrk``.
+The ``increment`` amount is based upon the ``sbrk_amount`` parameter passed to
+the ``bsp_libc_init`` during system initialization.
+.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
+If your BSP does not want to support dynamic heap extension, then you do not
+have to do anything special.  However, if you want to support ``sbrk``, you
+must provide an implementation of this method and define
+``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` in ``bsp.h``.  This informs
+``rtems/confdefs.h`` to configure the Malloc Family Extensions which support
+``sbrk``.
 bsp_fatal_extension() - Cleanup the Hardware
 …
 shared version of ``bsp_fatal_extension()`` that does nothing or performs a
 system reset.  This implementation is located in the following file:
 .. code:: c
     c/src/lib/libbsp/shared/bspclean.c
+The ``bsp_fatal_extension()`` routine can be used to return to a ROM
+monitor, insure that interrupt sources are disabled, etc..  This routine is the
+last place to ensure a clean shutdown of the hardware.  The fatal source,
+internal error indicator, and the fatal code arguments are available to
+evaluate the fatal condition.  All of the non-fatal shutdown sequences
+ultimately pass their exit status to ``rtems_shutdown_executive`` and this
+is what is passed to this routine in case the fatal source is
+RTEMS_FATAL_SOURCE_EXIT.
+On some BSPs, it prints a message indicating that the application
+completed execution and waits for the user to press a key before
+resetting the board.  The PowerPC/gen83xx and PowerPC/gen5200 BSPs do
+this when they are built to support the FreeScale evaluation boards.
+This is convenient when using the boards in a development environment
+and may be disabled for production use.
+The ``bsp_fatal_extension()`` routine can be used to return to a ROM monitor,
+insure that interrupt sources are disabled, etc..  This routine is the last
+place to ensure a clean shutdown of the hardware.  The fatal source, internal
+error indicator, and the fatal code arguments are available to evaluate the
+fatal condition.  All of the non-fatal shutdown sequences ultimately pass their
+exit status to ``rtems_shutdown_executive`` and this is what is passed to this
+routine in case the fatal source is ``RTEMS_FATAL_SOURCE_EXIT``.
+On some BSPs, it prints a message indicating that the application completed
+execution and waits for the user to press a key before resetting the board.
+The PowerPC/gen83xx and PowerPC/gen5200 BSPs do this when they are built to
+support the FreeScale evaluation boards.  This is convenient when using the
+boards in a development environment and may be disabled for production use.
 Configuration Macros
 ====================
+Each BSP can define macros in bsp.h which alter some of the the default configuration parameters in ``rtems/confdefs.h``.  This section describes those macros:
+- .. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
+  ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` must be defined if the
+  BSP has proper support for ``sbrk``.  This is discussed in more detail
+  in the previous section.
+- .. index:: BSP_IDLE_TASK_BODY
+  ``BSP_IDLE_TASK_BODY`` may be defined to the entry point of a
+  BSP specific IDLE thread implementation.  This may be overridden if the
+  application provides its own IDLE task implementation.
+- .. index:: BSP_IDLE_TASK_STACK_SIZE
+  ``BSP_IDLE_TASK_STACK_SIZE`` may be defined to the desired
+  default stack size for the IDLE task as recommended when using this BSP.
+- .. index:: BSP_INTERRUPT_STACK_SIZE
+  ``BSP_INTERRUPT_STACK_SIZE`` may be defined to the desired default interrupt stack size as recommended when using this BSP.  This is sometimes required when the BSP developer has knowledge of stack intensive interrupt handlers.
+- .. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY
+  ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined when the BSP
+  requires that RTEMS zero out the RTEMS C Program Heap at initialization.
+  If the memory is already zeroed out by a test sequence or boot ROM,
+  then the boot time can be reduced by not zeroing memory twice.
+- .. index:: BSP_DEFAULT_UNIFIED_WORK_AREAS
+  ``BSP_DEFAULT_UNIFIED_WORK_AREAS`` is defined when the BSP
+  recommends that the unified work areas configuration should always
+  be used.  This is desirable when the BSP is known to always have very
+  little RAM and thus saving memory by any means is desirable.
+Each BSP can define macros in bsp.h which alter some of the the default
+configuration parameters in ``rtems/confdefs.h``.  This section describes those
+macros:
+.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
+- ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` must be defined if the BSP has proper
+  support for ``sbrk``.  This is discussed in more detail in the previous
+  section.
+.. index:: BSP_IDLE_TASK_BODY
+- ``BSP_IDLE_TASK_BODY`` may be defined to the entry point of a BSP specific
+  IDLE thread implementation.  This may be overridden if the application
+  provides its own IDLE task implementation.
+.. index:: BSP_IDLE_TASK_STACK_SIZE
+- ``BSP_IDLE_TASK_STACK_SIZE`` may be defined to the desired default stack size
+  for the IDLE task as recommended when using this BSP.
+.. index:: BSP_INTERRUPT_STACK_SIZE
+- ``BSP_INTERRUPT_STACK_SIZE`` may be defined to the desired default interrupt
+  stack size as recommended when using this BSP.  This is sometimes required
+  when the BSP developer has knowledge of stack intensive interrupt handlers.
+.. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY
+- ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined when the BSP requires that
+  RTEMS zero out the RTEMS C Program Heap at initialization.  If the memory is
+  already zeroed out by a test sequence or boot ROM, then the boot time can be
+  reduced by not zeroing memory twice.
+.. index:: BSP_DEFAULT_UNIFIED_WORK_AREAS
+- ``BSP_DEFAULT_UNIFIED_WORK_AREAS`` is defined when the BSP recommends that
+  the unified work areas configuration should always be used.  This is
+  desirable when the BSP is known to always have very little RAM and thus
+  saving memory by any means is desirable.
 set_vector() - Install an Interrupt Vector
 ==========================================
+On targets with Simple Vectored Interrupts, the BSP must provide
+an implementation of the ``set_vector`` routine.  This routine is
+responsible for installing an interrupt vector.  It invokes the support
+routines necessary to install an interrupt handler as either a "raw"
+or an RTEMS interrupt handler.  Raw handlers bypass the RTEMS interrupt
+structure and are responsible for saving and restoring all their own
+registers.  Raw handlers are useful for handling traps, debug vectors,
+etc..
+The ``set_vector`` routine is a central place to perform interrupt
+controller manipulation and encapsulate that information.  It is usually
+implemented as follows:
+.. code:: c
+    rtems_isr_entry set_vector(                     /* returns old vector \*/
+    rtems_isr_entry     handler,                  /* isr routine        \*/
+    rtems_vector_number vector,                   /* vector number      \*/
+    int                 type                      /* RTEMS or RAW intr  \*/
+On targets with Simple Vectored Interrupts, the BSP must provide an
+implementation of the ``set_vector`` routine.  This routine is responsible for
+installing an interrupt vector.  It invokes the support routines necessary to
+install an interrupt handler as either a "raw" or an RTEMS interrupt handler.
+Raw handlers bypass the RTEMS interrupt structure and are responsible for
+saving and restoring all their own registers.  Raw handlers are useful for
+handling traps, debug vectors, etc.
+The ``set_vector`` routine is a central place to perform interrupt controller
+manipulation and encapsulate that information.  It is usually implemented as
+follows:
+.. code:: c
+    rtems_isr_entry set_vector(                 /* returns old vector \*/
+      rtems_isr_entry handler,                  /* isr routine        \*/
+      rtems_vector_number vector,               /* vector number      \*/
+      int                 type                  /* RTEMS or RAW intr  \*/
+    )
+    {
+    if the type is RAW
+    install the raw vector
+    else
+    use rtems_interrupt_catch to install the vector
+    perform any interrupt controller necessary to unmask
+    the interrupt source
+    return the previous handler
+      if the type is RAW
+        install the raw vector
+      else
+        use rtems_interrupt_catch to install the vector
+      perform any interrupt controller necessary to unmask the interrupt source
+      return the previous handler
+    }
+*NOTE:* The i386, PowerPC and ARM ports use a Programmable
+Interrupt Controller model which does not require the BSP to implement``set_vector``.  BSPs for these architectures must provide a different
+set of support routines.
+.. note::
+    The i386, PowerPC and ARM ports use a Programmable Interrupt Controller
+    model which does not require the BSP to implement ``set_vector``.  BSPs for
+    these architectures must provide a different set of support routines.
 Interrupt Delay Profiling
 …
 The RTEMS profiling needs support by the BSP for the interrupt delay times.  In
+case profiling is enabled via the RTEMS build configuration option``--enable-profiling`` (in this case the pre-processor symbol``RTEMS_PROFILING`` is defined) a BSP may provide data for the interrupt
+delay times.  The BSP can feed interrupt delay times with the``_Profiling_Update_max_interrupt_delay()`` function
+(``#include <rtems/score/profiling.h>``).  For an example please have a look
+at ``c/src/lib/libbsp/sparc/leon3/clock/ckinit.c``.
+case profiling is enabled via the RTEMS build configuration option
+``--enable-profiling`` (in this case the pre-processor symbol
+``RTEMS_PROFILING`` is defined) a BSP may provide data for the interrupt delay
+times.  The BSP can feed interrupt delay times with the
+``_Profiling_Update_max_interrupt_delay()`` function (``#include
+<rtems/score/profiling.h>``).  For an example please have a look at
+``c/src/lib/libbsp/sparc/leon3/clock/ckinit.c``.
 Programmable Interrupt Controller API
 =====================================
 A BSP can use the PIC API to install Interrupt Service Routines through
 a set of generic methods. In order to do so, the header files
 libbsp/shared/include/irq-generic.h and libbsp/shared/include/irq-info.h
+A BSP can use the PIC API to install Interrupt Service Routines through a set
+of generic methods. In order to do so, the header files
+libbsp/shared/include/irq-generic.h and ``libbsp/shared/include/irq-info.h``
 must be included by the bsp specific irq.h file present in the include/
 directory. The irq.h acts as a BSP interrupt support configuration file which
+is used to define some important MACROS. It contains the declarations for
+any required global functions like bsp_interrupt_dispatch(). Thus later on,
+every call to the PIC interface requires including <bsp/irq.h>
+The generic interrupt handler table is intitalized by invoking the``bsp_interrupt_initialize()`` method from bsp_start() in the bspstart.c
+file which sets up this table to store the ISR addresses, whose size is based
+on the definition of macros, BSP_INTERRUPT_VECTOR_MIN & BSP_INTERRUPT_VECTOR_MAX
+in include/bsp.h
+is used to define some important MACROS. It contains the declarations for any
+required global functions like bsp_interrupt_dispatch(). Thus later on, every
+call to the PIC interface requires including ``<bsp/irq.h>``
+The generic interrupt handler table is intitalized by invoking the
+``bsp_interrupt_initialize()`` method from bsp_start() in the bspstart.c file
+which sets up this table to store the ISR addresses, whose size is based on the
+definition of macros, ``BSP_INTERRUPT_VECTOR_MIN`` and
+``BSP_INTERRUPT_VECTOR_MAX`` in include/bsp.h
 For the generic handler table to properly function, some bsp specific code is
 required, that should be present in irq/irq.c . The bsp-specific functions required
 to be writen by the BSP developer are :
 - .. index:: bsp_interrupt_facility_initialize()
   ``bsp_interrupt_facility_initialize()`` contains bsp specific interrupt
+required, that should be present in ``irq/irq.c``. The bsp-specific functions
+required to be writen by the BSP developer are :
+.. index:: bsp_interrupt_facility_initialize()
+- ``bsp_interrupt_facility_initialize()`` contains bsp specific interrupt
   initialization code(Clear Pending interrupts by modifying registers, etc.).
   This method is called from bsp_interrupt_initialize() internally while setting up
   the table.
 - .. index:: bsp_interrupt_handler_default()
+  ``bsp_interrupt_handler_default()`` acts as a fallback handler when
   no ISR address has been provided corresponding to a vector in the table.
 - .. index:: bsp_interrupt_dispatch()
+  ``bsp_interrupt_dispatch()`` service the ISR by handling
   any bsp specific code & calling the generic method bsp_interrupt_handler_dispatch()
   which in turn services the interrupt by running the ISR after looking it up in
   the table. It acts as an entry to the interrupt switchboard, since the bsp
+  This method is called from ``bsp_interrupt_initialize()`` internally while
+  setting up the table.
+.. index:: bsp_interrupt_handler_default()
+- ``bsp_interrupt_handler_default()`` acts as a fallback handler when no ISR
+  address has been provided corresponding to a vector in the table.
+.. index:: bsp_interrupt_dispatch()
+- ``bsp_interrupt_dispatch()`` service the ISR by handling any bsp specific
+  code & calling the generic method ``bsp_interrupt_handler_dispatch()`` which
+  in turn services the interrupt by running the ISR after looking it up in the
+  table. It acts as an entry to the interrupt switchboard, since the bsp
   branches to this function at the time of occurrence of an interrupt.
 - .. index:: bsp_interrupt_vector_enable()
   ``bsp_interrupt_vector_enable()`` enables interrupts and is called in
+.. index:: bsp_interrupt_vector_enable()
+- ``bsp_interrupt_vector_enable()`` enables interrupts and is called in
   irq-generic.c while setting up the table.
 - .. index:: bsp_interrupt_vector_disable()
   ``bsp_interrupt_vector_disable()`` disables interrupts and is called in
+.. index:: bsp_interrupt_vector_disable()
+- ``bsp_interrupt_vector_disable()`` disables interrupts and is called in
   irq-generic.c while setting up the table & during other important parts.
 …
 .. code:: c
+    rtems_status_code rtems_interrupt_handler_install(   /* returns status code \*/
+    rtems_vector_number vector,                        /* interrupt vector \*/
+    const char \*info,                           /* custom identification text \*/
+    rtems_option options,                              /* Type of Interrupt \*/
+    rtems_interrupt_handler handler,                   /* interrupt handler \*/
+    void \*arg  /* parameter to be passed to handler at the time of invocation \*/
+    rtems_status_code rtems_interrupt_handler_install(   /* returns status code */
+      rtems_vector_number     vector,                    /* interrupt vector */
+      const char             *info,                      /* custom identification text */
+      rtems_option            options,                   /* Type of Interrupt */
+      rtems_interrupt_handler handler,                   /* interrupt handler */
+      void                   *arg                        /* parameter to be passed
+                                                            to handler at the time of
+                                                            invocation */
+    )
     rtems_status_code rtems_interrupt_handler_remove(   /* returns status code \*/
     rtems_vector_number vector,                       /* interrupt vector \*/
     rtems_interrupt_handler handler,                  /* interrupt handler \*/
     void \*arg                          /* parameter to be passed to handler \*/
+    rtems_status_code rtems_interrupt_handler_remove(   /* returns status code */
+      rtems_vector_number     vector,                   /* interrupt vector */
+      rtems_interrupt_handler handler,                  /* interrupt handler */
+      void                   *arg                       /* parameter to be passed to handler */
+    )
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-.. COMMENT: All rights reserved.

bsp_howto/networking.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Networking Driver
 …
 ============
+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``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.
+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 ``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.
+.. sidebar:: *Legacy Networking Stack*
+  This docuemntation is for the legacy FreeBSD networking stack in the RTEMS
+  source tree.
 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.
+- 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?
+- If the device uses DMA, is it capable of forming a single
+  outgoing packet from multiple fragments scattered in separate
+  memory buffers?
+- If the device uses DMA, is it capable of chaining multiple
+  outgoing packets, or does each outgoing packet require
+  intervention by the driver?
+- Does the device automatically pad short frames to the minimum
+bytes or does the driver have to supply the padding?
+- Does the device automatically retry a transmission on detection
+  of a collision?
+- 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?
+- 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?
+- How is the device Ethernet address set?  How is the device
+  programmed to accept or reject broadcast and multicast packets?
+- 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?
+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.
+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.
+- 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?
+- If the device uses DMA, is it capable of forming a single outgoing packet
+  from multiple fragments scattered in separate memory buffers?
+- If the device uses DMA, is it capable of chaining multiple outgoing packets,
+  or does each outgoing packet require intervention by the driver?
+- Does the device automatically pad short frames to the minimum 64 bytes or
+  does the driver have to supply the padding?
+- Does the device automatically retry a transmission on detection of a
+  collision?
+- 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?
+- 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?
+- How is the device Ethernet address set?  How is the device programmed to
+  accept or reject broadcast and multicast packets?
+- 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?
+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.
 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 (``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.
+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 (``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.
 - ``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.
+  This function releases the network semaphore.  The network driver tasks must
+  call this function immediately before making any blocking RTEMS request.
 - ``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.
 - ``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 ``rtems_event_receive`` to wait for the specified event
   or events and reobtains the semaphore.
   The value returned is the value returned by the ``rtems_event_receive``.
+  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.
+- ``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
+  ``rtems_event_receive`` to wait for the specified event or events and
+  reobtains the semaphore.  The value returned is the value returned by the
+  ``rtems_event_receive``.
 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 ``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``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:
+.. code:: c
+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
+``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``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:
+.. code-block:: makefile
     DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__
+This is equivalent to the following list of definitions.  Early versions
+of the RTEMS BSD network stack required that all of these be defined.
+.. code:: c
+    -D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \\
+    -DDIAGNOSTIC -DBOOTP_COMPAT
+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 (``c/src/lib/libchip/network/sonic.c``) for an example
+of this.  Because of this, network drivers should not include``<stdlib.h>``.  Doing so will result in conflicting definitions
+of ``malloc()``.
+*Application level* code including network servers such as the FTP
+daemon are *not* part of the BSD kernel network code and should not be
+compiled with the BSD network flags.  They should include``<stdlib.h>`` and not define the network stack visibility
+macros.
+This is equivalent to the following list of definitions.  Early versions of the
+RTEMS BSD network stack required that all of these be defined.
+.. code-block:: makefile
+    -D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS -DDIAGNOSTIC -DBOOTP_COMPAT
+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
+(``c/src/lib/libchip/network/sonic.c``) for an example of this.  Because of
+this, network drivers should not include ``<stdlib.h>``.  Doing so will result
+in conflicting definitions of ``malloc()``.
+*Application level* code including network servers such as the FTP daemon are
+*not* part of the BSD kernel network code and should not be compiled with the
+BSD network flags.  They should include ``<stdlib.h>`` and not define the
+network stack visibility macros.
 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``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:
+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 ``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:
 ``ifp->if_softc``
+    Pointer to the device-dependent data.  The first entry
+    in the device-dependent data structure must be an ``arpcom``
+    Pointer to the device-dependent data.  The first entry in the
+    device-dependent data structure must be an ``arpcom`` structure.
+``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 ``name`` entry in the configuration structure.
+``ifp->if_unit``
+    The device number.  The network stack uses this number and the device name
+    for device name lookups.  For example, if ``ifp->if_name`` is ``scc`` and
+    ``ifp->if_unit`` is ``1``, the full device name would be ``scc1``.  The
+    unit number should be obtained from the ``name`` entry in the configuration
     structure.
-``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 ``name`` entry in the configuration structure.
-``ifp->if_unit``
-    The device number.  The network stack uses this number and the
-    device name for device name lookups.  For example, if``ifp->if_name`` is '``scc``' and ``ifp->if_unit`` is '``1``',
-    the full device name would be '``scc1``'.  The unit number should be
-    obtained from the 'name' entry in the configuration structure.
 ``ifp->if_mtu``
     The maximum transmission unit for the device.  For Ethernet
     devices this value should almost always be 1500.
+    The maximum transmission unit for the device.  For Ethernet devices this
+    value should almost always be 1500.
 ``ifp->if_flags``
     The device flags.  Ethernet devices should set the flags
     to ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the
     device can broadcast packets to multiple destinations
     and does not receive and transmit at the same time.
+    The device flags.  Ethernet devices should set the flags to
+    ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the device can broadcast
+    packets to multiple destinations and does not receive and transmit at the
+    same time.
 ``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 ``ifqmaxlen``.
+    The maximum length of the queue of packets waiting to be sent to the
+    driver.  This is normally set to ``ifqmaxlen``.
 ``ifp->if_init``
 …
 ``ifp->if_output``
+    The address of the output function.  Ethernet devices
+    should set this to ``ether_output``.
+RTEMS provides a function to parse the driver name in the
+configuration structure into a device name and unit number.
+.. code:: c
+    The address of the output function.  Ethernet devices should set this to
+    ``ether_output``.
+RTEMS provides a function to parse the driver name in the configuration
+structure into a device name and unit number.
+.. code-block:: c
     int rtems_bsdnet_parse_driver_name (
     const struct rtems_bsdnet_ifconfig \*config,
     char \**namep
+      const struct rtems_bsdnet_ifconfig  *config,
+      char                               **namep
     );
+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 ``if_attach``.  Ethernet devices should then
+call ``ether_ifattach``.  Both functions take a pointer to the
+device's ``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.
+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 ``if_attach``.  Ethernet
+devices should then call ``ether_ifattach``.  Both functions take a pointer to
+the device's ``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.
 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 ``IFF_OACTIVE`` bit in the
+device's ``if_flags`` is not set.
+For many devices this function need only set the ``IFF_OACTIVE`` bit in the``if_flags`` and send an event to the transmit task
+indicating that a packet is in the driver transmit queue.
+transmitter.  This occures whenever the network stack adds a packet to a
+device's send queue and the ``IFF_OACTIVE`` bit in the device's ``if_flags`` is
+not set.
+For many devices this function need only set the ``IFF_OACTIVE`` bit in the
+``if_flags`` and send an event to the transmit task indicating that a packet is
+in the driver transmit queue.
 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
+.. code:: c
+    rtems_id
+    rtems_bsdnet_newproc (char \*name,
+    int stacksize,
+    void(\*entry)(void \*),
+    void \*arg);
+This function should initialize the device, attach to interrupt handler, and
+start the driver transmit and receive tasks.  The function:
+.. code-block:: c
+    rtems_id rtems_bsdnet_newproc(
+      char *name,
+      int   stacksize,
+      void  (*entry)(void *),
+      void *arg
+    );
 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.
+than once.  Make sure multiple versions of the receive and transmit tasks are
+not accidentally started.
 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 ``IFF_OACTIVE`` bit in ``if_flags`` and block until another outgoing
+packet is queued.
+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 ``IFF_OACTIVE`` bit in ``if_flags`` and block until another
+outgoing packet is queued.
 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 ``ether_input`` should be called
+to forward the packet to the network stack.   The arguments to ``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.
+This task should block until a packet arrives from the device.  If the device
+is an Ethernet interface the function ``ether_input`` should be called to
+forward the packet to the network stack.  The arguments to ``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.
 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.
+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.
 Write the Driver IOCTL Function
 …
 commands which must be handled are:
+``SIOCGIFADDR``
+``SIOCSIFADDR``
+    If the device is an Ethernet interface these
+    commands should be passed on to ``ether_ioctl``.
+``SIOCGIFADDR``, ``SIOCSIFADDR``
+    If the device is an Ethernet interface these commands should be passed on
+    to ``ether_ioctl``.
 ``SIOCSIFFLAGS``
+    This command should be used to start or stop the device,
+    depending on the state of the interface ``IFF_UP`` and``IFF_RUNNING`` bits in ``if_flags``:
+    This command should be used to start or stop the device, depending on the
+    state of the interface ``IFF_UP`` and``IFF_RUNNING`` bits in ``if_flags``:
     ``IFF_RUNNING``
         Stop the device.
     ``IFF_UP``
         Start the device.
     ``IFF_UP|IFF_RUNNING``
         Stop then start the device.
     ``0``
         Do nothing.
 …
 ============================================
+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``SIO_RTEMS_SHOW_STATS``.
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+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 ``SIO_RTEMS_SHOW_STATS``.

bsp_howto/non_volatile_memory.rst

-                      r54514fe
+                      r6d7a4d2
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: Written by Eric Norum
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
 Non-Volatile Memory Driver
 ##########################
+The Non-Volatile driver is responsible for providing an
+interface to various types of non-volatile memory.  These
+types of memory include, but are not limited to, Flash, EEPROM,
+and battery backed RAM.  The capabilities provided
+The Non-Volatile driver is responsible for providing an interface to various
+types of non-volatile memory.  These types of memory include, but are not
+limited to, Flash, EEPROM, and battery backed RAM.  The capabilities provided
 by this class of device driver are:
 …
 - Erase the Non-Volatile Memory Area
+There is currently only one non-volatile device driver included in the
+RTEMS source tree.  The information provided in this chapter
+is based on drivers developed for applications using RTEMS.
+It is hoped that this driver model information can form the
+basis for a standard non-volatile memory driver model that
+can be supported in future RTEMS distribution.
+There is currently only one non-volatile device driver included in the RTEMS
+source tree.  The information provided in this chapter is based on drivers
+developed for applications using RTEMS.  It is hoped that this driver model
+information can form the basis for a standard non-volatile memory driver model
+that can be supported in future RTEMS distribution.
 Major and Minor Numbers
 =======================
+The *major* number of a device driver is its index in the
+RTEMS Device Address Table.
+A *minor* number is associated with each device instance
+managed by a particular device driver.  An RTEMS minor number
+is an ``unsigned32`` entity.  Convention calls
+dividing the bits in the minor number down into categories
+that specify an area of non-volatile memory and a partition
+with that area.  This results in categories
+like the following:
+- *area* - indicates a block of non-volatile memory
+- *partition* - indicates a particular address range with an area
+From the above, it should be clear that a single device driver
+can support multiple types of non-volatile memory in a single system.
+The minor number is used to distinguish the types of memory and
+blocks of memory used for different purposes.
+The ``major`` number of a device driver is its index in the RTEMS Device
+Address Table.
+A ``minor`` number is associated with each device instance managed by a
+particular device driver.  An RTEMS minor number is an ``unsigned32`` entity.
+Convention calls dividing the bits in the minor number down into categories
+that specify an area of non-volatile memory and a partition with that area.
+This results in categories like the following:
+- ``area`` - indicates a block of non-volatile memory
+- ``partition`` - indicates a particular address range with an area
+From the above, it should be clear that a single device driver can support
+multiple types of non-volatile memory in a single system.  The minor number is
+used to distinguish the types of memory and blocks of memory used for different
+purposes.
 Non-Volatile Memory Driver Configuration
 ========================================
+There is not a standard non-volatile driver configuration table but some
+fields are common across different drivers.  The non-volatile memory driver
+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.
+*memory_type*
+There is not a standard non-volatile driver configuration table but some fields
+are common across different drivers.  The non-volatile memory driver
+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.
+``memory_type``
     is the type of memory device in this area.  Choices are battery backed RAM,
     EEPROM, Flash, or an optional user-supplied type.  If the user-supplied type
     is configured, then the user is responsible for providing a set of
+    EEPROM, Flash, or an optional user-supplied type.  If the user-supplied
+    type is configured, then the user is responsible for providing a set of
     routines to program the memory.
+*memory*
+``memory``
     is the base address of this memory area.
+*attributes*
+    is a pointer to a memory type specific attribute block.  Some of
+    the fields commonly contained in this memory type specific attribute
+    structure area:
+    *use_protection_algorithm*
+``attributes``
+    is a pointer to a memory type specific attribute block.  Some of the fields
+    commonly contained in this memory type specific attribute structure area:
+    ``use_protection_algorithm``
         is set to TRUE to indicate that the protection (i.e. locking) algorithm
+        should be used for this area of non-volatile memory.  A particular
+        type of non-volatile memory may not have a protection algorithm.
+    *access*
+        should be used for this area of non-volatile memory.  A particular type
+        of non-volatile memory may not have a protection algorithm.
+    ``access``
         is an enumerated type to indicate the organization of the memory
         devices in this memory area.  The following is a list of the
         access types supported by the current driver implementation:
+        - simple unsigned8
         - simple unsigned16
         - simple unsigned32
         - simple unsigned64
         - single unsigned8 at offset 0 in an unsigned16
         - single unsigned8 at offset 1 in an unsigned16
         - single unsigned8 at offset 0 in an unsigned32
         - single unsigned8 at offset 1 in an unsigned32
         - single unsigned8 at offset 2 in an unsigned32
         - single unsigned8 at offset 3 in an unsigned32
+    *depth*
+        devices in this memory area.  The following is a list of the access
+        types supported by the current driver implementation:
+          - simple unsigned8
+          - simple unsigned16
+          - simple unsigned32
+          - simple unsigned64
+          - single unsigned8 at offset 0 in an unsigned16
+          - single unsigned8 at offset 1 in an unsigned16
+          - single unsigned8 at offset 0 in an unsigned32
+          - single unsigned8 at offset 1 in an unsigned32
+          - single unsigned8 at offset 2 in an unsigned32
+          - single unsigned8 at offset 3 in an unsigned32
+    ``depth``
         is the depth of the progamming FIFO on this particular chip.  Some
         chips, particularly EEPROMs, have the same programming algorithm but

Context Navigation

Changeset 6d7a4d2 in rtems-docs

Legend:

bsp_howto/ada95_interrupt.rst

bsp_howto/analog.rst

bsp_howto/ata.rst

bsp_howto/clock.rst

bsp_howto/conf.py

bsp_howto/console.rst

bsp_howto/discrete.rst

bsp_howto/frame_buffer.rst

bsp_howto/ide_controller.rst

bsp_howto/index.rst

bsp_howto/initilization_code.rst

bsp_howto/linker_script.rst

bsp_howto/makefiles.rst

bsp_howto/miscellanous_support.rst

bsp_howto/networking.rst

bsp_howto/non_volatile_memory.rst