Part 1 Introduction
Part 2 Working with Mutex
Part 3 An Inside look of Mutex
Part 4 Extending Mutex
Part 5 Want to write an operating system?
Part 6 Acknowledgement
Part 7 Contact information

Part 1 Introduction

What is Mutex?
Mutex is a small operating system. It was designed to be a teachable operating system for students taking an operating systems course. Here are the characteristics of Mutex

• Runs on IBM 8086/88 compatible machines
• Runs in real mode
• Is single tasking
• Uses the original FAT12 file system
  

(Mutex was created by Tadesse Kebede and Tilaye Yismaw for their final-semester undergraduate independent project in the Department of Computer Science of Addis Ababa University, Ethiopia. Their email addresses are at the bottom.)

What do I need to start using Mutex?
Before you get started, you should have the following:

• a floppy disk that you don't have any necessary data on
• an 8086 compatible computer
• the Mutex package which contains all the necessary files required to start using Mutex

Part 2 Working with Mutex

This part describes the characteristics of Mutex, how to boot Mutex and start working on it. The end of Part 2 contains a very important information that you should know about the file system Mutex supports. Before you start, make sure you have all the materials mentioned in Part I.

Bootstrapping Mutex
To make a boot floppy disk of Mutex, follow the following procedures.

1. Creating a full formatted floppy disk
1.1 Insert the floppy disk you have prepared and open My Computer.
1.2 Right click on the floppy disk icon and choose format…
1.3 Click on format (Don't check the Quick format option).
1.4 Look out the window until the disk is formatted.
2. Writing the Mutex bootloader on the floppy disk.
2.1 Copy the file BootM.bin from the bin directory of the Mutex package to a suitable location on your hard disk, perhaps on the top of the system root directory
2.2 Open the command prompt
2.3 Change your current directory to the directory where you have copied the file BootM.bin
2.4 Enter the command debug BootM.bin
2.5 In the prompt that follows, type w 100 0 0 1
2.6 Type q to quit the debug program
2.7 Exit the command prompt
3. Copying Mutex files to the boot floppy
Copy all the files in the copy directory of the Mutex package, keeping the directory structure. A good way to do it is just selecting all the files in the copy directory and copying them into the root directory of the floppy disk. Copying the code folder is optional. You can also recompile the Mutex kernel if you have modified it. To recompile the kernel, follow these steps
1. Copy nasm.exe and mutex.asm (the kernel file) into a suitable location (there is no need of copying nasm.exe if you have it somewhere else in your disk and it's path is added to the system path)
2. On the command prompt, type nasm mutex.asm -o mutex.bin to compile the kernel
3. Copy the file mutex.bin on the Mutex floppy disk
4. Setting boot priority
To boot Mutex you insert the floppy disk into the computer you want to boot it from and power on the computer. But before you do that, you must make sure that the boot priority of the computer you are using is set correctly. To be able to boot Mutex, the floppy disk should have the first boot priority. You need to set this priority especially if you computer has another system installed on the hard disk and if the hard disk has the fist boot priority. To set the boot priority option, follow the following steps. Note that from now on, the computer we are referring to is the computer you are going to start Mutex on.
4.1 Power on, or restart the computer
4.2 On most computers you will see something like Press keyname to enter setup. The keyname could be F2, Delete, CTRL+ALT+ESC or any other key or combination of keys.
4.3 Press the key name specified. This will take you to the bios setup
4.4 Navigate around and set the boot priority so that the floppy disk has the first boot priority.
5. Fire it up!
After you have set the boot priority, reboot the computer to start Mutex.

If you have finished the steps 1-5 successfully, you should see Mutex loading and the prompt Mutex:) appears. Now you are ready to use Mutex

Commands supported by Mutex
Here are the following commands that Mutex supports and a short description of them. Note that commands in Mutex are case sensitive.
ver
Displays the version of Mutex that is currently running
echo somestring
Echoes any string you type
History
Shows the ten commands you have recently used, the most recent one appearing at the top.
reboot
Reboots the computer, restarting Mutex
clear
Clears the screen
list
Lists the files and directories in the present working directory. Directories are differentiated from files in that they have a (D) in front of them.
help [comandname]
Displays what the function of commandname is. Internally, what Mutex does is it look for a file by the name commandname in the manual directory and it display the file if it finds it.
disp filename
Displays the contents of a file given by filename. The file should be in the current working directory.
cd
Changes the present working directory. You can also use cd .. to go to the parent directory of your current directory
pwd
Shows the present working directory. Directories are delimited by forward slash and the root directory is represented by a single forward slash.
run filename
This is a very important command in Mutex. It loads and runs the file filename. The file must be an executable and it should be especially written for Mutex. For further information on how to write programs for Mutex, see Part 3, Writing programs for Mutex. Sample programs can be found in the sample directory. You can change your working directory to the samples directory and run one of them.

Caution! Before you work with files, make sure you read about the file system Mutex supports in Part 3.

Part 3 An Inside look of Mutex

This part shows a general overview of operating system operation, how Mutex handles memory, the system calls that Mutex supports and how to write programs to be run on Mutex.

Overview of operating system operation
Here is how Mutex boots and runs user's commands

1. Boot loader is loaded on memory and given control
2. Boot loader reads the kernel from disk and loads it
3. Boot loader gives control to kernel
4. Kernel initializes global variables, sets registers and the interrupt table
5. Kernel calls the shell
6. Shell takes control to create interaction between the operating system and the user
7. Shell accepts a command, parses the command and calls the appropriate procedure if the command exists.
8. Procedure returns to shell after end of execution. If run was called, the loaded program returns to the shell by calling the appropriate interrupt.
   

File System

Mutex supports the original FAT12 file system. But Windows 95 and above do not handle floppy disks with the original FAT12 format. The original format supports the 8.3 (maximum of eight characters for a file name, followed by a dot, then followed by maximum of three extension characters). But Windows 95 and above can let you have a file name which does not follow the 8.3 format. Since Mutex does not support this enhanced capability, you will have problems with some of the commands if such long file names exist in the floppy disk. But if you have files which have an 8.3 file name in your hard disk and if copy it to the floppy disk, Windows will keep the 8.3 format and Mutex will not have any problems with such files. Hence, if you want to work with files/subdirectories, follow the following steps.
1. Create the file/directory you need in your Windows computer
2. Change the name so that it is compatible with the 8.3 format
3. Finally copy the file/directory to the floppy disk
Beware that Creating a file/directory in the floppy with a long file name and renaming it to the 8.3 format will not work. In addition, note also that even if you create a New folder on the floppy disk and enter the folder name as soon as you create it, internally Windows first creates a folder by the name New Folder (which does not obey the 8.3 rule) and then gives you an option of renaming it. Hence it is generally advisable not to create files/subdirectories directly on the floppy disk.

Memory Management
Here is the layout of the memory when Mutex is running.

System call interface
System calls in Mutex are made by calling interrupts. The interrupts are called as int 0x21 and Mutex expects to find the interrupt number in al register. Here are the values ah can have and the corresponding interrupts.

For example, to call the interrupt which prints a line feed and a carriage return, you would write

mov al, 0x03
int 0x21

Writing programs for Mutex
While writing programs for Mutex, bear in mind the following points
1. Call only the interrupts supported by Mutex. The interrupts supported my Mutex are listed in Part 3, An inside look of Mutex.
2. Specify to the assembler that the program you are writing is going to be loaded at 0x5140
This is because the loader loads programs starting from address 0x5140 and the es register points to 0x0100. You can do this in NASM like this

[org 0x5140]
rest of your code

3. Copy the binary file made by NASM to the floppy disk (you can put it in any directory). Make sure you read the note about the file system Mutex supports.

An example
You can see the source code of the sample programs provided in the samples directory in the Mutex package. Let us take the program hello.asm. It is a program which prints the string hello and returns to the Mutex shell. To compile this file and run it under Mutex, follow these steps
1. Copy nasm.exe and the sample program hello.asm from the Mutex package to some convenient location.
2. Go to the command line and switch your current directory to the directory where you copied the file hello.asm program in step 1.
3. Type nasm hello.asm -o hello.bin
4. Copy the file hello.bin to the Mutex floppy disk
5. Boot Mutex
6. Under Mutex, switch to the directory which you copied the file (if it is not in the root directory).
7. Type run hello.bin You would see the program executing, and returning back to the Mutex shell.

Part 4 Extending Mutex

Anyone interested in modifying or extending Mutex is welcome to do so. In this part we will mention the features we wanted to add to Mutex but didn't. We have included tips on how to go about completing the features. Also, read Part 5, which includes information on how to write an operating system.

date and time commands
The date command requires a skill on handling numbers. Since there is no BIOS interrupt which displays a number, you need to write a function (or perhaps an interrupt because most programs need that) which displays numbers as characters. For example, you may store the number 2004 in the ax register but calling an interrupt which displays a character will not work unless you break the number into pieces and display each digit as a character.
The BIOS interrupt for date information will return years, months and days but we haven't been able to use the interrupt correctly. Try reading more about interrupts under 0x1A for this.
Multitasking!
At first, our proposal stated that we would write a system which is multitasking, implementing different scheduling algorithms. Later on, we discovered there is a choice we had to make. We had to decide if Mutex had to run in real mode or protected mode. We started to read about protected mode but it was taking more time than expected. Hence we chose to make Mutex a real mode operating system. Protected mode has lots of advantages including support for multitasking. If Mutex had to be changed to protected mode, its going to be a huge change and you may have to write most of the code all over again. There is a lot of information about protected mode on the web. Try reading more about the difference about protected mode and real mode. You can start at http://osdever.net
File system
The original proposal we submitted was very ambitious. It also stated that Mutex would implement it's own file system. The advantage of implementing a new file system is you get to learn a lot by designing your own file system and you don't have to have an extensive knowledge about the existing file systems. You just have to read about existing file systems for comparison purposes and to guide you how you can implement you own file system. We dropped this part of the proposal because implementing our own file system would force us to write a program which would run under windows and do the required conversion. This program would read a file in windows and write the file on the floppy disk, with our own file system specification. If you are upto it, then you can design your own file system and start with modifying the commands related to the file system like list and cd to make them "know" the new file system.

Part 5 Want to write an operating system?

If you want to write your own operating system, here are the things that we advice you to consider

Background knowledge

Assembly language!
Knowledge of assembly language is crucial while writing an operating system. If you are not comfortable with assembly language, you might as well start studying it before you start doing anything else. A lot of our time was spent learning assembly language. You might find code snippets on the net which show how you can boot an operating system. But if you don't know much about assembly language, its no use staring at the code and trying to comprehend what all the mov instructions are all about. Just start looking for a good assembly language book.
C
You can mix C and assembly language. C is very famous with being friendly with low level languages. You can write the parts which must be written in assembly and use C for the other parts. There are two ways in which you can mix assembly with C. You can use inline assembly where you write a C code and insert assembly language in the middle, or you can call assembly functions from C and vise versa. If your operating system is getting huge, its a good choice to start working with a high level language like C. We didn't have a chance to use C while writing Mutex because we didn't have much time to read about it, and we started loving assembly in the mean time :) A good C reference will have information about mixing assembly and C. You can also follow this link for a short introduction http://www.osdev.org/developers/guide01/index.jsp
Computer Architecture
Knowledge of computer architecture will be helpful. You need to know about the machine for which you are writing the operating system. For this, you can read any book on computer architecture. A short and concise book can be accessed at http://10.4.13.13/sirnivas/asm.pdf (it's a local address).
Operating systems
After all you are writing an operating system! Its best that you have a know how of operating systems, their functions and their evolution. Andrew S. Tanenbaum writes excellent books on operating systems and its advisable that you get one of his books. You can look for some lecture notes on the web too.

