TIPC Porting Guide

04 December 2007 [software version: TIPC 1.7.5]


Table of Contents

Step 0: Getting up to speed
Step 1: Preparing your development environment
Step 2: Adding support for essential TIPC capabilities
Step 3: Adding support for TIPC sockets
Step 4: Adding support for TIPC configuration
Step 5: Adding support for TIPC inter-node links
Step 6: Finishing up

Introduction

This document outlines the steps involved in porting TIPC to a new operating system. It also indicates how the existing Linux and VxWorks versions of TIPC can be utilized to make the job easier.

Step 0: Getting up to speed

It's probably a good idea to play around with an existing version of TIPC before beginning work on porting it to a new operating system.

  1. Read the TIPC Programmers Guide (available at http://tipc.sourceforge.net/documentation.html).

  2. Read the TIPC 1.7 User's Guide (available at the same location).

  3. Install TIPC on a single node, then run the TIPC demos or test suite to verify that it is functioning properly.

  4. Install TIPC on additional machines to create a multi-node network, and rerun the demos or tests.

Following completion of this step, you will have a good idea how TIPC should work once your porting is done.

Step 1: Preparing your development environment

Identify what OS you are going to use. Install the OS in your development environment, and ensure you have the appropriate compilers and build environment working. Get your OS built and running.

Following completion of this step, you should be able to build and run your OS without TIPC.

Step 2: Adding support for essential TIPC capabilities

Now the real work begins!

  1. Identify what TIPC code base you are going to use.

    It is recommended that TIPC 1.7.5 (or the latest stable version of TIPC) be used for any porting exercise. Code for the Linux TIPC 1.7.5 is available from the TIPC project website (http://tipc.sourceforge.net). Code for VxWorks TIPC 1.7.5 will be posted soon; in the meantime, a tarball can be obtained from Elmer Horvath (elmer.horvath@windriver.com).

  2. Copy the TIPC files into your development environment.

    In the Linux version of TIPC (the standard reference model, from which all others are derived), there are 3 main locations for TIPC files in the kernel source tree:

    include/linux/

    This directory contains .h files that can be used by user-space TIPC applications, kernel-space TIPC applications, and by TIPC itself.

    include/net/tipc/

    This directory contains .h files that can be used by kernel-space TIPC applications and by TIPC itself.

    net/tipc/

    This directory contains .h and .c files that are used only by TIPC itself.

    In addition to the TIPC kernel files, you will also need the user-space TIPC application, tipc-config. It consists of a single file (tipc-config.c), plus its own makefile.

    Place these TIPC files in appropriate locations in your operating system; you may need more than 3 or fewer than 3 directories for this. Caveat: If you do combine files from different directories you may need to deal with the fact that there are two files called "tipc.h" (i.e. include/linux/tipc.h and include/net/tipc/tipc.h); fortunately, all other TIPC files names are unique.

  3. Try building the TIPC common files.

    At a minimum, you are probably going to have to modify the following files:

    include/linux/tipc.h ,
    include/linux/tipc_config.h ,
    include/net/tipc/tipc.h ,
    include/net/tipc/tipc_plugin_if.h ,
    include/net/tipc/tipc_plugin_msg.h ,
    include/net/tipc/tipc_plugin_port.h

    The main change required here is the replacement of the various Linux-specific #include directives with their corresponding equivalents in your operating system.

    net/tipc/Makefile ,
    net/tipc/KConfig

    These files will need to be modified, replaced, or supplemented with other code to allow your operating system to build TIPC.

    net/tipc/tipc_core.h

    This file must be modified to declare any Linux APIs that are not present in your operating system; the main areas involve the implentation of spinlocks, timers and signals, and socket buffers (which are discussed below). In some cases you may be able to define an API as an inline routine; in other cases you can just declare the function prototype and defer the implementation until later. The VxWorks version of this file can provide valuable guidance here.

  4. Implement equivalents for the Linux sk_buff APIs used by TIPC.

    The VxWorks version of TIPC provides an example of how to write wrapper routines to provide an sk_buff-type API for a non-Linux network buffer. You can put the definitions of any non-inlined sk_buff routines in net/tipc/tipc_core.c or use a separate .c file.

  5. Implement equivalents for the Linux spinlock and atomic operation APIs used by TIPC to provide single-threading during the manipulation of certain data structures.

    Note that you do not actually have to use true spinlocks and atomic operations here; for example, the VxWorks version of TIPC implements these APIs using task-level semaphores. Also note that you also have the option of consolidating the various mutual exclusion mechanisms into a single mutex (i.e. only implement a single global lock for all of TIPC); this can have the benefit of reducing TIPC's memory requirements and simplifying your adaptation code, but may impact performance by forcing TIPC to run in a single-threaded manner more often than necessary. As before, you can put the definitions of any non-inlined spinlock/atomic routines in net/tipc/tipc_core.c or use a separate .c file.

  6. Implement the code that allows TIPC to defer work to a different thread of control, either through the use of timers or signals.

    This code is typically implemented using simple wrappers in net/tipc/tipc_core.h, in conjunction with non-inlined routines in net/tipc/tipc_handler.c. The Linux version of TIPC is able to use operating system timers directly, so there is no timer code present in the .c file; the VxWorks version of TIPC maintains its own set of timer data structures, and utilizes a task to run the specified routine when a timer expires. A "signal" (not to be confused with a Unix-type signal sent to a process) is a routine that TIPC schedules for immediate execution in a context other than the one that is currently executing. The Linux version of TIPC maintains a queue of pending signals and executes them in a tasklet; thus it is possible for timer routines and signal routines to execute concurrently. The VxWorks version of TIPC implements signals as timers that have a timeout of zero; thus timer and signal routines never run at the same time.

  7. Disable the code that allows TIPC to use Linux's Netlink configuration mechanism (i.e. the code in net/tipc/tipc_netlink.c).

    This code isn't needed until Step 4, and can even be omitted entirely (as it is in the VxWorks version of TIPC).

  8. Finish updating net/tipc/tipc_core.c to allow your operating system to initialize TIPC.

Following completion of this step, you should be able to bring up TIPC without it crashing. (It won't do anything useful at this point since your won't be able to run any TIPC applications, so it will be hard to tell if you've actually got everything working properly. Still, not crashing is a good start ...)

Ordering of Remaining Steps

Depending on your preferences, you may want to skip to Step 5 before doing Steps 3 and 4. Getting TIPC's links to come up will demonstrate that you've got your basic sk_buff, spinlock/atomic, and timer/signal code working properly. You will have to hack things a bit to get TIPC to configure a bearer without using tipc-config.

Step 3: Adding support for TIPC sockets

Modify net/tipc/tipc_socket.c to provide support for AF_TIPC sockets in your operating system. You may also have to update some non-TIPC files in your operating system (for example, to define the AF_TIPC symbol). In the VxWorks case, it was also necessary to create some additional TIPC files to tie the tipc_socket.c code to the socket infrastructure of the operating system.

Following completion of this step, you should be able to run TIPC applications on a single node. The portable TIPC test suite (PTTS) can be used to help verify things are working properly.

Step 4: Adding support for TIPC configuration

Modify tipc-config.c to allow users to dynamically monitor and re-configure TIPC. In the VxWorks case, support for Linux's Netlink interface was omitted; this means that requests sent to TIPC's configuration service by the tipc-config application are always sent via TIPC sockets, even when they are issued to the same node that is running tipc-config.

Following completion of this step, you should be able to display the contents of the TIPC name table, and do similar management-type operations.

Step 5: Adding support for TIPC inter-node links

Modify net/tipc/tipc_eth_media.c to allow it to interact with Ethernet device drivers on your operating system. (This assumes that actually you want to TIPC to run over Ethernet, as most users do; if not, you can leave this file out and remove the code that initializes the Ethernet media type in tipc_core.c.)

If you want to support a new media type you will need to create your own media file (although tipc_eth_media.c may still be a good starting point); you will also need to modify tipc_core.c to ensure that the media type is properly initialized when TIPC starts up. The VxWorks version of TIPC contains a couple of bearers that have been added to support new shared memory-based media types; see the files tipc_sm_media.c and tipc_dshm_media.c.

Caveat: The media used by TIPC must have a broadcast capability, otherwise TIPC's automatic link setup mechanism will not work; if this is not present in your media you will have to get your media to simulate the broadcast capability.

Following completion of this step, you should be able to configure one or more TIPC bearers (i.e. interfaces) so that TIPC will establish links between network nodes. Again, the PTTS can be used to verify that TIPC is operating correctly.

Step 6: Finishing up

Your porting of TIPC is now complete. Congratulations!

If possible, please contribute your code to the TIPC project website (at http://tipc.sf.net) so that others can help test and enjoy your handiwork.