Freescale PPC e200 (MPC 56xx)

From ErikaWiki

Revision as of 10:58, 19 March 2012 by Eguidieri (Talk | contribs)
Jump to: navigation, search

ERIKA Enterprise supports the PPC e200 family microcontrollers. The support for RT-Druid is available starting from release 1.5.0. The support includes:

  1. Support MPC5674F (e200z7). MPC5668G (e200z6) is supported in version 1.6.0; version 1.6.1 will support both cores (z6 and z0) of the MPC5668G (already available on the Subversion repository).
  2. Support for the WindRiver DIAB and Freescale CodeWarrior compilers.
  3. Support for single- and multi-stack configurations.
  4. ISR Type 1 and Type 2.
  5. ORTI support.
  6. Full Lauterbach support.
  • Supported compilers
    • WindRiver DIAB C Compiler 5.5.1 and 5.8.0.
    • Freescale CodeWarrior:
      • Windows: CodeWarrior Development Studio for MPC55xx/56xx 2.7
      • Linux: CodeWarrior Development Studio for MCU 10.1
  • Mode of operation
    • Monostack: The Monostack configuration of the ERIKA Kernel models the fact that all tasks and ISRs in the system share the same stack.
    • Multistack: Every thread can have its private stack, or it can share it with other threads.
    • Multicore: Currently limited to the MPC5668G, it follows the same philosophy used by ERIKA on other multicore systems and specified by Autosar: two instances of the operating systems run on the two cores, and communication between cores is performed with a few APIs and shared memory.
  • MMU Handling
    • Static global mappings to let all the application see all the memory/peripherals in the system; no memory protection is implemented and all the code is executed in supervisor mode.

Contents

Host Configuration

Wind River Diab

  • Compiler: The compiler commands (dcc, das, dld, and dar) are assumed to be reachable from the $PATH. If a specific version of them has to be used it must be specified in pkg/cfg/arch/cc_z7diab.mk
  • Operating system: The PPC e200 port has been developed under Debian testing/unstable as of May 2010; the only known requirement is Java 1.6 to run RT-Druid.
  • In the reference environment, the Diab toolchain was located in /opt/case/diabdata/<version> and Eclipse in /opt/eclipse. No hard requirement is made by the build system, as specified above.

Freescale CodeWarrior

  • Compiler: The compiler directory can be specified using the environment variable PPC_CW_BASEDIR; this directory must contain the directories PA_Support, and PA_Tools or PowerPC_EABI_Tools. ERIKA makefiles find all the files they need with relatives paths from there. Please notice that makefiles require that the variable PPC_CW_BASEDIR do not contain any space. An evaluation or a limited version of the compiler can be downloaded from the Freescale Web site.
  • Operating system: both Linux and Windows are supported. CodeWarrior support has been developed under Debian Linux and Windows XP, but other (and more recent) versions should work. On Windows, CodeWarrior Development Studio for MPC55xx/56xx version 2.7 is used, and on Linux CodeWarrior Development Studio for MCU version 10.1. On Windows the Cygwin environment is used for ERIKA makefiles, so the PPC_CW_BASEDIR variable must use forward slashes '/' and must not contain spaces; you can always convert the path with the cygpath command. For example, in this case the value to use is /cygdrive/c/PROGRA~1/FREESC~1/CWFORM~1.7:
 $  cygpath.exe `cygpath.exe -ms "/c/Program Files/Freescale/CW for MPC55xx and MPC56xx 2.7"`
 /cygdrive/c/PROGRA~1/FREESC~1/CWFORM~1.7
  • OIL file: Currently, an EEOPT with value "__CODEWARRIOR__" must be specified in the OIL file. See #OIL file configuration for more details.

