Saturday, 28 September 2013

GSOC : A new dawn

The results are out for GSOC 2013. And thanks to Carol, I got an email congratulating me that I passed the midterms (once again !!). I'd like to thank my mentors and other prominent developers in the RTEMS community whose criticism & wisdom helped me in completing my task and making a worthwhile contribution to RTEMS.

Wanna know how I celebrated passing GSOC final evaluation ? I attended the GDG New Delhi DEVFEST at Google Office, Gurgaon & got a chance to relish this lovely cake. Have a bite  !!

And a couple of cupcakes with cool toppings...

Well, as they say that its not the end, but only the start of a new journey. So, I hope that my journey takes me on a memorable ride where I get to contribute greatly to open source, RTEMS & even more awesome projects.

Monday, 23 September 2013

GSOC : End of the Road ??

This final post written during the end of the coding period of GSOC 2013 summarizes the work done by me this summer on RTEMS. I've created a separate repository on github where all the code & work done by me can be found. I'll briefly take you through the work done & stuff left in the pipeline below :

Contributed Work

  • 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 & publicly available on a google drive document.

  • 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.

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.

I sincerely hope that my work will benefit the RTEMS community as a whole in the long run & avoid incurring any more technical debt  so that someone else doesn't have to pay for it. I gladly look forward to working with RTEMS developers in future while continuing the work done in GSOC & maybe more !!

Saturday, 14 September 2013

GSOC : Automating rule checking for BSP Unified way

Alas, we've arrived at the last leg of this GSOC journey. At the start of the application phase of GSOC, my mentor Joel explained to me that 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. And he wished that it would be great, if I could automate checking of these rules that I formulate by observing some model BSPs(lpc24xx).

I believe that I've accomplished that automated rule checking by writing a bash script that searches for discrepancies in a specific BSP, all BSPs in a family or all the RTEMS BSPs in libbsp directory according to the parameters passed. This script can be downloaded from here. Based on my observation, I compiled a list of critical files & methods that every BSP must include and use. 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 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
  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 ';' on another. Since grep only parses line by line, so it cannot do this job very easily. What I did is that I trimmed all newlines(\n) 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.

Some of the interesting results I found out with my script were :
  • arm/gumstix : bspreset.c not compiled 
  • arm/gumstix : bsp_reset() present in file startup/bspstart.c
  • powerpc/beatnik : bspreset.c not compiled 
  • powerpc/beatnik : bsp_reset() present in file include/bsp.h startup/reboot.c
  • powerpc/mpc55xxevb : start.S not present in correct path 
  • powerpc/mpc55xxevb : bspreset.c not compiled 
  • powerpc/mpc55xxevb : bsp_reset() present in file startup/reset.c 
  • powerpc/mpc55xxevb : bspgetworkarea.c not compiled 
  • powerpc/mpc55xxevb : bsp_work_area_initialize() present in file startup/bspworkareainit.c
The above discrepancies would've been really hard to find if searched manually. I hope my work helps the RTEMS community in following the Unified way for BSP file organization & kill any discrepancies if found any.

Tuesday, 20 August 2013

GSOC Update 3

This blog post covers the progress for my RTEMS GSOC Project Unified APIs since the midterm evaluation. I thank my mentors for evaluating heartily so that I can continue on with the project.

Some portion of removing legacy support from bsps was done before the midterms. Since there being about 100+ total bsps in the RTEMS tree, it is quite impossible to cover each and every one of them. The earlier work included replacing legacy methods with the generic methods & documenting this procedure along the way, so that it can be continued by me or anyone else in the future. But in order to remove legacy portion of code in most BSPs, the base support for a BSP needs to be modified, so that the generic interrupt framework can work on it. This includes setting up the generic interrupt handler table and a couple of other things.

