From 24bafb897b71f569acc710eac82cebb3bb3e64b1 Mon Sep 17 00:00:00 2001 From: bemxio Date: Wed, 11 Sep 2024 16:57:03 +0200 Subject: [PATCH] add more information to the readme --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 394a50d..ae9c0ba 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,57 @@ # Gicho -*Gicho* (기초, "basic" in Korean) is a simple operating system running in 16-bit real mode. Written in C and Assembly, made for learning purposes and for fun. +*Gicho* (기초, "basic" in Korean) is a simple operating system running in 16-bit real mode. Written in C and Assembly, made primarily for learning purposes and for fun. -It has a CLI interface that supports basic low-level commands like `peek`, `poke`, etc. It can also run external code from a disk. +It has a CLI interface that supports basic low-level commands like `peek` and `poke`. It can also call BIOS interrupts, read and write data from/to a disk, as well as execute other programs. ## Building To build Gicho, you will need a couple of prerequisites: -- A Linux host - on Windows, you can use [WSL](https://docs.microsoft.com/en-us/windows/wsl/install) or a virtual machine. -- [`gcc-ia16`](https://github.com/tkchia/gcc-ia16) - a GCC cross-compiler for the kernel. If you use Arch Linux, you can install it from the [AUR](https://aur.archlinux.org/packages/gcc-ia16), otherwise you'll probably need to build it from source. -- [NASM](https://www.nasm.us) - an assembler for the bootloader. You should be able to install it from your package manager. -- [QEMU](https://www.qemu.org) (optional) - an emulator to run the OS. It should also be available in your package manager. +- **A Linux host system** - while it is theoretically possible to set up the environment on other OSes, it is not supported. On Windows, you can use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). +- **[`gcc-ia16`](https://github.com/tkchia/gcc-ia16)** - if you're on an Arch-based distro, you can install it from the [AUR](https://aur.archlinux.org/packages/gcc-ia16). Otherwise, you'll probably need to build it from source. +- **[GNU make](https://www.gnu.org/software/make)** - you should be able to install it from your package manager, e.g. `apt install make` for Debian-based distros. +- **[NASM](https://www.nasm.us)** - it should also be available in your package manager. +- **[QEMU](https://www.qemu.org) (optional)** - in case you want to run or debug the OS, it's recommended to use QEMU. Like with Make and NASM, the package manager should have it. -Once you have all the prerequisites, simply clone the repository, and then run `make` in the root directory of the project. This will create a `gicho.bin` file in the `build` directory. +1. Get the source code. You can either download the ZIP archive by pressing the *Code > Download ZIP* button, or clone the repository with [Git](https://git-scm.com) by running `git clone https://github.com/bemxio/gicho`. +2. Ensure all variables in the [`Makefile`](Makefile) are correct. You can change GCC, NASM, and QEMU paths if they are different on your system, as well as the path of the disk image. +3. Run `make` in the root directory of the project. This will compile the kernel and the bootloader, link them together, and create an image file you can run. -If you installed QEMU, you can launch Gicho by running `make run`. +## Running +### QEMU +The [`Makefile`](Makefile) has a target for running the OS in QEMU. If you installed it earlier, just run `make run` and it should start Gicho up in a new window. -## Contributing -Contributions are welcome! If you want to contribute, whether it's just a simple question or a whole pull request, feel free to do so. +In case you want to start it up manually, you can execute the following command: +```sh +qemu-system-i386 -drive file=,format=raw +``` +with `` being the path to the disk image. By default, it's `build/gicho.img`. + +### VirtualBox +It is also possible to run Gicho in VirtualBox. To do so, create a new VM, set whatever settings you want, then go to the *Storage* tab in the settings, add a floppy controller and attach the disk image to it. Start the VM and it should boot right up. + +### Real Hardware +Gicho is a hit-or-miss when it comes to running on real hardware. **It is unable to run on UEFI PC's with no legacy boot support.** If you have a computer that supports it, you can write the image file onto a USB drive using tools like [`dd`](https://www.gnu.org/software/coreutils/dd) or [balenaEtcher](https://www.balena.io/etcher), and then boot from it. + +Here's an example of how to write the image using `dd`: +```sh +dd if= of=/dev/sdX status=progress +``` +where `` is the path to the disk image and `/dev/sdX` is the USB drive. **Make sure you have specified the correct device, as this command will overwrite data on it.** + +## Usage +Gicho has 9 available commands: +- `help` - displays a list of available commands. +- `echo [text]` - prints the specified text to the screen. +- `clear` - clears the screen. +- `peek
` - reads a byte at a specified address in memory. +- `poke
` - writes a byte to the specified memory address. +- `int [registers]` - calls a BIOS interrupt with optional register values, in the format of space-separated assignments (e.g. `ah=0 al=0x03 bx=0x0449`). +- `read [offset] [memory address]` - reads sectors from a disk into memory. By default, the offset is 0 and the memory address is `0x7e00`. +- `write [memory address] [offset]` - writes sectors from memory to a disk. THe defaults are the same as for `read`. +- `run [address]`- executes a program at the specified address. By default, it's `0x7e00`. + +The image file contains two sample programs, `hello.asm` and `rainbow.asm`. You can run them by first reading them into memory by running `read 0x80 1 18`, then executing one of them with the `run` command for `hello.asm` and `run 0x7e29` for `rainbow.asm`. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +Contributions are welcome! If you want to contribute, whether it's an issue you've encountered or a pull request with new features, feel free to do so. \ No newline at end of file