Writing SPIN Extensions

3 June 1996

There are three new ways to extend the SPIN kernel.

From the command line with domain command and foo.rc scripts
From user space using usyscall.
At boot time as a static extension in the start library.

These extension systems are supported by automatic code generated from the M3 compiler, quake, make and some shell scripts all based on directives in the extension's m3makefile.

Extension Directories

The directory for extension foo, will look like this:

                         foo/
           Makefile foo.c src/ ALPHA_SPIN/ encap_foo.s
                      -----------
		    	foo/src
                Foo.i3  Foo.m3  m3makefile
                      -----------
			foo/ALPHA_SPIN
		FooUser.s extend_foo.c foo.rc  and the module object files

Extension m3makefile

The m3makefile describes the domains that modules in this extension import. The quake templates and m3 compiler will generate code to load the modules listed and link them with the domains imported.

This example is for the domain library, which uses SIEG to generate a syscall interface. That means modules in this extension import the Sieg domain, which in turn needs UserSpaceThreads.

	overridepath = [ THISTREE , FULLTREE ]
	DomainImport("SpinPublic","kernel","spincore",overridepath)
	DomainImport("SpinTrusted","kernel","spincore",overridepath)
	DomainImport("Sieg","user","sieg",overridepath)
	DomainImport("UserSpaceThread","user/thread","threadcore",overridepath)

	Package("DomainLib")

	implementation("DomainLib")
	sieg_extension("DomainLib")

	Extension({})

Several files are produced by the m3makefile in the ALPHA_SPIN subdir.

foo.rc is a script of domain commands that will load the extension's modules and link with the domains the m3makefile imports.
extend_foo.c contains a C function that will use libdomain to load and link an encapsulated extension (see Makefile below).
FooUser.s holds the sieg generated syscall for the Foo.i3 interface.

Application Makefile

At the moment applications load their extensions from arrays in their data segment. These encapsulations are generated by the encap script (local/bin/encap). The extension build process produces a C function that loads these arrays into the kernel. It uses a sieg domain library called libdomain to load and link the arrays.

The CAM application is just downloads its extension and then print it did so. cam.c is written from scratch by the user.

main(int argc, char **argv)
{
	cam_extension(); /* <- generated in ALPHA_SPIN/extend_cam.c */
	printf("cam loaded\n");
}

Extension Makefiles follow a common form. This sample is for cam where cam_domain is the resulting application program. cam.c uses dlib for the printf and the domain library to load the extension. The 'extension' target will run m3build if the extensions were touched.

	THISTREE:=$(shell cd ../..; pwd)
	include $(THISTREE)/make.conf

	vpath %.a	$(THISTREE)/user/lib:$(FULLTREE)/user/lib
	vpath crt0.o	$(THISTREE)/user/lib:$(FULLTREE)/user/lib

	all: extension cam_domain
	cam_domain: crt0.o cam.o extend_cam.o encap_cam.o libdomain.a libc.a
		$(LD) $(LDFLAGS) -o $@ $^

	extension: m3sources	# make.extension has the rule to build m3sources

	install: all
		cp cam_domain $(THISTREE)/user/bin

	clean:
		rm -rf ALPHA_SPIN
	include ../make.extension

Several files are produced by gmake

ALPHA_SPIN/*. If the files src/ have been touched or their imports have been rebuilt, make will call m3build to build the extension
encap_foo.s is produced by the encap program (local/bin/encap) and contains the extensions object files in a format expected by the code in ALPHA_SPIN/extend_foo.c.
foo itself. This Makefile is where the user space application program is built.

Extending SPIN

Boottime Extensions

The list of boot time extensions is in spin/kernel/Makefile in the STATIC_EXTENSIONS variable. The default list was chosen to match the functionality of spin-18. These extensions become part of the start library in spin/kernel/start.

Static extensions are encapsulated into open arrays by the encap script just as for applications. The mkextender script in start/src generates Encap modules that dynamically links the open arrays produced by encap.

At boottime, the main bodies of the encap modules queue an Init function with the BootEncap module. The BootEncap module main body forks a thread that will run all those Init procedures once scheduling starts. The Encap modules are ordered by importing all the Encaps that are to run before it. The Init procedures are run serially.

Command Line Extensions

Once SPIN is up, extensions can be loaded from the command line. The load command is still there but works only for extensions that link only with SpinTrusted and SpinPublic.

Each extension has a script generated by the compiler that will load and link it into the kernel. This is ALPHA_SPIN/foo.rc. Those scripts are series of "domain" commands that you can also use at the shell prompt. Use "domain check foo" to look for unresolved symbols.

	!> script ~/spin/user/sync/rwlock/ALPHA_SPIN/rwlock.rc
	rwlock .......... 39 KB  link complete.
	rwlock run M3 main bodies.
	>>> extension loaded: 10 new units, 589 total units

Application Extensions

Applications download their extensions from user space using the foo_extension() function generated in ALPHA_SPIN/extend_foo.c. This generated code uses the domain library, which in turn uses Sieg, which imports UserSpaceThreads. These domains must be loaded either at boot time or from the command line. In spin-19, UserSpaceThreads are loaded at boottime and the user/scripts/exec.rc will load Sieg and the domain library.

	!>script ~/spin/user/scripts/exec.rc

	!>script ~/spin/user/cam/osf.cam.rc
	!>exec ~/spin/user/bin/cam_domain

{becker|ddion}@cs.washington.edu