RKH
Installation

Table of Contents

Prev: Home
Next: Porting

The RKH project is organized through a hierarchical directory structure to facilitate its distribution, support and maintenance. This structure also includes application examples and demos on several platforms. The following annotated directory tree lists the most important directories and files provided in the standard RKH distribution. The explanation section immediately following the directory tree explains the structure in more detail.

<RKH-root> - RKH-root directory
|-- demo - Demostrative and example applications
|-- doc - Documentation
|-- source - Source and test code files of RKH
|-- template - Templates for source code files
|-- third-party - Third-party software components
|-- tools - Used tools
|-- copying.txt - Licence file
\-- README - Change log file

Figure 1 Top level directories


This section includes:

RKH source files

The following figure shows the upper level of /source directory. Every module has been structured to be testable and maintainable, using /inc, /src, and /test directories. Every implementation file of any module have its own test cases, which are included in corresponding directory within /test.

<RKH-root> - RKH-root directory
|-- demo - Demostrative and example applications
|-- doc - Documentation
|-- source - Source and test code files of RKH
| |-- fwk - Miscellaneous module
| |-- queue - Fixed-size memory block module
| |-- sm - State machine module
| |-- sma - Active object module
| |-- tmr - Software timer module
| \-- trc - Runtime tracing module
| |-- inc - Contains specification files of module
| | |-- rkhtrc_define.h - Internal defines specification
| | |-- rkhtrc_filter.h - Runtime trace filter specification
| | |-- rkhtrc.h - Trace session specification
| | |-- rkhtrc_out.h - Trace output specification
| | |-- rkhtrc_record.h - Trace record specification
| | \-- rkhtrc_stream.h - Trace stream specification
| |-- src - Contains implementation files of module
| | |-- rkhtrc_filter.c - Runtime trace filter
| | |-- rkhtrc_record.c - Trace record
| | \-- rkhtrc_stream.c - Trace stream
| \-- test - Contains unit test files of module
| |-- build -¨Project builder
| |-- filter - Unit test for rkhtrc_filter.c file
| | |-- inc - Specification files of test cases
| | |-- runner - Run the test cases
| | |-- src - Implementation of test cases
| | \-- stub - Test-doubles
| |-- record - Unit test for rkhtrc_record.c file
| \-- stream - Unit test for rkhtrc_stream.c file
|-- template - Templates for source code files
|-- third-party - Third-party software components
|-- tools - Used tools
|-- copying.txt - Licence file
\-- README - Change log file

Figure 2 RKH source directory

RKH portable directory

All software components of the RKH, contain a platform abstraction layer. It is an indirection layer that hides the differences in hardware and software environments in which RKH operates, so that the RKH source code does not need to be changed to run in a different environment. Instead, all the changes required to adapt RKH are confined to this layer. It's basically composed by a few files, rkhplat.h and rkhtype.h, which include references to the actual platform-dependent files like rkhport.h and rkht.h. The platform-specific code for the RKH port is defined by rkhport.c. Not all RKH ports require this file.

As said above, each platform, compiler or processor supported by RKH must have its own platform-dependent file, called rkhport.h by RKH convention. Next, each rkhport.h file must be referenced from rkhplat.h header file, located in source/fwk/inc directory. The next listing shows an example of rkhplat.h, where "__CFV1CW63__", and "__W32STVC08__" are used to instruct the C/C++ compiler to include header files from the specific RKH port directory, which must be created if not exists. The key point of the design is that all platform-independent RKH source files includes the same rkhplat.h header file as the application source files.

#ifdef __CFV1CW63__
#include "..\..\portable\cfv1\rkhs\cw6_3\rkhport.h"
#endif
#ifdef __W32STVC08__
#include "..\..\portable\80x86\win32_st\vc08\rkhport.h"
#endif
..

The idea behind conditional compilation is that a rkhport.h can be electively compiled, depending upon whether a specific value has been efined.

Note
The path of platform-dependent file must be relative.

The RKH uses a set of integer quantities. That maybe machine or compiler dependent. These types must be defined in rkht.h file.
Each rkht.h file must be referenced from rkhtype.h header file, located in source/fwk/inc directory. The next listing shows an example of rkhtype.h, where "__CFV1CW63__", and "__W32STVC08__" are used to instruct the C/C++ compiler to include header files from the specific RKH port directory. The key point of the design is that all platform-independent RKH source files include the same rkhtype.h header file as the application source files.

