[HOWTO] build and run RTEMS on or1ksim

This post describes how to build, configure RTEMS to run on or1ksim emulator. Installing the tool-chain is a prerequisite before applying the steps in this post; if you have not already installed them, check out the steps here and do it. Once the tool-chain are installed and seen in the executable path, you may proceed with the following steps.

1- Set up the work space.

$ mkdir ~/rtems-dev
$ cd ~/rtems-dev

2- Clone my RTEMS project repo

This is temporary, by the end of the project, all the code at my repo should be upstreamed to RTEMS.

$ git clone git@github.com:heshamelmatary/rtems-gsoc2014.git
$ cd rtems-gsoc2014

3- Switch to or1k branch

I have created a branch for the project to help me with arranging and generating patches against master; meanwhile, keep master branch synchronized with remote.

$ git checkout or1k

4- bootstrap

$ bootstrap -p
$ bootstrap

5- Configuring and building 

$ cd ../
$ mkdir b-rtems
$ cd b-rtems
$ ../rtems-gsoc2014/configure --target=or1k-rtems4.11 --enable-rtemsbsp=or1k_or1ksim --disable-posix --disable-itron --disable-networking --disable-smp

You should get hello and ticker applications in their executable form. Other applications/tests will fail to compile because of other features/implementations that are not supported yet.

Running and debugging hello.exe

1- First you should have an or1ksim configuration script suitable for or1ksim BSP. This is the sim.cfg file I use at this stage of the project. It should be placed at your home directory. Note that as long as more features like: FP, cache manager, MMU manager are added, this file has to be changed to simulate these functionalists on or1ksim.

2- Run hello application on or1ksim.

The configuration file uses RSP (remote protocol) to enable GDB to connect to or1ksim. So, when running or1ksim, it reads configuration script, loads the program into the proper addresses, and waits for GDB to connect.

$ cd $HOME/rtems-dev/b-rtems/or1k-rtems4.11/c/or1k_or1ksim/testsuites/samples/hello/
$ or32-elf-sim -f ~/sim.cfg hello.exe

You should get something similar to the following picture:

3- Run GDB and connect to or1ksim 

From another terminal run GDB and connect to or1ksim

$ or1k-rtems4.11-gdb $HOME/rtems-dev/b-rtems/or1k-rtems4.11/c/or1k_or1ksim/testsuites/samples/hello/hello.exe

From gdb, attach it to or1ksim

(gdb) target remote :50001 

(gdb) continue

UART should emit the string output to or1ksim (and any other channel you provided in configuration script)

References 

[1] Porting RTEMS to OpenRISC - Introduction 

[2] My github project repo (RTEMS).

[3] RTEMS or1k tool-chain status.

[4] HOWTO build or1k-rtems4.11 tool-chain.
[5] RTEMS kernel status.

RTEMS kernel port for OpenRISC | Status Report - 25062014

As introduced before, this year I'm porting RTEMS to OpenRISC 1000 architecture during GSoC program. Other than getting the tool-chain built for RTEMS, the project is mainly about RTEMS kernel. In this post, I'll list the latest updates, concerning RTEMS kernel, that have been achieved so far. The current status is that RTEMS hello and ticker samples can run on or1ksim (see HOTWO build and run RTEMS for OpenRISC).

The code is in its earlier stages, and there is a lot more to do; though, the current code is fairly simple enough that allows anyone to build RTEMS and get hello and ticker samples exes. The project is spread out across RTEMS main components (directories):

CPUKIT

Other than generic APIs, this directory should include shared stuff for any CPU that RTEMS supports; and now it includes or1k. Mainly, it provides details, definitions, configurations, and code for each CPU family for a given architecture. For or1k, the only family is OR1200. It contains processor configurations and properties embedded in .h, .c .S files like:

