wiki:GSoC/2013/UnifiedAPIs

Version 15 (modified by Chris Johns, on 12/02/14 at 10:43:03) (diff)

--

GSOC 2013 : Unified APIs

Mentors

Joel Sherrill, Chris Johns, Amar Takhar

Student

Vipul Nayyar

Introduction

The broad aim of Unified APIs project is to identify standard patterns of code implementation and file inclusion so that all BSPs follow the one true way in doing work and including proper components for it. To identify this one true way, a specific BSP needs to rise and be recognized as a model for other BSPs. Hence, the arm lpc24xx is a good reference to observe and write down rules for.

Contributed Work during GSOC 2013

  • Submitted patches to remove legacy code from RTEMS bsps which have been accepted & are currently a part of the official RTEMS repository. These patches were submitted for bsps : csb337, csb336, edb7312, gumstix, gba, rtl22xx, & pc386.
  • Since more than about 100 bsps are a part of RTEMS, so guided instructions & rules for continuing this work has been compiled & is present in my github repository.
  • Studied the PIC interrupt model based on the comments written in irq-generic.h & my own observations. Information about PIC Interrupt Model API is added to the current RTEMS documentation.
  • For bsps that do not use the generic interrupt framework , rules to initialize & use it are written and present in the code repository. These rules specify how bsp specific code & the generic code works together & handles Interrupt Service Routines before, during and after an interrupt has occurred.
  • Based on my observations from model bsp lpc24xx , rules were compiled based on an ongoing discussion in the community on how bsp support files are included & compiled. These rules specify which set of files are a must to be used by a bsp & in which directory they all must lie. These rules will in future help in maintaining a unified pattern for BSP file organization.
  • Since the above rules are very difficult to check manually for each bsp, so a bash script was written merging the functionality of check_submission from rtems-testing. This script is supposed to be a final test for any bsp developer before his code is accepted into RTEMS, so as to check whether that the bsp code submitted follows this unified pattern of file organization & formatting or not.

Automated Rule Checking with check_submission

The main objective of the Unified API project is to determine a unified pattern of file usage, directory structure & the methods that each file uses.The checking of above rules is automated with the check_submission script.

Based on the observations from lpc24xx, a list of critical files & methods that every BSP must include and use was compiled. These files & methods belonging to a component for a BSP can be deemed as critical or non-critical. The rule-checking is accomplished by the following way :

  1. Check if a file is being compiled by searching it's name in the Makefile.am for a BSP.
  2. If file not found, then report it.
  3. Check if the file being compiled is present in the correct directory as defined by the rules.
  4. If location of file is not correct, report it.
  5. Check if the corresponding functions for a file are defined in there or not. This takes place by searching for the definition of a method in that file with the help of a simple regex [a-z|A-Z|0-9|_]+[ ]*$i[ ]*\(
  6. If the function is not located in it's specified file, then search whether it's defined in some other file maybe. Report it
  7. Check whether a required header is being installed by searching it's name in the Makefile.am
  8. Compile a list of all RTEMS internal functions(i.e starting with an '_' ) defined in cpukit & libcpu.
  9. Compile another list of functions starting with an '_' being executed in BSP by searching for a ';' to ensure that function is actually being called. Searching for a function being called from a file can be a bit intimidating if the function calling spans multiple lines, meaning that the function name is on one line & the semicolon on another. Since grep only parses line by line, so it cannot do this task very easily. What happens now is that all the newlines are trimmed while searching a file. The whole file now being concatenated in a single line, so grep is ideal for searching the pattern [ |][_]+[a-z|A-Z|0-9|_]*[ ]*[\n]*\([;]*\)[ ]*;
  10. Find common function names in the above two lists in order to ensure that the function being called in a bsp is infact been defined in cpukit or libcpu. Report it.

In order to obtain the results of the script successfully, either call it from a libbsp, cpu family or a bsp directory or pass it a path for a single or multiple bsp directories so that it can validate the location of a bsp in the RTEMS tree. If no path is passed, the pwd is evaluated and searched for bsps.

  • Passing only the directory name for bsp, cpu family or libbsp displays the discrepancies found only for critical files & functions. Following parameters need to be passed to expand the horizon
  • --warnings : gives all the critical & non-critical discrepancies found in a bsp.
  • --verbose : gives the whole story of a BSP. Any discrepancy & a correct rule implementation is also displayed.
  • --tests : gives test specific checks for each given BSP.

To be Done

  • Continue working with the RTEMS community to strengthen the unified way rules and include more checks in it as suggested.
  • Increase code coverage for removing legacy support from bsps by converting them to PIC interrupt support model.
  • Submit regular patches so as to correct the warnings flagged by the new check_submission script in rtems-testing.