summaryrefslogtreecommitdiffstats
path: root/bsp-howto
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2019-04-03 13:30:22 +0200
committerSebastian Huber <sebastian.huber@embedded-brains.de>2019-04-04 07:40:18 +0200
commit1d48fb5a0035362ee462172696043691a700a0cc (patch)
tree3c55883a44d484fdbb629d1df9580da1be9598c5 /bsp-howto
parentc2e582db3209318444c00116a82c7cb95c0d4efd (diff)
downloadrtems-docs-1d48fb5a0035362ee462172696043691a700a0cc.tar.bz2
bsp-howto: Move BSP Doxygen recommendations
Update #3704.
Diffstat (limited to 'bsp-howto')
-rw-r--r--bsp-howto/coding-doxygen-bsp.rst717
-rw-r--r--bsp-howto/index.rst1
2 files changed, 718 insertions, 0 deletions
diff --git a/bsp-howto/coding-doxygen-bsp.rst b/bsp-howto/coding-doxygen-bsp.rst
new file mode 100644
index 0000000..d5ab21e
--- /dev/null
+++ b/bsp-howto/coding-doxygen-bsp.rst
@@ -0,0 +1,717 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+
+.. COMMENT:TBD - Convert the following to Rest and insert into this file
+.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen_for_BSPs
+
+
+Doxygen Recommendations for BSPs
+================================
+
+RTEMS contains well over a hundred `Board Support Packages (BSPs)
+<wiki:TBR/Website/Board_Support_Packages>`_. , across over 20 different
+`CPU Architectures <wiki:TBR/UserManual/SupportedCPUs>`_. . What this
+means is that there is a lot of hardware dependent code that gets
+written, and that adding Doxygen to properly document it all can be a
+very complicated task.
+
+The goal of this document is to attempt to simplify this process a bit,
+and to get you started on adding Doxygen to the bsps/ directory in a way
+that is logical and has structure. Before we move on to detailing the
+process of actually adding Doxygen to BSPs, you will be greatly served by
+having at least a basic understanding of the purpose of a Board Support
+Package (it always helps to know a bit about what you're documenting),
+as well as of the existing structure of the bsps/ directory.
+
+Feel free to skip around and skim parts of this.
+
+BSP Basics
+----------
+
+Embedded development is hard. Different CPUs have different instructions
+for doing the same thing, and different boards will have all sorts of
+different hardware that require unique drivers and interfaces. RTEMS
+handles this by having discrete packages, BSPs, to encapsulate
+code to accommodate for unique hardware. BSPs seek to implement the
+Hardware-Software interface. This, in a nutshell, is one of the `core
+purposes <wiki:Mission_Statement>`_. of RTEMS: To abstract (as much as
+is possible) away from the physical hardware and provide a standards
+compliant real-time environment for the embedded developer. If you think
+about it, the operating system on your normal computer serves a very
+similar purpose.
+
+Common Features Found In BSPs
+-----------------------------
+
+Although the actual implementation code will differ between BSPs, all
+BSPs will share some degree of common functionality. This is because
+that no matter what exact hardware you have, you need some basic features
+implemented in order to have a real time system you can develop on. Some
+of the most common shared features across most boards include:
+
+ * **console**: is technically the serial driver for the BSP rather than
+ just a console driver, it deals with the board UART (i.e. serial devices)
+ * **clock**: support for the clock tick - a regular time basis for the kernel
+ * **timer**: support of timer devices, used for timing tests
+ * **rtc** or **tod**: support for the hardware real time clock
+ * **network**: the Ethernet driver
+ * **shmsupp**: support of shared memory driver MPCI layer in a
+ multiprocessor system
+ * **gnatsupp**: BSP specific support for the GNU Ada run-time
+ * **irq**: support for how the processor handles interrupts (probably
+ the most common module shared by all boards)
+ * **tm27**: specific routines for the tm27 timing test
+ * **start** and **startup**: C and assembly used to initialize the
+ board during startups/resets/reboots
+
+These are just some of the things you should be looking for when adding
+Doxygen to a BSP.
+
+Note that there is no guarantee a particular BSP will implement all of
+these features, or even some of them. These are just the most common
+ones to look for. RTEMS follows a standardized naming convention for
+the BSP sub directories, so you should be able to tell in most cases
+what has been implemented on the BSP level and what has not.
+
+Shared Features
+---------------
+
+Some of the RTEMS executive is hardware independent and can be abstracted
+so that the same piece of code can be shared across multiple CPU
+architectures, or across multiple boards on the same architecture. This
+is done so that chunks of software can be reused, as well as aiding
+in reducing the development and debugging time for implementing new
+BSPs. This greatly aids the developer, but as someone seeking to document
+this code, this can make your life a little bit harder. It is hard to
+tell by looking at the directory of a BSP which features have simply been
+left out and which features are being implemented by using shared code
+from either from the architecture (../shared) or the base bsps/ shared
+directory (../../shared). You may be looking at the BSP headers and notice
+that you have an irq.h, but no irq.c implementing it, or you might even be
+missing both. You know that the processor has interrupt support somehow,
+but where is it? The easiest way to figure this out is by looking at
+the Makefile.am for a BSP. We'll detail this process more in a bit.
+
+Rationale
+---------
+
+As someone adding documentation and not doing actual development
+work, you might think it is not necessary to know some of the in and
+outs of BSPs. In actuality, this information will prove to be very
+useful. Doxygen documentation works by grouping things and their
+components (i.e. functions and other definitions), and by having
+brief descriptions of what each group does. You can't know what to
+look for or know how to group it or know how to describe it without
+some basic knowledge of what a BSP is. For more information on any
+of the above or BSPs in general, check out the `BSP Development Guide
+<http://rtems.org/onlinedocs/doc-current/share/rtems/html/bsp_howto/index.html>`_.
+.
+
+The Structure of the bsps/ directory
+------------------------------------
+
+All BSPs are found within the bsps/ directory, which is itself very
+well ordered. At the first level, we find a directory for each CPU
+architecture RTEMS supports, as well as a directory for code shared by
+all implementations.
+
+ .. code-block:: shell
+
+ $ cd bsps
+ $ ls
+ arm bsp.am lm32 m68k mips no_cpu README sparc
+ avr h8300 m32c Makefile.am moxie powerpc sh sparc64
+ bfin i386 m32r MERGE.PROCEDURE nios2 preinstall.am shared v850
+
+
+If we cd into a specific architecture, we see that a similar structure is
+employed. bsps/arm/ contains directories for each Board Support Package
+for boards with an ARM cpu, along with a folder for files and .h's shared
+by all BSPs of that architecture.
+
+ .. code-block:: shell
+
+ $ cd arm
+ $ ls
+ acinclude.m4 edb7312 gumstix Makefile.am realview-pbx-a9 stm32f4
+ configure.ac gba lm3s69xx nds rtl22xx xilinx-zynq
+ csb336 gdbarmsim lpc24xx preinstall.am shared
+ csb337 gp32 lpc32xx raspberrypi smdk2410
+
+Finally, if we cd into a specific BSP, we see the files and .h's that
+compose the package for that particular board. You may recognize the
+directory names as some of the [common features] we outlined above,
+like '''irq''', '''clock''', '''console''', and '''startup'''. These
+directories contain implementations of these features.
+
+ .. code-block:: shell
+
+ $ cd raspberrypi
+ $ ls
+ bsp_specs configure.ac include make misc README
+ clock console irq Makefile.am preinstall.am startup
+
+Another way to get an idea of the structure of bsps/ is to navigate
+to a directory and execute the "tree -f" command. This outputs a nice
+graphic that conveys some of the hierarchical properties of a particular
+directory.
+
+ .. code-block:: shell
+
+ $ pwd
+ ~/rtems/bsps/arm/raspberrypi
+ $ tree -f
+ .
+ |-- ./bsp_specs
+ |-- ./clock
+ | `-- ./clock/clockdrv.c
+ |-- ./configure.ac
+ |-- ./console
+ | |-- ./console/console-config.c
+ | `-- ./console/usart.c
+ |-- ./include
+ | |-- ./include/bsp.h
+ | |-- ./include/irq.h
+ | |-- ./include/mmu.h
+ | |-- ./include/raspberrypi.h
+ | `-- ./include/usart.h
+ |-- ./irq
+ | `-- ./irq/irq.c
+ |-- ./make
+ | `-- ./make/custom
+ | `-- ./make/custom/raspberrypi.cfg
+ |-- ./Makefile.am
+ |-- ./misc
+ | `-- ./misc/timer.c
+ |-- ./preinstall.am
+ |-- ./README
+ `-- ./startup
+ |-- ./startup/bspreset.c
+ |-- ./startup/bspstart.c
+ |-- ./startup/bspstarthooks.c
+ |-- ./startup/linkcmds
+ `-- ./startup/mm_config_table.c
+
+
+In short, BSPs will use the following directories:
+
+ * bsps/**shared** <- code used that is shared by all BSPs
+ * bsps/**CPU**/**shared** <- code used shared by all BSPs of a particular CPU architecture
+ * bsps/**CPU**/**BSP** <- code unique to this BSP
+
+As you can see, the bsps/ directory has a very logical and easy to
+understand structure to it. The documentation generated by Doxygen
+should attempt to match this structure as closely as possible. We want
+an overarching parent group to serve the same purpose as the bsps/
+directory. In it, we want groups for each CPU architecture and a group
+for the shared files. We then want groups for each BSP. Breaking our
+documentation up into discrete groups like this will greatly simplify
+the process and make the documentation much easier to go through. By
+learning about the existing structure of the bsps/ directory, we get an
+idea of how we should structure the Doxygen groups we create. More on
+this in the next section.
+
+Doxygen
+-------
+
+Now that we have covered some of the preliminaries, we can move on to
+what you are actually reading this wiki page for: adding Doxygen to the
+bsps/ directory. Let's start with some Doxygen basics. Skip this if you
+are already comfortable with Doxygen.
+
+In addition to this, check out the page on `Doxygen Recommendations
+<wiki:Developer/Coding/Doxygen >`_. , which also contains a fair amount
+of information that will not be covered here.
+
+Doxygen Basics
+--------------
+
+Doxygen is a documentation generator. It allows for documentation to be
+written right by the source code, greatly easing the pains of keeping
+documentation relevant and up to date. Doxygen has many commands,
+used for things like annotating functions with descriptions, parameter
+information, or return value information. You can reference other files
+or even other documentation.
+
+The core component of Doxygen (that we care about right now at least) is
+what's called a **group**, or **module**. These are used to add structure
+and associate groups of files that serve a similar purpose or implement
+the same thing.
+
+Doxygen Headers
+---------------
+Doxygen is always found in a special Doxygen comment block, known as a
+**Doxygen header**. In RTEMS, this block comes in the form of a multiline
+comment with some included Doxygen commands, which are preceded by the '@'
+tag. Take a look at this Doxygen header that declares the arm_raspberrypi
+module, which houses the documentation in the BSP for the Raspberry Pi.
+
+ .. code-block:: c
+
+ bsps/arm/raspberrypi/include/bsp.h:
+
+ /**
+ * @defgroup arm_raspberrypi Raspberry Pi Support
+ *
+ * @ingroup bsp_arm
+ *
+ * @brief Raspberry Pi support package
+ *
+ */
+
+You see a few commands here that we'll cover in the following
+sections. Briefly, the @defgroup command declares a new group, the
+@ingroup command nests this group as a submodule of some other group (in
+this case bsp_arm), and the @brief command provides a brief description
+of what this group is.
+
+The @defgroup Command
+---------------------
+
+The @defgroup command is used to declare new groups or modules. Think
+"define group". The syntax of this command is as follows:
+
+ .. code-block:: c
+
+ @defgroup <group name> <group description>
+
+
+The group name is the name used by Doxygen elsewhere to reference this
+group. The group description is what is displayed when the end user
+navigates to this module in the resulting documentation. The group
+description is a couple words formatted as how it would be in a table
+of contents. This part is what actually shows up in the documentation,
+when the user navigates to this group's module, this description will
+be the modules name.
+
+Groups should only be declared (@defgroup) in .h files. This is
+because Doxygen is used primarily to document interfaces, which are
+only found in .h files. Placing @defgroups in .h files is the only real
+restriction. Which .h file you place the group declaration in surprisingly
+doesn't matter. There is no information in the resulting documentation
+that indicates where the group was declared. You will see that we do
+have some rules for where you should place these declarations, but we
+also use this fact that it doesn't matter to our advantage, in order to
+standardize things.
+
+The @defgroup command is used only to define ''structure''. No actual
+documentation is generated as a result of its use. We must @ingroup things
+to the group we declare in order to create documentation. Even though it
+does not generate visible documentation, the @defgroup command is still
+very important. We use it in a way that seeks to emulate the structure
+of the bsps/ directory itself. We do this by creating a hierarchy of
+groups for each CPU architecture and each BSP.
+
+The @ingroup Command
+--------------------
+
+The @ingroup command is used to add 'things' to already declared
+groups or modules. These 'things' can either be other groups, or files
+themselves. The syntax of the @ingroup command is as follows:
+
+ .. code-block:: shell
+
+ @ingroup <group name>
+
+
+The group name is the actual name, not description, of the group you
+want to add yourself to. Remember that group name was the second argument
+passed to the @defgroup command.
+
+Using the @ingroup command is how we add ''meaning'' to the ''structure''
+created by using @defgroup. @ingroup associates the file it is found in
+and all other Doxygen found within (function annotations, prototypes, etc)
+with the group we declared with the @defgroup command. We add related
+files and headers to the same groups to create a logical and cohesive
+body of documentation. If the end user wanted to read documentation
+about how the raspberry pi handles interrupts, all they would have to
+do would be to navigate to the raspberry pi's interrupt support module
+(which we created with a @defgroup command), and read the documentation
+contained within (which we added with @ingroup commands).
+
+@ingroup is found within all Doxygen headers, along with an @brief
+statement. There are two types of Doxygen headers, which we will go over
+after we see a description of the @brief command.
+
+The @brief Command
+------------------
+
+The @brief command is used to give either a) a brief description
+in the form of an entry as you would see it in a table of contents
+(i.e. Capitalized, only a couple of words) or b) a brief topic sentence
+giving a basic idea of what the group does. The reason you have two uses
+for the brief command is that it is used differently in the two types of
+Doxygen headers, as we will see shortly. The syntax of the brief command
+is self evident, but included for the sake of completion:
+
+ .. code-block:: shell
+
+ @brief <Table of Contents entry '''or''' Topic Sentence>
+
+
+The Two Types of Doxygen Headers
+--------------------------------
+
+There are two types of Doxygen Headers. The first type is found at the
+beginning of a file, and contains an @file command. This type of header
+is used when @ingroup-ing the file into another doxygen group. The form
+of the @brief command in this case is a topic sentence, often very close
+to the file name or one of it's major functions. An example of this type
+of header, found in bsps/arm/raspberrypi/include/bsp.h is as follows:
+
+ .. code-block:: c
+
+ Header type 1: used to add files to groups, always found at the beginning of a file
+ /**
+ * @file
+ *
+ * @ingroup raspberrypi
+ *
+ * @brief Global BSP definitions.
+ */
+
+ /*
+ * Copyright (c) YYYY NAME
+ *
+ * <LICENSE TERMS>
+ */
+
+
+Notice the form and placement of this type of header. It is always found
+at the beginning of a file, and is in its own multiline comment block,
+separated by one line white space from the copyright. If you look at the
+header itself, you see a @file, @ingroup, and @brief command. Consider
+the @file and the @ingroup together, what this says is that we are
+adding this file to the raspberrypi group. There is actually a single
+argument to the @file command, but Doxygen can infer it, so we leave
+it out. Any other Doxygen, function annotations, function prototypes,
+#defines, and other code included in the file will now be visible and
+documented when the end user navigates to the group you added it to in
+the resulting documentation.
+
+Now let's consider the second type of header. This type is syntactically
+very similar, but is used not to add files to groups, but to add groups
+to other groups. We use this type of header to define new groups
+and nest them within old groups. This is how we create hierarchy
+and structure within Doxygen. The following is found, again, in
+bsps/arm/raspberrypi/include/bsp.h:
+
+ .. code-block:: c
+
+ Header type 2: Used to nest groups, found anywhere within a file
+ /**
+ * @defgroup arm_raspberrypi Raspberry Pi Support
+ *
+ * @ingroup bsp_arm
+ *
+ * @brief Raspberry Pi Support Package
+ */
+
+It looks very similar to the first type of header, but notice that the
+@file command is replaced with the @defgroup command. You can think
+about it in the same way though. Here we are creating a new group, the
+arm_raspberry pi group, and nesting it within the bsp_arm group. The
+@brief in this case should be in the form of how you would see it in a
+table of contents. Words should be capitalized and there should be no
+period. This type of header can be found anywhere in a file, but it is
+typically found either in the middle before the file's main function,
+or at the tail end of a file. Recall that as we are using the @defgroup
+command and creating a new group in this header, the actual .h we place
+this in does not matter.
+
+The second type of header is the **structure** header, it's how we
+create new groups and implement hierarchy. The first type of header
+was the **meaning** header, it's how we added information to the groups
+we created.
+
+For more examples of Doxygen structure and syntax, refer to BSPs found
+within the arm architecture, the lpc32xx and raspberrypi BSPs are
+particularly well documented. A good way to quickly learn more is by
+tweaking some Doxygen in a file, then regenerating the html, and seeing
+what has changed.
+
+Generating Documentation
+------------------------
+
+Doxygen is a documentation generator, and as such, we must
+generate the actual html documentation to see the results
+of our work. This is a very good way to check your work, and
+see if the resulting structure and organization was what you had
+intended. The best way to do this is to simply run the `do_doxygen script
+<https://github.com/joelsherrill/gci_tasks/blob/master/2015/doxygen_c_header_tasks/validate/do_doxygen>`_. To use the script:
+
+Make sure Doxygen is installed. Also, the environment needs to have the
+root directory of RTEMS set in the variable `r` so that `$r` prints the
+path to RTEMS, and the script takes as argument a relative directory
+from there to generate the doxygen, for example to generate the doxygen
+for all of bsps/ you would do:
+
+ .. code-block:: shell
+
+ export r=~/rtems
+ ./do_doxygen bsps
+
+Doxygen in bsps/
+----------------
+
+Now that we've covered the basics of Doxygen, the basics of BSPs and the
+structure of the bsps/ directory, actually adding new Doxygen to bsps/
+will be much easier than it was before. We will cover a set of rules and
+conventions that you should follow when adding Doxygen to this directory,
+and include some tips and tricks.
+
+Group Naming Conventions
+------------------------
+
+This is an easy one. These are in place in order for you to quickly
+identify some of the structure of the Doxygen groups and nested groups,
+without actually generating and looking at the documentation. The basic
+idea is this: when defining a new group (@defgroup), the form of the name
+should be the super group, or the name of the group you are nesting this
+group within, followed by an underscore, followed by the intended name
+of this new group. In command form:
+
+ .. code-block:: c
+
+ <----- This is your group name -------> <--usual description -->
+ @defgroup <super-group name>_<name of this group> <group description>
+
+
+Some examples of this:
+
+* **bsp_arm**: This is the group for the arm architecture. It is a
+member of the all inclusive bsp-kit group (more on this in structure
+conventions), so we prefix it with the "**bsp**" super group name. This
+is the group for the arm architecture, so the rest is just "'''arm'''"
+
+* **arm_raspberrypi**: This is the group for the Raspberry Pi BSP. It
+is is an arm board, and as such, is nested within the bsp_arm group. We
+prefix the group name with an "**arm**" (notice we drop the bsp prefix
+of the arm group - we only care about the immediate super group),
+and the rest is a simple "'''raspberrypi'''", indicating this is the
+raspberrypi group, which is nested within the bsp_arm group.
+
+* **raspberrypi_interrupt** This is the group for code handling
+interrupts on the Raspberry Pi platform. Because this code and the group
+that envelops it is Raspberry Pi dependent, we prefix our name with a
+"**raspberrypi**", indicating this group is nested within the raspberrypi
+group.= Structure Conventions =
+
+This covers where, when, and why you should place the second type of
+Doxygen header. Remember that our goal is to have the structure of
+the documentation to match the organization of the bsps/ directory as
+closely as possible. We accomplish this by creating groups for each
+cpu architecture, each BSP, and each shared directory. These groups are
+nested as appropriate in order to achieve a hierarchy similar to that
+of bsps/. The arm_raspberrypi group would be nested within the bsp_arm
+group, for example.
+
+Where to place @defgroup
+------------------------
+
+Remember how I said it really doesn't matter where you place the
+@defgroup? Well, it does and it doesn't. It would be chaotic to place
+these anywhere, and almost impossible to tell when you have a @defgroup
+and when you don't, so we do have some rules in place to guide where
+you should place these.
+
+@defgroups for CPU Architectures and Shared Directories
+-------------------------------------------------------
+
+The standardized place for these is within a special doxygen.h file
+placed within the particular architectures shared directory. This
+doxygen.h file exists solely for this purpose, to provide a standard
+place to house the group definitions for CPU architectures and the
+shared directory for that architecture. This is done because there is
+no single file that all architectures share, so it would be impossible
+to declare a standardized location for architecture declarations without
+the creation of a new file. This also allows others to quickly determine
+if the group for a particular architecture has already been defined or
+not. Lets look at the doxygen.h for the arm architecture as an example,
+found at arm/shared/doxygen.h:
+
+ .. code-block:: c
+
+ /**
+ * @defgroup bsp_arm ARM
+ *
+ * @ingroup bsp_kit
+ *
+ * @brief ARM Board Support Packages
+ */
+
+ /**
+ * @defgroup arm_shared ARM Shared Modules
+ *
+ * @ingroup bsp_arm
+ *
+ * @brief ARM Shared Modules
+ */
+
+
+The doxygen.h contains only 2 Doxygen headers, both of which are of
+the second type. One header is used to create the groups for the arm
+architecture **bsp_arm**, nesting it as part of the bsp_kit group,
+and the other creates an **arm_shared** group to house the code that is
+shared across all BSPs of this architecture. Because these are the second
+type of Doxygen header, where we place them does not matter. This allows
+us to place them in a standard doxygen.h file, and the end user is non
+the wiser. Note that this .h file should never be included by a .c file,
+and that the only group declarations that should be placed here are the
+declarations for the CPU Architecture group and the shared group.
+
+There is also a doxygen.h file that exists at the root bsps/shared
+directory, to @defgroup the the parent **bsp_kit** group (the only
+group to not be nested within any other groups) and to @defgroup
+the **bsp_shared** group, to serve as the holder for the bsps/shared
+directory.
+
+If the architecture in which the BSP you are tasked with does not have
+one of these files already, you will need to copy the format of the file
+here, replacing the **arm** with whatever the CPU Architecture you are
+working with is. Name this file doxygen.h, and place it in the shared
+directory for that architecture.
+
+The only groups you should ever add to this CPU group would be groups
+for specific BSPs and a group for the shared directory.
+
+@defgroups for BSPs
+-------------------
+
+These are much easier than placing @defgroups for CPU Architectures. The
+overwhelming majority of the time, the @defgroup for a BSP is found within
+the bsp.h file found at '''''bsp'''''/include/bsp.h. It is usually placed
+midway through or towards the end of the file. In the event that your
+board lacks a bsp.h file, include this group declaration within the most
+standard or commonly included header for that BSP.
+
+The group for a BSP should **always** be nested within the group for
+the CPU architecture it uses. This means that the Doxygen header for
+defining a BSP group should always look something like this:
+
+ .. code-block:: c
+
+ /**
+ * @defgroup *architecture*_*BSP* *name*
+ *
+ * @ingroup bsp_*architecture*
+ *
+ * @brief *BSP* Support Package
+ */
+
+
+@defgroups for Everything Else
+------------------------------
+
+Never be afraid to add more structure! Once the basic CPU and BSP group
+hierarchy is established, what we're left with is all the sub directories
+and implementation code. Whether working within a shared directory for
+a CPU architecture, or within a BSP directory, you should always be
+looking for associations you can make to group files together by. Your
+goal should be to avoid @ingroup-ing files directly to the cpu_shared
+group and the cpu_bsp group as much as possible, you want to find more
+groups you can nest within these groups, and then @ingroup files to
+those groups. Here are some things to look for:
+
+Look Common Features Implemented
+--------------------------------
+
+Remember that list of common features outlined in the BSP Basics
+section? Find the .h's that are responsible for providing the interface
+for these features, and @defgroup a group to @ingroup the files
+responsible for implementing this feature.
+
+RTEMS has a naming convention for its BSP sub directories, so it should
+be a really quick and easy process to determine what features are there
+and what is missing.
+
+Examples of this are found within the **arm_raspberrypi** group, which
+contains nested subgroups like **raspberry_interrupt** to group files
+responsible for handling interrupts, **raspberrypi_usart** to group files
+responsible for implementing USART support, and many other subgroups.
+
+Check out the Makefile
+----------------------
+
+When working within a BSP, take a look at the Makefile.am. Often times,
+you will find that the original developer of the code has outlined the
+groups nicely for you already, with comments and titles before including
+source files to be built. Also, this is often the only way to tell which
+features a BSP simply does not implement, and which features a BSP borrows
+from either the architecture's shared group, or the bsps/ shared group.
+
+Start with a .h, and look for files that include it
+---------------------------------------------------
+
+You should end up with a @defgroup for ''most'' .h files. Some .h files
+are related and will not have independent groups, but most provide
+interfaces for different features and should have their own group
+defined. Declare a group for the header, then use cscope to find the files
+that include this header, and try to determine where the implementation
+code for prototypes are found. These are the files you should @ingroup.
+
+Files with similar names
+------------------------
+
+If you see that a few files have similar names, like they are all prefixed
+with the same characters, then these files should most likely be part
+of the same group.
+
+Remember, your goal is to @defgroup as much as you can. The only files
+you should be @ingroup-ing directly to the BSP group or the shared group
+are files that don't cleanly fit into any other group.
+
+Where to place @ingroup
+-----------------------
+
+The @ingroups you add should make sense.
+
+* If you are working within an architecture's shared directory, @ingroup should be adding things either to the *architecture*_shared group, or some sub group of it.
+
+* If you are working within a BSP directory, @ingroup should be adding things to either the *architecture_*bsp* group, or some sub group of it.
+
+@ingroup in the first type of Doxygen Header
+--------------------------------------------
+
+Remember that in the first type of Doxygen header, we are adding files
+to groups. This type of header should always be at the top of the
+file. You should be adding files that are associated in some way to
+the same groups. That is to say, if three different .h files provide an
+interface allowing interrupt support, they should be a part of the same
+group. Some good ways to associate files were outlined above.
+
+@ingroup in the second type of Doxygen Header
+---------------------------------------------
+
+Here we are using the @ingroup command to add groups to other groups,
+creating a hierarchy. The goal for bsps/ is to have one single group that
+holds all other groups. This root group is the **bsp_kit** group. All
+groups should be added either directly to this group (if you are creating
+an architecture group) or added to one of its sub groups.
+
+When nesting groups, try to match the structure of bsps/ as closely as
+possible. For example, if a group is defined to associate all files that
+provide for a real time clock for the raspberrypi, nest it within the
+arm_raspberrypi group.
+
+@ingroup for shared code
+------------------------
+
+This is tricky. You may end up in a situation where your BSP uses code
+found in either the architecture shared directory, or the bsps/shared
+directory. Even though this code is logically associated with the BSP,
+as stated above: all files in the shared directory should be added to
+either the *architecture*_shared group, or some subgroup of it ''not''
+the BSP group. You could make a note under the @brief line in the header
+(which shows up in the resulting documentation) that a particular BSP
+uses this code.
+
+When working with shared code, you should be careful and add notes to
+@brief to indicate that it is a shared code or interface. Prefixing things
+with "Generic" is a good idea here. You will still be able to form groups
+and associate things when working on the shared level, but sometimes you
+will find that you have the interface (.h) to @defgroup, but not many
+files to add to the group as it may be hardware dependent. This is okay.
diff --git a/bsp-howto/index.rst b/bsp-howto/index.rst
index 4795e08..67f64d8 100644
--- a/bsp-howto/index.rst
+++ b/bsp-howto/index.rst
@@ -40,3 +40,4 @@ RTEMS BSP and Driver Guide (|version|).
ata
ide_controller
command
+ coding-doxygen-bsp