• In which direction the stack grows. For or1200 the stack is growing down.
• FP unit presence. There is no handling code for FP currently, it's on my TODO list.
• Endianess. Big endian.
• Context Control. This is a structure containing necessary processor context (registers) to be saved/retrieved during context switches. Currently, all general purpose registers are saved as well as supervision register; this is to be optimized in the future.
• Processor definitions. This includes macros for first group of registers that all architectures should implement; most notably supervision register. 
• Context Initialize. This function is implemented to support RTEMS multi-tasking. Initially, it sets elements of Context Control struct including: beginning address of the stack into sp (stack pointer) register and fp (frame pointer) register, loading lr (link register) and sr (supervision register). It's called part of the process of starting multi-tasking.
• Context Switch. The most important function for multi-tasking. Functionality of context switching is supplied via an assembly file called or1k-context-switch.S. This file contains or1k assembly instructions for saving/restoring processor context. It's always invoked for any multi-tasking application.  

There is not any cache or MMU managers currently, this is on my TODO list.

LIBBSP

libbsp is directory that includes every BSP (Board Support Package) for each architecture. For or1k, a new or1ksim BSP is added as an interface to or1k port; it's intended to run on or1ksim emulator. The new BSP contains:

start code

start code is the entry point for the program; it's resposible for providing abstract ISR handlers. For or1ksim, reset and timer handlers are the only statically installed handlers currently. _reset simply jumps to _start which does the following:

1. Load stack and frame pointers.
2. Clear .bss section. 
3. Call bootcard function.

bootcard is a major part for linking BSPs and CPUKIT libraries, it acts as a coordinator from the beginning of initializing the board along with initializing RTEMS data structures, initializing drivers, multi-tasking, etc. The steps an application goes through from the time the first BSP code is executed until the first application task executes are illustrated in the following figure.

linkcmds

This is the linker script describing how the exe code will fit into memory, defining linker symbols that are used in other areas of RTEMS, and handling alignments. The structure of how or1ksim BSP utilizes memory is described in the following figure.

linker symbols 

linker-symbols.h externs all linker symbols for other RTEMS components that may use it. For example, this file is required for initializing context control (in cpukit), zeroing .bss section, and initializing stack and frame registers.

Console driver

Console driver is using UART. For or1ksim simulator, a configuration script is provided to map UART registers to base address 0x90000000. It's working on 115200 baud rate. The process of initializing the console driver includes initializing UART control. Also, the driver implements send_char(), which is used to implement printf, printk within higher layers. Currently, this is the only way we can get output to stdout. or1ksim can be configured to use xterm, tty0, or other channels for rx and/or tx.

Clock driver

Clock driver is essential for RTEMS scheduling purposes and some applications like ticker. The current clock driver implements initialization and tick facility. It should install the tick timer handler into the proper vector location and generate timer interrupt every N ticks. Number of ticks that fire an interrupt is calculated from some RTEMS configurations and the board frequency (100 MHz for or1ksim).  

The clock driver currently is not working in real-time, however, it makes multi-tasking and scheduling working. This issue is to be fixed soon. Also, on my TODO list, the implementation of RTEMS timer benchmark.

IRQ 

IRQ implementation is almost null; once creating IRQ manager for or1ksim (next task), I will generate patches for or1k port to RTEMS to be upstreamed.

In the following post, I will describe HOWTO get, configure, install, run, debug RTEMS application samples (hello and ticker) from my repo. Eventually (by the end of the project), all this code should be upstreamed to RTEMS so that anyone can build RTEMS for or1k like any other target.

References 

[1] Porting RTEMS to OpenRISC - Introduction 

[2] My github project repo (RTEMS).

[3] RTEMS or1k tool-chain status.

[4] HOWTO build or1k-rtems4.11 tool-chain.

[HOWTO] Build RTEMS tool-chain for OpenRISC targets

This post provides two methods of building RTEMS tool-chain for OpenRISC 1000 architecture: 1) building from RSB (RTEMS Source Builder) and 2) building each tool/program separately by downloading official tools' releases and apply our RTEMS specific patches to them. Merely, RSB is responsible for all the stuff including: setting up the environment, downloading releases, applying patches, configuring, building, and installing all the tools. The resulted tools should be program prefixed with or1k-rtems4.11-*. You may want to have a look at OpenRISC ELF GNU tool-chain; but note that RTEMS applications can't be built via these tools. The tool-chain has been tested and used on Fedora 20 and Ububtu 12.04 LTS. 

