NavigateBooting Running Extra |
The MikeOS User HandbookFor version 4.7, 9 April 2022 - (C) MikeOS DevelopersThis documentation file explains how to boot and use the MikeOS operating system on a real PC or an emulator. If you have just downloaded MikeOS and want to run it, this is the guide you need. If you have any questions, see the MikeOS website for contact details and mailing list information. Click the links on the left to navigate around this guide. BootingDisk imagesAfter you have extracted the MikeOS .zip file, switch into the disk_images/ directory and you'll see three files:
So, these files are virtual disk images that you can write to real floppy disks or CD-Rs, or run in a PC emulator as described in a moment. WritingFor running MikeOS on a real PC, you will need to write one of the virtual disk images to physical media. If you have a USB key then this is simple -- we can write the floppy disk image to the USB key, and the PC will boot it like a virtual floppy. On Linux, insert your USB key and unmount it when it appears (but don't remove it). Then open a command line window and enter dmesg to view the kernel messages. You will see an indication at the end of the messages of the device you just plugged in -- eg /dev/sdb. Note that you just need the device, eg /dev/sdb, rather than the number (eg /dev/sdb1). Then enter (in the disk_images directory): dd if=mikeos.flp of=/dev/sdb Of course, replace sdb with the device node. The key is now ready for booting. On Windows, download the open source Flashnul program, plug in your USB key and enter flashnul -p to get a list of drives. When you've spotted your USB key, enter flashnul [number] -L mikeos.flp (in the disk_images directory), replacing [number] with the number you got before. The key is now ready for booting. Note: if you plug your USB key back into the machine, the operating system may try to alter the partition structure and stop it from working properly. So treat it as a MikeOS-only key until you want to reformat it for normal use. For floppy disks, on Windows you can use a program called RawWrite to copy mikeos.flp to a floppy disk. On Linux, use the dd utility like this: dd if=mikeos.flp of=/dev/fd0 If you want to run MikeOS on a machine that doesn't have a floppy drive and doesn't boot from USB keys, you can burn and boot the mikeos.iso CD image. Any decent Windows CD burning software will allow you to write an ISO image to a CD-R; if you don't have one, try InfraRecorder. On Linux, a graphical burning program such as K3b should do the trick, or you can use the command line: cdrecord -dao dev=/dev/cdrom mikeos.iso Real PCsAt a minimum, any 386 PC with 1MB of memory and a keyboard should be able to run MikeOS. In fact, you may be able to get it running on an older machine -- please do let us know if so! Just start your PC with the MikeOS floppy, CD-ROM or USB key inserted, and you should see the initial dialog screen. On some systems, you may need to change the boot order in your BIOS so that the PC boots from the floppy, CD or USB key rather than the hard drive. EmulatorsA quick way to try MikeOS, and one that doesn't involve writing disk images to physical media, is to use an emulator. This is particularly useful if you're writing MikeOS software or changing the OS as described in the other two Handbooks. Some of the best emulators:
For VirtualBox and VMware, configure the boot device to use the MikeOS floppy disk or CD ISO image. With QEMU on Linux, run test-linux.sh, or for QEMU on Windows switch into the directory where you installed the emulator and enter: qemu.exe -L . -m 4 -boot a -fda mikeos.flp -soundhw all -localtime You will need to change the path to mikeos.flp accordingly. RunningUsageWhen MikeOS starts up, you'll see a dialog box which gives you the option of a program list of a command line interface. Using the cursor keys and Enter, choose OK for the former and Cancel for the latter. In the program list you can select a .BIN or .BAS program with the up/down cursor keys and hit Enter to run it. Also, you can press Esc to return back to the original list/CLI selection screen. At the command line, enter DIR to show a list of programs, and HELP to display inbuilt commands. You can run a program by entering the full filename (eg EDIT.BIN) or just the name without the extension (eg EDIT). There are also file management commands such as COPY, REN, DEL and SIZE. ProgramsMikeOS includes several programs to perform various tasks and demonstrate features of the OS, such as:
Note that FILEMAN.BIN and EDIT.BIN try to write to the floppy drive, so if you've booted from a CD-R and try to manipulate files you will see write errors as it's a read-only medium after burning. Copying filesIf you've written MikeOS to a real floppy disk, you can just copy extra files onto that disk in your file manager. But if you want to add files to the floppy disk images, that requires a bit of extra work -- you need to access the disk image as if it was a real floppy. First up is Linux: switch to the MikeOS main directory, then enter the following commands as root: mkdir looptmp mount -o loop -t vfat disk_images/mikeos.flp looptmp Now the contents of the MikeOS virtual floppy disk image are accessible in the newly-created looptmp/ directory. (We have loopback-mounted the disk image onto our filesystem.) Copy your programs into that directory, for example: cp MYPROG.BIN looptmp/ When you're done, unmount the virtual floppy image and remove the temporary directory: umount looptmp rm -rf looptmp You can now write mikeos.flp to a floppy disk or boot it in an emulator. If you want to recreate the CD ISO image, run build-linux.sh as root; this will update mikeos.iso with the new floppy contents. If you're running Windows, you will need a special program to access mikeos.flp as if it was a real floppy. One tool you can use is the ImDisk Virtual Disk Driver; download and run it to install. You can then mount the floppy disk image like this: imdisk -a -f mikeos.flp -s 1440K -m B:Copy your files into the B: drive. When you are finished, enter: imdisk -d -m B: Now the files that you copied to B: have been written into mikeos.flp. MonitorYutaka Saito has contributed a MikeOS program that lets you enter machine code in hexadecimal format and execute it. Run MONITOR.BIN from the command line and you'll be presented with a '=' prompt. Now you can enter your instructions, or just 'x' to exit back to the OS. MikeOS programs are loaded at the 32KiB (32768) point. The monitor converts hex code and executes it at location 36864 in RAM -- that is, 4KiB after the where the monitor program is loaded. This is so that your code doesn't overwrite the monitor! Consequently, any code you run should be ORGed to 36864. For example, this is a small MikeOS program which displays the letter 'M' on the screen. After we've assembled it, we can run ndisasm on the resulting binary to see the hexadecimal codes:
(The first three lines are merely assembly directives, so they don't generate any code.) Now that we have the hex codes, we can enter them into the monitor. Note that the code must be terminated with a dollar sign ($) character, and spaces are allowed. So, you can enter at the '=' prompt: BE0790 E8FD6F C3 4D00$ When you enter this, the monitor will convert the hex codes to machine code at location 36864 in RAM, and call that location to execute it. (Just like normal MikeOS programs, you should finish with a ret instruction.) After execution, you'll be returned to the monitor. You can then enter 'r' to re-run the converted code, or 'x' to exit. Serial portYou can use MikeOS as a Minicom-like serial terminal emulator with TERMINAL.BIN. This lets you connect a MikeOS machine to, for instance, a UNIX machine, and operate the UNIX machine from MikeOS. Connect a serial (null-modem) cable between the two machines, then set up your UNIX machine with a terminal session on the serial port. For instance, if you have a Linux machine, you would add a line like this to /etc/inittab: T0:2345:respawn:/sbin/getty/ -L ttyS0 9600 vt100 When you restart your Linux machine, it will wait for a login on the serial port. Connect the null-modem cable to a MikeOS machine, and run TERMINAL.BIN in MikeOS. You can now enter your username and password to log in. Note that MikeOS configures the serial port to be 9600 baud, no parity, 8 data bits, 1 stop bit. If you wish to change these settings, edit source/features/serial.asm and see the port port setup code at the start of the file (then rebuild MikeOS as described in the System Developer Handbook). Also note that only a handful of VT100 commands have been implemented at present, so programs which do complicated things with the screen (such as Emacs) may not display properly. To exit the program, press the F8 key. (You can change this to a different key by editing the source code near the start of programs/terminal.asm.) ExtraHelpIf you have any questions about MikeOS, or you're developing a similar OS and want to share code and ideas, go to the MikeOS website and join the mailing list as described. LicenseMikeOS is open source and released under a BSD-like license (see doc/LICENSE.TXT in the MikeOS .zip file). Essentially, it means you can do anything you like with the code, including basing your own project on it, providing you retain the license file and give credit to the MikeOS developers for their work. |