CSCI Operating Systems, Winter 2019 Lab 1 : Introduction to the BLITZ Tools, git, kpl, makefile, etc. Due Date: 21 January 2019

Size: px

Start display at page:

Download "CSCI Operating Systems, Winter 2019 Lab 1 : Introduction to the BLITZ Tools, git, kpl, makefile, etc. Due Date: 21 January 2019"

Corey Nicholson
5 years ago
Views:

1 CSCI Operating Systems, Winter 2019 Lab 1 : Introduction to the BLITZ Tools, git, kpl, makefile, etc. Due Date: 21 January 2019 Lab and Homework Assignments You may work together to complete the labs, but each person must have their own submission. Homework assignments, however, must be completed, debugged, and uploaded individually. Overview and Goal This lab introduces you to several of the BLITZ tools that you ll be using throughout the term to complete lab and homework assignments. BLITZ was designed specifically for writing a small OS kernel, and was developed by Harry H. Porter at Portland State University. The tools have been modified for use here at WWU. Do not use the original tools. Both executables for the Linux cluster and source code are provided to you so you can install BLITZ on your machine if you so choose. Sections 1 5 pertain to BLITZ setup, and Section 6 onward is the lab. Submission instructions and the rubric are the last section. Throughout this (and future) labs, as well as homework assignment instructions, text that is provided in a box is instructing you to issue verbatim one or more commands via the command line. For example, the following is instructing you to issue the command whoami on the command line : whoami 1 The Documentation Documents describing the BLITZ tools are available at harry/blitz. The local copies of the below 10 documents are at the following : cs.wwu.edu/~jagodzf/teaching/csci447/blitz/. Phil Nelson also keeps a copy, at https: //facultyweb.cs.wwu.edu/~phil/classes/blitz. 1. An Overview of the BLITZ System (7 pages) 2. An Overview of the BLITZ Computer Hardware (8 pages) 3. The BLITZ Architecture (71 pages) 4. Example BLITZ Assembly Program (7 pages) 5. BLITZ Instruction Set (4 pages) 6. The BLITZ Emulator (44 pages) 7. An Overview of KPL, A Kernel Programming Language (66 pages) 8. Context-Free Grammar of KPL (7 pages) 9. BLITZ Tools: Help Information (13 pages) 10. The Format of BLITZ Object and Executable Files (12 pages) 1

2 2 Read the Overview Document Read the first document, An Overview of the BLITZ System, before proceeding. 3 BLITZ hosting and tools You will develop your operating system code on a host computer and you will be running the BLITZ tools on that host computer. BLITZ has been installed on the department s Linux systems, and your code submissions will be run (and tested) there. The BLITZ tool set is made up of the following components: kpl: The KPL compiler asm: The BLITZ assembler lddd: The BLITZ linker blitz: The BLITZ machine emulator (the virtual machine and debugger) diskutil: A utility to manipulate the simulated BLITZ DISK file dumpobj: A utility to print BLITZ.o and a.out files hexdump: A utility to print any file in hex check: A utility to run through a file looking for problem ASCII characters endian: A utility to determine if this machine is Big or Little Endian These tools are listed more-or-less in the order they would be used. You will probably only need to use the first 4 or 5 tools and you may pretty much ignore the remaining tools. The last three tools are only documented by the comments at the beginning of the source code files, which you may read if interested. 4 Setup for use The Blitz executables are available on the department Ubuntu Linux machines in Filip s directory at the following location: /home/jagodzf/public html/teaching/csci447/blitz/bin So that you can invoke the tools (programs) from the command line from any of your directories, add the above bin location to your PATH variable in your login shell rc file. For bash, the file name is.profile, and you may need to create one if the file doesn t exist yet. In case you have never added anything to your path before, edit or create the.profile file in your home directory (assuming you are using bash). For example, placing the following line at the end of your.profile file will make your shell look for commands in the blitz bin directory: export PATH=$PATH:/home/jagodzf/public_html/teaching/csci447/blitz/bin After you edit your.profile file, you need to logout and log back in, or instruct your shell to read/process the new contents of the.profile file by issuing the source command : source /.profile 2