My focus for this kind of bsp transformation was arm nds( Nintendo DS ). The patch for nds can be seen here. Some of the rules, features that I observed/formulated are:
  • In order to initialize the generic interrupt handler table at the start,  the bsp_interrupt_initialize() method should be called from bsp_start() which sets up this table to store the ISR addresses, whose size is based on the definition of macros, BSP_INTERRUPT_VECTOR_MIN & BSP_INTERRUPT_VECTOR_MAX in include/bsp.h
  • All the BSP specific interrupt related code should be present in bsp/irq/irq.c. This bsp specific file should contain the following methods:
    1. rtems_status_code bsp_interrupt_facility_initialize() which contains bsp specific interrupt initialization code(Clear Pending interrupts by modifting registers, etc ). This method is called from bsp_interrupt_initialize() in libbsp/shared/src/irq-generic.c
    2. void bsp_interrupt_handler_default() which acts as a fallback handler when no ISR address has been provided corresponding to a vector in the table.
    3. void bsp_interrupt_dispatch() service the ISR by handling any bsp specific code & calling the generic method bsp_interrupt_handler_dispatch() which in turn services the interrupt by running the ISR after looking it up in the table.
    4. rtems_status_code bsp_interrupt_vector_enable() enables interrupts and is called in irq-generic.c while setting up the table.
    5. rtems_status_code bsp_interrupt_vector_disable() disables interrupts and is called in irq-generic.c while setting up the table & during other important stuff.
  • The bsp_interrupt_dispatch() acts as an entry to the interrupt switchboard. Hence the address of this method needs to be stored in a specific address where the bsp branches to at the time of occurrence of an interrupt. BSP specific manual is needed for that kind of info. This step is generally done in assembly written in the bsp/start/start.s file.
  • The bsp/include/irq.h contains the declarations for any required global functions like bsp_interrupt_dispatch().
  • The overall irq related files, generic & bsp specific used are :
              1.  Headers installed :

              2.  Source Files compiled

Saturday, 10 August 2013

Unified APIs Observations

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 stuff and including proper components for it.

To identify this one true way, a specific BSP needs to rise and be recognised as a model for other BSPs by the RTEMS community. Hence, the arm lpc24xx is probably a good reference to start with. Do provide any feedback that you think might help improve this project.

Following are the specifications for the generic IRQ related & other important files that the arm lpc24xx includes based on, and this same pattern must be followed by the other BSPs supported by RTEMS :

Start Files

File : start.S
Location : bsp/start/start.S | libbsp/arch/shared/start/start.S
 _start //  Label associated with the starting address of the program

File : bspstart.c
Location : libbsp/shared/bspstart.c | libbsp/arch/shared/bspstart.c | bsp/startup/bspstart.c
 bsp_start() // Performs BSP specific initializations

File : bspreset.c
Location : libbsp/shared/bspreset.c | libbsp/arch/shared/bspreset.c | bsp/startup/bspreset.c

Standard files used for setting up environment

File : bootcard.c Location : libbsp/shared/bootcard.c Header : libbsp/shared/include/bootcard.h boot_card() // First C code invoked File : bspclean.c Location : libbsp/shared/bspclean.c | bsp/startup/bspclean.c bsp_fatal_extension() // Shutdown File : bspgetworkarea.c Location : libbsp/shared/bspgetworkarea.c | libbsp/arch/shared/bspgetworkarea.c | bsp/startup/bspgetworkarea.c bsp_work_area_initialize() // Initialize the RTEMS Workspace and the C Program Heap File : bsplibc.c Location : libbsp/shared/bsplibc.c bsp_libc_init() // Initialize the C Library File : bsppost.c Location : libbsp/shared/bsppost.c bsp_postdriver_hook() // BSP specific code for the initialization sequence File : bsppredriverhook.c Location : libbsp/shared/bsppredriverhook.c | libbsp/arch/shared/bsppredriverhook.c | bsp/startup/bsppredriverhook.c bsp_predriver_hook() File : gnatinstallhandler.c Location : libbsp/shared/gnatinstallhandler.c // No need to include this during compilation, seems empty !! File : sbrk.c Location : libbsp/shared/sbrk.c | libbsp/arch/shared/sbrk.c | bsp/startup/sbrk.c sbrk() File : stackalloc.c Location : libbsp/shared/src/stackalloc.c Header : libbsp/shared/include/stackalloc.h bsp_stack_allocate_init() // Initialize Heap bsp_stack_allocate() // Allocate Heap bsp_stack_free() // Free Heap

