It was a great Google Summer of Code instance this year for me working on a project of my interest (Porting RTEMS to OpenRISC), and achieved a good progress. In this post I will give some implementation details about the parts I worked on, and what has been done so far.
The main low-level part of the OpenRISC CPU port goes there. The port provides configurations of the CPU there. All of the cpukit code I have written is now upstream. The following are the major parts of cpukit already implemented.
A new file called or1k-utility.h is added to contain great deal of OpenRISC specific information. Special purpose registers definitions and bit locations and masks within these registers are there. Also, some of the most frequently used functions like _OR1K_mfspr, and _OR1K_mtspr, power management are added. Most of OpenRISC/RTEMS .c files (e.g. BSP clock driver, interrupt handling, UART driver, etc) include this file.
New real-world interrupt handling scheme has been implemented to follow most of other RTEMS ports implementation. Interrupt handling now has stages to go through:
1.1.1 BSP: The very-early executed code starts from the BSP assembly code. Please see or1ksim BSP start.S section below for more details. Once an interrupt is raised, the PC jumps to a specific address at the BSP code, and from there it jumps to _ISR_Handler, a big chuck of assembly code located at cpukit port, and it's the core of interrupt handling.
1.1.2 _ISR_Handler: I consider this the core of interrupt handling for this port. This is a very critical code that needed to be implemented accurately. Initially, it allocates a new space in the interrupted task stack to save CPU_Exception_frame content. CPU_Exception_frame for OpenRISC is shown in the next figure.
Once a new space is allocated in the stack, the task context is dumped there. Then nesting level is incremented, and thread dispatching is disabled. At this point, a decision must be made if it's needed to switch the stack to RTEMS SW interrupt stack depending on the nesting level. Once all of the previous actions have been done, the code would be ready to jump to the user C handler.
1.1.3 C Handler: This is the user C handler which can be installed dynamically. Initially, there are default handlers set by the BSP at the startup code. Later, a user can install a new C Handler by calling _CPU_ISR_install_vector(). An example quoted from the or1ksim clock driver, installing the C handler is followed.
1.1.4 Restore exception context: After returning from the C handler, a check whether a thread dispatch is necessary, and if so, jump to _Thread_Dispatch. The final action is to restore the previously saved context and return from interrupt.
1.1.5 Default ISR Handler
This is a default ISR C handler that is installed for all interrupt types in the BSP vector table statically at startup code. Later, the code can install other C handlers with vector index if needed. The implementation of this default handler just calls rtems_fatal with exception error code, and CPU_Exception_frame. rtems_fatal in tern, halts the processor and print out the context frame if needed.
The following flowchart shows how interrupts are processed in RTEMS for OpenRISC.
This file is provided by every port. It contains CPU configurations, available features, stack growth direction, macros definition, inline functions, and other configurations and CPU specifications every port should provide. For example, enable/disable interrupts are implemented there.
Although power management is optional HW feature, I added handling code for targets that supports it. As or1ksim is capable of simulating power management features (sleep mode), the IDLE task could make use of it by going into sleep mode instead of generic IDLE loop.
Once a thread is created, its control structure needs to be initialized. The port should implement such a function. The initialization involves setting up the stack pointers, entry point and SR register. In future implementation, TLS and FP implementation support would take a role here.
This is a utility function that can be useful for dumping the content of the exception frame in a formatted way.
or1ksim is the first BSP for the new OpenRISC port. It's intended to run on or1ksim (the main or1k emulator). It simulates great range of real hardware features. I have worked on implementing the most important parts that most BSPs provide.
This file contains the very early executed code for or1ksim BSP. Once the program starts, a reset interrupt occurs, jumping to _start assembly function. _start is responsible for:
It is also responsible for interrupts stuff, providing ISR vector table which contains addresses of user exception C handlers. Initially, this table is setup with default ISR Handler from cpukit (refer to the cpukit, interrupt handling section). Installing a new C handler involves writing to this table.
Moreover, HW interrupts jump to arbitrary addresses, in which start.S provide generic prologue code that passes vector number to _ISR_Handler before jumping to it.
Console driver is implemented to enable the BSP to emit some output characters to the console. Most RTEMS tests use console driver (printk, printf), to output some data regarding test results and to notice there behavior. The following figure is an output of running ticker.exe (one of RTEMS test samples) that use both console and clock drivers. It's running on or1ksim and attached to gdb.
Clock driver is needed for any BSP/target that needs multi-tasking (i.e, context switch) and operating systems scheduling features. OpenRISC has only one timer called tick timer. The or1ksim BSP provides clock driver initialization that setup necessary registers, tick time, installing Clock_isr C handler, and enable tick timer interrupts. RTEMS uses tick timer restart mode, so when a tick interrupt occurs it restart itself and count from zero again. Also or1ksim clock driver implementation provides a function called or1ksim_clock_at_tick which is executed part of the RTEMS Clock_isr C handler to do HW specific actions. For OpenRISC, it just clears pending interrupts, setup the TTMR register again, and reset TTCR (timer counter) to zero (optional). Please note that or1ksim is not accurate regarding timing.
Simple timer benchmark driver is provided to run some tests that help profiling and calculating some performance statistics. It's mainly based on the clock driver.
At early stages of the project, I had to work on the GNU toolchain to support building RTEMS for or1k targets. The work involved adding some configurations and modifying scripts to add or1k-rtems* and similar stuff. The following status of the toolchain is supplied at the time of this post was written. It may be changed later.
By now, OpenRISC folks pushed their new or1k support upstream to cvs and that included my work. So, binutils can be built for both or1k-elf and or1k-rtems* targets by cloning cvs target. This work would be included in the next binutils release (2.25?)
I had to work on newlib library as it's used by RTEMS as the main embedded library instead of libgcc. We (RTEMS and OpenRISC communities) discussed about some licence issues, and RTEMS community took a decision to avoid the licence problem. The OpenRISC GPL newlib code might be rejected by sourceware, so, I had to provide a complete minimal port for OpenRISC/RTEMS to newlib. It's now upstream and can be built from RSB or manually. By doing that, we avoided the possibility that newlib from OpenRISC folks might be rejected. Later, when OpenRISC people want to push their code (after resolving these licence issues), they would have to adapt, modify, and add to my upstream code there.
OpenRISC community is working hard to push their gcc work upstream. I expect that to happen soon. I may be lucky enough to be one of the contributors of the early or1k gcc port when it's upstream.
gdb code (both OpenRISC and my RTEMS additions) may have to be delayed from being merged upstream. In the time being, or1k-rtems* toolchain is using a big bulk patch from my repository for building gdb7-7 release for or1k-rtems4.11-gdb. Hopefully, OpenRISC would push the code soon.
or1ksim can be built and run as described in OpenRISC instructions page. No additional work needed to run for RTEMS except sim.cfg, which is provided in my repo.
RSB (RTEMS Source Builder) is a great tool to build all the toolchain (i.e, binutils, newlib/gcc, gdb, or1ksim) from source on many platforms and operating systems. It's created and maintained by Chris Johns who mentored my this GSoC instance. I have added support for RSB to build the tools for or1k-rtems*-*. I am using Linux to build the toolchain, however, Chris stated recently that RSB can run on Windows, including the new or1k-rtems*-* toolchain.
1. CPUKIT
The main low-level part of the OpenRISC CPU port goes there. The port provides configurations of the CPU there. All of the cpukit code I have written is now upstream. The following are the major parts of cpukit already implemented.
1.1 Utility
1.2 Interrupt handling
New real-world interrupt handling scheme has been implemented to follow most of other RTEMS ports implementation. Interrupt handling now has stages to go through:
1.1.1 BSP: The very-early executed code starts from the BSP assembly code. Please see or1ksim BSP start.S section below for more details. Once an interrupt is raised, the PC jumps to a specific address at the BSP code, and from there it jumps to _ISR_Handler, a big chuck of assembly code located at cpukit port, and it's the core of interrupt handling.
1.1.2 _ISR_Handler: I consider this the core of interrupt handling for this port. This is a very critical code that needed to be implemented accurately. Initially, it allocates a new space in the interrupted task stack to save CPU_Exception_frame content. CPU_Exception_frame for OpenRISC is shown in the next figure.
CPU_Exception_frame
Once a new space is allocated in the stack, the task context is dumped there. Then nesting level is incremented, and thread dispatching is disabled. At this point, a decision must be made if it's needed to switch the stack to RTEMS SW interrupt stack depending on the nesting level. Once all of the previous actions have been done, the code would be ready to jump to the user C handler.
1.1.3 C Handler: This is the user C handler which can be installed dynamically. Initially, there are default handlers set by the BSP at the startup code. Later, a user can install a new C Handler by calling _CPU_ISR_install_vector(). An example quoted from the or1ksim clock driver, installing the C handler is followed.
 |
