Ucos-Mmu Sysmanual
Ucos-Mmu Sysmanual
Ucos-Mmu Sysmanual
System Manual
Version 3.1.0
Micriµm
Empowering Embedded Systems
www.Micrium.com
2
Disclaimer
Specifications written in this manual are believed to be accurate, but are not
guaranteed to be entirely free of error. Specifications in this manual may be
changed for functional or performance improvements without notice. Please make
sure your manual is the latest edition. While the information herein is assumed to
be accurate, Micrium Technologies Corporation (the distributor) assumes no
responsibility for any errors or omissions and makes no warranties. The distributor
specifically disclaims any implied warranty of fitness for a particular purpose.
Copyright notice
The latest version of this manual is available as PDF file in the download area of our
website at www.micrium.com. You are welcome to copy and distribute the file as
well
as the printed version. You may not extract portions of this manual or modify the
PDF file in any way without the prior written permission of Micrium Technologie
Corporation. The software described in this document is furnished under a license
and may only be used or copied in accordance with the terms of such a license.
Trademarks
Names mentioned in this manual may be trademarks of their respective companies.
Brand and product names are trademarks or registered trademarks of their
respective holders.
Registration
Please register the software via email. This way we can make sure you will receive
updates or notifications of updates as soon as they become available. For
registration please provide the following information:
Contact address
Micrium Technologies Corporation
949 Crestview Circle
Weston, FL 33327-1848
U.S.A.
Phone : +1 954 217 2036
FAX : +1 954 217 2037
WEB : www.micrium.com
Email : support@micrium.com
Manual versions
This manual describes the latest software version. The software version number can
be found in the table .Software versions. Later in this chapter. If any error occurs,
please inform us and we will try to help you as soon as possible. For further
information on topics or routines not yet specified, please contact us.
Manual
Date By Explanation
Rev
1.0 2009-02-19 MH Initial Version
1.1 2009-02-24 MH Add chapter “Configuration” and “Hook
Function”
1.2 2009-03-06 MH Minor Corrections
1.3 2009-04-24 MH Add API function PARHardwareCall() and
remove board specific BSP descriptions.
2.0 2009-10-05 MG Change function prototypes; Add API
functions PARShutdown() and PARInit();
2.1 2010-01-12 RB Add API functions
PARPhaseGetTableTick(),
PARPhaseGetCycleTime(),
PARPhaseGetTimeOffset() and
PARPhaseSetTime() in Timing Control
chapter
2.2 2010-03-22 RB Update Manual for Software Version 3.0.0
3.1.0 2010-06-30 RB Update Manual for Software Version 3.1.0
Changed parameters of
PARIrqTrigger() in chapter Partition
Interrupt
Added Hook Function
PARIrqConfigHook()
Table of Contents
1 Introduction 5
1.1 Terms 5
2 µC/OS-MMU Architecture 6
2.1 Space Partitioning 6
2.2 Time Partitioning 7
2.3 Privileged User Application 8
2.3.1 Hardware Access 8
2.3.2 Partition Control 8
2.3.3 Timing Control 9
2.3.4 Partition Interrupt 10
2.3.5 Using µC/OS-II Services 10
2.4 User Application 10
2.4.1 Hardware Access 10
2.4.2 Partition Interface 11
2.4.3 Service Call 11
2.4.4 Partition Interrupt 11
2.4.5 A plain main() 12
2.4.6 Using a Guest OS 12
3 Board Support Package 13
4 Configuration 14
4.1 Phase Tables 14
4.2 Memory Layout 14
4.3 Service Call Function 15
4.4 Partition Interrupt 15
5 Hook Functions 16
References 18
Contact 18
1 Introduction
µC/OS-MMU is a memory management extension, based on µC/OS-II, which simplifies the
separation of multiple applications within a safety critical system. The extension is designed to
provide a high level interface to manage multiple applications in time- and space partitions which
is configurable and easy to use. Considering strict coding rules during development, the source
code is highly efficient in resource usage (in RAM and ROM) and certifiable with a minimum
effort.
Before reading this guide, you should already have a solid knowledge of the C programming
language and the use of µC/OS-II services. If you feel, that your knowledge in C programming is
not sufficient, we recommend the “The C Programming Language” by Kernighan and Ritchie,
which describes the programming standard and, in newer editions, also covers the ANSI C
standard.
1.1 Terms
Within this manual, the following terms are used:
Term Description
Space A memory region with a continuous address range
Privileged Mode The access permission of the processor is allowed to all memory regions.
This must be supported by the processor core hardware. An application
which runs in this mode, is called privileged application.
User Mode Access permission of the processor is limited to the memory region
related to the own partition ID. This must be supported by the processor.
Often this feature is realized within the MMU (memory management unit)
or MPU (memory protection unit) of a processor.
Core Software The privileged application, which implements the time- and space
partitioning. The core software is based on a core OS. The default core
OS is µC/OS-II.
Partition A predefined space linked to one user application.
Board Support The software parts which links the core software components to the
Package (BSP) processor specific hardware features (like timer, interrupt controller, etc..)
Core OS Port The adaptation of the core OS to the processor (e.g. register set, FPU
support, context switching, etc..)
MMU Port The adaptation of the core software to the processors memory
management (or protection) unit.
Time Phase A timeslot of a fix length which is guaranteed to the linked component.
The linked component can be the core software or one of the partitions.
Phase Table The definition of the order of multiple time phases
2 µC/OS-MMU Architecture
The µC/OS-MMU extension provides an environment where applications can be implemented
with the insurance, that no user application can disturb or corrupt any other user application. This
insurance is called “Time and Space Partitioning”. This chapter describes the architectural design
and the intended usage of the time and space partitioning on system level view.
Partition #1 .. N
User
User
Application
Privileged Application EMPTY
User without OS
Application Guest OS
Core OS
The example system contains a “Privileged User Application”, which is able to access the,
controls the partition #1 to #3 and can change the system timing behavior by changing the active
phase table. The “User Application”, which can include a Guest OS (a complete RTOS, e.g.
µC/OS-II, with no link to the Core OS) or can be implemented as a plain main() function. The
example system has an empty partition for future extensions, which will have no influence on the
currently running system in timing or system reactions.
Partition #3
Partition #2
Partition #1
Core SW
t1 t2 t3 t4 t5
Runtime
Idle Time
Additional time due to self
suspended partition
The example system will be executed with 5 phase times (t 1 .. t5). The phase table, which holds
these phases is marked as cyclic, so the phase table time (sum of t1 .. t5) is the cycle time of the
system. The system designer guarantees the first phase t1 to the core software. The second
phase is linked to the partition #2. Partition #2 will not need the whole guaranteed time, but will
loop in a waiting loop (e.g. Idle Task) until the next phase will be started by the scheduler. The
phases t3 and t5 are linked to partition #1. Partition #1 will not need the whole guaranteed time
slots and suspends itself. The system designer specifies, that all unused runtime within these two
phases are provided to the core software as an additional runtime. The phase t4 is linked to
partition #3. Partition #3 will not need the whole guaranteed time and suspends itself. The
system designer specifies, that this unused runtime is provided to the next phase as an
additional runtime.
The system designer may define as much phase tables as needed for all system modes. The
core software is able to switch between the phase table definitions at any time. The system
timing behavior changes at the end of the current phase table.
The hardware access is highly hardware and system dependent. The µC/OS-MMU package
includes some board support package elements, which may be used by the “Privileged User
Application”.
Note, that within the standard µC/OS-MMU package only those hardware modules are
supported, which are needed by the µC/OS-MMU time and space partitioning handling. For
extended (or full) support of your hardware within the board support package, please contact us.
The descriptions in this manual assume the standard board support package (see chapter 3
Board Support Package).
The “Privileged User Application” can control the existence and lifetime of partitions with the
following API functions:
This function initializes the memory environment for the µC/OS-MMU. After calling this
function the target specific memory management unit is active. This function is typically
called during system startup before PARStart() is called (see detailed description in
µC/OS-MMU Reference Manual).
This function initializes the core OS (µC/OS-II) and the µC/OS-MMU extension. This
function is typically called during system startup and will NOT return to the calling
function. After this function call, uC/OS-MMU is running (see detailed description in
µC/OS-MMU Reference Manual).
This function stops the µC/OS-MMU system (see detailed description in µC/OS-MMU
Reference Manual).
This function creates a partition with the given partition ID “parID”. The return value
indicates the success of the creation (see detailed description in µC/OS-MMU Reference
Manual).
This function deletes the partition with the given partition ID “parID”. The return value
indicates the success of the deletion (see detailed description in µC/OS-MMU Reference
Manual).
This function suspends the partition with the given partition ID “parID”. The parameter
“mode” defines the handling of upcoming events addressed to the partition (ignoring the
event, event delivery to the partition, etc.). The return value indicates the success of the
suspension (see detailed description in µC/OS-MMU Reference Manual).
This function resumes the partition with the given partition ID “parID”. The return value
indicates the success of the resuming (see detailed description in µC/OS-MMU
Reference Manual).
The “Privileged User Application” can change the use of the currently active phase table at any
time. This change takes effect at the end of the currently running phase table. Multiple phase
tables are intended for different system modes like “Startup Mode”, “Normal Operation Mode” or
“Maintenance Mode”. The following API function is available:
This function sets the next phase configuration table. This next phase table will be
loaded and executed at the end of the current phase table. The return value indicates
the success of the phase table switching (see detailed description in µC/OS-MMU
Reference Manual).
The “Privileged User Application” can get timing information’s of the running phase scheduling at
any time. The following API functions are available:
This function returns the index of the currently running phase within the current phase
table (see detailed description in µC/OS-MMU Reference Manual).
This function returns the number of finished phase table cycles (see detailed description
in µC/OS-MMU Reference Manual).
This function returns the execution time of a single phase table cycle with a resolution of
1µs (see detailed description in µC/OS-MMU Reference Manual).
This function returns the time within the current phase table cycle with a resolution of 1µs
(see detailed description in µC/OS-MMU Reference Manual).
The “Privileged User Application” can adjust the timing of the active phase table. The following
API function is available:
For a valid phaseId, the corresponding phase time will be adjusted with the given time
shift value timeShift with a resolution of 1µs (see detailed description in µC/OS-MMU
Reference Manual).
The “Privileged User Application” or an interrupt service function can deliver events to the “User
Application”. In µC/OS-MMU context we call these event delivery functions “Virtual Interrupt
Functions”. The user application can implement and install virtual interrupt functions, which will
be triggered by the core software after detecting the specified event. The following API function
for this action is available:
This function triggers the interrupt with the given ID in the given partition or all partitions
(see detailed description in µC/OS-MMU Reference Manual).
Due to the fact, that µC/OS-MMU is an extension on top of µC/OS-II, the “Privileged User
Application” can use all µC/OS-II services like any traditional µC/OS-II application. Some
considerations must be taken into account when designing the privileged user application:
The µC/OS-MMU extension is implemented like a µC/OS-II application, too. Therefore some
resources and priorities must be shared without conflicts. See the µC/OS-MMU Config Manual
for details on the used resources and priorities.
The user application normally has no hardware access. On some processors hardware
components are accessed via memory mapped register sets. With a MMU or MPU unit, which
supports the needed granularity, these memory mapped register sets may be mapped into a user
application.
In general, the user application can not handle any interrupt service requests.
The “User Application” provides a static partition header as a data exchange interface (shared
memory) to the core software. The partition header must be located within the partition memory
area at a well known address (which is configurable in the core software). The partition header
contains the following information’s (see detailed description in µC/OS-MMU Config Manual):
An Interrupt Table
The service call mechanism is designed to allow the user application the execution of privileged
function under core software control. The service calls are implemented as a part of the core
software and presented to the partitions. The following API function is available:
This function requests the service call function, which is identified by the member
“ServiceIndex” in the parameter structure “scData”. If the requested service needs data
or returns data, the member “UserData” must be initialized to a corresponding variable
reference. The structure member “ErrCode” indicates the success of the service call (see
detailed description in µC/OS-MMU Reference Manual).
The user application can implement and install virtual interrupt functions, which will be triggered
by the core software after detecting a specified event. The following API functions are available:
This function initializes the interrupt tables with default values (all interrupts disabled).
This function is typically called during system startup (see detailed description in µC/OS-
MMU Reference Manual).
This function registers the given interrupt handler function for the given interrupt id (irq).
The priority prio is defined for future versions (see detailed description in µC/OS-MMU
Reference Manual).
This function enables the interrupt handler for to the given interrupt id irq (see detailed
description in µC/OS-MMU Reference Manual).
This function disables the interrupt handler for to the given interrupt id irq (see detailed
description in µC/OS-MMU Reference Manual).
The usage of a simple main() function is possible. For system behaviors with no fixed timing
behavior, the main() function may include an endless loop doing the needed actions.
Note: This endless loop is only executed in that phase times, which are linked to the
corresponding partition. The partition did not know, that the execution was interrupted for the
specified time.
Using a Guest-OS within the separated and protected environment is possible. The Guest-OS
port and adaptations for µC/OS-II are existing and delivered with the standard µC/OS-MMU
package.
The board support package must be initialized as soon as possible within the startup process.
Typically the first statement in function main(). The following API function is provided for this
action:
This function must be called at the very beginning of the startup phase. This function
calls all needed BSP{xxx}Init() functions in the correct order. These initialization
functions are described in the following chapters for completeness only. The user must
NOT call the individual BSP{xxx}Init() functions.
All other API calls are highly processor, board and customer specific. The documentation is
available on request.
4 Configuration
The configuration of µC/OS-MMU is typically done via constant, read only arrays of data with the
described content. The following subchapters explain the detailed configuration data.
The maximal number of phases within a phase table is predefined with a symbolic
constant. The system may use less than the maximum number of phases within one or
all phase tables (see detailed description in µC/OS-MMU Config Manual).
The single phase of a phase table is defined with a fix duration (in µs) and the pointer to
the related software component, e.g. core software or partition #1..#n. The phase table
holds a fix number of entries (see above) where the unused entries are filled with zero.
(see detailed description in µC/OS-MMU Config Manual).
The phase table pool holds multiple phase tables in arbitrary order. The activation of a
phase table is done with the index within this phase table pool (see detailed description
in µC/OS-MMU Config Manual).
Core Software
The core software is running in privileged mode and must have access to all needed
hardware components, the system register set and (at least read only access) to the
partition memory regions (see detailed description in µC/OS-MMU Config Manual).
Partitions
The partition is running in user mode and must have access to the partition memory
region. No other region is mandatory, but the partitions can optionally share memory
regions with system dependent access permissions (see detailed description in µC/OS-
MMU Config Manual).
The maximal number of service call functions is predefined with a symbolic constant
(see detailed description in µC/OS-MMU Config Manual).
PARSCInstall() shall be used to register an user defined service call function. This
function shall be called in the user function PARSCInitHoook() (see detailed description
in µC/OS-MMU Reference Manual).
The service call may be requested within the partition with the API function
PARServiceCall().
The interrupt service functions must be registered by the user application with the API
function PARIrqInstall() (see detailed description in µC/OS-MMU Reference Manual).
To start an interrupt service functions for event delivery, the user application must
enable the individual service functions with the API function PArIrqEnable() (see detailed
description in µC/OS-MMU Reference Manual). Then the core software can trigger the
interrupt service function with the API function PARIrqTrigger().
5 Hook Functions
The µC/OS-MMU extension supports several hook functions, which can be used to adapt the
product to the system needs.
This hook function is called once before the system initialization will initialize the MMU.
This hook function is called after the system initialization has initialized the MMU.
This hook function is called once at the end of the initialization of the partitions and
before the OS time tick will start. This allows the user to perform other operations, e.g.
creating additional Core OS tasks, before the partition scheduler will start.
This hook function is called once after the Core OS is stopped. PARShutDownHook()
allows the user to handle additional shutdown actions.
This hook function is called once during the startup phase, before the first running phase
configuration will be initialized. The return value of this function must be the index within
the phase table pool for the startup phase table.
This hook function is called once at the start of the partition phase scheduler task.
allows the user to implement functionality with the cycle time of the active phase table.
This hook function is called before the partition of the next phase table entry will be
activated. The parameter “nextPhase” indicates the ID of the phase, which will be
started. The parameter “nextParID” indicates the ID of the partition, which will be started.
This hook function is called after the current phase time is elapsed, before the partition
of the elapsed phase will be suspended. The parameter “elapsedPhase” indicates the ID
of the phase, which will be stopped. The parameter “elapsedParID” indicates the ID of
the partition, which will be stopped.
This hook function is called from the service call function when a guest partition requests
to suspend itself. The parameter “curPhase” indicates the ID of the current phase, which
gives runtime away. The “userData” contains the pointer to the application user data
passed from the partition.
This hook function is called after all internal service calls are installed. PARSCInitHook()
allows the user to install own service call functions.
References
µC/OS-II, The Real-Time Kernel, 2nd Edition
Jean J. Labrosse
R&D Technical Books, 2002
ISBN 1-57820-103-9
Contact
Micriµm Embedded Office
949 Crestview Circle August-Braun-Straße 1
Weston, FL 33327 88239 Wangen
USA Germany
954-217-2036 +49 7522 970 008 0
954-217-2037 (FAX) +49 7522 970 008 99 (FAX)
e-mail: sales@micrium.com e-mail: info@embedded-office.de
WEB: www.micrium.com WEB: www.embedded-office.de