Porting Ioto
While porting Ioto is not too difficult, porting any software is not for the novice. It requires skill to read another person's code and adapt it to a new environment. These instructions are intended for experienced developers who want to port Ioto to a new operating system or processor architecture.
Overview
Ioto has been written to maximize the ease of porting to a new environment. The O/S and processor-dependent code have been contained while the bulk of the code is cross-platform. Most of this dependent code is in the src/rLib.c file which represents the Safe Runtime (R).
Steps in Porting to a New System
Pick a Name for the O/S
If you are doing a port for a new operating system, you need to pick a symbolic name that will be used in conditional compilation, Makefiles, MakeMe files, and operating system specific directories. Some existing O/S names are: "linux", "windows", "freebsd", "freertos", "macosx" and "vxworks".
These names are used as upper-case pre-processor defines and in some cases as lower-case directory names.
Select the base O/S to emulate
The easiest way to port to a new O/S is to find the closest existing supported O/S that the Ioto software already supports and use it as a base to modify. For example, if you are porting to QNX, you may want to use the Linux port as a base.
Create the Makefile
Create the Makefile by copying the makefile for the similar O/S. i.e. in our example, Copy the projects/ioto-linux-default.mk Makefile to projects/ioto-qnx-default.mk. Then edit the appropriate compiler and linker switches.
1 2 | |
Tailor the cross-platform O/S header.
To insulate most of the Ioto source code from the differences of various operating systems, the include/osdep.h header file wraps all the required O/S headers and publishes a consistent set of types and prototypes. None of the source files include normal O/S headers like
When porting the osdep.h, start by copying the sections in osdep.h that pertain to your base copied O/S. These will be protected by "#if BASEOS" defines. In the example of QNX, we would look for, and copy, any sections with "#if LINUX" and create "#if QNX" sections.
DO NOT introduce conditional code in other O/S sections. It is better to copy the entire contents from the base O/S and modify. It is better to isolate the code for each O/S.
Test the Headers with a Hello World Program.
Don't use the make system yet. Just create an empty C hello world program and include "osdep.h". Compile it and shake out the issues.
Port the Fiber Context Module
Ioto uses fiber coroutines that swap stacks to provide overlapped I/O and compute. Fibers solve the main problem with multi-threaded programming where multiple threads access the same data at the same time and require complex locking to safeguard data integrity. Fibers solve this problem by enabling a procedural straight line coding style.
The existing fiber code supports the CPU architectures: arm, arm64, itanium, mips, mips64, ppc, ppc64, riscv, riscv64, sparc, tidsp, sh, x86, x64 and xtensa.
Other architectures are supported by emulating fibers over posix pthreads.
The fiber header uctx-os.h detects your CPU architecture by a set of conditional compilation tests and enables the appropriate CPU or PTHREAD fiber management code.
Port the Safe Runtime Source Code
The Safe Portable Runtime (R) wraps the operating system services and exposes a portable, consistent interface for Ioto to utilize. So now is the time for the real work. You will need to modify the lib/rLib.c file to support your new platform.
In rLib.c, you will see banners marking where the various sub-files have been catenated together. The main sections to modify will be socket.c, thread.c time.c and wait.c. Search for conditional code sections for your base O/S and copy/modify as appropriate.
Test Compile the rLib
To start out, test compile just the R library.
1 | |
At this stage of the porting effort, the make command will undoubtedly provoke a stream of errors. Use this to work out the bugs in r.h and rLib.c for your O/S.
Compile the Rest
After the R library, it is more downhill. The rest of the code under ./lib should compile and build more easily. It is quite cross-platform.
1 | |
After building the library, you can port the cmds/main.c which is the default Ioto main program.
Test Ioto
1 | |
Working with the Ioto Development Team
Once you have a basic port running, you should send it back for the team to look over. They can provide advice and suggestions.
If you wish, you can contribute your changes back to EmbedThis to be merged back into the core Ioto code. This will make your task of assimilating new releases much easier. Contributed code must be provided under an MIT license.
Good luck and have fun. Please give feedback to the development team at dev@embedthis.com.