The tools/programs releases in the time being this post was written are:

• binutils-2.24
• gcc-4.8.2
• newlib-2.1.0
• gdb-7.7
• or1ksim-github-head

Building RTEMS from RSB

Please have a look at RSB documentation here. It provides details in a thorough manner about RSB: how to download RSB, check environment, build RTEMS tool-chain for a specific target. Also, it gives a clear picture how RSB works internally.

1- Setup development and work space

$mkdir ~/rtems-dev

$cd ~/rtems-dev

2- Clone RSB 

$ git clone git://git.rtems.org/rtems-source-builder.git
$ cd rtems-source-builder

3- Check host environment

Check if host environment is setup correctly.

$ source-builder/sb-check

This command will tell you if any packages are required to be installed, if you miss any, please install them and try again, once every thing is Ok, you should have the following message:

$ source-builder/sb-check
RTEMS Source Builder environment is ok

 4- Building

$ cd rtems
$ ../source-builder/sb-set-builder --log=l-or1k.txt --prefix=$HOME/rtems-dev/rtems/4.11 \ 4.11/rtems-or1k

5- Check if all tools are installed successfully. You should get the following results

$ ls $HOME/rtems-dev/rtems/4.11
bin include lib libexec share or1k-rtems4.11
$ ls $HOME/development/rtems/4.11/bin

 

6- Add the newly installed tool-chain to the executable PATH

$ export PATH=$PATH:/$HOME/development/rtems/4.11/bin

Building RTEMS manually 

Currently, all or1k and RTEMS related patches are not upstreamed. So, we have to download official releases and apply patches to support or1k and RTEMS to them. I have worked on combining both or1k and RTEMS patches for all the tools against official tool releases. The following method of building the tools should be temporal. Eventually all patches including or1k and RTEMS should be upstreamed and tools should be built without patches provided here. 

1- Setup development and work space

$mkdir ~/rtems-dev

$cd ~/rtems-dev

2- Get the sources

• binutils-2.24
• gcc-4.8.2
• newlib-2.1.0
• gdb-7.7

3- Get the patches

Download all patches for the previous binutils, gcc, newlib, gdb releases from my repo; preferably, the latest patches (with respect to commit time). Put them in the same directory. 

4- Unpack archives 

$ tar xf binutils*.tar.* 
$ tar xf gcc*.tar.* 
$ tar xf newlib*.tar.* 
$ tar xf gdb*.tar.*

5- Apply patches

$ cd binutils-2.24
$ cat ../binutils*.diff | patch -p1
$ cd ../gcc-4.8.2
$ cat ../gcc*.diff | patch -p1
$ cd ../newlib-2.1.0$ cat ../newlib*.diff | patch -p1
$ cd ../gdb-7.7
$ cat ../gdb*.diff | patch -p1

 $ cd ../ 

6- Configure and build tools

• Create build directories for all the tools

$ mkdir b-binutils b-gcc b-gdb

• Configure and build binutils

$ cd b-binutils
$ ../binutils-2.24/configure --target=or1k-rtems4.11 --prefix=$HOME/rtems-dev/rtems/4.11
$ make
$ make install

• Setup the PATH to include binutils binaries 

$ export PATH=$PATH:/$HOME/rtems-dev/rtems/4.11/bin

• Link newlib into gcc directory

$ cd ../gcc-4.8.2/
$ ln -s ../newlib-2.1.0/newlib .

• Configure and build gcc and newlib

$ cd ..
$ cd b-gcc
$ ../gcc-4.8.2/configure --target=or1k-rtems4.11 --prefix=$HOME/rtems-dev/rtems/4.11 --with-gnu-as --with-gnu-ld --enable-languages="c,c++" --enable-threads --disable-libssp --with-newlib --with-system-zlib --disable-libstdcxx-pch --disable-nls --without-included-gettext --disable-win32-registry --disable-lto --enable-newlib-io-c99-formats

$ make 

$ make install

• Configure and build gdb