Design

The design is crucial in operating system implementation. It is very costly to change your mind about the design in the middle of your implementation. Before you start writing any code, read more about what you want to do and look on the web if there is any related work done with what you want to do. Only when you are sure that your design is feasible should you begin implementing.

Tools

The following tools are the ones that we have found to be the most important.
Assembler
When you are writing an operating system, you will definitely need to write assembly code and its best that you choose one which is widely used. You will find codes written in assembly but for different assemblers NASM (Netwide Assembler) and MASM (Microsoft Assembler) are two famous assemblers that we have come across. Mutex is written in assembly language for NASM. If you want to extend Mutex, you will need this assembler. The official site of NASM is at nasm.sourceforge.net
BIOS interrupt list
One of the most difficult sides of writing an operating system is using BIOS interrupts only. You do not have cool interrupts which print a string or read a sector of a disk. Every interrupt must be a BIOS interrupt. If there are any other interrupts that you are going to call, they will be interrupts which you have written. Those will be the system calls that your operating system supports. So you can write interrupts which perform the usual chores and use those. Hence, you need to have a list of the interrupts that BIOS supports. The web is a good resource for learning about BIOS interrupts. We have been using HELPPC, which is a documentation showing BIOS interrupts. You can download it at http://hem.passagen.se/danma/asmprog.htm
Virtual Machine
You need to test your operating system while you work. But you may not have a computer to test it with and it would be painful to reboot your computer each time you have made a little modification to your operating system. Even if you have another computer for testing purposes, it would consume your time to reboot every time. A Virtual Machine Software is a software which allows you to run an operating system inside another operating system. You may think of it as a simulator which makes the operating system running inside it to "think" that its running on a computer having full control of it. VMware Workstation is a virtual machine software we have been using to test Mutex. Its one of the best virtual machines around and we recommend using it. Another software you can use is Virtual PC.
Disk editor
When you are working with disks, there will be a time when you need to see the raw data on a disk. A disk editor becomes vital when you work with file systems. Remember that your operating system may even implement its own file system which is different from other common operating systems' format. A disk editor can help you see and modify the raw data on a disk. You can write anywhere on the disk any information you like. You can check if your operating system is writing what you want it to write on a disk by observing the raw data on the disk. Disk editors are hexadecimal editors too. You open disks and see each 16 bits in each sector. You can also open an executable file and see it's contents or modify it. Disk editors are helpful especially when you are working with boot disks and file systems. Hex Workshop is a file and disk editor we have been using. It has been beneficial with the commands related to the FAT12 file system like cd and list.
Text Editor
There are plenty of text editors around. We have been using Notepad and Em Editor while developing Mutex. But around the end of our project Notepad has created a big headache for us. Notepad starts making errors when it's given large files and long lines with many characters that wrap around. Even worse, the goto line number command in Notepad does not work by counting new line characters, making it hard for you to debug programs. Hence we suggest that you use Em Editor or any other text editor, preferably one which highlights some assembly language keywords.