3 To verify that you modified the PATH variable correctly, issue the kpl command from a prompt: kpl You should see the following: ***** ERROR: Missing package name on command line ********** 1 error detected! ********** If you see anything else, then something is wrong. Ask Filip for help if you have any questions. 5 Running BLITZ on your own computer If you are working anywhere in your directory tree on the WWU linux machines, and you don t want to install BLITZ on your own computer, skip this section. The BLITZ tools run on the following host platforms: Apple Macintosh, OS X, either PPCbased or Intel-based machines, Sun Solaris Unix / Linux Systems Windows, using Cygwin which emulates the Unix POSIX interface (see If you want to compile your own copy of the BLITZ tools on your own computer, the source code for all the BLITZ tools is available at BlitzSrc.wwu.tgz. The following steps are for installing and running BLITZ on your own machine. Copy the source tar ball to your machine. (see above for location) Extract the tar ball. Modify the makefile and set the make variable BINDIR to where you want your blitz tools installed. The command make install will make and install the tools. Change your PATH environment variable to include the value you put in the BINDIR definition. 3

4 6 Set up a gitlab project for 447 assignment turn-in During this quarter, you will be turning in your code assignments via the department s gitlab server. Git is a powerful (and very popular) version control system. The idea is simple : your code is stored in a remote location. You can pull (retrieve) that code, and push (upload) changes to it. Many online resources are available detailing the useful git commands and functions. Some of the command-line git comments you ll be using include branch, push, pull, commit, and add. I recommend you use the documentation and tutorials on the official github website ( git-scm.com/) if you are not familiar with git. The git cheat sheet is especially useful, available at Complete the following steps to create your git repo in the department s gitlab instance. These git instructions are a bit verbose, but that s because this is the first lab. 1. Proceed to log in, and create a new gitlab project with the exact following name (capitalization and the underscore are important, because a script will be used to retrieve your submission(s)): csci447 w19 2. Select Members from the dropdown gear menu in the upper right corner of our gitlab web page, and add Filip Jagodzinski (user jagodzf) as a member to your project. Please provide at least Reporter access, which will allow me to retrieve your submissions. You can have my access expire by the end of the term. 3. From a command line, clone your project to a working directory. The clone path is provided to you on the repo page of the gitlab webpage. If you are unsure how to do this (or how to issue any other git command, do a web search and/or ask Filip). An alternative is to use the manual pages on the department s Linux machines. For example, man git branch will display the documentation for git s branch command. If you are working on a CS WWU linux machine, I recommend you create a directory, cs447 for example, and clone the git repo into that directory. 4. In your local (on the WWU linux account) git, create a README file with your name on the first line, and on the second line write Winter CSCI add the README file to your local repo, commit the change, and push the change back to the master branch of the remote git. If done correctly, return to the gitlab web page, and when you navigate to your csci447 w19 repo, the contents of the README file should be displayed. Hint : Use the -m flag to add a messsage to your commit. The following are the exact commands you would issue, one-by-one : git add README git commit -m "inserting README file" git push 6. Create and checkout a new branch in your local git, and name it lab1. When creating a new branch, ALWAYS do that from the master branch. Otherwise, if you create a new branch while on a branch, you are creating a branch of a branch. Refer to the man pages, or perform a web search, to find out how to create and/or check out a branch. 4

5 7. To check which branches are available and which branch you are currently on, issue the branch command : git branch You should see something like the following : * lab1 master where the asterisk specifies the current branch that you are on. 8. Create a new directory, lab1, and place there the unzipped and untarred files from the zipped tar ball from the course website. The files should include the files DISK, *.s, *.h, *.k, and the makefile. 9. Before you push any code to the remote git, it is a good idea to inspect any changes that you ve made (if any) to your local files. That is done by invoking the status command : git status which would output something like the following: On branch lab1 Untracked files: (use "git add <file>..." to include in what will be committed) lab1/ nothing added to commit but untracked files present (use "git add" to track) which indicates that lab1 is a new directory, but that it, nor any of the files in the directory, have not been flagged to be uploaded (included in) the remote git. 10. add and commit the directory to your git, as well as all of the files in that directory. 11. push the new branch to the remote gitlab. When dealing with branches, you must inform git that you want to push your code from your local branch to the remote branch. The following will achieve that: git push --set-upstream origin lab1 Note that you need to have the lab1 branch checked out when you issue this command. In other words, issue the push command when you are working in the local branch lab1. You should not have a lab1 directory on the branch master. Do your work on the lab1 branch for the remainder of this lab. IMPORTANT : by convenion, executable (binary), object (.o), and any other nontext files are not pushed to a git repository. Do not add nor commit nor push such files to your repo! That is because such files are architecture and computer dependent, and are also huge, so pushing them to your git repo will bloat your repository. Only code source files, and plain-text files, are pushed to a git repo. 5

6 7 The BLITZ Assembly Language In this course you are not required to write (much) assembly language code, but you will have to write some for this lab (and perhaps homework 1). However, you will be using some interesting routines which can only be written in assembly. Most if not all assembly language routines will be provided to you, but you will need to be able to read them. Take a look at the files Echo.s and Hello.s to see what BLITZ assembly code looks like. 8 Assemble, Link, and Execute the Hello Program The files you ve downloaded contain an assembly language program called Hello.s. First invoke the assembler (the tool called asm ) to assemble the program: asm Hello.s This should produce no errors and should create a file called Hello.o. The Hello.s program is completely stand-alone; it does not need any library functions and does not rely on any operating system. Nevertheless, it must be linked to produce an executable (an a.out file). The linking is done with the tool called lddd. (In UNIX, the linker is called ld.) lddd Hello.o -o Hello By default, the executable is named a.out, but the -o Hello option specifies that the executable should be named Hello. Execute the program, using the BLITZ virtual machine (emulator): blitz -g Hello The -g option is the auto-go option and it means begin execution immediately. You should see: Beginning execution... Hello, world! **** A debug instruction was encountered ***** Done! The next instruction to execute will be: : A1FFFFB8 jmp 0xFFFFB8! targetaddr = main Entering machine-level debugger... ====================================================== ===== ===== ===== The BLITZ Machine Emulator ===== ===== ===== ===== Copyright , Harry H. Porter III ===== ===== ===== ====================================================== Enter a command at the prompt. info about commands. > Type quit to exit or help for 6

7 At the prompt, quit and exit by typing q (short for quit ). You should see this: > q Number of Disk Reads = 0 Number of Disk Writes = 0 Instructions Executed = 1705 Time Spent Sleeping = 0 Total Elapsed Time = 1705 This program terminates by executing the debug machine instruction. This instruction causes the emulator to stop executing instructions and throws the emulator into command mode. In command mode, you can enter commands, such as quit. The emulator displays the character > as a prompt. After the debug instruction, the Hello program branches back to the beginning. Therefore, if you resume execution (with the go command), it will result in another printout of Hello, world!. 9 A second BLITZ assembly code example, Echo Another assembly language program has been provided for you, named Echo. All that it does is listen to the keyboard, and echoes the typed keys back to the monitor. Inspect the Echo.s file. To assmble, link, and run the program : asm Echo.s lddd Echo.o -o Echo blitz Echo On the last line, we have left out the auto-go -g option. Now, the BLITZ emulator will not automatically begin executing; instead it will enter command mode. When it prompts, type the g command (short for go ) to begin execution. Type some text. Each time the ENTER/RETURN key is pressed, you should see the output echoed. For example: > g Beginning execution... abcd abcd this is a test this is a test q q **** A debug instruction was encountered ***** Done! The next instruction to execute will be: cont: 0000A4: A1FFFFAC jmp 0xFFFFAC! targetaddr = loop > This program watches for the q character and stops when it is typed. If you resume execution with the go command, this program will continue echoing whatever you type. The Echo program is also a stand-alone program, relying on no library functions and no operating system. 7

8 10 The KPL Programming Language In this course, you will write code in the KPL programming language. In preparation for homework 1, begin studying the document titled An Overview of KPL: A Kernel Programming Language, which is one of the 10 documentation files for BLITZ made available for you. Should you read the entirety of that document, word-for-word? No. Should you be familiar with the contents, so that you may use that file as a reference? Yes Compile and Execute a KPL Program called HelloWorld The HelloWorld.k and HelloWorld.h files are being provided for you. Inspect them. These contain the equivalent of the program code (.cpp,.c) and header (.h) for C++ and C. Note that the original Blitz/KPL system used.c files for code, but the compiler has been changed at WWU to use the.k suffix so these files are not confused with C programs by tools like emacs. Type the following commands to compile and link the HelloWorld program: kpl -unsafe System asm System.s kpl HelloWorld asm HelloWorld.s asm Runtime.s lddd Runtime.o System.o HelloWorld.o -o HelloWorld There should be no error messages. The HelloWorld program makes use of some other code, which is contained in the files System.h and System.k. These must be compiled with the -unsafe option. If you leave that out, you ll get 17 compiler error messages, such as: System.h:39: ***** ERROR at PTR: Using ptr to void is unsafe; you must compile with the unsafe option if you wish to do this Using the UNIX compiler convention, this means that the compiler detected an error on line 39 of file System.h. KPL programs are often linked with routines coded in assembly language. Right now, all the assembly code we need is included in a file called Runtime.s. Basically, the assembly code takes care of: Starting up the program Dealing with runtime errors, by printing a message and aborting Printing output (There is no mechanism for input at this stage... This system really needs an OS!) Now execute this program. Type: blitz -g HelloWorld You should see the Hello, world... message. What happens if you type g at the prompt, to resume instruction execution? 8

9 10.2 The makefile The lab1 directory contains a file called makefile, which is used with the UNIX make command. Whenever a file in the lab1 directory is changed, you can type make to re-compile, re-assemble, and re-link as necessary to rebuild the executables. Notice that the following command : kpl HelloWorld will be executed whenever the file System.h is changed. Each package (such as HelloWorld) will have both a header file and a code file. The HelloWorld package uses the System package. Whenever the header file of a package that HelloWorld uses is changed, HelloWorld must be recompiled. However, if the code file for System is changed, you do not need to recompile HelloWorld. You only need to re-link (i.e., you only need to invoke lddd to produce the executable). Consult the KPL documentation for more info about the separate compilation of packages Modify the HelloWorld Program To get more practice, modify the HelloWorld.k program by un-commenting the following line: --foo (10) In KPL, comments are through end-of-line. Simply remove the hyphens and recompile as necessary, using make. The foo function calls bar. The bar function does the following things: Increment its argument Print the value Execute a debug statement Recursively call itself When you run the modified HelloWorld program it will print a value and then halt. The keyword debug in the code is a statement that will cause the emulator to halt execution. Hint: In later assignments, you will probably want to place debug in programs you write when you are debugging, so you can stop execution and look at variables. If you type the go command, the emulator will resume execution. It will print another value and halt again. Type go several times, causing bar to call itself recursively several times. Then try the st command (st is short for stack ). This will print out the execution stack. Try the fr command (short for frame ). You should see the values of the local variables in some activation of bar. Try the up and down commands. These move around in the activation stack. You can look at different activations of bar with the fr command Try Some of the Emulator Commands Try the following commands to the emulator, where abbreviations are shown in parentheses: quit (q) help (h) go (g) 9

10 step (s) t reset info (i) stack (st) frame (fr) up down The step, st, command will execute a single machine-language instruction at a time. You can use it to walk through the execution of an assembly language program, line-by-line. The t command will execute a single high-level KPL language statement at a time. Try typing t several times to walk through the execution of the HelloWorld program. See what gets printed each time you enter the t command. The i command (short for info) prints out the entire state of the (virtual) BLITZ CPU. You can see the contents of all the CPU registers. There are other commands for displaying and modifying the registers. The h command (short for help) lists all the emulator commands. Take a look at what help prints. The reset command re-reads the executable file and fully resets the CPU. This command is useful during debugging. Whenever you wish to re-execute a program (without recompiling anything), you could always quit the emulator and then start it back up. The reset command does the same thing but is faster. Make sure you get familiar with each of the commands listed above; you will be using them later. Feel free to experiment with other commands, too. 11 What to Hand In & Rubric First, make sure you have committed all your changes, including the modified HelloWorld.k file, to the lab1 branch of your git repository on gitlab. Next, create a transcript of a terminal session showing you using the BLITZ system. You should at least run the echo program, as well as the modified HelloWorld program. If you do not know about creating a script file, you can learn about the UNIX script command by accessing the manual page for it: man script Note that if you try to use a text editor while running script, a bunch of garbage characters may be put into the file. Please do not do this. Name your script file lab1-script or lab1- script.txt, and add it to your lab1 branch. Don t forget to commit that file and push it to your lab1 branch. It is a good idea to use the web interface at gitlab.cs.wwu.edu to verify you have the correct files on the gitlab server as that is where they will be retrieved for grading. 10

11 csci447 w19 created in your gitlab, and jagodzf has been granted access permissions 2 The README file has been created and pushed to the master branch 2 branch lab1 created, and files have been pushed to it 2 HelloWorld has been correctly modified and pushed to the lab1 directory 2 A transcript, lab1-script or lab1-script.txt has been created, and pushed to the 2 lab1 directory Total 10 points 11

Programming Project 1: Introduction to the BLITZ Tools

Programming Project 1: Introduction to the BLITZ Tools Due Date: 2nd October 2017 before 11:30 AM. Duration: One Week Overview and Goal In this course you will be creating an operating system kernel. You