CS 354 - Fall 2020

XINU Set-up

Objectives:

The following instructions describe how to:

1. XINU Configuration

To use XINU, several environment variables must be set. First log onto one of the frontends xinu01.cs.purdue.edu, xinu02.cs.purdue.edu, ..., xinu21.cs.purdue.edu which are Linux PCs. For remote login see Section 5. To login you should be able to use your career account user and password. If you have any trouble with your account and its setup, please see the department help pages at http://www.cs.purdue.edu/help. If these pages do not address your particular problem, please use the trouble command from the command line to report the problem.

The following assumes that your shell is bash. The syntax may vary slightly if you use a different shell. (Run "echo $0" to determine your current shell.)

Setting environment variables for XINU:

    1.  Edit .bashrc in your home directory by adding /p/xinu/bin to your path:

         export PATH=${PATH}:/p/xinu/bin

    2.  Run  source  .bashrc (or its equivalent) to make the change take effect.

Accessing and untarring XINU tarball source files:

  1. Change to your home directory, if you are not already in it.

  2. Unpack:
  3. tar zxvf /homes/cs354/xinu-fall2020.tar.gz
    

    In your home directory, you will now have a directory called xinu-fall2020. The subdirectories under this directory contain source code, header files, configuration files, and Makefile for compiling XINU.


2. Building XINU

To compile the XINU kernel which will be loaded and executed on a backend machine, run "make" in the compile/ directory:
	% cd xinu-fall2020/compile
	% make clean
	% make
This creates a loadable executable file named xinu.xbin. This file is loaded on a backend machine in Section 3 ('Running XINU').

If, upon loading xinu.xbin and power cycling to run XINU the system hangs, repeat 'make clean' followed by make. When adding new source files to XINU, run 'make rebuild' followed by make to incorporate changes. If XINU hangs or crashes after following the above steps, the cause is likely to be bugs in your code modifications. To avoid starting from scratch, maintain working versions that you can return to.


3. Running XINU

The executable XINU binary runs on a selected backend machine. We have 96 dedicated backends: galileo101.cs.purdue.edu, ..., galileo196.cs.purdue.edu.

The backends are all Intel Galileo development boards which run the quark system on chip processor.

The backend machines are shared resources. When a backend machine is grabbed by a student, it is dedicated for use by that student to run his/her version of XINU. To see which backends are available for booting XINU, type:

% cs-status -c quark
This will show you who is using each backend and how long they have been using it. As with all hardware, sometimes they fail and may become unavailable until repaired by our technical staff.

To boot your copy of XINU on a backend, connect to a back-end by issuing the command:

% cs-console [galileo1__]
With no arguments cs-console will connect you to the first available backend (including broken ones). Occasionally, backend hardware malfunctions. If you suspect this to be the case, please inform the TAs.

To load your copy of XINU onto a selected backend:

(control-@) OR (control-spacebar)     //esc to local command-mode

(command-mode) d    //download command

file: xinu.xbin      //tell it to download 'xinu.xbin' (this example assumes that you are in the xinu-fall2020/compile directory)

(control-@) OR (control-spacebar)    //esc to local command-mode 

(command-mode) p    //power cycle the backend
After several seconds XINU should boot with a "Welcome to Xinu!" message that looks something like this:
Xinu for galileo -- version #10  (park)  Wed Aug 19 15:34:30 EDT 2020

Ethernet Link is Up
MAC address is 98:4f:ee:00:0a:cf
 250076704 bytes of free memory.  Free list:
           [0x0015C1E0 to 0x0EFD8FFF]
           [0x0FDEF000 to 0x0FDEFFFF]
    111249 bytes of Xinu code.
           [0x00100000 to 0x0011B290]
    135848 bytes of data.
           [0x0011F020 to 0x001402C7]


Hello World!

I'm the first XINU app and running function main() in system/main.c.

I was created by nulluser() in system/initialize.c using create().

My creator will turn itself into the do-nothing null process.

I will create a second XINU app that runs shell() in shell/shell.c as an example.

You can do something else, or do nothing; it's completely up to you.

...creating a shell


------------------------------------------
   __    __   _____    _   _    _    _
   \ \  / /  |__ __|  | \ | |  | |  | |
    \ \/ /     | |    |  \| |  | |  | |
    / /\ \    _| |_   | \   |  | |  | |
   / /  \ \  |     |  | | \ |  \  --  /
   --    --   -----    -   -     ----
------------------------------------------


Welcome to Xinu!


xsh $

To disconnect and free up the backend:

(control-@) OR (control-spacebar)

(command-mode) p    //power cycle the backend; wait until you see "Press [Enter] ..."

(control-@) OR (control-spacebar)

(command-mode) q    //quit

NOTE:

Please do not leave a running copy of your XINU on a backend. This will prevent others from using that backend.


4. Troubleshooting

  1. We only show the mapping from bash to tcsh. If you use other shell types, please contact the TAs. The mapping is as follows: Edit .cshrc instead of .bashrc. Add a line setenv PATH ${PATH}:/p/xinu/bin instead of export PATH=${PATH}:/p/xinu/bin. Run tcsh instead of source .bashrc.
  2. Try to figure out what's going on by yourself. Oftentimes the steps described above were not precisely followed.
  3. When your XINU executable misbehaves or crashes (i.e., does not do what you intended when programming the kernel) then debug the problem(s) and try again. Since your version of the XINU kernel runs over dedicated hardware, you are in full control. That is, there are no hidden side effects introduced by other software layers that you are not privy to. By the same token, everything rests on your shoulders.
  4. If you get repeatedly stuck with "Booting XINU on ... " please contact the TAs.
  5. If you are not able to get a free backend, please contact the TAs.

5. Remote Login

You can remote access the frontend lab PCs using TLS/SSL applications such as ssh on Linux/MacOS and PuTTY (or OpenSSH) on Windows. Use of the backends is limited to implementing, testing, and evaluating lab assignments of CS 354. You access the backends through one of the frontend machines in the XINU Lab.


6. An Example App: XINU Shell

By default, when XINU boots up, it runs a shell (xsh). To view all the usable shell commands, run the help command:

	xsh $ help

	shell commands are:

	argecho      date         help         netinfo      udp          ?            
	arp          devdump      kill         ping         udpecho      
	cat          echo         memdump      ps           udpeserver   
	clear        exit         memstat      sleep        uptime

Take a moment to run some shell commands and view their output. Specifically make sure you run the ps command which lists information about running processes.

	xsh $ ps
	Pid Name             State Prio Ppid Stack Base Stack Ptr  Stack Size
	--- ---------------- ----- ---- ---- ---------- ---------- ----------
	  0 prnull           ready    0    0 0x0EFDEFFC 0x0EFDEEC0     8192
	  1 rdsproc          wait   200    0 0x0EFDCFFC 0x0EFDCAAC    16384
	  2 Main process     recv    20    2 0x0EFD8FFC 0x0EFD8F64    65536
	  3 shell            recv    50    3 0x0EFC8FFC 0x0EFC8C6C     8192
	  4 ps               curr    20    4 0x0EFC6FFC 0x0EFC6E18     8192

Here you can see the several pieces of information for all processes currently running. The name gives some detail about what the process is intended for. XINU always contains a special process with process identifier (pid) 0 called the null process (or prnull). This process is the first process created by XINU and is always ready to execute. Unlike other processes, prnull is handcrafted without using create(). The inclusion of this process ensures that there is always something for XINU to execute even if all other processes have finished or are waiting for something. By default, UNIX/Linux and Windows have similar null or idle processes.


Back to the CS 354 web page