Interrupt Files

File : irq.c Location : bsp/irq/irq.c Header : bsp/include/irq.h bsp_interrupt_vector_enable() // Enable interrupt bsp_interrupt_vector_disable() // Disable interrupt bsp_interrupt_facility_initialize() // Initialize Interrupt Controller, do other BSP specific initialization. bsp_interrupt_dispatch() // Reads vector number & calls bsp_interrupt_handler_dispatch() to service the interrupt with the appropriate handler. File : irq-default-handler.c Location : libbsp/shared/src/irq-default-handler.c // Contains default interrupt handler File : irq-generic.c Location : libbsp/shared/src/irq-generic.c Header : libbsp/shared/include/irq-generic.h // Generic BSP interrupt support implementation File : irq-info.c Location : libbsp/shared/src/irq-info.c Header : libbsp/shared/include/irq-info.h //Generic BSP interrupt information implementation File : irq-legacy.c Location : libbsp/shared/src/irq-legacy.c // Generic BSP interrupt support legacy implementation File : irq-server.c Location : libbsp/shared/src/irq-server.c // Generic BSP interrupt server implementation File : irq-shell.c Location : libbsp/shared/src/irq-shell.c // Generic BSP interrupt shell implementation

Real Time Clock

File : rtc-config.c Location : rtc/rtc-config.c bspxx_rtc_initialize() // Initialize RTC chip bspxx_rtc_get_time() // Get time bspxx_rtc_set_time() // Set time bspxx_rtc_probe() // Returns true if device configured by this entry in the RTC_Table is present. File : tod.c Location : libbsp/shared/tod.c | bsp/tod/tod.c // Real Time Clock Driver Wrapper for Libchip

Benchmark Timers

File : benchmark_timer.c Location : bsp/benchmark_timer/benchmark_timer.c benchmark_timer_initialize() // Initialize benchmark timer benchmark_timer_read() // Returns benchmark time units benchmark_timer_disable_subtracting_average_overhead()

Other installed headers

File : include/bsp.h // Global Definitions File : include/bspopts.h File : include/irq.h // Interrupt Definitions File : libbsp/shared/include/coverhd.h // Defines to represent the overhead associated with calling a particular directive from C File : libbsp/shared/include/utility.h // Utility macros File : libbsp/shared/include/tm27.h // Timing test

Thursday, 25 July 2013

GSOC : Rules for updating legacy code in RTEMS BSPS

The legacy API employed by RTEMS bsps consists of methods defined in libbsp/shared/src/rq-legacy.c . The prototypes for these functions are written in cpukit/include/rtems/irq.h
Following are the rules/recommendations that must be followed while updating legacy code from RTEMS BSPs. They are:

  • The replacement of legacy methods should happen like this:

BSP_get_current_rtems_irq_handler()      → Obsolete

BSP_install_rtems_irq_handler()        → rtem_interrupt_handler_install()

BSP_install_rtems_shared_irq_handler() → rtems_interrupt_handler_install()

BSP_remove_rtems_irq_handler()            → rtems_interrupt_handler_remove()

BSP_rtems_irq_mngt_set()                      → bsp_interrupt_initialize()

BSP_rtems_irq_mngt_get()                     → Obsolete

  • All uses of rtems_irq_connect_data type and other data types from legacy API should be removed and replaced with suitable data types if required.

rtems_irq_connect_data  → Use components of this data type individually

rtems_irq_number           →  rtems_vector_number

rtems_irq_hdl_param      →  void *

