Disclaimer

I take no responsability for any problems a user might have on following this gist. This includes university problems.

The motivation for this is to document, as dummy-oriented as possible, a way to setup and add a system call to Minix OS. This is a classic assignment at Operational Systems classes (and is pretty cool tbh)

Configuration:

ISO used: minix_R3.3.0-588a35b.iso
Download: http://download.minix3.org/iso/minix_R3.3.0-588a35b.iso.bz2

md5: 78cc6093bc9e68c74f32f37e144451bd
SHA256: 389be8cbc2b74022671c082d0b88511b17e63b18003a14647b03331e3467b4c4

Virtualization software used: VirtualBox 5.0.40_Ubuntu r115130
Configurations:

Name: minix
Type: Other, Version: Other/Unknown
1 GB ram
VDI (Fixed size, 6 GB)

Installation

Insert the ISO in your virtualized machine and power it on
Enter root
Enter setup
Press enter to continue
Enter your keyboard layout (I'm using without any problems an irish keyboard with uk layout)
Press enter to continue until prompted on a yes/no question, then you enter yes
When prompted to reboot, type poweroff to shutdown the system instead
Remove the ISO from your virtualized machine

The system is now installed. You can boot the virtual machine and enter root to log as root user. Any command below is expected to be ran as root unless stated.

Before anything else...

...update the pkgin packages:

pkgin update

C utilities

Installing binutils, clang, nano (if you're hacky, you can install vim instead of nano)

pkgin install binutils clang nano

Optional: installing Vim: (Vim is nicer, but further instructions will support Nano instead)

pkgin install vim
printf 'set backspace=indent,eol,start' >> /root/vim.rc # fix backspace behaviour

And from now, you can write text (or source codes) with nano and compile C source code with Clang.
e.g.:

nano hello_world.c
# edit a hello_world program, ctrl-x to exit, Y to save, enter to confirm
clang hello_world.c -o hello_world
./hello_world

Create a new user (optional but recommended)

Add a new user and set a password for it (because you know, safety) (password is semi-mandatory for using SSH, just do it)

useradd -m giba_god # giba_god is only an example whose name reflects the truth
passwd giba_god

OpenSSH (optional)

Installing openssh and running it and setting it to start automatically

pkgin install openssh
printf 'sshd=YES\n' >> /etc/rc.conf # enable SSH daemon
/usr/pkg/etc/rc.d/sshd start # start SSH

Optional: allowing to SSH into root (not recommended)

printf 'PermitRootLogin yes' >> /usr/pkg/etc/ssh/sshd_config # useful in case you opted for not creating another users besides root

Setting a root password (recommended. Semi-mandatory for using ssh into root)

passwd root

Now Minix is running a SSH server. That means you can connect to it from other clients (e.g.: from your Windows)

Connecting via SSH from host OS (optional)

Instructions below are for VirtualBox

If host OS is Linux:

VBoxManage modifyvm "<YOUR VM NAME GOES HERE>" --natpf1 "guestssh,tcp,,2222,,22" # my VM name is minix, but yours may be different
ssh -l <USERNAME> -p 2222 localhost

And now you are connected remotely to your Minix! Huzzah!

If host OS is Windows:

With cmd on VirtualBox folder

VBoxManage modifyvm "<YOUR VM NAME GOES HERE>" --natpf1 "guestssh,tcp,,2222,,22" # my VM name is minix, but yours may be different

Close cmd. Download and open PuTTY
On Connection>Data, change 'Auto-login username' to the user you want to connect to (e.g.: root)
On Session, type 'localhost' on 'Host Name' and '2222' on port and connect

And now you are connected remotely to your Minix! Huzzah!

Getting Minix source code

For whatever reason, Minix source files are NOT included since 3.3 (am I right?). To get them, follow bellow

pkgin install git-base
cd /usr/pkg/etc/rc.d/
rm kadmind kcm kdc kpasswdd # these files may cause a bunch of errors, see https://groups.google.com/forum/#!topic/minix3/HrQe7xJbnDQ
git clone git://git.minix3.org/minix /usr/src
cd /usr/src
git checkout v3.3.0 # we do not want to mess with bleeding edge code (do we?)

Now you have Minix source on your system! Huzzah!
You can add system calls to it, recompile it, and have fun with it!

To The Action!

(a.k.a. modifiying and recompilling the system)

pkgin install bmake gmake # netBSD make and GNU make are needed to recompile minix
# edit whatever you want into the system (refer to the other document provided to create system calls)
cd /usr/src
make build # this will recompile EVERYTHING. make services or make install may also work; more testing is needed

Info resources:

Good luck on your exams! :-)

Adding a simple systemcall to Minix's Process Manager (PM) server to print hardcoded text

https://github.com/Drowze/minix/commit/4dd321aab13a53ab3c534e0853832b930a84a272
After rebooting and compiling (with make build) you can test the new system call:

#include <lib.h>

int main() {
	message m; // Minix message to pass parameters to a system call
	_syscall(PM_PROC_NR, WHOSTHERE, &m);
}

Adding a more complex system call, to print the maximum common divisor between two numbers

https://github.com/Drowze/minix/commit/03e4bcf4244f771056a9dc932db9345377f9cfe8
After rebooting and compiling (with make build) you can test the new system call:

#include <stdio.h>
#include <lib.h>

int main() {
	message m; // Minix message to pass parameters to a system call
	printf("n1: ");
	scanf("%d", &m.m1_i1);
	printf("n2: ");
	scanf("%d", &m.m1_i2);
	
	int mdc = _syscall(PM_PROC_NR, MDC, &m);
	printf("The greatest common divisor between %d and %d is %d", n1, n2, mdc);
	
	return 0;
}

Adding a new library with a function with your system call inside of it

Objective: printf("%d", mdc(10, 15); and whosthere()

Implement whosthere() function:
https://github.com/Drowze/minix/commit/16b0e130a10efb282d6d8545a3277c4f86e1a7fa
Implement mdc() function:
https://github.com/Drowze/minix/commit/17289c32fc67c4fd50fa60a7d6c0d44e73a990b1

diogofurtado/minix_tutorial.md