\documentclass[a4paper, 11pt,oneside]{article}
\usepackage[
  top=1.5cm,
  bottom=1cm,
  left=2cm,
  right=1.5cm,
  headheight=25.22153pt, % as per the warning by fancyhdr
  includehead,includefoot,
  heightrounded, % to avoid spurious underfull messages
]{geometry} 

\usepackage[T1]{fontenc}
\usepackage{microtype}
\usepackage{fancyhdr}
\usepackage{fancyvrb}
\usepackage{lipsum}
\usepackage{url}
\usepackage{listings}
\usepackage{lastpage}
\usepackage{enumitem}
\usepackage{datetime}
\usepackage{minted}

\settimeformat{hhmmsstime}
\yyyymmdddate

\pagestyle{fancy}
\fancyhf{} % clear all fields

\pagestyle{fancy}
\lhead{CMSC 125: Operating Systems \\ First Semester 2023-2024}
\rhead{Institute of Computer Science \\ University of the Philippines Los Banos}
\rfoot{JACHermocilla | CC BY-NC-SA 4.0}
%\cfoot{Enjoy!:)}
\cfoot{\thepage\ of \pageref{LastPage}}
\lfoot{Revision: \today\ \currenttime}
%\rfoot{https://jachermocilla.org/teaching/125}
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}

\begin{document}

\begin{center}
	{\LARGE \textbf{ICS-OS Lab 01: Building and Booting ICS-OS}}
\end{center}

\section*{Objectives}
   At the end of this activity, you should be able to:
   \begin{enumerate}[itemsep=0pt,parsep=0pt]
   	   \item set up the build environment;
       \item build the kernel binary image;
       \item build the distribution floppy disk image; and
       \item boot ICS-OS and run two commands.
   \end{enumerate}   

\section{Introduction}
ICS-OS is an instructional operating system that can be used for understanding different operating system concepts.  An operating system is no different from other software in that it is written in a programming language, such as C. 

The build process creates the compressed kernel binary image (\texttt{vmdex}) and the floppy disk image (\texttt{ics-os-floppy.img}). Since ICS-OS has a relatively large number of source files, 
the \texttt{Make} utility is used for the build. You can examine the contents of \texttt{Makefile} 
to learn more of the details how this is done.

To start ICS-OS, the floppy disk image is set as the boot device in Qemu,  
an emulator for various machine microarchitectures. The floppy disk image 
contains the GRUB bootloader which transfers control to the ICS-OS kernel ( 
\texttt{vmdex}). After the boot process, a prompt is provided for users to 
enter commands. 

\section{Prerequisites}
The recommended development environment is Ubuntu 20.04 or later. The actual building of the kernel is done inside an Ubuntu 16.04 container. Familiarity with the command line is also needeed. GitHub Codespaces can also be used but will not have graphics support. Install the following packages on your local machine/VM or in Codespaces terminal after opening the repo. 

\begin{minted}[frame=single,framesep=10pt]{bash}
$sudo apt update
$sudo apt install qemu-system-x86 gcc-multilib git
\end{minted}


\section{Deliverables and Credit}
Perform the tasks below and capture screenshots while you do them. Submit a PDF 
file containing the screenshots with captions. Do not forget to put your name 
and laboratory section. Credit is five (5) points.

\section{Tasks}

\subsection*{Task 1: Install Docker and Docker-Compose}
\texttt{docker}\footnote{https://docs.docker.com/engine/install/ubuntu/} and 
\texttt{docker-compose}\footnote{https://docs.docker.com/compose/install/linux/\#install-using-the-repository} 
should be installed to build in the latest versions of Ubuntu (see footnote for 
links to the guides). Also perform the post-install steps\footnote{https://docs.docker.com/engine/install/linux-postinstall/}. 

In Codespaces, these are already installed.

\subsection*{Task 2: Clone the repository and explore the source tree}
ICS-OS\footnote{https://github.com/srg-ics-uplb/ics-os/} is open source and is 
hosted on Github. Run the following command to checkout the source code and 
explore the source tree. This step should be done if you are not using Codespaces.


\begin{minted}[frame=single,framesep=10pt]{bash}
$git clone https://github.com/srg-ics-uplb/ics-os.git ics-os-yourinitials
\end{minted}

In the command above, the source will be cloned in the \texttt{ics-os-yourinitials} directory. We will refer to this directory in this document as \texttt{\$ICSOS\_HOME}. You can also use the \texttt{export} command to define it as an environment variable.

We create a branch for lab01 to make code management easier.
\begin{minted}[frame=single,framesep=10pt]{bash}
$cd $ICSOS_HOME
$git checkout -b lab01
$git branch  #check that you are in the lab01 branch
\end{minted}


\subsection*{Task 3: Build ICS-OS kernel}
The build process must be done inside a docker container(an Ubuntu 16.04 environment). There is a 
\texttt{\$ICSOS\_HOME/ics-os/docker-compose.yml} and a 
\texttt{\$ICSOS\_HOME/ics-os/Dockerfile} that describe the build environment.

Open a new terminal. Start and enter the container using the commands below.

\begin{minted}[frame=single,framesep=10pt]{bash}
$cd $ICSOS_HOME/ics-os
$docker compose run ics-os-build
\end{minted}

You will be dropped to a root shell inside the container where you can perform 
the build. The \texttt{\$ICSOS\_HOME/ics-os} directory is mapped to 
\texttt{/home/ics-os} inside the container. Thus, you can perform the edits 
outside the container(in another terminal) and the changes will be reflected 
inside the build environment. The following steps will build the kernel image. 

\begin{minted}[frame=single,framesep=10pt]{bash}
:/#cd /home/ics-os
:/#make clean
:/#make
\end{minted}

Note that the details of the steps are in the 
\texttt{\$ICSOS\_HOME/ics-os/Makefile}.

\subsection*{Task 4: Create the disk and boot ICS-OS}
Open a new terminal. Build the boot floppy then start Qemu with the floppy 
image as boot device using the commands below. 

\begin{minted}[frame=single,framesep=10pt]{bash}
$cd $ICSOS_HOME/ics-os
$sudo make floppy
$make boot-floppy 
\end{minted}

In GitHub Codespaces, the following commands must be used since its harder to set up the GUI.
\begin{minted}[frame=single,framesep=10pt]{bash}
	$sudo make floppy
	$qemu-system-i386 -fda ics-os-floppy.img -curses 
\end{minted}



You should now see the GRUB boot menu. Simply press enter to boot ICS-OS. Note 
that the details of the steps are in the \texttt{\$ICSOS\_HOME/ics-os/Makefile}.

\subsection*{Task 5: Run ICS-OS commands}
Once the ICS-OS command prompt (\texttt{\%}) appears, type \texttt{help}. 
Examine the list of commands and run two of these commands. Do not forget 
to capture screenshots of the outputs.

\subsection*{Task 6: Cleanup}
To exit the build container. 
\begin{minted}[frame=single,framesep=10pt]{bash}
:/#exit
\end{minted}

Go back to the master branch of the source code.
\begin{minted}[frame=single,framesep=10pt]{bash}
$git checkout master
$git branch
\end{minted}

\section{Reflection}
Write some realizations and questions that crossed your mind while doing this 
lab. 

\end{document}