$ cd ../
$ cd b-gdb$ ../gdb-7.7/configure --target=or1k-rtems4.11 \
--prefix=$HOME/rtems-dev/rtems/4.11 \
--verbose --disable-nls \
--without-included-gettext \
--disable-win32-registry \
--disable-werror \
--disable-sim} \
--without-zlib \
--with-expat \
--with-python} \
--prefix=$HOME/rtems-dev/rtems/4.11

Building or1ksim

You can follow instructions here to build and configure OpenRISC simulator- or1ksim. Patch for building or1ksim from RSB is on its way to be commited soon.

 

References 

[1] Porting RTEMS to OpenRISC - Introduction 

[2] My github project repo (RTEMS).

[3] RTEMS or1k tool-chain status.

[4] HOWTO build or1k-rtems4.11 tool-chain.

RTEMS (or1k-rtems4.11-*) tool-chain for OpenRISC | Status Report - 25062014

Part of my GSoC project: Porting RTEMS to OpenRISC, I worked on hacking GNU tools to be able to build these tools for RTEMS targeting OpenRISC 1000 (AKA OR1K) architecture. These tools include: binutils, GCC and GDB. Besides, I had to work on Newlib port for OR1K since RTEMS depends on it. or1ksim (OR1K main emulator) is also part of the tool-chain. Currently, all the tools are working fine.

First I will list the status of each tool/program separately. After that (in the next few posts), we will come to the process of building the tool-chain. The following descriptions are concerned with some specific releases:

• binutils-2.24
• gcc-4.8.2
• newlib-2.1.0
• gdb-7.7
• or1ksim-github-head

binutils

There has a been a small patch for binutils to support building it for RTEMS. No big deal with it. Recently, supporting or1k for binutils has been upstreamed; so the next task for RTEMS is to push our patch for review and be upstream to binutils cvs repo.


Newlib

RTEMS depends on Newlib as a library instead of the big libgcc one. Mainly, only Newlib/newlib is necessary for RTEMS. libgloss is not used because RTEMS should provide all the functions and systems calls there. There are some issues regarding Licences and a possibility that the or1k Newlib port may not be upstreamed consequently. Hence, I had to revert back to an old patch to avoid such conflicts. Also, I did not include all of libgloss code. Moreover, I had to write setjmp.S from scratch for the same reason.


GCC

Most of GCC work was about configurations. Some other definitions had to be added to include the proper headers for RTEMS and avoid others from OR1K. libgloss libraries for BSPs provided by OR1K are no longer linked by default (since RTEMS does not use any of them). To test my Newlib port, I had to link bare-metal applications with libnosys.a. Eventually GCC is working fine with Newlib.


GDB

A minimal effort was spent on GDB. It should be built without or1ksim embedded as built-in library. Instead, the current method of debugging with GDB, is to remotely attach it to or1ksim emulator via RSP protocol.


OR1KSIM

The OpenRISC simulator is just used as is from github. Anyone who uses or1ksim should provide a configuration script for his or her target. This is the current sim.cfg script I use to run or1ksim RTEMS BSP. It should be added to your home directory or the current directory you run the simulator from.


RSB (RTEMS Source Builder)

In the time being, all of the previous tools (excluding or1ksim) can be built from RSB; it's the latest modern tool RTEMS uses to build all the tool-chain for targets that RTEMS support. Therefor, I had to add support to RSB to build rtems4.11-or1k-* tool-chain. The patch for such a purpose is committed, so any one can clone RSB and build the entire tool-chain from it. Building the tool-chain from RSB is the easiest way.

In the next few posts, I will introduce some tutorials HOWTO build the tool-chain both manually and from RSB.

References

[1] Porting RTEMS to OpenRISC - Introduction 
[2] My github project repo (RTEMS).
[3] RTEMS or1k tool-chain status.
[4] HOWTO build or1k-rtems4.11 tool-chain.
[5] or1k/rtems related stuff.
[6] tool-chain patches

[GSoC] Porting RTEMS to OpenRISC - Introduction

