diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/assembly-programming.md | 28 | ||||
| -rw-r--r-- | doc/internal/gdt.txt | 7 | ||||
| -rw-r--r-- | doc/internal/mem.txt | 23 | ||||
| -rw-r--r-- | doc/internal/ple.txt | 12 | ||||
| -rw-r--r-- | doc/ints.txt | 30 |
5 files changed, 92 insertions, 8 deletions
diff --git a/doc/assembly-programming.md b/doc/assembly-programming.md new file mode 100644 index 0000000..78f81ac --- /dev/null +++ b/doc/assembly-programming.md @@ -0,0 +1,28 @@ +# Assembly Programming on Portland + +Assembly programming on Portland OS works pretty similarly to other OS's, but the linking phase varies in order to get the proper Portland Executable format for the output. + +## Portland-specific quirks + +The linker script used in the "Compiling and linking" section only recognizes `.text`, `.rodata`, `.data` and `.bss` sections, so please only use these. All of these except `.bss` are treated the same when the executable is loaded, so it doesn't really matter which section you put anything in except for alignment considerations, but it is still helpful for debugging and for readability to put things into the proper sections. This linker script provides a symbol `__pl_length` at the end of the `.data` section, used for generating the PLE header, so don't name any symbols this. + +## Portland ABI + +At program startup¸ we are in 32-bit protected mode in ring 3. The data and stack segments are equal, and these and the code segment refer to a region of memory containing `.text`, `.rodata` and `.data` (all three loaded verbatim from the executable) at address zero, followed by an uninitialized region of memory the size of `.bss`. The stack pointer is initialized to the end of this region, and the instruction pointer is initialized to the `_entry` label. + +See `ints.txt` for information about system calls. + +## Compiling and linking + +The following commands are used to compile and link an (NASM) assembly program into a Portland Executable. Replace the parts in all caps (except the `-O` argument to `objcopy`) with the relevant file names. The `user_elf.ld` file can be found at `src/user-elf.ld` in the kernel repository. + +``` +nasm -f elf32 SOURCE_FILE_1.asm -o SOURCE_FILE_1.o +nasm -f elf32 SOURCE_FILE_2.asm -o SOURCE_FILE_2.o +... + +ld -T user_elf.ld SOURCE_FILE_1.o SOURCE_FILE_2.o ... -o PROGRAM.elf +objcopy -O binary PROGRAM.elf PROGRAM.ple +``` + +After running each of these commands, `PROGRAM.elf` is a regular 32-bit ELF file containing the compiled program, with symbol table and all, useful for debugging. The `.ple_head` section contains the PLE header placed at the start of the executable by `objcopy`, and can be ignored when examining the ELF file. The `PROGRAM.ple` file is an executable file that can be run by Portland OS.
\ No newline at end of file diff --git a/doc/internal/gdt.txt b/doc/internal/gdt.txt index 0a8b5ea..26f7be9 100644 --- a/doc/internal/gdt.txt +++ b/doc/internal/gdt.txt @@ -1,2 +1,5 @@ -0x08: 0x0000.0000 - 0x0007.ffff (code) -0x10: 0x0000.0000 - 0x000f.ffff (data)
\ No newline at end of file +0x08: 0x0000.0000 - 0x0003.7fff (code) +0x10: 0x0000.0000 - 0x1fff.ffff (data) +0x18: task +0x20: user code +0x28: user data
\ No newline at end of file diff --git a/doc/internal/mem.txt b/doc/internal/mem.txt index d8b9913..0819fb7 100644 --- a/doc/internal/mem.txt +++ b/doc/internal/mem.txt @@ -1,6 +1,17 @@ -0x0001.0000 - 0x0001.ffff (64k): unused -0x0002.0000 - 0x0002.7fff (32k): fat -0x0002.8000 - 0x0002.bfff (16k): unused -0x0002.c000 - 0x0002.ffff (16k): 32 file buffers -0x0003.0000 - 0x0003.7fff (32k): kernel -0x0003.8000 - 0x0003.ffff (32k): kernel stack
\ No newline at end of file +0x0000.4000 - 0x0000.4003 (4): bootloader info + 0x0 byte: support flags + 0x80: PCI + 0x1 byte: PCI "hardware characteristics" + 0x2 byte: PCI minor + 0x3 byte: PCI major + 0x4 byte: last PCI bus + +0x0000.4200 - 0x0000.42ff (256): VESA info +0x0000.4300 - 0x0000.43ff (256): VBE strings + +0x0001.0000 - 0x0001.1fff (8k): memory map + +0x0003.0000 - 0x0003.7fff (32k): kernel +0x0003.8000 - 0x0003.ffff (32k): kernel stack + +0x1000.0000 - 0x1fff.ffff (256M): dynamic memory
\ No newline at end of file diff --git a/doc/internal/ple.txt b/doc/internal/ple.txt new file mode 100644 index 0000000..1bcceb4 --- /dev/null +++ b/doc/internal/ple.txt @@ -0,0 +1,12 @@ +Portland Executable Format + +0x00 magic dword 0xb9ba4c50 +0x04 minor version word 0x0000 +0x06 major version word 0x0000 +0x08 payload file offset dword +0x0c payload length dword +0x10 bss length dword +0x14 virtual entry point dword + +Payload loaded at start of cs=ds=ss. +bss after payload, esp set to end of bss.
\ No newline at end of file diff --git a/doc/ints.txt b/doc/ints.txt new file mode 100644 index 0000000..1da08fd --- /dev/null +++ b/doc/ints.txt @@ -0,0 +1,30 @@ +int 0x30 - exit task +int 0x31 - yield to scheduler +int 0x33 - extend data section by eax bytes + actual amount extended returned in eax + +int 0x32 - system call +system call number in eax +args in ebx, ecx, edx, esi, edi +result in eax + + function | eax | eax out | ebx | ecx | edx | esi | edi +---------------|-----|-----------|---------------|--------|--------|-----|----- + vga_blank | 0x0 | | | | | | + vga_set_color | 0x1 | | color | | | | + vga_printch | 0x2 | | char | | | | + vga_printsz | 0x3 | | sz string | | | | + vga_printsn | 0x4 | | non-sz string | length | | | + | | | | | | | + fs_open | 0x5 | handle | path | | | | + fs_open_root | 0x6 | handle | | | | | + fs_new | 0x7 | handle | path | | | | + fs_close | 0x8 | | handle | | | | + fs_delete | 0x9 | | path | | | | + fs_exists | 0xa | does | path | | | | + fs_seek | 0xb | seeked by | handle | by | | | + fs_tell | 0xc | position | handle | | | | + fs_read | 0xd | read | handle | max | buffer | | + fs_write | 0xe | written | handle | max | buffer | | + | | | | | | | + plef_run | 0xf | handle | image path | | | |
\ No newline at end of file |