#ifdef __CFV1CW63__
#include "..\..\portable\cfv1\rkhs\cw6_3\rkht.h"
#endif
#ifdef __W32STVC08__
#include "..\..\portable\80x86\win32_st\vc08\rkht.h"
#endif
...

The idea behind conditional compilation is that a rkht.h can be selectively compiled, depending upon whether a specific value has been defined.

Note
The path of platform-dependent file must be relative.

See the Porting section for more information. The following figure shows the source/portable/ directory.

<RKH-root> - RKH-root directory
|-- demo - Demostrative and example applications
|-- doc - Documentation
|-- source - Source and test code files of RKH
| |-- fwk
| |-- mempool
( 1)| |-- portable - Platform-specific RKH ports
( 2)| | |-- 80x86 - Ports to the 80x86 processor
| | | |-- linux_st - Ports to Linux with scheduler emulation
| | | | \-- gnu - Ports with the GNU compiler
| | | | |-- rkhport.c - RKH port to Linux source file
| | | | |-- rkhport.h - RKH platform-dependent include file
| | | | \-- rkht.h - RKH platform-dependent include file
| | | |-- win32_mt - Ports to Win32 multithreding
| | | | \-- vc - Ports with the Visual Studio C++ IDE
( 3)| | | \-- win32_st - Ports to Win32 with scheduler emulation
( 4)| | | \-- vc - Ports with the Visual Studio C++ IDE
( 5)| | | |-- rkhport.c
( 6)| | | |-- rkhport.h
( 7)| | | \-- rkht.h
| | |-- arm-cortex - Ports to the ARM Cortex processor
| | | |-- ksdk_os - Ports to OS abstraction layer of KSDK
| | | | \-- ucosiii - Ports to uCOS-III RTOS
| | | | \-- kds - Ports with KDS IDE
| | | \-- rkhs - Ports to the native cooperative scheduler
| | | |-- arm_cm0 - Ports to the ARM Cortex-M0 processor
| | | | \-- cw_v10 - Ports with the Codewarrior v10 compiler
| | | |-- arm_cm3 - Ports to the ARM Cortex-M3 processor
| | | | \-- codered - Ports with the code_red IDE
| | | |-- arm_cm4f - Ports to the ARM Cortex-M4 processor
| | | | \-- cw_v10 - Ports with the Codewarrior v10 compiler
| | | \-- ksdk
| | | \-- kds
( 8)| | |-- cfv1 - Ports to the Coldfire V1 processor
( 9)| | | \-- rkhs - Ports to the native cooperative scheduler
(10)| | | \-- cw6_3 - Ports with the Codewarrior v6.3 compiler
(11)| | | |-- rkhport.c
(12)| | | |-- rkhport.h
(13)| | | \-- rkht.h
| | |-- s08 - Ports to the S08 processor
| | | \-- rkhs - Ports to the native cooperative scheduler
| | | \-- cw6_3 - Ports with the Codewarrior v6.3 compiler
| | |-- test - Only used for unit test
| | \-- ucos - Ports to uCOS-III RTOS version 3
| | \-- v3.03.01
| |-- queue
| |-- sm
| |-- sma
| |-- tmr
| \-- trc
|-- template
|-- third-party
|-- tools
|-- copying.txt
\-- README

