Date: Tue, 26 Nov 1996 00:08:22 GMT Server: NCSA/1.5.2 Last-modified: Mon, 29 Jan 1996 15:38:25 GMT Content-type: text/html Content-length: 21535

Menubar Operating Systems Laboratory Organization and Tools

Operating Systems
Laboratory Organization and Tools

Carol Miller

HTML by William Hicks and Earl Shannon

Table of Contents
Introduction
Operating System Development Tools

xcc as download odt busers Xinu8


Program Development Example
Troubleshooting


Introduction:

The Operating Systems Laboratory of the Computer Science Department is provided for students enrolled in upper level undergraduate and graduate operating system courses. This document contains a description of the computers in the lab and the software development tools available to students in these advanced classes.


Laboratory Configuration

The Operating Systems Laboratory, often referred to as OSL, for the Computer Science Department is located in Daniels 205. This lab is a vital resource for two undergraduate courses (CSC 451 and CSC 452) and the graduate level real-time operating systems course (CSC 574). The computers in the laboratory for CSC 451 consist of a single Sun Sparc and five Sun 3/60 Xinu clients, named friedpie, fishstick, onionring, tatortot, and frenchfry.

Hushpuppy

The Sparc workstation, known as hushpuppy, is where student accounts are located and Xinu software development is done. Hushpuppy uses the SunOS operating system which is a 4.3 version of UNIX with System V release 3.2 extensions. It is connected to the campus network via ethernet and uses TCP/IP to communicate with other machines. Hushpuppy can also be reached by using a Hayes compatible modem through the NCSU Campus dataswitch, university terminal servers, or from other computer systems via Internet using the address hushpuppy.csc.ncsu.edu or just plain hushpuppy if you are currently in the NCSU Internet Domain.

To telnet to hushpuppy you can also just click here.

SunOS has many of the commands found on other campus machines such as aza, the Eos workstations, and garfield, some of which are running Digital Equipment's ULTRIX. Familiarity with any of these systems will allow you to quickly become comfortable using SunOS. Help is available via the on-line manuals commonly called man pages. The following is an example to show how to display man pages for the SunOS command ls, which will list the contents of a directory.

	sun4-%man ls

Hushpuppy responds with:
	
	reformatting page. Wait... done

	LS(1V)			USER COMMANDS			LS(1V)

	NAME ls - list the contents of a directory

	SYNOPSIS ls [-aAcCdfFgilLqrRstu1 ] filename ...

	SYSTEM V SYNOPSIS /usr/5bin/ls [-abcCdfFgilLmnopqrRstux] filename ...
and continues with the remaining information on the ls command.

Xinu Clients

There are five Xinu clients. They are named fishstick, frenchfry, onionring, tatortot, and friedpie. They are Sun 3/60 with 8 or 4 megabytes of RAM, two serial ports, an ethernet connection, and a SCSI port. The console port (one of the two serial ports) on each of the five clients is connected to hushpuppy via a multiplexer. This connection allows the server machine to act as a front end to the Xinu client and eliminates the need for an additional terminal. The operating system also suppports a terminal connected to the second serial port, but which is not currently configured.
The five target machines (clients) are connected to each other and to hushpuppy through an ethernet network. It is through this connection the clients download Xinu executables created on the Sparc (hushpuppy). Devices such as hard disks, CD-ROMs, and scanners can be connected to the Sun via the SCSI port.

Contents


Operating System Development Tools

Xinu is a small operating system originally designed for the Digital Equipment LSI 11 computer but has been transported to other platforms; it is for this reason that a Xinu target machine is sometimes called an LSI. Written by Douglas Comer and associates at Purdue University, Xinu and its development tools are used to explore the different aspects of operating system design. Xinu Version 6 is discussed in Comer's book Operating System Design, The Xinu Approach volume one. Volume two of this text covers Xinu Version 7. Xinu 6 is currently installed on hushpuppy and can be found in the directory /usr/Xinu/. The C and MC68030 assembly source files for Xinu 6 are located in the directory /usr/Xinu/src, Xinu header files are in /usr/Xinu/include/, and the library files are located in /usr/Xinu/lib/.

xcc: C Compiler for Xinu

The command xcc invokes the C compiler, assember, and loader to produce object files, Motorola MC68030 assembly language files, or Xinu executables from input files located on hushpuppy. The input files can be C source files, Motorola 680xx assembly source files, object files, or libraries of object files. The distinction between the different types of files is made by the suffix of the file name:

	Suffix		File Type
	.c		C source code
	.s		MC680xx assembly source
	.o 		object file
	.a		object file library