| or1ksim clock driver install ISR handler |
1.1.4 Restore exception context: After returning from the C handler, a check whether a thread dispatch is necessary, and if so, jump to _Thread_Dispatch. The final action is to restore the previously saved context and return from interrupt.
1.1.5 Default ISR Handler
This is a default ISR C handler that is installed for all interrupt types in the BSP vector table statically at startup code. Later, the code can install other C handlers with vector index if needed. The implementation of this default handler just calls rtems_fatal with exception error code, and CPU_Exception_frame. rtems_fatal in tern, halts the processor and print out the context frame if needed.
default or1k exception handler implementation
The following flowchart shows how interrupts are processed in RTEMS for OpenRISC.
Flowchart of RTEMS/OpenRISC interrupt processing
1.3 Context Switch
A major part of any operating system is context switch. This code simply dumps the task context of the currently executing task, and restore the context of the heir task to the processor state making it running. The OpenRISC port only saves/restore preserved registers across function calls.
1.4 cpu.h
This file is provided by every port. It contains CPU configurations, available features, stack growth direction, macros definition, inline functions, and other configurations and CPU specifications every port should provide. For example, enable/disable interrupts are implemented there.
Snippet code of or1k/rtems/cpu.h file
1.5 Power management
Although power management is optional HW feature, I added handling code for targets that supports it. As or1ksim is capable of simulating power management features (sleep mode), the IDLE task could make use of it by going into sleep mode instead of generic IDLE loop.
IDLE Thread body using power management sleep mode
1.6 Context initialize
Once a thread is created, its control structure needs to be initialized. The port should implement such a function. The initialization involves setting up the stack pointers, entry point and SR register. In future implementation, TLS and FP implementation support would take a role here.
Context initialize implementation
1.7 Exception frame print
2. or1ksim BSP
or1ksim is the first BSP for the new OpenRISC port. It's intended to run on or1ksim (the main or1k emulator). It simulates great range of real hardware features. I have worked on implementing the most important parts that most BSPs provide.
2.1 Start.S
This file contains the very early executed code for or1ksim BSP. Once the program starts, a reset interrupt occurs, jumping to _start assembly function. _start is responsible for:
- Setup SR registers to Supervision mode.
- Load stack and frame pointers.
- Clear .bss area.
- Jump to boot_card.
It is also responsible for interrupts stuff, providing ISR vector table which contains addresses of user exception C handlers. Initially, this table is setup with default ISR Handler from cpukit (refer to the cpukit, interrupt handling section). Installing a new C handler involves writing to this table.
or1ksim BSP vector table
Moreover, HW interrupts jump to arbitrary addresses, in which start.S provide generic prologue code that passes vector number to _ISR_Handler before jumping to it.
prologue exception handling instructions at start.S
2.2 Console driver
Console driver is implemented to enable the BSP to emit some output characters to the console. Most RTEMS tests use console driver (printk, printf), to output some data regarding test results and to notice there behavior. The following figure is an output of running ticker.exe (one of RTEMS test samples) that use both console and clock drivers. It's running on or1ksim and attached to gdb.
ticker.exe output
2.3 Clock driver
Clock driver is needed for any BSP/target that needs multi-tasking (i.e, context switch) and operating systems scheduling features. OpenRISC has only one timer called tick timer. The or1ksim BSP provides clock driver initialization that setup necessary registers, tick time, installing Clock_isr C handler, and enable tick timer interrupts. RTEMS uses tick timer restart mode, so when a tick interrupt occurs it restart itself and count from zero again. Also or1ksim clock driver implementation provides a function called or1ksim_clock_at_tick which is executed part of the RTEMS Clock_isr C handler to do HW specific actions. For OpenRISC, it just clears pending interrupts, setup the TTMR register again, and reset TTCR (timer counter) to zero (optional). Please note that or1ksim is not accurate regarding timing.
2.4 Timer benchmark
Simple timer benchmark driver is provided to run some tests that help profiling and calculating some performance statistics. It's mainly based on the clock driver.
3. toolchain
At early stages of the project, I had to work on the GNU toolchain to support building RTEMS for or1k targets. The work involved adding some configurations and modifying scripts to add or1k-rtems* and similar stuff. The following status of the toolchain is supplied at the time of this post was written. It may be changed later.
3.1 binutils
By now, OpenRISC folks pushed their new or1k support upstream to cvs and that included my work. So, binutils can be built for both or1k-elf and or1k-rtems* targets by cloning cvs target. This work would be included in the next binutils release (2.25?)
3.2 newlib
I had to work on newlib library as it's used by RTEMS as the main embedded library instead of libgcc. We (RTEMS and OpenRISC communities) discussed about some licence issues, and RTEMS community took a decision to avoid the licence problem. The OpenRISC GPL newlib code might be rejected by sourceware, so, I had to provide a complete minimal port for OpenRISC/RTEMS to newlib. It's now upstream and can be built from RSB or manually. By doing that, we avoided the possibility that newlib from OpenRISC folks might be rejected. Later, when OpenRISC people want to push their code (after resolving these licence issues), they would have to adapt, modify, and add to my upstream code there.
3.3 gcc
OpenRISC community is working hard to push their gcc work upstream. I expect that to happen soon. I may be lucky enough to be one of the contributors of the early or1k gcc port when it's upstream.
3.4 gdb
gdb code (both OpenRISC and my RTEMS additions) may have to be delayed from being merged upstream. In the time being, or1k-rtems* toolchain is using a big bulk patch from my repository for building gdb7-7 release for or1k-rtems4.11-gdb. Hopefully, OpenRISC would push the code soon.
3.5 or1ksim
or1ksim can be built and run as described in OpenRISC instructions page. No additional work needed to run for RTEMS except sim.cfg, which is provided in my repo.
3.6 RSB
RSB (RTEMS Source Builder) is a great tool to build all the toolchain (i.e, binutils, newlib/gcc, gdb, or1ksim) from source on many platforms and operating systems. It's created and maintained by Chris Johns who mentored my this GSoC instance. I have added support for RSB to build the tools for or1k-rtems*-*. I am using Linux to build the toolchain, however, Chris stated recently that RSB can run on Windows, including the new or1k-rtems*-* toolchain.
References
[1] RTEMS
[2] OpenRISC