This year (2014) I’m participating in GSoC program with RTEMS. The project—Porting RTEMS to OpenRISC— (as its name indicates) aims to port RTEMS to OpenRISC architecture. Porting a well-known open source RTOS software like RTEMS for a big open source hardware architecture such as OpenRISC would be of useful to both HW and SW communities. The new port will target a broad range of users and fields (hobbyists, digital designers, computer architecture, embedded systems, industrial applications, etc).

In order to have a successful long term RTEMS port for OpenRISC that people can use, there are main goals (increments) to achieve during the project:

1- Integrate OpenRISC toolchain into RTEMS

To be able to compile and build RTEMS for OpenRISC architecture, some tools need to be added to RTEMS toolchain first. OpenRISC has its own tool-chain independent of RTEMS. So, the job would involve integrating both OpenRISC and RTEMS tool-chain, and make the necessary modifications/additions that fit for RTEMS. These tools include:

• binutils
• gdb
• newlib 
• gcc
• RSB (RTEMS Source Builder)

2- Porting low-level pieces of RTEMS

This includes writing start assembly, device drivers, interrupt handlers, context save, etc. The main components in RTEMS which this goal have to deal with are:

score/cpu: To define general/common OpenRISC architecture's functions.
libcpu (optional): To contain cache and MMU managers.
libbsp: BSPs code.

3- Writing a BSP for a board that OpenRISC supports

A simple BSP that can run hello world and ticker would be needed to be a front-end interface to OpenRISC and RTEMS users. Two BSPs can implemented:

openrisc_or1ksim: This BSP should be for simulation and debugging purposes only.
openrisc_atlys: I have Atlys board which can be used during the project to be the first OpenRISC BSP on RTEMS. Atlys is supported by OpenRISC and libgloss port and can run linux kernel.

4- Setup simulators and debuggers for OpenRISC.

This task includes writing sim-scripts to use openrisc or1k tools, simulators, debuggers. Software and hardware debugging should supported at this stage.

Environment 

• Platform: Fedora 20 and Ubuntu 12.04 LTS.
• Toolchain: Latest toolchain for OpenRISC.
• Simulators: or1ksim and/or qemu.
• Debuggers: gdb connected to or1ksim (OpenRISC tools). Also I should be debugging at real HW (Atlys board) by gdb via JTAG channel.
• Hardware: Atlys FPGA board (supported by OpenRISC).

If you are interested, I should be posting any updates for the project here in my blog. Also, you may want to have a look at project source code at my github account. Project link at RTEMS also exists.

My experience with GSoC

Back to 2012, I was already familiar with some interesting program called GSoC that Google organizes for students to do open source software projects. Like most of CS and Computer Engineering students, GSoC was a great opportunity: only if I could have the chance to participate in. The expectation of being accepted was almost null for me. But why not giving a try? What will I lose? So, I decided to take a step.

Embedded Systems, Operating Systems, RTOS, C: all the keywords I needed to find an accepted organization which matches my interests, and that's exactly what RTEMS tags include in the melange website: the official host for GSoC program. Immediately, I clicked on the link to the RTEMS website, read what RTEMS is about, and searched for open projects. Not surprisingly, there was an open project that appealed to me. To be able to write down a good proposal, I started to read more documentations. After having some headlines in the proposal, it was gradually increasing in size, details and consistency in parallel with reading more about the project details and grasping more concepts. "Nice, now I think I can submit my proposal," I said to myself. Fortunately, submitting my proposal was early and, later, I knew this was one lucky move; I got a lot of valuable and detailed comments from the folks of RTEMS community. That's how things became serious.

The comments made me feel that what I proposed was something important, and needed by users; a feeling that I never had before. I began to try to understand comments, ask about more details, read more and more; consequently, these comments dramatically re-factored my proposal structure and details. After a few weeks of discussions and modifications, the proposal was ready. Once the deadline of application period hit, I was comfortable with what I did. I thought I could not have done better. Few weeks later, the accepted projects were announced, and guess what? I had been accepted! Absolutely, that was a turning point in my life.