Target configuration and programming

  • ERIKA is configured through RT-Druid and an OIL file
  • ERIKA supports the Freescale MPC5674F, and MPC5668G MCUs (we have been able to run it on an MPC5567 and others; Freescale MCUs are really very similar).
  • At system boot the interrupt controller is set up to work in Software Vector Mode, and all the interrupts are associated to default handlers. The kernel does not use any specific device/interrupts, although for testing purposes it is possible to use the decrementer and some gpios as interrupt sources. All the code is executed from flash, all the data sections are loaded into the SRAM at boot time (the MMU is configured to provide 1:1 mappings for code running in system mode for all the sensible regions, like flash, sram and device registers).
  • The version in the repository supports both FLE and VLE modes.
  • The scripts generated by the build process are compatible with Lauterbach v200912. The commands generated to setup the NEXUS port are not compatible with older releases of the Lauterbach software. In case you hit this problem, remove the NEXUS.* lines from the generated scripts, ad set up the port according to the Lauterbach version you are using.
  • Target registers are used according the PPC ABI described in the DIAB manual.
  • The stack fill pattern is configurable at compile time, but is assumed to be 0xa5.
  • For Osek conformance classes, which support TerminateTask(), each running task requires 96 bytes of stack.

For multistack configurations, 76 bytes are required on each stack for context switching. You can add this numbers to the requirements of your application to estimate task usage.

  • Stack pointer is aligned at 16 byte (fixed in version 1.6)

MCUs

  • The MCUs supported are currently the following:
    • MPC5674F (Mamba)
    • MPC5668G (Fado)

OIL file configuration

For more information about configuration through OIL file, see Tutorial: RT-Druid and OIL basics. Here only the e200zX-specific part of OIL is described.