Figure 3 RKH portable directory

  • ( 1) Platform-specific RKH ports. The directory source/portable/ contains platform-dependent files to be used by RKH applications. This directory structure is the most complicated because of the large number of choices available, such as CPU architectures, compilers, operating systems, and compiler options. Each of those choices is represented as a separate level of nesting in a hierarchical directory tree, so that each dimension in the multi-dimensional space of options can be extended independently from the others. Also, the directory branch for each port is individually customizable, so each branch can represent only choices relevant for a given CPU, operating system, compiler, etc.
  • ( 2) Ports to the 80x86 processor. The CPU architecture is placed as the first level of nesting within the source/portable/ directory. Examples of CPU architectures could be: 80x86, Coldfire, S08, ARM Cortex, ARM Thumb, MSP430, etc. Please note that a separate directory is needed whenever the CPU architecture is significantly different.
  • ( 3) Ports to Win32 with scheduler emulation. The second level of nesting, under the CPU architecture, is the operating system used.
  • ( 4) Ports with the Visual Studio C++ compiler. The next level of nesting, under each operating system directory, is the directory for the compiler used.
  • ( 5) RKH platform-dependent source file. The platform-specific source file is optional and many ports don't require it.
  • ( 6) RKH platform-dependent include file. Frequently, defines the interrupt locking method, the critical section management, among other things. The key point of the design is that all platform-independent RKH source files include the same rkhplat.h header file as the application source files.
  • ( 7) RKH platform-dependent include file. In this file is defined the data types that uses RKH. The key point of the design is that all platform-independent RKH source files include the same rkhtype.h header file as the application source files.
  • ( 8) Ports to the Coldfire V1 processor
  • ( 9) using the native simple cooperative scheduler
  • (10) with the Codewarrior v6.3 compiler
  • (11-13) Idem (5-7)

RKH demo applications

The demo/ directory contains the application examples that are included in the standard RKH distribution. The structure of the demo/ is the most complicated because of the large number of choices available, such as CPU architectures, compilers, operating systems, and compiler options. Each of those choices is represented as a separate level of nesting in a hierarchical directory tree, so that each dimension in the multi-dimensional space of options can be extended independently from the others. Also, the directory branch for each RKH port is individually customizable, so each branch can represent only choices relevant for a given CPU, operating system, compiler, etc.

Each RKH application must have its own configuration file, called rkhcfg.h. This file adapts and configures RKH by means of compiler definitions and macros allowing to restrict the resources consumed by RKH. Adjusting this definitions allows to reduce the ROM and RAM consumption, and to enhance the system performance in a substantial manner.

<RKH-root> - RKH-root directory
( 1)|-- demo - Demostrative and example applications
( 2)| |-- 80x86 - Demos for the x86 processor
( 5)| | |-- ahsm - Abstract State Machine example
( 7)| | | |-- build - IDE/Compiler dependent files
| | | | |-- linux_st - Linux with scheduler emulation
| | | | | \-- Makefile - GNU toolchain project
( 3)| | | | \-- win32_st - Win32 with scheduler emulation
( 4)| | | | \-- vc - Visual Studio project
| | | |-- bsp.h - Contains the BSP specification
| | | |-- main.c - Contains the main() function along with an example for using the RKH trace facility
| | | |-- my.c - Implements the 'my' state machine, which illustrates all aspects of implementing state machines with RKH framework
| | | |-- my.h - Contains the declaration of active object, signals, and other facilities shared among the components of the application
| | | \-- rkhcfg.h - Adapts and configures RKH
( 6)| | \-- subm - Submachine example
( 9)| |-- cross - Cross-platform examples
| | |-- blinky - Blinky example
| | | |-- build - Platform (IDE/Compiler/OS/Processor) dependent files
| | | | |-- 80x86 - For x86 processor
| | | | | |-- linux_st - Linux with scheduler emulation
| | | | | \-- win32_st - Win32 with scheduler emulation
| | | | |-- arm-cortex - For ARM Cortex processors
| | | | | \-- rkhs - For the native scheduler
| | | | | |-- arm_cm0 - For ARM Cortex-M0 processor
| | | | | | \-- frdm-kl25z - For Freedom board frdm-kl25z
| | | | | | \-- cw_v10 - For IDE Codewarrior v10
| | | | | |-- arm_cm3 - For ARM Cortex-M3 processor
| | | | | | \-- lpcx-1769 - For specific lpcx-1769 processor
| | | | | | \-- lpcxpresso - For IDE Codewarrior v10
| | | | | \-- arm_cm4f - For ARM Cortex-M4 processor
| | | | | |-- frdm-k64f - For Freedom board frdm-k64f
| | | | | \-- twr_k60 - For Tower board K60
| | | | |-- cfv1 - For Coldfire V1 processors
| | | | \-- s08 - For S08 (8-bits) processors
| | | |-- blinky.c - The Blinky active object implementation
| | | |-- blinky.h - The Blinky active object specification
| | | |-- bsp.h - Contains the BSP specification
| | | |-- main.c - Contains the main() function along with an example for using the RKH trace facility
( 8)| | | \-- rkhcfg.h - Adapts and configures RKH
| | \-- shared - Shared example
| | |-- build - Platform (IDE/Compiler/OS/Processor) dependent files
| | | |-- 80x86 - For x86 processor
| | | | |-- win32_mt - Win32 multithread
| | | | \-- win32_st - Win32 with scheduler emulation
| | | \-- arm-cortex - For ARM Cortex processors
| | | |-- ksdk_os - For OS abstraction layer of KSDK with OS
| | | | \-- ucosiii - For uCOS-III RTOS
| | | | \-- frdm-k64f - For Freedom board frdm-k64f
| | | | \-- kds - For IDE KDS
| | | \-- rkhs - For the native cooperative scheduler
| | | \-- ksdk_bm - For OS abstraction layer of KSDK bare-metal
| | | \-- frdmk64f - For Freedom board frdm-k64f
| | | \-- kds - For IDE KDS
| | |-- bsp.h - Contains the BSP specification
| | |-- client.c - The Client active object implementation
| | |-- client.h - The Client active object specification
| | |-- main.c - Contains the main() function along with an example for using the RKH trace facility
| | |-- rkhcfg.h - Adapts and configures RKH
| | |-- server.c - The Server active object implementation
| | |-- server.h - The Server active object specification
| | \-- shared.h
| \-- libbsp - BSP library for several platforms
| |-- common
| \-- platform
| |-- 80x86
| | |-- linux
| | \-- win
| |-- arm-cortex
| | |-- arm_cm0
| | | \-- frdm-kl25z
| | |-- arm_cm3
| | | \-- lpc17xx
| | \-- arm_cm4f
| | |-- frdm-k64f
| | \-- twr_k60
| |-- cfv1
| | \-- DEMOQUE128
| \-- s08
| \-- DEMOQE128
|-- doc
|-- source
|-- template
|-- third-party
|-- tools
|-- copying.txt
\-- README