rtems_irq_hdl      →  void *

  • Remove functions if they’re defined but not used, or if they’re empty.
  • Insert prototypes for non-global functions( having no declarations in a header file) in order to remove any compiler warnings.
  • Make functions static if they’re only used in that specific file.
  • Obtain status of install() & remove() functions in a rtems_status_code status and check it’s value with an assert().
  • While using install() method from the new API, the on() function needs to be called if it’s defined, and it’s not empty.
  • While using remove() method from the new API, the off() function needs to be called before, if it’s defined, and it’s not empty.
  • The implementation of is_enabled/is_on() helper from previous structure should be removed if it’s not used already.
  • Inserting a declaration of a global function in the same file is a bad hack.

Tuesday, 16 July 2013

GSOC Update 2

This blog post covers the progress for my RTEMS GSOC Project Unified APIs from 5th July till now( roughly the next 10 days, since my last GSOC post ). The task for removing legacy support completely from different BSPs is on, and in full swing.

As of now, major work has been done on ARM BSPs which include csb336, csb337, edb7312, gumstix, rtl22xx & gba. I've been asked to set the nds BSP aside for a while, since it uses custom internal methods defined for that BSP, but having the same name as the Legacy API. I'm right now working on pc386 & a couple more in powerpc. Links to accepted commits can be seen here

As a high school and a college student now, I've always been fascinated by Facebook and it's culture. Their core philosophy goes by the words "Move Fast and Break Things". The meaning behind this slogan is not to cause havoc, but instead to encourage engineers to build more things and learn faster. The idea is that if you never break anything, you’re probably not moving fast enough. Hence, you're not learning.

Although I deeply understand this quote, and feel motivated by it, I seem to be taking the above lines a bit literally while working on my GSOC Project. I feel a need to move fast with my work, sending patches in an accelerated sequence again & again until I've corrected them and they're accepted. During this process, Joel & Sebastian seem to be always behind me pointing me towards the things that I've actually broken along my way, instead of improving them. I've been asked to move forward carefully reminding me to check my work for quality, rather than quantity, and I appreciate this suggestion.

What I would like to summarize with this post is that, I'm maybe breaking more stuff at a time, rather than fixing it, but I'm definitely fulfilling the most important aspect of this above philosophy. That is, I am learning. And I am improving my work, along with maintaining my speed.

Friday, 5 July 2013

GSOC Update 1

This blog post follows the progress of my GSOC Project - Unified APIs for the first 15 days of the coding period. According to my proposal, the main task for my project included identifying and implementing a unified pattern of file usage and header installation among various BSPs in the RTEMS tree.

During my discussion with Joel Sherrill(my Mentor), we identified an important sub-task that needed to be done first. This was removing legacy support from the BSPs. The legacy code is defined in the file libbsp/shared/src/irq-legacy.c , which include the following deprecated methods :

  • int BSP_get_current_rtems_irq_handler(rtems_irq_connect_data *cd)
  • int BSP_install_rtems_irq_handler(const rtems_irq_connect_data *cd)
  • int BSP_install_rtems_shared_irq_handler(const rtems_irq_connect_data *cd)
  • int BSP_remove_rtems_irq_handler(const rtems_irq_connect_data *cd)
  • int BSP_rtems_irq_mngt_set(rtems_irq_global_settings *config)
  • int BSP_rtems_irq_mngt_get(rtems_irq_global_settings **config)
These methods need to be updated with functions from the new generic framework present in libbsp/shared/src/irq-generic.c , written by Sebastian Huber. I've submitted patches for arm-csb336 and arm-csb337 for now. But I'll increase this list shortly.

Since being new to RTEMS, I've been committing a few minor mistakes while submitting the patches. But Sebastian, Joel and Gedare have been very helpful. Being experienced developers themselves, I really appreciate their support  in pointing out and correcting those mistakes.

Monday, 27 May 2013

Hello World

The traditional Hello World post.
This blog will follow my GSOC 2013 updates for my Unified APIs Project with RTEMS. Here's a cool pic of the GSOC welcome goodies that I received.

Hoping for a great learning experience this summer.