This manual has the purpose of helping software developers understand how they should be using Pure64 to load their kernel.

This manual assumes you have some understanding of a typical boot process.

You'll have to have NASM installed to build the software.

In the top directory of Pure64, just run the following:

./build.sh

A computer with at least one 64-bit Intel or AMD CPU (or anything else that uses the x86-64 architecture)

At least 2 MiB of RAM

The ability to boot via a hard drive, USB stick, or the network

Here's a minimal kernel, written for NASM, that you could use with Pure64. Once it's loaded, it enters an infinite loop. The file can be called kernel.asm.

BITS 64
ORG 0x100000

start:
	jmp start

The ORG statement tells NASM that the code should be made to run at the address, 0x100000.

Assemble it like this:

nasm kernel.asm -o kernel.bin

Here's a similar example written in C with GCC. The file can be called kernel.c.

void _start(void) {

	for (;;) {

	}
}

The kernel needs a linker script to be loaded to 1 MiB, replacing NASMs ORG instruction. The file can be called kernel.ld.

OUTPUT_FORMAT("binary")
OUTPUT_ARCH("i386:x86-64")

SECTIONS
{
    . = 0x100000;
    .text : {
        *(.text)
    }
    .data : {
        *(.data)
    }
    .rodata : {
        *(.rodata)
    }
    .bss : {
        *(.bss)
    }
}

Compile is like this:

gcc -c kernel.c -o kernel.o -mno-red-zone -fno-stack-protector -fomit-frame-pointer
ld -T kernel.ld -o kernel.bin kernel.o

The flags added to the first command are there to help GCC produce could that will run in kernel space. The second command simply takes kernel.o and orders it as the linker script tells it to.

The _start symbol must always appear first within flat binaries as Pure64 will call the start of the file so it must contain executable code. Function definitions (such as inline ones) in header files could interfere with the placement of the _start symbol. The best solution is to put the entry point in a separate file that calls the main function. Such a file could be called start.c.

extern int main(void);

void _start(void)
{
    main();
}

This file would always have to be linked in front of everything else. For the above example that would mean the linker command above would have to become:

ld -T kernel.ld -o kernel.bin start.o kernel.o

After creating a kernel this is a possible routine to create a bootable image. The commands require Pure64 to be build and pure64.sys and mbr.sys to be in the same directory as your kernel with the name kernel.bin

dd if=/dev/zero of=disk.img count=128 bs=1048576
cat pure64.sys kernel.bin > software.sys

dd if=mbr.sys of=disk.img conv=notrunc
dd if=software.sys of=disk.img bs=512 seek=16 conv=notrunc

After creating a bootable image it can be tested using qemu: qemu-system-x86_64 -drive format=raw,file=disk.img

This memory map shows how physical memory looks after Pure64 is finished.

When creating your Operating System or Demo you can use the sections marked free, however it is the safest to use memory above 1 MiB.

Pure64 stores an information table in memory that contains various pieces of data about the computer before it passes control over to the software you want it to load.

The Pure64 information table is located at 0x0000000000005000 and ends at 0x00000000000057FF (2048 bytes).

A copy of the E820 System Memory Map is stored at memory address 0x0000000000006000. Each E820 record is 32 bytes in length and the memory map is terminated by a blank record.