Update the BSP howto.

Closes #2590.

1 files changed, 130 insertions, 138 deletions

diff --git a/bsp_howto/makefiles.rst b/bsp_howto/makefiles.rst
index 3701e07..7932561 100644
--- a/bsp_howto/makefiles.rst
+++ b/bsp_howto/makefiles.rst
@@ -1,169 +1,169 @@
 .. 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 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 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.
+Makefiles Used During The BSP Building Process
+==============================================
 
-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.
+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:
 
-During the build phase, the source files are compiled into object files
-and libraries are built.
+- ``bootstrap`` to regenerate all files that are generated by autoconf and
+  automake.
 
-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.
+- ``bootstrap -c`` to remove all files generated by autoconf and automake.
 
-Makefiles Used During The BSP Building Process
-==============================================
+- ``bootstrap -p`` to regenerate ``preinstall.am`` files.
 
-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:
+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.
 
-- ``bootstrap`` to regenerate all files that are generated by
-  autoconf and automake.
+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.
 
-- ``bootstrap -c`` to remove all files generated by autoconf and
-  automake.
+The ``Makefile`` files generated are processed when configuring and building
+RTEMS for a given BSP.
 
-- ``bootstrap -p`` to regenerate ``preinstall.am`` files.
+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.
 
-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 ``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.
-
-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
+.. code-block:: makefile
 
     include_HEADERS = include/bsp.h
     include_HEADERS += include/tm27.h
     include_HEADERS += include/erc32.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``.
-
-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
-
-    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 \\
+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-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
     ...
     noinst_LIBRARIES = libbsp.a
     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``.
-
-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
+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 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
     RTEMS_CPU=m68k
@@ -177,20 +177,12 @@ found in the ``make/custom`` directory.
     # optimize flag: typically -O2
     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.
-
-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.
+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.