RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Installation
rkh_bunner.jpg

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 - RKH demo applications
+-doc - RKH documentation
\-source - RKH source files
| copying.txt - licence file
| README - change log file
| rkh.chm - reference manual

Figure 1 Top level directories


This section includes:


RKH source files

The following figure shows the \source directory.

<RKH-root> - RKH-root directory
|
+-demo - Demo applications
+-doc - Documentation
\-source - RKH source code files
| +-include - Contains platform-independent header files
| | rkh.h - Framework interface
| | rkhassert.h - Assert definitions
| | rkhevt.h - Event data type and other related macros
| | rkhitl.h - Internal use only
| | rkhmp.h - Fixed-size memory block services interface
| | rkhplat.h - Supported and portable platforms
| | rkhrdy.h - Native priority management
| | rkhrq.h - Queue services interface
| | rkhs.h - Simple and cooperative scheduler interface
| | rkhtim.h - Timer services interface
| | rkhtrc.h - Trace facility
| | rkhtype.h - Defines the data types that uses RKH
| |
| \-portable - Contains platform-dependent files
| |
| | rkh.c - State machine engine
| | rkhdyn.c - Dynamic event management, and event framework services
| | rkhmp.c - Fixed-size memory block
| | rkhrq.c - Queue (copy by reference)
| | rkhs.c - Simple and cooperative scheduler
| | rkhsma.c - State machine application (SMA) registration.
| | rkhtbl.c - Binary map tables.
| | rkhtim.c - Software timer.
| | rkhtrc.c - Platform-independent source code of runtime tracing.
|
| copying.txt - Licence file
| README - Change log file
| rkh.chm - Reference manual

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 \include directory. The next listing shows an example of rkhplat.h, where CFV1CW63, and W32STVC08 are used to nstruct the C/C++ compiler to include header files from the specific KH port directory. The key point of the design is that all latform-independent RKH source files include the same rkhplat.h eader 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. The following listing shows the required data type definitions:

// Denotes a signed integer type with a width of exactly 8 bits
typedef signed char ri8_t;
// Denotes a signed integer type with a width of exactly 16 bits
typedef signed short ri16_t;
// Denotes a signed integer type with a width of exactly 32 bits
typedef signed long ri32_t;
// Denotes an unsigned integer type with a width of exactly 8 bits
typedef unsigned char rui8_t;
// Denotes an unsigned integer type with a width of exactly 16 bits
typedef unsigned short rui16_t;
// Denotes an unsigned integer type with a width of exactly 32 bits
typedef unsigned long rui32_t;
// Denotes an unsigned integer type that is usually fastest to operate with
// among all integer types.
typedef unsigned int ruint;
// Denotes a signed integer type that is usually fastest to operate with
// among all integer types.
typedef signed int rint;
// Denotes a boolean type.
// The true (RKH_TRUE) and false (RKH_FALSE) values as defined as macro
// definitions in \c rkhdef.h file.
typedef unsigned int rbool_t;

Next, each rkht.h file must be referenced from rkhtype.h header file, located in \include 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 \portable directory.

<RKH-root>
|
+-demo
+-doc
\-source
| +-include - RKH platform-independent header files
( 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
| | | | |
( 3) | | | | \-win32_st - Ports to Win32 with scheduler emulation
( 4) | | | | \-vc08 - Ports with the Visual Studio C++ compiler
( 5) | | | | rkhport.c
( 6) | | | | rkhport.h
( 7) | | | | rkht.h
| | | |
| | +-arm-cortex - Ports to the ARM Cortex processor
| | | \-rkhs - Ports to the native cooperative scheduler
| | | +-arm_cm3 - Ports to the ARM Cortex-M3 processor
| | | | \-codered - Ports with the code_red compiler
| | | | rkhport.c
| | | | rkhport.h
| | | | rkht.h
| | | |
| | | \-arm_cm4f - Ports to the ARM Cortex-M3 processor
| | | \-cw_v10 - Ports with the Codewarrior v10 compiler
| | | rkhport.c
| | | rkhport.h
| | | rkht.h
| | |
( 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
| | | rkhport.c
| | | rkhport.h
| | | rkht.h
| | +... - Ports to other CPUs
| | - RKH platform-independent source code
| | rkh.c
| | rkhdyn.c
| | ...
|
| copying.txt
| README
| rkh.chm

Figure 3 RKH portable directory

  • ( 1) Platform-specific RKH ports. The directory \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 \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>
|
( 1) +-demo - RKH demo applications
( 2) | +-80x86 - Demos for the x86 processor
| | +-linux_st - Demos for Linux with scheduler emulation
| | |
( 3) | | +-win32_st - Demos for Windows with scheduler emulation
( 4) | | | \-vc08 - Demos for Visual Studio C++
( 5) | | | +-ahsm - Abstract State Machine example for Windows
( 6) | | | \-subm - Submachine example for Windows
( 7) | | | \-prj - IDE-dependent files
| | |
| +-common - Common files
| \-cross - Cross-platform examples
| \-blinky - Blinky example
| | bky.c - the Blinky active object
| | bky.h - the Blinky header file
| | bkyact.c - the Blinky actions
| | bkyact.h - the Blinky actions header file
| | main.c - the \c main() function
( 8) | | rkhcfg.h - RKH configuration file for Blinky demo
| |
| \-platform - Platform-specific RKH BSP
| +-80x86 - Examples for the x86 processor
| | +-linux_st - Examples for Linux with scheduler emulation
| | | \-gnu
| | | bsp.c - BSP for the Blinky application
| | | bsp.h - BSP header file
| | | Makefile - external Makefile for GNU Tool
| | | tcptrc.c - BSP source code for Trazer
| | | tcptrc.h - BSP include file for Trazer
| | +-win32_st - Examples for Win32 with scheduler emulation
| | \-vc08
| | | bsp.c
| | | bsp.h
| | | tcptrc.c
| | | tcptrc.h
| | |
| | \-prj
| | | blinky.ncb
| | | blinky.sln
| | | blinky.vcproj
| | |
| | \---Debug
| +-arm-cortex - Examples for the ARM Cortex processor
| | \-rkhs - Examples for the native scheduler
| | +-arm_cm3
| | | \-lpcx
| | | \-codered
| | \-arm_cm4f
| | \-freedom
| | \-cw_v10
| +-...
+-doc
\-source
| copying.txt
| README
| rkh.chm

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\prj\ 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 .. \platform\ directory. The structure of the .. \platform\ 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