How to create a new system call in the IOM

This tutorial is a step-by-step explanation of how to add a system call to the IOM module of ChorusOS 4.0 and 4.0.1 versions.

1. Getting Started

Product version:
This tutorial refers to ChorusOS 4.0 and 4.0.1. The tutorial is cross platform, but the source example and some of the pathnames used relate specifically to the UltraSPARC target delivery. In order to implement all of the steps described in the tutorial you also need to have the complete source version of ChorusOS, not only the source of the IOM.

Pre-Requisites:
You must have an understanding of kernel programming and, in particular, FreeBSD file system semantics.

Pathnames:
All pathnames in this tutorial are related to the default installation directory of the Sun Embedded Workshop 4.0.1 product:

/opt/SUNWconn/SEW/4.0.1/chorus-usparc/src

Since the patching mechanism depends on the ChorusOS source tree being untouched, always keep an untouched reference copy of the source tree of the product; otherwise you will not be able to apply any patches from Sun. Before you start following the example, make sure that you use a working copy of the whole product and not just a copy of the Build directory.

The following steps must be taken to add a system call to the IOM:

• Declare the new call
• Match the call interface to a new LAP entry point
• Define the new LAP call
• Declare the system call the array of module services
• Code the system call
• Reconfigure the OS and build a new archive

Back to Top

2. A Simple Example

This tutorial shows you how to add a new system call named getinode() to the IOM that returns the inode of a given file.

Note: The code for getinode() is simple, but since it is only here as an example, the code itself is not explained.

Contrary to the normal BSD convention of one big array of system calls, in ChorusOS 4.0 and 4.0.1, system calls are accessed through a two-level array structure with one array of system calls per module. Actors will invoke the IOM system calls using a LAP invocation mechanism. The IOM defines eleven modules:

Each of these modules in turn defines and exports a set of system calls. This is done in the file os/common/src/bsd/include/bsdSysCalls.h

In the next steps, the getinode() system call will be added to the calls of the FILEIO module. Therefore, you first need to add an entry for your new system call (IOM_GETINODE) and increase the number of system calls defined for the FILEIO module (IOM_FILEIO_NUMBER) by one:

[...]

#define IOM_FILEIO_NUMBER       39

[...]

Back to Top

3. The iomcalls Library

The iomcalls library provides actors with the IOM entry points for all regular BSD system calls (file, sockets, and so on).

You need to define the LAP entry point for your new call. This is first done in os/common/src/iom/lib/iomcalls.h where you match the userland interface of the call getinode() to the LAP as follows:

/*
 * Posix-FileIO
 */

[...]

Next, each LAP is declared in a special file in the same directory os/common/src/iom/lib/ following a set framework (or set of rules). And each of the LAPs already defined as part of the product have a similar file associated with them.

The argument of the system call must be copied into a default ScLapArg structure defined in os/common/src/include/cx/lapLibCall.h

To do this, create a file named iomgetinode.c that contains the following:

#include "iomcalls.h"

    LIBIOMINIT(long);
    SET_HEADER(IOM_GETINODE);

        arg.a1.a1p = path;

    INVOKE(&scIomLap);

    if (arg.header.error)
        return -1L;
    else
        return arg.header.result;
}
 
 

Finally, to complete this step you must instruct the compiler to add this new function to the IOM Direct Invocation Library. For that purpose, you need to add an entry for iomgetinode.c in os/common/src/iom/lib/common.mf

C__SRCS = \

Back to Top

4. Code the Actual System Call

Since you have chosen to add your system call to the FILEIO module of the IOM, you will place your code in directory iom/src/os/iom/sys/bsd/kern/vfs and, most important, update the array of functions defined for this module in iom/src/os/iom/sys/bsd/kern/vfs/vfs_syscalls.c.

/*

 * POSIX-FILEIO Module initialization
 */

[...]

In this same directory, create a file called get_inode.c and input the following lines of code:

#include <sys/param.h>
#include <sys/systm.h>
#include <sys/sysproto.h>
#include <sys/namei.h>
#include <sys/kernel.h>
#include <sys/vnode.h>
#include <sys/proc.h>
#include <sys/ucred.h>

Back to Top

5. Reconfigure the Build Directory, Compile and Rebuild the Archive

Finally, you need to add this file to the IOM binary by updating the file iom/src/os/iom/sys/bsd/kern/vfs/common.mf as follows:

##############################################################################
#
# Component = AFM BSD kernel code.
# Module = makeTarget
#
# Synopsis = specific makefile.
#
# Copyright 1994-2004 Sun Microsystems, Inc. All rights reserved.
#
#
##############################################################################
#
# #ident  "@(#)common.mf 1.6     99/10/10 SMI"
#
##############################################################################

C__SRCS = \

        vfs_bio.c \
        vfs_cache.c \
        vfs_init.c \
        vfs_lookup.c \
        vfs_subr.c \
        vfs_syscalls.c \
        vfs_vnops.c \
        kern_physio.c \
        get_inode.c

Then, with BUILD_DIR being set to point to the Chorus build directory, rebuild the iomcalls library and the N_iom.r binary (the IOM):

Once this is done, the iomcalls library is generated and you can recompile the IOM:

Finally, regenerate the chorus archive:

Back to Top

6. Testing getinode()

Once your UltraSPARC target has been rebooted with the new archive, you can test your new system call with a simple little actor such as this one:

/***** test_iom_call.c *****/

Here's a sample output from this test:

Back to Top

Appendix

List of modified files:

os/common/src/bsd/include/bsdSysCalls.h
os/common/src/iom/lib/iomcalls.h
os/common/src/iom/lib/common.mf
iom/src/os/iom/sys/bsd/kern/vfs/vfs_syscalls.c
iom/src/os/iom/sys/bsd/kern/vfs/common.mf

List of created files:

os/common/src/iom/lib/iomgetinode.c
iom/src/os/iom/sys/bsd/kern/vfs/get_inode.c

Back to Top