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 Makefile.am, 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