I got to do new things and learn interesting stuff about software engineering, how design phase is very important, the benefits of feedback and discussions, why it’s useful to frequently interact with the community via mailing list and IRC. Moreover, I learned a lot about technical issues and coding. Exclusively to my project with RTEMS, my technical hands-on experience has been enriched in a variety of areas like: C programming, RTOS, gdb, gcc, simulators, hardware, embedded systems, git, source control, documentation, other open source tools, and a lot more. Making connections with some great mentors there was one great aspect of participating in GSoC.

I enjoyed having commitments, deadlines, challenges and troubles. That's what GSoC is partially about (other than encouraging students to work with open source software): a real world work experience. People in RTEMS, and any other organization, want you to complete your project successfully. They are thrilled to help you with every challenge you face. Thanks to my mentor, I was able to pass midterm and final evaluations, and I could brag that I am a former GSoC participant.

Statement of accomplishment - GSoC'2012

Next year (2013), I applied to GSoC with RTEMS (again!) and I have been accepted. Right after GSoC, I participated in GCI--Google Code In--as a mentor, not surprisingly, with the same organization. This year (2014), I have applied to GSoC with RTEMS and I am currently awaiting the announcement of accepted students (wish me luck).

GCI'2013

For me, GSoC made what it aims/claims to achieve:

(a) I learned much about open source software.
(b) Now I am stuck to open source and RTEMS.
(c) Got hands-on experience with real world software process.
(d) Made connections with great developers.
(e) Achieved a glory (and got a nice paycheck).

If you are a student and you're considering applying to GSoC, here is my two cents:

(a) Do not worry about your modest experience, you're ought to learn in the first place. Basics are enough.
(b) Make a proposal and get in touch with the organization community. Do both early!
(c) Your proposal should be well structured and detailed. It should explain how will you work on the project and give a clear and reasonable timeline as well as deliverables. Most organizations provide a template for writing proposals.
(d) Choose a project that 1) appeals to the organization and its users, 2) match your interests. Most likely it will be one of the projects ideas.

Inside low-level details of RTEMS/MMU project

Objectives :

This post aims to reveal low-level details of libmm for ARM BSPs. The main objectives are to know how low-level layer works and how to port libmm for a new (ARM) BSP.

ARM/LIBMM interaction :

Since libmm is about managing memory protection, Caches and MMU, libmm relies on ARM Co-processor 15: the primary co-processor which manages memory at the HW level for all modern ARM cores. CP-15 contains some control registers that help us to manage memory both at startup and dynamically.

The main CP-15 control register (C1) contains flags that we set/unset during RTEM initialization and application run-time. Figure-1 shows control register format on ARMv6. Please note that some of CP-15 C1 register flags may exist for a specific ARM architecture and absent for another one, also some flags maybe deprecated in modern architectures but still there not to hurt compatability. You can find each flag use and its meaning at the reference manual for ARM architectures [1] and CPU you develop in.

Figure-1 ARM CP-15 Control Register Format

The most important flags we use are M and C flags. M flag is used to enable/disable MMU, while C flag is used to enable/disable Cache unit.
CP-15 also contains other useful registers like :

• Translation Table Base Register : Points to the First level of page-tables (Sections or Super Sections)
• Domain Access Control : The purpose of the Domain Access Control Register is to hold the access permissions for a maximum of 16 domains.
• Cache Operations .
• TLB Operations.
• Interrupt Status Register.

 ARM CP-15 API in RTEMS

RTEMS has a header file (arm-cp15.h) the contains code needed to do any operation on CP-15 and its registers. This should be the backend API for ARM BSPs that implements low-level libmm API. Another new header file called arm-cp15-start.h is created to help initializing CP-15 at BSP startup. The next section illustrates how ARM CP-15 is initialized.

arm-cp15-start.h initialization 

The main components and areas that involve libmm/MMU initialization are

•  Linker defines : These defines at linker-symbols.h export macros and variables that point to registers like translation table base (page-table directory), object addresses for some sections and other useful linker variables. Figure-2 shows some linker variables quoted from ARM linker-symbols.h

• 

  Figure 2: Example linker symbols from ARM linker-symbols.h

•  mm-config-table is an initialization table which contains entries each of which describes a section of the program object file by its starting address, end address and CPU memory attributes it "should" have. Every BSP should define its own init table which is passed to mminit function. Figure-3 shows the format of such a table.