For example, xcc would assume the files main.c, io.c, and control.c to be C source code and the file lowlevel.s to be an assembly module. It is recommended that you use xcc to assemble routines written in assembly language.
Below are the switches (options sent to programs via the command line) that xcc understands.

	Switch		Purpose
	-c		To suppress the loading(linking) phase of the
			compilation, and force xcc to stop after
			producing '.o' files from source programs.

	-o output	To name the final output file output.

	-v		Verbose output narrating each step of the 
A
			compile.

	-Dname		Define name to the preprocessor, as if by the
			#define directive.

	-E		Run only the macro preprocessor on the named
			C programs, and send the result to standard
			output.

	-Idir		#include files whose names do not begin with 'I'
			are always sought first in the directory of
			the file argument, the in directories named in
			the -I options, then in directories on a 
			standard list.

	-O		Invoke the object-code improver as part of the
			C compilation.

	-P 		Run only the macro preprocessor on the named C
			programs, and send the result to corresponding
			files suffixed with .i.

	-S		Compile the named C programs into assembly
			language, and leave the asembly-language output
			in corresponding files suffixed with .s, without
			assembling or loading the result.

	-L		Include the standalone startup routine to allow
			downloading without Xinu.  The xcc command can be
			used to generate modules for downloading that do
			not contain the Xinu operating system.  The -L
			switch is used to create this standalone object file.
			When a standalone module is mode, the linker uses 
			the libsa.a library of functions instead of the usual
			libx.a and libc.a.

			
For example, to compile a C source file named main.c, an assembly listing named lowlevel.s, and the object io.o into an executable named prog1 use xcc in the following way:
	xcc -o prog1 main.c lowlevel.s io.o
For more information about the above options, consult the man pages on the Sun C compiler (cc command).

as: MC680xx Assembler

The Sun 3/60's are based upon the Motorola 68000 family of microprocessors. The command as can be used to assemble 680xx source files into machine code, however the resulting binary file in not in the proper format for downloading. It is for this reason that you are encouraged to use xcc to do all your assembling. The assemble the file setup.s, enter:
	xcc setup.s

download: Download Executable to Xinu Client

The download command loads the absolute binary program image produced by xcc into the memory of the target machine. The name of the file to download can be provided as an argument otherwise the name a.out is assumed. The -m option can be used to select a 3/60 to send your binaries to, otherwise any available client machine is used. For example:
	download -mfishstick prog1 
will download the file prog1 to fishstick. If no client is available (all are reserved by other users) then download will display an error message.

odt: Connect the User Terminal to the Console Port on the Xinu Client

The command odt takes it name from the on-line debugging technique (odt) feature of the LSI 11 and PDP 11 computers. This feature is a ROM-based monitor which accepts console keyboard commands. The name odt has been kept for historical reasons and to provide uniformity across different Xinu platforms. The development tool odt is used to connect the user's terminal to the console port on a client machine. Input from the keyboard is sent to the 3/60 and output for the 3/60 is displayed on your terminal.
To run a downloaded program, enter odt at the prompt on the server machine. You will see a message telling you to which 3/60 you are being connected. This will automatically be the machine you selected previously when you downloaded your executable. Press <Return> a few times until a > prompt appears. If you do not get a prompt or if it seems that a program is already running on the client then enter the key sequence \ (the backslash character) followed by <Control-@> repeatedly until the 3/60 responds with the correct prompt. Enter b at the prompt to boot the client. This will load Xinu and your executable into the memory of the machine. Start your program by typing g 4000 and pressing . Below is an example using the above instructions.
	sun4-%download prog1
	using front end 'hushpuppy':   Using backend 'fishstick'
	downloading file: prog1
	Sent Xk bytes 
	download completed

Note: The X in the line Sent Xk bytes will be some number.
	sun4-%odt
	using front end 'hushpuppy':   Using backend 'fishstick'
	Using /dev/ttyX

Note: The X in the line Using /dev/ttyX will be a device name such as m00.
	>b
	EEPROM boot device...Boot: le(0,0,0)
	Using IP Address 152.1.58.32 = 98013A20
	Booting from tftp server at 152.1.58.33 = 98013A21
	Downloaded X bytes from tftp server.

Note: The X in the above line will be some number.
	>g 4000
At this point Xinu will start and your program will begin execution. To return to hushpuppy press <Control-C>. This ends the odt session and causes the connection between the front-end (hushpuppy) and a 3/60 to be broken. Pressing <Control-C> does not cause the Xinu client to stop executing your program, it may continue executing after odt has been exited.
B
	<Control-C>Machine released
	sun4-%
If a target machine begins behaving strangely it may need to be reset. To reset a 3/60, connect to it using the odt command as shown above. At the odt prompt enter k 2 (the letter k followed by a space and then the number 2) and press . This will casue the client to reset, perform a self-test, then load any downloaded program into memory.
Two switches (program options) commonly used with odt are -m and -h.
	Switch	      		Purpose
	-mMachine Name  	causes odt to connect the user terminal to Sun
				named Machine Name (an odt following a download
				will automatically use the same 3/60 selected 
				by the download if the -m switch is not used)

	-h			allows this 3/60 to remain reserved while
				another is also being used.
