Changes between Version 2 and Version 3 of Developer/Coding/Doxygen_for_BSPs


Ignore:
Timestamp:
Nov 22, 2014, 4:38:26 AM (5 years ago)
Author:
Chris Johns
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Coding/Doxygen_for_BSPs

    v2 v3  
    22
    33
    4 RTEMS contains well over a hundred [wiki:BoardSupportPackageInformation 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.
     4RTEMS 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.
    55
    66The 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.
    77
    8 Feel free to skip around and skim parts of this. = BSP Basics =
     8Feel free to skip around and skim parts of this.
     9= BSP Basics =
    910
    1011Embedded 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 [wiki:TBR/Website/Mission_Statement core purposes] 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.
     
    240241
    241242Remember 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.
    242 == =@defgroups for CPU Architectures and Shared Directories ===
     243=== @defgroups for CPU Architectures and Shared Directories ===
    243244
    244245The 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:
     
    269270
    270271The only groups you should ever add to this CPU group would be groups for specific BSPs and a group for the shared directory.
    271 == =@defgroups for BSPs ===
     272=== @defgroups for BSPs ===
    272273
    273274These 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.
     
    283284  */
    284285}}}
    285 == =@defgroups for Everything Else ===
     286=== @defgroups for Everything Else ===
    286287
    287288Never 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:
    288 == ==Look Common Features Implemented ====
    289 
    290 Remember that list of [wiki:Doxygen_Recommendations_for_BSPs#Common_Features_Found_In_BSPs 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.
     289==== Look Common Features Implemented ====
     290
     291Remember 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.
    291292
    292293RTEMS 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.
    293294
    294295Examples 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.
    295 == ==Check out the Makefile ====
     296==== Check out the Makefile ====
    296297
    297298When 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.
    298 == ==Start with a .h, and look for files that include it ====
     299==== Start with a .h, and look for files that include it ====
    299300
    300301You 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.
    301 == ==Files with similar names ====
     302==== Files with similar names ====
    302303
    303304If 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.
     
    310311 * 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.
    311312 * 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.
    312 == =@ingroup in the first type of Doxygen Header ===
     313=== @ingroup in the first type of Doxygen Header ===
    313314
    314315Remember 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.
    315 == =@ingroup in the second type of Doxygen Header ===
     316=== @ingroup in the second type of Doxygen Header ===
    316317
    317318Here 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.
    318319
    319320When 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.
    320 == =@ingroup for shared code ===
     321=== @ingroup for shared code ===
    321322
    322323This 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.