diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/assembly-programming.md | 28 | ||||
| -rw-r--r-- | doc/internal/gdt.txt | 5 | ||||
| -rw-r--r-- | doc/internal/mem.txt | 23 | ||||
| -rw-r--r-- | doc/internal/ple.txt | 12 | ||||
| -rw-r--r-- | doc/ints.txt | 52 | ||||
| -rw-r--r-- | doc/keys.txt | 42 |
6 files changed, 86 insertions, 76 deletions
diff --git a/doc/assembly-programming.md b/doc/assembly-programming.md deleted file mode 100644 index 78f81ac..0000000 --- a/doc/assembly-programming.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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 deleted file mode 100644 index 26f7be9..0000000 --- a/doc/internal/gdt.txt +++ /dev/null @@ -1,5 +0,0 @@ -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 0819fb7..c5f5e8b 100644 --- a/doc/internal/mem.txt +++ b/doc/internal/mem.txt @@ -1,17 +1,28 @@ -0x0000.4000 - 0x0000.4003 (4): bootloader info +0x0000.4000 - 0x0000.4007 (8): bootloader info 0x0 byte: support flags 0x80: PCI + 0x40: PAE 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 + 0x6 word: BIOS memory map length -0x0001.0000 - 0x0001.1fff (8k): memory map +0x0000.4f98 - 0x0000.4fff (104): TSS +0x0000.5000 - 0x0000.5fff (4k): kernel page directory -0x0003.0000 - 0x0003.7fff (32k): kernel +0x0001.0000 - 0x0001.ffff (64k): BIOS memory map + +0x0003.0000 - 0x0003.7fff (32k): kernel text, data, rodata 0x0003.8000 - 0x0003.ffff (32k): kernel stack +0x0004.0000 - 0x0005.ffff (128k): pagemap + +0x000a.0000 - 0x000f.ffff (384k): VGA and BIOS memory + +0x0040.0000 - 0x007f.ffff (4M): kernel page tables + +0x00f0.0000 - 0x00ff.ffff (1M): ISA memory -0x1000.0000 - 0x1fff.ffff (256M): dynamic memory
\ No newline at end of file +0x0400.0000 - 0x07ff.ffff (64M): kernel heap, bss pages +0x0800.0000 - 0xffff.ffff (rest): user pages, hardware memory
\ No newline at end of file diff --git a/doc/internal/ple.txt b/doc/internal/ple.txt deleted file mode 100644 index 1bcceb4..0000000 --- a/doc/internal/ple.txt +++ /dev/null @@ -1,12 +0,0 @@ -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 index 1da08fd..2a97049 100644 --- a/doc/ints.txt +++ b/doc/ints.txt @@ -1,30 +1,32 @@ -int 0x30 - exit task -int 0x31 - yield to scheduler -int 0x33 - extend data section by eax bytes - actual amount extended returned in eax +quit task is int 0x38 -int 0x32 - system call + +yield task is int 0x39 +eax is cleared on yield + + +syscall is int 0x30 system call number in eax args in ebx, ecx, edx, esi, edi result in eax + note: do not assume eax is unmodified if there is no value to be returned +modifies ecx, edx + +file system calls have units of bytes unless otherwise specified +functions returning handles or pointers use 0 to indicate error +functions returning "success" use 1 for success and 0 for failure +see keys.txt for the return type of the "get key" system call + +invalid system call numbers change eax to -1, and have no other effect. + - 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 + function | eax | eax out | ebx | ecx | edx | esi | edi +---------------|-----|---------------|---------------|-------------|-------|--------|----- + open file | 0x0 | handle | drive number | path | | | + close file | 0x1 | | handle | | | | + file read | 0x2 | read | handle | file offset | count | buffer | + get file size | 0x3 | size | handle | | | | + start task | 0x4 | success | drive number | path | | | + log string | 0x5 | | sz string | | | | + get key | 0x6 | keycode | | | | | + allocate ram | 0x7 | start pointer | pages | | | |
\ No newline at end of file diff --git a/doc/keys.txt b/doc/keys.txt new file mode 100644 index 0000000..a083eba --- /dev/null +++ b/doc/keys.txt @@ -0,0 +1,42 @@ +keycodes are 32-bit integers. + +the low byte indicates the key itself. for printable characters (and keys with +reasonable translations to ascii control codes), this is the ascii code. for +other ones, something in the range of 0x80 to 0xff is used, seen in table 1. + +the top 24 bits indicate several flags. these are seen in table 2, where bit 0 +is the lowest bit of the second lowest byte of the keycode, and bit 23 is the +highest bit of the highest byte of the keycode. + +the "get key" system call returns 0 if there is not a key available. it is +recommended to make the system call and, if it returns 0, yield to the scheduler +and then loop back to making the system call. this way your task does not block +the cpu while waiting for keyboard input. see the "get_key_char" function in +user.c of the "knob" library for an example of this. + + +table 1: + + code | key +------|----- + 0x80 | + .... | + 0xff | + +table 2: + +bit 0: left shift +bit 1: right shift +bit 2: caps lock +bit 3: insert +bit 4: num lock +bit 5: scroll lock +bit 6: left alt +bit 7: right alt +bit 8: left control +bit 9: right control +bit 10: left meta +bit 11: right meta + +bits 12-23 are reserved for future versions. in this version, they should be set +to zero when giving a keycode, and should be ignored when recieving a keycode.
\ No newline at end of file |