CPU (CPU_DATA)
CPU must be set to E200ZX. The exact model is specified with the MODEL item (supported values are E200Z0, E200Z6 and E200Z7. Generation of VLE code can be selected by setting VLE to TRUE; please notice that all the application and the OS code must have the same setting, as ERIKA makefiles do not support mixed programs. Size in byte of the shared stack can be specified with the optional SYS_STACK_SIZE item.
Example of a CPU_DATA section:
CPU_DATA = PPCE200ZX {
	ID = "MainCpu";
	MODEL = E200Z7;
	APP_SRC = "main.c";
	MULTI_STACK = FALSE;
	VLE = FALSE;
	SYS_STACK_SIZE = 512;
};
On multicore systems, one CPU_DATA instance can exist for each core. They must have different IDs. See ERIKA multicore support for more details about multicore systems on Erika.
MCU
MCU support is present for MPC5674F and MPC5668G. The only item supported is MODEL, which can be either MPC5674F or MPC5668G. The only difference produced by this setting is in the memory map and the Lauterbach scripts.
Example:
MCU_DATA = PPCE200ZX {
	MODEL = MPC5674F;
};
EEOPTs
See also EEOPT for common EEOPTs.
Special options for the PPC e200 ERIKA porting can be specified through EE_OPT items in the OS section (please notice that the value for an EE_OPT is a string, so double quotes (") must be added around the values in this list.
EE_ISR_DYNAMIC_TABLE
Used to enable dynamic ISR table support that let register ISR handler at runtime calling EE_e200z7_register_ISR.
__E200ZX_EXECUTE_FROM_RAM__
When specified, a linker script is used that maps both code and data in the RAM space. Executables produced with this option can be used only together with a debugger that loads the program in memory. By default, code and constant data are mapped to Flash, data to RAM.
__CODEWARRIOR__
Invoke Freescale CodeWarrior compiler. See #Freescale CodeWarrior for information on how to configure the compiler. The default compiler is Wind River Diab; see #Wind River Diab for configuration.
__USE_CUSTOM_LINKER_SCRIPT__
Don't use the dafault linker script. Users can direct the linker to use their own linker script by setting the LDFLAGS variable. Example:
OS EE {
   EE_OPT = "__USE_CUSTOM_LINKER_SCRIPT__";
   LDFLAGS = "../my_linker_script.ld";
};
__USE_CUSTOM_CRT0__
Don't use Erika default crt0. Users can provide their own crt0 by adding source files in the usual way (APP_SRC in the OIL file).
__MINIMAL_CC_OPTIONS__
Enable only the compiler flags absolutely needed to compile Erika, so users can easily add their preferences in CFLAGS.
__EE_USE_MMU__
Enable the MMU support. The MMU can be configured by calling EE_e200zx_mmu_setup(). See the MMU section in pkg/cpu/e200zx/inc/ee_cpu.h for more details. An example configuration can be found in examples/ppc/demos/mmu_init.
__EE_CRT0_INIT_MMU__
Initialize the MMU from the crt0. See examples/ppc/demos/mmu_init for an example, and the MMU section in pkg/cpu/e200zx/inc/ee_cpu.h.
DEBUG
On this architecture, enabling debug symbols does not inhibit optimization.

There are a few examples in the ERIKA code base that can be used as a starting point for new projects. Examples include also a makefile, which can be used to compile a project without a need of an IDE. The makefile runs RT-Druid non-interactively, and requires the environment variable RTDRUID_ECLIPSE_HOME to point to the Eclipse directory where RT-Druid is installed.

Examples can be accessed as templates in RT-Druid (see How to create, compile and debug an application for Freescale MPC5674F), or directly in the source code: examples/ppc/.

In the first version of ERIKA and RT-Druid supporting e200zX, the only e200-specific setting in the OIL configuration file was the CPU_DATA value, which had to be set to MPC5674F instead of PPCE200ZX. This not supported any more.

APIs

  • List of functions (see pkg/cpu/e200zx/inc/ee_cpu.h and pkg/cpu/e200zx/inc/ee_irq.h for prototypes and other details):
    • EE_e200z7_register_ISR(level, handler, priority): Associate handler to the IRQ level, with the given priority.
    • EE_e200z7_decrementer_setup(delay): Configure the decrementer to raise an interrupt every delay cycles.
    • EE_e200z7_decrementer_setup_oneshot(delay): Configure the decrementer to raise an interrupt delay cycles after invocation.
    • EE_e200z7_stop_decrementer(): Stop the decrementer from generating interrupts.
    • EE_e200zx_setup_fixed_intv(bitpos): Enable the fixed-interval interrupt.
    • EE_e200zx_stop_fixed_intv(): Disable the fixed-interval interrupt.
    • EE_e200zx_mmu_setup(entries, count): MMU initialization.

Interrupts

There are two way to configure ISR. The standard way is the static way with OIL configuration (example):

 ISR DecrIsr {
   CATEGORY = 2;
   ENTRY = "DECREMENTER";
 };
 
 ISR FixedIntvIsr {
     CATEGORY = 2;
     ENTRY = "FIXED_INTV";
     HANDLER = "fixed_intv_handler";
 };
 
 ISR IsrLow {
   CATEGORY = 2;
   PRIORITY = 1;
   ENTRY = "0";
 };
   ISR IsrMedium {
   CATEGORY = 2;
   PRIORITY = 2;
   ENTRY = "1";
 };
 
 ISR IsrHigh {
   CATEGORY = ;
   PRIORITY = 3;
   ENTRY = "2";
   HANDLER = "isr_high_handler";
 };

In static ISR table handling mode there's full support for both ISR1 and ISR2 for external interrupt, to register an handler you should use the suitable macro (ISR1 or ISR2) passing the value of HANDLER filed or the IS configuration name, in case the former is missing. The configuration field ENTRY declare the position of the handlerinside the vector table (the example show three handler that get the first three position in vector, corrisponding to software interrupt request).

There is direct support for two cpu internal exceptions, those generated by the time base facilities: decrementer and fixed interval timer. Support for watch dog timer will be added. To register an handler for internal interrupt you have to use ISR1_INT or ISR2_INT macros.

You can register handler by code dinamically with with the EE_e200z7_register_ISR() described above. To enable dynamic ISR table support you must declare EE_OPT=EE_ISR_DYNAMIC_TABLE' configuration OIL file.

ISRs (Interrupt Service Routines) are just void functions with no arguments. For external interrupts (IVOR4), the EOI (End Of Interrupt) is issued by ERIKA's handler; user ISRs need not bother about that.

Multicore support (MPC5668)

Boards

  • ERIKA has been developed on an Axiom MPC5674evbfxmb evaluation board.
  • The kernel has no dependency on the board itself, but some of its functionalities can be used for debugging purposes. Including file "pkg/board/axiom_mpc5674fxmb/inc/ee_board.h" the following functions can be used:
    • EE_leds_init(): which sets up the GPIOs associated with the leds.
    • EE_EE_leds(mask): which turns the i-th led on or off depending on the state of the i-th bit in the mask passed as an argument.
    • EE_led_<X>_on()/EE_led_<X>_off(): turns led X on or off.
    • EE_buttons_disable_interrupts(button): disables the interrupt associated to the given button.
    • EE_buttons_enable_interrupts(button): enables it.
    • EE_buttons_clear_ISRflag(button): acknowledges the interrupt coming from the given button.
    • EE_button_get_B<X>(): gets the status of button X.
    • EE_buttons_init(): initializes the GPIOs associated to buttons.
  • The functions above are available if, respectively, __USE_LEDS__ and __USE_BUTTONS__ are defined upon inclusion of ee_board.h
  • The connections are assumed to be the following:
    • GPIO 147-150: connected to LED0-3. Looking at the pins on the EVB:
      • ETPUB1 -> USER_LED1
      • ETPUB2 -> USER_LED2
      • ETPUB3 -> USER_LED3
    • GPIO 450: connected to BUTTON0 (ETPUC9 -> USER_DEV1)

Multicore support

In the ERIKA multicore support for PPC e200 there are a few aspects specific to the PPC e200 architecture, and they are described here. Please refer to ERIKA multicore support for general information on ERIKA multicore systems.

The PPC evaluation board supported by Erika Multicore is the Freescale MPC5668G/E Evaluation kit, the details can be found at http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPC5668GKIT.

Currently, it is possible to run a multicore application only from RAM (it should be possible to run the code from Flash by tweaking the linker script and joining the ELF files, but nobody has tried that). On MPC5668G, the internal SRAM is partitioned statically in two: memory from 0x40000000 to 0x4001FFFF is reserved to the first core and shared variables, while memory from 0x40020000 to 0x4003FFFF is reserved to the second core. 0x40020000 is used as the starting address of the second core.

Shared variable data is allocated in a single section (.mcglobald). Access to this section must be performed without cache, or the OS may malfunction. ERIKA crt0 does not enable cache; if you want to enable it, you should also make sure that the .mcglobald section is allocated on a page on its own by the linker script, and that the MMU is configured to mark such page as non-cached.

The OS uses two software interrupts (6 and 7) and two hardware semaphores (0 and 1) of the MPC5668G to handle inter-core communication. They are initialized inside StartOS(). While all the other software interrupts and semaphores are available for user applications, those used by the OS should not be meddled with by user code. It is okay to briefly mask the interrupts with higher-priority interrupts or by disabling interrupts.

Examples of multicore applications are in examples/ppc/dual_examples. In particular, examples/ppc/dual_examples/mono_activate01 and examples/ppc/dual_examples/multi_event01 are complete applications, nearer to real-world usage.

Lauterbach Trace32 and ORTI support

The ERIKA build system for PPC e200 produces a Lauterbach Trace32 configuration file (t32.cmm) and a ORTI description file (system.orti) inside the output directory. The ORTI file is produced only if ORTI support is enabled in the OIL configuration file. To launch the Trace32 debugger, please issue t32mppc from the output directory. The ERIKA build system honors the T32SYS environment variable, if set.

For multicore projects, the files mentioned above are produced inside the core directories for each core, and a startup script (named start.sh) is produced in the output directory. To run the debugger, please issue start.sh from the output directory. The script creates two instances of the debugger, one for each core. When MPC5668G is turned on, only the first (Z6) core is enabled. In order to simulate the real setup, the debugger connected to the second (Z0) core does not enable its core, but it is responsibility of the code running on the Z6 core to enable the Z0 core (this is different from the example script for MPC5668G distributed with the Lauterbach Trace32 software). Nonetheless, the startup script loads all the code and the debug symbols for both core and both debugger instances. In a typical debugging session, you start the execution of the code on the Z6 core from its debugger, and then, when the Z0 core has become active, start also the code on the Z0 core from the Z0 debugger. The barrier inside StartOS() comes handy to synchronize the code running on the two cores. The start.sh script runs only on Linux; currently the ERIKA build system does not support Windows to run Trace32 for e200 multicore systems.

Internals

Interrupts

Interrupt handling in PPC e200 ERIKA uses software vector mode and a single entry point for all interrupts and exceptions, which is EE_e200z7_irq(). This function calls the user ISR and issues the end-of-interrupt for external interrupts; when the served interrupt is not nested, i.e., it interrupted a task directly, EE_e200z7_irq() also calls the scheduler before returning.

This scheme of IRQ handling can be changed by rewriting the crt0 and changing the IVOR setup. In this way it is possible, for example, to use hardware vector mode. Please note that it is important that the end-of-interrupt be issued before calling the scheduler, as the scheduler may not return when a new task is to be scheduled.

Download and install of Eclipse, RT-Druid, and ERIKA source

To build an ERIKA application you need:

  • ERIKA source code
  • RT-Druid and a hosting Eclipse
  • Some command-line tools

ERIKA source code

ERIKA source code is bundled with RT-Druid. ERIKA for PPC e200 honors the definition of ERIKA_FILES, so you can use the latest version of ERIKA as explained in Tutorial: Installing ERIKA and RT-Druid, and compile your first application#Bleeding edge.

Eclipse and RT-Druid in one piece

A complete version of an Eclipse installation together with the RT-Druid plugin can be downloaded from this page: http://erika.tuxfamily.org/erika-for-multiple-devices.html. Please make sure to use a version not older than 1.6.0 beta. See also Tutorial: Installing ERIKA and RT-Druid, and compile your first application.

Eclipse and RT-Druid piece by piece

Alternatively, if you already have a copy of Eclipse or you want to use a version of Eclipse different from the one provided by the page above, you can follow this procedure.

Procedure for installation:

  • Step 0:
Get Eclipse and required plug-ins;
Where possible, the suggestion is to download the all in one update site and use the eclipse update manager or to use the eclipse update manager directly on a web site;
  • Eclipse
If you don't have any eclipse installations, you can download eclipse with cdt already installed from Eclipse IDE for C/C++.
It is also possible use an already installed distribution of eclipse or to download one (for example from Eclipse Downloads) and then add all missing plug-ins.
  • EMF
The main page to download EMF is Eclipse Modeling Framework.
The version to download is related to the eclipse version: eclipse 3.3 -> emf 2.3 , eclipse 3.4 -> emf 2.4, eclipse 3.5 -> emf 2.5, eclipse 3.6 -> emf 2.6.
The list of required plugins is:
org.eclipse.emf.common
org.eclipse.emf.ecore
org.eclipse.emf.edit
org.eclipse.emf.common.ui
org.eclipse.emf.edit.ui
Clearly it is possible to install more plugins, like the whole emf runtime or sdk
  • CDT
The main page to download CDT is CDT Downloads.
Also here, the version to download is related to eclipse version.
In this case is required only the cdt runtime plugin.
Forum Post (in italian) about installing the Eclipse plugins
  • Step 1:
Open Eclipse;
From the menu Help select Install New Software...;
Add with the button Add... the reference site mentioned above (fill the Location field with this: http://download.tuxfamily.org/erika/webdownload/rtdruid_beta);
Tick all plug-ins related to RT-Druid core and to Erika Enterprise, then click on the button Next to install them;
Restart Eclipse;
  • Step 2:
From the menu File select New and then RT-Druid Oil and C/C++ Project;
From the Project menu select one of the available e200 demo tests;
Then click on the project name with the right mouse button and build to obtain the elf object module for debugging;

Additional software

ERIKA uses GNU make and some command-line utilities to build programs. You need the following tools (please notice that only the less common commands are listed here; very common commands that are present in any Unix/POSIX system like ls are not listed for simplicity):

  • make (GNU version)
  • gawk (GNU AWK)
  • sed
  • grep

For Linux the above commands are present in virtually every standard installation; but you can always install them from the respective packages of your distributions.

For Windows, Cygwin is recommended. Please make sure to include the above packages (package names are the same as the tool names).

HOWTOs

Personal tools