Creating SPIN Extensions

Creating and Running Extensions
for iX86 SPIN

Extensions

Extensions are code modules written in Modula-3 that are a means of extending the SPIN kernel.

There are a number of extensions provided with your SPIN distribution. If you would like to begin by loading and running some existing extensions, go down to Extending SPIN. Otherwise, you can begin creating your own extensions after reading the next section on writing extensions.

Writing Extensions

Extension Directory Structure

There is a standard directory structure for an extension. Let's use the hello extension as an example. Go to spin/user/hello/ and make clean.

# cd /home/mydir/spin/user/hello
# make clean

Now take a look at what exists in spin/user/hello. This is the basic directory structure you should follow when creating your own extensions.

			hello
			  |
		      __________
		     |	        |
	         Makefile      src
				|
		           ___________________
		          |         |         |
		     Hello.i3   Hello.m3   m3makefile

Now build the hello extension by typing make in ~/spin/user/hello, and then take a look at the directory structure.

			      hello
			        |
		  _____________________________________
		 |          |	     |      	       |
	     IX86_SPIN   Makefile  m3.deps.IX86_SPIN  src
		 |                                     |
	         |                            ___________________
             "Lots of      	     	     |        |          |
	     new files"		 	 Hello.i3   Hello.m3   m3makefile

In the IX86_SPIN directory there are a number of files generated by m3makefile. These include:

hello.rc	A script of domain commands that will load the extension's modules and link with the imported domains specified in the m3makfile
extend_hello.c	Contains a C function that uses libdomain to load and link an encapsulated extension. This is used to load an extension from a user-space program.
.io, .mo	Modula-3 object files

How this extension is built is specified by the m3makefile. Much of the content of the m3makefile is the same as can be found in any m3makefile. However there is also some SPIN specific functionality. The DomainImport function specifies what interfaces are going to be used by this extension. For example in the m3makefile for Hello you can see the line:

DomainImport("SpinPublic","kernel","spincore",overridepath)

This says that the Hello extension is going to use the SpinPublic interface which is defined in ~/spin/kernel/spincore/SpinPublic.i3. The directory names "kernel" and "spincore" make up the path to the file and are written in this way due to limitations in the quake language. Look at some other m3makefiles with longer paths and you will get the idea.

For more information on m3build, m3makefiles, and quake, take a look at the Modula-3 home page.

Extending SPIN

There is more than one way to run extensions in SPIN. The easiest way for someone working with SPIN for the first time is to load and run them from the command line. Later you may want to utilize one of the other methods.

Extensions from the Command Line

To load and run extensions from the command line, simply use the script command. Lets run the Hello World extension located in spin/user/hello/ as an example. You may wish to take a look at the source code in src/Hello.m3 and make some changes before compiling this extension.

Inside spin/user/hello/, type make to compile. Once the extension is compiled you can download and run it from the SPIN shell prompt with the script command shown below. The extension is then fetched over the network and run. Your output should look something like this: (Here loom16 is the name of the machine running SPIN)

(140) loom16> script ~/spin/user/hello/IX86_SPIN/hello.rc
hello ..... 4 KB link complete.
Hello world from inside SPIN!
(140) loom16>

Boot-time Extensions

Boot-time extensions are a static part of the kernel and are executed when you boot SPIN. These extensions are specified in ~/spin/kernel/Makefile in the definition of STATIC_EXTENSIONS. During compilation the *.io and *.mo object files are transformed into an encap_*.s file which becomes an integer array in the data segment.

Init Extensions

There are other extensions that are loaded and linked automatically after the kernel boots. These are specified in ~/spin/user/scripts/init.IX86_SPIN. In this case the *.io and *.mo files are read directly over the network via the script command. The method for fetching these extensions can also be specified in init.IX86_SPIN.

Questions/Comments