Patience

You won't go far if you are not patient with such a project. If you get stuck, be patient and try doing the following

• Look on the web if there is any related material with what you are doing
  
• Check if your design is correct
• Look at the code you have written carefully
• Try explaining to yourself what you have done, or even better, ask someone else to sit beside you and explain to that person what you are trying to do and how you figured you would do it.
• If you have spent hours trying to find an error but didn't find it, stop debugging and do something else.
  
  

While writing code...

• Keep your code clean and simple.
• Write short and precise comments.
• Keep versions of your operating system. If you mess up the code, you can always rollback to the previous version.
• Write batch files for common actions you make like compiling and copying your operating system to your floppy disk.
• Keep versions of your operating system. If you mess up the code, you can always rollback to the previous version and start all over again

Links

The web is an invaluable tool for projects on operating systems. Besides the ones included above, here are some other important links:
Mutex is a modification of the operating system Josh, which can be accessed at http://www.ansanest.com/josh/ We strongly advice that you read the tutorial too.
http://www.geocities.com/mvea/bootstrap.htm Tutorial on how to write a boot loader. Mutex uses this bootloader.
http://osdever.net/ Tutorials, tools to download, forums .. A nice place to start designing an operating system.
http://webster.cs.ucr.edu/AsmTools/NASM/ You can find NASM here along with a complete documentation for it.
http://www.cse.unl.edu/~jgompert/OS/TableOfContents.htm A hello world operating system, shows you the basics
http://people.msoe.edu/~sebern/courses/cs384/papers97/buttron.pdf FAT12 file system specification
http://www.acm.uiuc.edu/sigops/roll_your_own/ A very good tutorial on how to write your own operating system

Part 6 Acknowledgement

We would like to express our gratitude for those who have helped us on this tough project.
Mr. Jacob Elisoff, our advisor on the project has thought us a lot about project management. He always pulled us out when we have drowned ourselves in unnecessary complications. He has also assisted us on making this documentation more useful through his valuable comments.
Dr. Dawit Bekele has given us the initiative to start the project along with Mr. Jacob E.
Ato Abate Tibebu, Ato Biniam Selemon and Ato Tewodros Negussie were extremely tolerant with our constantly annoying requests. They have provided us most of the materials we required in the project.
Ato Setegn Shanko has readily allowed us to make Mutex files and this documentation available to everyone.
Student Yared Getachew has been very helpful preparing sample programs for testing.

Part 7 Contact information

If you have any questions, suggestions or comments, please don't hesitate to contact us at one of the following addresses:

     tadesse_kf  at  yahoo  dot  com
     tilayeyismaw  at  yahoo  dot  com