Figure-3 mm_config_table format

For CPU Memory Attributes field, it simply represents a page-table entry for the CPU libmm is ported for. Figure-4 shows an example of RaspberryPi/ARM1176JZF-S CPU first-level page table entries formats.

Figure-4 Backwards-compatible first-level descriptor format.

An example of mm_config_table is the table for RaspberryPi BSP. It uses some linker defines to set starting addresses and sizes of sections. For the CPU Memory Attributes field, arm-cp15.h macros are used. Figure-5 is a real code for mm_config_table for RaspberryPi BSP.

Figure-5 raspberrypi mm_config_table example.

•   linkcmds : This is the linker script passed to the linker during compilation/linking process. It manages how sections are organized in the final executable file and reserve memory areas for run-time demands. What concerns us about the linker file is to tell the linker where should be the global page-table and its size. Also this file should export the translation table base to other rtems low-level layers (such as libmm). For RaspberryPi BSP on RTEMs, the 128 MB memory is mapped as shown in figure-5.

Figure-6 RTEMS/RaspberryPi BSP memory map

•  mminit.c : This file contains an implementation for bsp_memory_management_initialize which is a part of libmm API. Every BSP that supports libmm should implement this function. mminit.c should contain all variables, macros, routines that initialize memory management HW. For RaspberryPi, the implementation is direct wrapper to arm_cp15_start_setup_translation_table_and_enable_mmu_and_cache included from arm-cp15-start.h. mm_config_table and its size are passed to this function which iterates over the table entries, and set HW page table entries according to mm_config_table entries.

Setting page table entries dynamically 

Some applications may need to set memory attributes for a specific area of memory dynamically (within application phase). Examples of these applications are dynamic linker/loader and POSIX mman.h API. libmm supports dynamic setting of memory attributes through a call to bsp_memory_management_set_attributes routine which is a part of libmm low-level API. Every BSP that supports libmm should implement this function. In RTEMS/ARM, we share mm.c file to support this feature. mm.c should translate high-level HW-independent libmm attributes (at score/mm.h file) to CPU specific attributes, thus, we can share high-level APIs between different BSPs and architectures. Figure-7 is a shared translation macro for different ARM BSPs (quoted from mm.c).

Figure-7 Translating high-level LIBMM attributes to CPU attributes.

At the run-time, the process of dynamically setting page-table attributes involves:

1. Disable interrupts.
2. Disable MMU and Cache unit.
3. Get page table indices for the region to apply attributes on.
4. Set page-table attributes.
5. Enable MMU and Cache unit.
6. Enable interrupts.

How to port libmm for a new BSP ? porting !

To port libmm for a new BSP you should simply follow these steps :

For static initialization part :

• Create mm_config_table according to the memory map of the new BSP. For ARM BSPs that share mminit.c and mm.c this table name should be the same (currently it's called bsp_mm_config_table).
• Define the size of the previous table with a shared name (bsp_mm_config_table_size).
• implement bsp_memory_management_initialize for the new BSP.

For dynamic part : 

• Create a translation attributes that convert high-level HW independent attributes (at score/mm.h) to the CPU of your BSP.
• implement bsp_memory_management_set_attributes

File that contains these implementation should include <libbsp/mm.h> which has prototypes for libmm low-level API.

How to make sure that the new port works ? porting !

To make sure your new port works fine you have to :

• Run sample tests (hello.exe, ticker.exe). If these tests runs as expected that means libmm initialization is done successfully, Otherwise the program should hang and give no output.
• Run mmtest2.exe (at libtests/mmtest2) that tests dynamic part of libmm and triggers some exceptions. Figure-8 is an example of mmtest2 output that runs successfully.

Figure-8 Output of mmtest2.exe

Acronyms : 

CP15    Co-Processor 15
libmm    memory management library
BSP      Board Support Package
MMU    Memory Management Unit
API       Application Programming Interface
TLB      Translation Lookaside Buffer
mminit    memory management initialize
init         initialization

References :

[1] ARM Architecture Reference Manual.
[2] github repo for the project.