wiki:GCI/Obsolete/RefactorBSPs

Version 3 (modified by Joel Sherrill, on 09/06/18 at 20:17:21) (diff)

--

Refactoring Board Support Packages

Table of Contents

    Error: Page GCI/Coding/RefactorBSPs does not exist

Please read all instructions before proceeding.

Rationale

The following task requires refactoring some pieces of code present in the Board Support Packages. During GSOC, a set of rules were devised that identified standard patterns of code implementation and file inclusion across all BSPs. Some of the example tasks in this category are to move a function definition from its current source file location to another file, or moving a file to another location within the BSP subdirectory.

Modifying BSP : 101

A BSP is a set of code files that provides the glue between RTEMS and a device mother-board. All the BSP code is concentrated in the directory c/src/lib/libbsp which is further subdivided based on CPU family and BSP.

For example, the c/src/lib/libbsp/arm and bsps/arm directories contain the BSPs for the 'arm' family, and c/src/lib/libbsp/arm/gumstix and bsps/arm/gumstix directories refer to the 'gumstix' BSP. The use of two directories is admittedly confusing and reflects some work in transition. All of the source code is in bsps/ and the build system files are under c/src/libbbsp.

The set of rules pertaining to the standardization of file location and function definitions each file must contain can be found here.

After making changes to any of the files, you'll need to make sure to compile it so that no errors are left. The Users Guide can help you in learning how to compile a BSP for the first time.

RTEMS uses the GNU Autotools for its build system. The Makefile.am, part of Automake, present in each BSP directory contains the list of source files which have to be compiled. The 'libbsp_a_SOURCES' container consists of space seperated values of the path to source files which will be compiled. So in case a new file is created in the BSP, the entry for that newly created file needs to be added to 'libbsp_a_SOURCES'.

First things first

The first thing to do is to have a working build of the BSP. Ideally, you will already have followed the GSOC Getting Started Guide from completing the previous GCI task. Now you'll need to repeat the effort for the CPU and BSP of the task that you are undertaking, which may require installing a new RTEMS Toolset so that you can cross-compile the BSP. Once you verify that the BSP builds "cleanly", you can start your task. (For these tasks we do not require proof of execution, only of correct compilation.)

In the following points we'll take a look at the kind of tasks that this category can contain.=== Move a function to a new file ===

cpu_family/bsp : Move bsp_reset() in startup/bspstart.c to  bsp/startup/bspreset.c
  • Create a branch? on git for your work. This will make managing your patch easier.
    git checkout master
    git pull
    git checkout -b bspreset
    
  • Ensure your checkout compiles without errors by running 'make' in your build directory.
  • If the target file does not exist, create it.
    • Add the name of the new file to Makefile.am
    • Re-run bootstrap -p and bootstrap from the libbsp directory, e.g.
      cd c/src/lib/libbsp
      ../../../../bootstrap -p
      ../../../../bootstrap
      
  • Move the function definition from the current file to the target file.
  • Include the same headers as in the previous file.
  • Compile and check for any errors.
    • You can re-compile RTEMS without re-running configure, just run 'make' as you did when compiling RTEMS the first time for this BSP.
  • Generate a patch for evaluation
    • Add the modified files to git and create a commit.
    • Create a patch? as the following shows, where you replace bsp with the name of the bsp.
      cd c/src/lib/libbsp
      git add cpu/bsp/startup/bspreset.c
      git commit -a -m "bsp: Move bsp_reset() to bsp/startup/bspreset.c"
      # verify the commit message and contents look right, and that your name and email address appear
      git format-patch HEAD^ -o ../../../../../
      
  • Upload the patch to Melange for your submission.

Move a file within a bsp

Some of the details are given in the above section on moving a function to a new file. See those instructions for clarification of the following steps if needed.

cpu_family/bsp : irq.c should be moved to irq/irq.c
  • Move the given file from it's current location to the target location.
  • Update the path entry of this file in Makefile.am
  • Re-run bootstrap -p and bootstrap from the libbsp directory, as above.
  • Compile and check for any errors.
  • Submit the patch for evaluation.