Figure 4 Demo application directories

  • ( 1) RKH demo applications. The demo/ directory contains the application examples that are included in the standard RKH distribution. The structure of the demo/ is the most complicated because of the large number of choices available, such as CPU architectures, compilers, operating systems, and compiler options. Each of those choices is represented as a separate level of nesting in a hierarchical directory tree, so that each dimension in the multi-dimensional space of options can be extended independently from the others. Also, the directory branch for each RKH port is individually customizable, so each branch can represent only choices relevant for a given CPU, operating system, compiler, etc.
  • ( 2) Demos for the x86 processor. The CPU architecture is placed as the first level of nesting within the demo/ directory. Examples of CPU architectures could be: 80x86, Coldfire, S08, ARM Cortex, ARM, MSP430, etc. Please note that a separate directory is needed whenever the CPU architecture is significantly different.
  • ( 3) Demos for Windows with scheduler emulation. The second level of nesting, under the CPU architecture, is the operating system used.
  • ( 4) Demos for Visual Studio C++. The next level of nesting, under each operating system directory, is the directory for the compiler used.
  • ( 5-6) Finally, the example application is located in its own directory. In this case, abstract hierarchical state machine example. This application is very useful to learn and explore the Statechart and UML features.
  • ( 7) The ahsm/build/ subdirectory contains the IDE-dependent files, like object files, executable, and among others.
  • ( 8) As mentioned above, each of application that use RKH must be defined its own configuration file, rkhcfg.h.
  • ( 9) This directory provides several examples on how to use RKH, designed to experiment with RKH immediately. The simplicity of the code and state diagrams means it also serves as a good starter project for people who are not yet familiar with RKH. Also, this examples are demostration projects considered cross-platform, because of they are able to function on more than one computer architecture or operating system. The code of demos are located in the <rkh>/demo/cross/ directory, where <rkh> stands for the installation directory chosed to install the accompanying software. Each example contains the platform-independent source code and a
    .. build/ directory. The structure of the .. build/ branch closely mirrors the structure of the source/portable/ directory, which contains platform-specific header files and libraries to be used by RKH applications.

Prev: Home
Next: Porting