Context Navigation

← Previous Change
Wiki History
Next Change →

Notice: We have migrated to GitLab launching 2024-05-01 see here: https://gitlab.rtems.org/

Doxygen_for_BSPs

Timestamp:: 10/23/18 18:16:24 (6 years ago)
Author:: Joel Sherrill
Comment:: Change more libbsp to bsps

Legend:

: Unmodified
: Added
: Removed
: Modified

Developer/Coding/Doxygen_for_BSPs

-                      v5
+                      v6
 RTEMS contains well over a hundred [wiki:TBR/Website/Board_Support_Packages Board Support Packages (BSPs)], across over 20 different [wiki:TBR/UserManual/SupportedCPUs CPU Architectures]. 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 libbsp 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 libbsp directory.
+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.
 …
 = 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 libbsp 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.
+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 [http://rtems.org/onlinedocs/doc-current/share/rtems/html/bsp_howto/index.html BSP Development Guide].
 = The Structure of the libbsp directory =
+= 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.
 …
 }}}
 If we cd into a specific architecture, we see that a similar structure is employed. libbsp/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.
+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.
 {{{
 …
 }}}
 Another way to get an idea of the structure of libbsp 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.
+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.
 {{{
 …
  *  bsps/'''''CPU'''''/'''''BSP'''''             <- code unique to this BSP
 As you can see, libbsp 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 libbsp 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 libbsp directory, we get an idea of how we should structure the Doxygen groups we create. More on this in the next section.
+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 libbsp directory. Let's start with some Doxygen basics. Skip this if you are already comfortable with 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 [wiki:Developer/Coding/Doxygen Doxygen Recommendations], which also contains a fair amount of information that will not be covered here.
 …
 {{{
 libbsp/arm/raspberrypi/include/bsp.h:
+bsps/arm/raspberrypi/include/bsp.h:
 /**
 …
 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 libbsp directory itself. We do this by creating a hierarchy of groups for each CPU architecture and each BSP.
+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 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 libbsp/arm/raspberrypi/include/bsp.h is as follows:
+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:
 {{{
 …
 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 libbsp/arm/raspberrypi/include/bsp.h:
+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:
 {{{
 …
 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 [https://github.com/joelsherrill/gci_tasks/blob/master/2015/doxygen_c_header_tasks/validate/do_doxygen do_doxygen script]. 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 libbsp you would do:
+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:
 {{{
 …
 }}}
 = Doxygen in libbsp =
 Now that we've covered the basics of Doxygen, the basics of BSPs and the structure of the libbsp directory, actually adding new Doxygen to libbsp 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.
+= 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 =
 …
  *  '''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 libbsp 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 libbsp. The arm_raspberrypi group would be nested within the bsp_arm group, for example.
+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 ==
 …
 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 libbsp/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 libbsp/shared directory.
+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.
 …
 ==== 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 libbsp shared group.
+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 ====
 …
 === @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 libbsp 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 libbsp 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.
+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 libbsp 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.
+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.