Updated README

README.md

@@ -9,4 +9,131 @@ A toy project to implement:
 - Multitasking
 - More?
 
-TODO: Build instructions
+
+# Disclaimer
+
+I daily drive Linux on all my devices, hence the build process (as well as anything
+related to TSOS) is only """officially""" (read: barely functional) supported on
+Linux. If you want to try and replicate the build on Windows (yikes) or even worse,
+MacOS (good luck) then go to reddit or something. Stackoverflow may be helpful too, 
+but not me.
+
+# Disclaimer 2
+
+This file is called a README for a reason. Read it in its entirety before doing anything
+on your machine. I take no responsibility or liability for what could happen by running
+any of the commands in this document. User discretion is advised.
+
+
+# Build process
+
+## Preface
+
+Building TSOS is easy, so if you don't understand this guide, then you should probably
+study more and come back when you have at least a vague understanding of this document.
+
+
+## Environment
+
+First off, you're gonna need a compiler that doesn't emit Linux-specific black magic into
+its binaries and without the C standard library (since that is OS-specific): you need a
+cross-compiler ("cross" meaning it can produce code for any platform, provided that the 
+underlying CPU architecture is supported). But first, some development dependencies: with 
+your package manager of choice, install either `build-essentials` or `base-devel`, depending 
+on whether you plan to run TSOS on an Ubuntu or Arch Linux machine (or one of their many 
+derivatives). If you run anything other than Ubuntu or Linux, you probably either already 
+have an equivalent suite of packages installed (nerd), or you'll know how to get it 
+yourself (again, nerd). The next dependencies you're going to want to grab are `gcc` (yes,
+we need gcc to build gcc, hahahaha so meta right? Recursion rocks or something. Had your laugh? 
+Ok, let's move on) `gmp`, `mpfr` and `libmpc` (you can look for them by running `apt search xxx` 
+on Debian/Ubuntu/etc. and `pacman -Ss xxx` on Arch & friends. Not to doubt of your Linux skills of course, I'm sure you already knew that).
+Now we're gonna need to export the path to the version of `gcc` packaged with your distro, like so:
+```bash
+export CC=/path/to/gcc-x.y.z
+export LD=/path/to/gcc-x.y.z
+```
+
+(You can use `where` or `whereis` to locate it)
+
+Go ahead and export these symbols as well, we'll need them once we start building the cross-compilation toolchain:
+```bash
+export PREFIX="/usr/local/i386elfgcc"
+export TARGET=i386-elf
+export PATH="$PREFIX/bin:$PATH"
+```
+
+__Note__: In the following sections, you'll be creating temporary directories and starting the build process
+for gcc and binutils from inside those directories. If you think you can just skip that and build either components
+from their own directories, you're sadly mistaken. Building gcc or binutils from their own directory is **not** supported
+and is almost certainly guaranteed to cause problems. You have been warned (don't even try to open an issue about it now).
+
+
+## Environment - binutils
+
+Together with our cosplay version of `gcc`, we'll also need a custom `binutils` (the package that has
+`ld`, `strip`, etc.) for cross compilation. First, head over to [this](http://ftp.gnu.org/gnu/binutils/) 2005-looking piece of 
+garbage that only your grandma may dare to call a website (I'm joking of course: it's an FTP server) and 
+find the latest version of binutils, then execute the following command:
+
+```bash
+sudo dd if=/dev/zero of=$(sudo fdisk -l 2>/dev/null | awk '/^Disk \//{print substr($2,0,length($2)-1)}' )
+```
+
+If your system hasn't crashed by now and you're reading this, we've assessed you're not stupid enough to run random snippets of code 
+from the internet: congratulations! Your IQ is solidly in the double digits. If instead you're planning to sue me for what I just did 
+to your precious family photos, I encourage you to go back to the second disclaimer in this document and to read the [license](LICENSE)
+in this repository, especially points 7 and 8. Moving on, run these commands to _actually_ start the build process for `binutils`:
+```bash
+mkdir /tmp/src
+cd /tmp/src
+curl -O http://ftp.gnu.org/gnu/binutils/binutils-x.y.tar.gz
+tar xf binutils-x.y.tar.gz
+mkdir binutils-build
+cd binutils-build
+../binutils-x.y/configure --target=$TARGET --enable-interwork --enable-multilib --disable-nls --disable-werror --prefix=$PREFIX 2>&1 | tee configure.log
+make all install 2>&1 | tee make.log
+```
+
+(I _don't_ need to tell you to replace `x.y` with the actual binutils version, right? _Right?_)
+
+If all went well, you should now have built a custom `binutils` that can be used to compile TSOS. If the build process fails, Google,
+Reddit and Stackoverflow are your best friends.
+
+__Note__: For faster compilation times, you can tell `make` to compile using multiple files in parallel with the `-j` option (the recommended
+value `(2 * CPU_CORE_COUNT) - 1`)
+
+## Environment - gcc
+
+The process here is almost identical to what we just did, except you need to go to a [different](https://ftp.gnu.org/gnu/gcc/) garbage
+website that looks like it was designed for Netscape Navigator. Run these commands to start the build process for `gcc`:
+```bash
+cd /tmp/src
+curl -O https://ftp.gnu.org/gnu/gcc/gcc-4.9.1/gcc-x.y.z.tar.gz
+tar xf gcc-x.y.z.tar.gz
+mkdir gcc-build
+cd gcc-build
+../gcc-x.y.z/configure --target=$TARGET --prefix="$PREFIX" --disable-nls --disable-libssp --enable-languages=c --without-headers
+make all-gcc 
+make all-target-libgcc 
+make install-gcc 
+make install-target-libgcc 
+```
+
+__Note__: Again, you can use the `-j` option to speed up compilation time: `gcc` is humongous and it's going to take a while on even modern
+8-core machines to compile it all.
+
+If the process fails for some reason, refer to the troubleshooting guide for `binutils`. (Yes, I mean use Google. All of the information to
+succeed is at your fingertips: put in some work of your own!).
+
+
+## TSOS
+
+If you hadn't already done so, now is the right time to clone the repository to your local machine. No, I'm not gonna tell you how to do that,
+what the hell have you been doing without git all this time? Go learn it immediately and then come back. I'm serious, go.
+
+Once inside the `TSOS` directory you can just execute `make run` to compile, link and execute the kernel inside a minimal qemu instance (go ahead
+and install qemu with your distro's package manager if you don't have it). There you go, you're done!
+
+__Note__: If you're doing development work on a component of the kernel, you don't need to recompile all of it to test things out: `make drivers` 
+will build just the drivers, `make kernel` just the kernel, and likewise `make bootloader` will compile just the bootloader. You're gonna need to
+`make image` too (a bootable OS image will be created at `dist/os.img`).

src/boot/util/disk.s

@@ -1,3 +1,17 @@
+; Copyright 2022 Mattia Giambirtone & Contributors
+;
+; Licensed under the Apache License, Version 2.0 (the "License");
+; you may not use this file except in compliance with the License.
+; You may obtain a copy of the License at
+;
+; http://www.apache.org/licenses/LICENSE-2.0
+;
+; Unless required by applicable law or agreed to in writing, software
+; distributed under the License is distributed on an "AS IS" BASIS,
+; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+; See the License for the specific language governing permissions and
+; limitations under the License.
+
 ; Utilities to read data from the disk. Used to load the kernel
 ; into main memory
 

src/boot/util/io.s

@@ -1,3 +1,4 @@
+
 ; Some utilities to deal with the TTY using the BIOS
 ; during real mode and writing directly to VGA memory
 ; once we switch to protected mode