Before starting the port

This chapter describes what you need to do before starting the port.

OS knowledge and experience

Knowledge and experience with the target operating system is key to a successful port. This knowledge should extend to development environment and target hardware. The type of knowledge required includes such details as synchronization mechanisms, thread creation, memory management, timing, device drivers, board support packages, memory maps, TCP/IP support, priority and scheduling schemes, and so forth. See "OS capabilities" on page 25 for a list of OS capabilities required by the
TargetRTS.

Experience with porting the TargetRTS to other platforms will aid greatly as the ports tend to follow a pattern. For each development environment and operating system there are bound to be a few surprises. See "Common problems and pitfalls" on page 99.

Tool chain functionality

A functioning development environment must be in place before porting can begin. This includes the correct installation of tools such as linkers, compilers, assemblers and debuggers. To build the
TargetRTS you must have working version of Perl for your development host (version 5.002 or greater). Perl is used extensively in the makefiles for the TargetRTS.

It is also important to initialize environment variables for inclusion of header files and location of library files. An easy way to test this is the creation of simple program, such as "Hello World", which is compiled and run on the target. This step is described in "Simple non-ObjecTime program on target" on page 27.

OS capabilities

The target operating system must have a set of services that satisfy the requirements of the TargetRTS. In general, most commercial real-time operating systems (RTOS) have these services. Before starting a port, check for these basic capabilities in the target RTOS. Table 1 lists the TargetRTS feature and its corresponding RTOS service.

Required Operating System Services for C++

TargetRTS Feature	Operating System Service
RTSyncObject	Semaphore, mailbox, signal, condition variable — service must provide infinite and timed blocking.
RTTimespec::getclock	A function is required to return the current time. The more precision the better. In general, RTOS will return time with precision of its internal timer.
RTThread	Task creation function — must be able to create task or thread with specified stack size and priority. Be aware of priority scheme — some RTOS use 0 as highest priority while others may use 0 for lowest priority.
RTMutex	Semaphore, mutex, etc. — a mutual exclusion mechanism. Some RTOS provide optimized mutex service along with semaphores.
RTDiagStream (output to console)	Standard input and output — this may not be provided out-of-the-box. For embedded targets, device drivers added to the board support package may be required. Output is generally routed to external serial ports but TCP/IP or UDP/IP may be used instead.
RTDebuggerInput (input from console)	As above. This can be removed from the C++ TargetRTS via configuration options. For more information, see "Customizing the Target Services Library" on page 47 of the C++ Target Guide.
Target Observability & External Layer	TCP/IP support is required. This includes device drivers in the board support package for the ethernet hardware on the target. If not provided this is a substantial do-it-yourself project. This can be removed from the TargetRTS via configuration options. For more information, see "Customizing the Target Services Library" on page 47 of the C++ Target Guide.
new, delete	RTOS must support some sort of memory management. In general, this is hidden from the user by the compiler as the RTOS resolves the new and delete symbol.
main function	Some RTOS have their own main function defined. If so, then the main function in the TargetRTS must be redefined.

Required Operating System Services for a Multi-threaded C TargetRTS

TargetRTS Feature	Operating System Service
RSL_semaphore	Semaphore, condition variable — service must provide infinite and timed blocking.
RSL thr_create	Task creation function — must be able to create task or thread with specified stack size and priority. Be aware of priority scheme — some RTOS use 0 as highest priority while others may use 0 for lowest priority.
RSL_mutex	Semaphore, mutex, etc. — a mutual exclusion mechanism. Some RTOS provide optimized mutex service along with semaphores.
RSL_nextChar (input from console)	Standard character input. This can be removed from the C TargetRTS via configuration options.
Target Observability	TCP/IP support is required. This includes device drivers in the board support package for the ethernet hardware on the target. If not provided this is a substantial do-it-yourself project. This can be removed from the TargetRTS via configuration options.
malloc, free	RTOS should support some sort of memory management. If it is not supported, it may be possible to write your own.
main function	Some RTOS have their own main function defined. If so, then the main function in the TargetRTS must be redefined

Simple non-ObjecTime program on target

An easy way to test the tool chain functionality is to create a simple program that prints out "Hello World" on the console.

This program should not use any TargetRTS code or libraries. Compile, link, and download the program to the target. If it executes successfully, then your development environment is ready.

Further testing is strongly recommended. This would include some basic RTOS services such as thread creation in the program. Again, no TargetRTS code or libraries should be used. Many RTOS provide example programs to compile and run. Try these out and verify the functionality. If you are using a source-level debugger, verify that you can step through the source code and examine variables. If the debugger is aware of operating system data structures, then check to see if this functions. Another important test for C++ compilers is to include a static constructor in the test program. This will ensure that proper initialization is performed. The purpose of this testing to ensure that all of the required operating system features are operational and understood before attempting the port of the TargetRTS.

TCP/IP functionality

In order to support target observability for the new port, the target operating system must provide a compatible TCP/IP stack. In general, the TCP/IP layer must support BSD sockets interface, that is, the creation and deletion of sockets, functions such as open(), connect(), bind(), listen(), select(), and so forth. Typically, RTOSs try to provide a BSD-compliant TCP/IP stack. This is a common source of problems with new ports. See "Common problems and pitfalls" on page 99.

If a TCP/IP stack is not provided, then you must implement one, which requires significant effort. The lack of ethernet hardware may require the use of SLIP or PPP over a serial port, although this will severely affect the performance of target observability.

Floating point operations

Some of the C++ TargetRTS classes (for example, RTReal) require the use of floating point operations. Investigate the support for floating point on your target system. It is possible to configure the support for RTReal from the TargetRTS via configuration options. For more information, see "Customizing the Target Services Library" on page 47 of the C++ Target Guide.

Standard input/output functionality

The TargetRTS needs standard input and output to a console for log messages, panic messages, and debugger input/output. This may already be provided by the target development or operating system. Some embedded RTOS and development tools may not provide standard input and output. This requires the addition of serial port device drivers to the board support package. The use of TCP/IP or UDP/IP to provided standard input/output is also an option.

Debugging

The use of a source-level debugger that provides some sort of operating system awareness is the best development tool for the port. This is the easiest way to examine source code, memory, variables, registers, stacks, and so forth.

Training

Training is an important component of a successful port. ObjecTime offers training courses to help users understand, use, and port the TargetRTS. Your RTOS vendor may also offer training and this is recommended as well.

What to do before calling ObjecTime support

The following steps should be followed before calling ObjecTime support for help with a custom port of the TargetRTS.

1. Get to know your compiler/linker/debugger tool chain. Be sure it is installed correctly and programs can be compiled, linked, downloaded to the target hardware and run successfully.
2. Get to know your target operating system. Be sure that an example multithreaded program that exercises the various features of the RTOS is compiled, linked and downloaded to the target hardware and runs successfully. Do not use ObjecTime Developer for this example program. This should be produced independently to verify toolchain and RTOS functionality.
3. Read this guide and, if you are porting to a C++ target, the C++ Target Guide that is included with ObjecTime Developer to understand the required capabilities of the RTOS needed to support the
   TargetRTS.
4. Ensure that the TCP/IP stack for your target platform is operational. In particular the sockets interface must be working and additional utilities such as gethostbyname() and gethostbyaddr() must be functioning.
5. Test the functionality of the standard input and output for your target. This will probably be verified in earlier steps.
6. Learn how to use the target debugger. This will be a useful tool when doing the port.
7. Get as much training on ObjecTime Developer, the RTOS, and tool chain as possible.