For example, odt -mfishstick -h will access fishstick and keep the reservation for those computers which have already reserved. Normally, downloading and using odt to connect with one Xinu client releases any other reservations.

busers: List the Xinu Client Users

The command busers lists each of the 3/60s that is currently being reserved and the login name of the user who is using the target machine. Example:
	sun-4% busers
     
     	fishstick     idle time = 0 mins     class =   SUN reserved by ershanno
     	frenchfry     idly time = 2 mins     class =   SUN reserved by wjhicks
Contents

Program Development Example

Any editor can be used to create source files. This sample program is compiled using the xcc command and download with the Xinu operating system to a Sun 3/60. The system call getc is used to read characters form the terminal.
C source program:
	#include <conf.h>
	main ()
	{
		char c;
		while ((c=getc(CONSOLE))!= 'A')
		printf("%c\n",c);

	} /* end of sample program */

The program is compiled using xcc.
	sun-4%>xcc prog1.c
	prog1.c:

	a.out:
	596+0 records in
	37+1 records out

	sun-4%>
The output file a.out is the absolute object image for the 3/60.
	sun-4%> download a.out
	sun-4%>odt
	Using fishstick

	> b
	EEPROM boot device...Boot: le(0,0,0) 
        Using IP Address 152.1.58.32 = 98013A20
        Booting from tftp server at 152.1.58.33 = 98013A21
        Downloaded 5432 bytes from tftp server.

	>g 4000

The program executes until the letter 'A' is typed. Press <Control-C> to release the target machine and return to hushpuppy. Remember, ending an odt session will not halt any programs that may be executing on a target machine.

Contents


Working in Xinu 8

Adding Commands to Xinu 8 Shell
Note: When adding commands to usercmds make sure the name of the function has the same name as the file. This is not absolutely necessary as long as the function to be run when a given command is typed in the shell corresponds with the function you think you are running. This link is setup in the cmd.h file.

The function should have the following structure:

COMMAND my_command(stdin, stdout, stderr, nargs, args)
   int     stdin, stdout, stderr, nargs;
   char    *args[];

This function would be saved in a file called my_command.c

Using make in Xinu 8

Make needs to be run in your Xinu 8 directory to create the downloadable file which will be run on the Sun 3/60s. To do this there is a special script already written for this specific task. It is called Makeall. It should be located in the following directory:

{home}/xinu/src/sys
To execute it you will probably have to tell the shell where the script is located since this directory is not in your path. If your are in the directory where Makeall is located the line to execute it would be:

Sun-4%>./Makeall

Getting a copy of Xinu 8

To get a copy of Xinu 8 just click
here

This will get a copy of the tared and compressed file. To untar and unzip the file, you will need to do the following

This will create three directories: docs, programs, and xinu. The source code is located in xinu and can be changed as described above.

Trouble Shooting in OSL

Trouble with xcc
The command xcc creates temporary object files in your current directory when compiling C programs and assembling 680xx programs. These temporary files have the same names as the source files except with a .o suffix. It is therefore not possible to compile two modules with the same base name (name excluding the suffix) in the same directory such as read.c and read.s because the resulting object files will have the same name.
Trouble with download
If the hushpuppy responds to a download request with NO Suns Available you must wait until someone releases a target machine as all are currently in use.
Trouble with odt
If a 3/60 refuses to respond (at the point where you are expecting an odt prompt) press \ (backlash) then <Control-@> multiple times. If you see any prompt other than > when you start an odt session then another user's program is still running on the client. Use the same same key sequence described above to abort the other program then boot normally.
If a <Control-c> does not return you to hushpuppy, login to another terminal and kill your odt process (or ask an operator to do this for you).
Stack Overflow
The Suns in OSL are 32 bit machines and need twice as much memory to strore addresses and data as the 16 bit LSI 11 computers used in Volume 1 of Douglas Comer's book. There are example programs in the textbook that use the Xinu system call create to spawn new processes. You should double or triple the stack sizes given in the book for these programs to be sure each process has enough memory. If a process runs out of stack space Xinu will reply with the error message Panic: current process stack overflow.
Report Problems with Lab Equipment
If a problem persists with a particular machine, report it by sending mail to ops and use another 3/60. Mail sent to ops goes to all the operators and the first one to read your message will correct the problem.


For comments or sugestions about this document please send email to

Earl Shannon ershanno@hushpuppy.csc.ncsu.edu

Bill Hicks wjhicks@hushpuppy.csc.ncsu.edu
last-update: 1/29/96
version: 1.0