diff options
Diffstat (limited to 'documentation/kernel-interface')
| -rw-r--r-- | documentation/kernel-interface/keys.txt | 78 | ||||
| -rw-r--r-- | documentation/kernel-interface/sockets.txt | 28 | ||||
| -rw-r--r-- | documentation/kernel-interface/syscalls.txt | 178 |
3 files changed, 284 insertions, 0 deletions
diff --git a/documentation/kernel-interface/keys.txt b/documentation/kernel-interface/keys.txt new file mode 100644 index 0000000..1b92afa --- /dev/null +++ b/documentation/kernel-interface/keys.txt @@ -0,0 +1,78 @@ +a key packet, as returned by the kernel, is a 32-bit value. the top +13 bits are currently reserved. the next 11 bits are flags as follows: + 0x040000: break (as opposed to make) + 0x020000: num lock is on + 0x010000: caps lock is on + 0x008000: right windows + 0x004000: left windows + 0x002000: right alt + 0x001000: left alt + 0x000800: right ctrl + 0x000400: left ctrl + 0x000200: right shift + 0x000100: left shift +the bottom 8 bits represent the key. for us qwerty, they are: + 0x00: reserved | 0x40: reserved | 0x80: reserved | 0xc0: reserved + 0x01: f9 | 0x41: , / < | 0x81: reserved | 0xc1: reserved + 0x02: reserved | 0x42: k / K | 0x82: reserved | 0xc2: reserved + 0x03: f5 | 0x43: i / I | 0x83: reserved | 0xc3: reserved + 0x04: f3 | 0x44: o / O | 0x84: reserved | 0xc4: reserved + 0x05: f1 | 0x45: 0 / ) | 0x85: reserved | 0xc5: reserved + 0x06: f2 | 0x46: 9 / ( | 0x86: reserved | 0xc6: reserved + 0x07: f12 | 0x47: reserved | 0x87: f7 | 0xc7: reserved + 0x08: reserved | 0x48: reserved | 0x88: reserved | 0xc8: reserved + 0x09: f10 | 0x49: . / > | 0x89: reserved | 0xc9: reserved + 0x0a: f8 | 0x4a: / / ? | 0x8a: reserved | 0xca: numpad / + 0x0b: f6 | 0x4b: l / L | 0x8b: reserved | 0xcb: reserved + 0x0c: f4 | 0x4c: ; / : | 0x8c: reserved | 0xcc: reserved + 0x0d: tab | 0x4d: p / P | 0x8d: reserved | 0xcd: reserved + 0x0e: ` / ~ | 0x4e: - / _ | 0x8e: reserved | 0xce: reserved + 0x0f: reserved | 0x4f: reserved | 0x8f: reserved | 0xcf: reserved + 0x10: reserved | 0x50: reserved | 0x90: reserved | 0xd0: reserved + 0x11: left alt | 0x51: reserved | 0x91: right alt | 0xd1: reserved + 0x12: left shift | 0x52: ' / " | 0x92: | 0xd2: reserved + 0x13: reserved | 0x53: reserved | 0x93: reserved | 0xd3: reserved + 0x14: left ctrl | 0x54: [ / { | 0x94: right ctrl | 0xd4: reserved + 0x15: q / Q | 0x55: = / + | 0x95: reserved | 0xd5: reserved + 0x16: 1 / ! | 0x56: reserved | 0x96: reserved | 0xd6: reserved + 0x17: reserved | 0x57: reserved | 0x97: reserved | 0xd7: reserved + 0x18: reserved | 0x58: caps lock | 0x98: reserved | 0xd8: reserved + 0x19: reserved | 0x59: right shift | 0x99: reserved | 0xd9: reserved + 0x1a: z / Z | 0x5a: enter | 0x9a: reserved | 0xda: numpad enter + 0x1b: s / S | 0x5b: ] / } | 0x9b: reserved | 0xdb: reserved + 0x1c: a / A | 0x5c: reserved | 0x9c: reserved | 0xdc: reserved + 0x1d: w / W | 0x5d: \ / | | 0x9d: reserved | 0xdd: reserved + 0x1e: 2 / @ | 0x5e: reserved | 0x9e: reserved | 0xde: reserved + 0x1f: reserved | 0x5f: reserved | 0x9f: left win | 0xdf: reserved + 0x20: reserved | 0x60: reserved | 0xa0: reserved | 0xe0: print screen + 0x21: c / C | 0x61: reserved | 0xa1: reserved | 0xe1: pause + 0x22: x / X | 0x62: reserved | 0xa2: reserved | 0xe2: reserved + 0x23: d / D | 0x63: reserved | 0xa3: reserved | 0xe3: reserved + 0x24: e / E | 0x64: reserved | 0xa4: reserved | 0xe4: reserved + 0x25: 4 / $ | 0x65: reserved | 0xa5: reserved | 0xe5: reserved + 0x26: 3 / # | 0x66: backspace | 0xa6: reserved | 0xe6: reserved + 0x27: reserved | 0x67: reserved | 0xa7: right win | 0xe7: reserved + 0x28: reserved | 0x68: reserved | 0xa8: reserved | 0xe8: reserved + 0x29: space | 0x69: numpad 1 | 0xa9: reserved | 0xe9: end + 0x2a: v / V | 0x6a: reserved | 0xaa: reserved | 0xea: reserved + 0x2b: f / F | 0x6b: numpad 4 | 0xab: reserved | 0xeb: cursor left + 0x2c: t / T | 0x6c: numpad 7 | 0xac: reserved | 0xec: home + 0x2d: r / R | 0x6d: reserved | 0xad: reserved | 0xed: reserved + 0x2e: 5 / % | 0x6e: reserved | 0xae: reserved | 0xee: reserved + 0x2f: reserved | 0x6f: reserved | 0xaf: menu | 0xef: reserved + 0x30: reserved | 0x70: numpad 0 | 0xb0: reserved | 0xf0: insert + 0x31: n / N | 0x71: numpad . | 0xb1: reserved | 0xf1: delete + 0x32: b / B | 0x72: numpad 2 | 0xb2: reserved | 0xf2: cursor down + 0x33: h / H | 0x73: numpad 5 | 0xb3: reserved | 0xf3: reserved + 0x34: g / G | 0x74: numpad 6 | 0xb4: reserved | 0xf4: cursor right + 0x35: y / Y | 0x75: numpad 8 | 0xb5: reserved | 0xf5: cursor up + 0x36: 6 / ^ | 0x76: escape | 0xb6: reserved | 0xf6: reserved + 0x37: reserved | 0x77: num lock | 0xb7: reserved | 0xf7: reserved + 0x38: reserved | 0x78: f11 | 0xb8: reserved | 0xf8: reserved + 0x39: reserved | 0x79: numpad + | 0xb9: reserved | 0xf9: reserved + 0x3a: m / M | 0x7a: numpad 3 | 0xba: reserved | 0xfa: page down + 0x3b: j / J | 0x7b: numpad - | 0xbb: reserved | 0xfb: reserved + 0x3c: u / U | 0x7c: numpad * | 0xbc: reserved | 0xfc: reserved + 0x3d: 7 / & | 0x7d: numpad 9 | 0xbd: reserved | 0xfd: page up + 0x3e: 8 / * | 0x7e: scroll lock | 0xbe: reserved | 0xfe: reserved + 0x3f: reserved | 0x7f: reserved | 0xbf: reserved | 0xff: reserved diff --git a/documentation/kernel-interface/sockets.txt b/documentation/kernel-interface/sockets.txt new file mode 100644 index 0000000..73dade6 --- /dev/null +++ b/documentation/kernel-interface/sockets.txt @@ -0,0 +1,28 @@ +in hilbert os, a "socket" is a two-way byte-wise communication construct. each +socket has two ends, which can be either open or closed. each process has a +number of handles to sockets. sockets can be created in one of two ways: either +creating a private socket or connecting to a socket listener. + +private sockets: + a private socket is created with the "create private socket" system call. the + process creating the socket gets both ends of the socket. + +socket listeners: + a socket listener is created with the "create socket listener" system call. + an id string is passed to that system call and remains associated with the + listener throughout its lifetime. only one socket listener may have a given + id at once. while a socket listener exists, the owner of the listener can + call the "accept socket connection" system call, and any process can call the + "connect to socket" system call with that id passed. each of these system + calls blocks until the other occurs, at which point a socket is created with + the two process as its endpoints, and then both system calls return. the + listener remains alive after the socket is created, and can be used to create + more sockets until stopped with the "stop socket listener" system call. + +when a process is created, an end of a socket can be "gifted" to that process. +when that happens, the end remains open, and is now accessible by the giftee +and not by the gifter. + +when either end of a socket is closed, the other end of the socket remains +valid, and can be read from until empty. when both ends of a socket are closed, +the socket disappears. diff --git a/documentation/kernel-interface/syscalls.txt b/documentation/kernel-interface/syscalls.txt new file mode 100644 index 0000000..792c300 --- /dev/null +++ b/documentation/kernel-interface/syscalls.txt @@ -0,0 +1,178 @@ +on application entry: + there is a 1MiB - 8KiB area mapped writable and not + executable with guard pages on either side, and rsp is + set to the top of that. all other registers are set to 0. + +the ARGC environment variable holds the number of arguments to main. +the ARGV0, ARGV1, ARGV2, etc environment variables hold those arguments. + +for all system calls: + rax, rdi, rsi, rdx are in/out paramters. + rbx, rbp, rsp, r12-r15 are preserved. + rcx, rflags, r8-r11 are clobbered. + +interrupts (including the timer!) are disabled during system calls. + +stream result: + 0 = success + 1 = bad handle + 2 = io error + 3 = out of bounds + 4 = does not exist + 5 = not a regular file + 6 = not an executable + 7 = not writable + 8 = not seekable + 9 = socket id already used + 10 = socket id not in use + 11 = socket listener closed + 12 = other end closed + 13 = already exists + 14 = not sized + +encode color: + rax in: 0 + edi in: r + g * 256 + b * 65536 + eax out: encoded color + +get framebuffer: + rax in: 1 + rax out: pointer to framebuffer + rdi out: width + height * 2 ** 32 + esi out: pitch + framebuffer is always 32 bpp. use the encode color syscall + to encode colors. pitch is in dwords, not in bytes. + +open file: + rax in: 2 + rdi in: pointer to file path + rsi in: file path length + rdx in: + bit 0: allow creation + bit 1: only allow creation + rax out: stream result + rdi out: stream handle (if rax = success) + +end this thread: + rax in: 3 + edi in: exit code (signed, only used if this was last thread) + +get new pages: + rax in: 4 + rdi in: number of pages to allocate + rax out: start of first page + the allocated pages are next to each other, writable, and not executable. + +get input packet: + rax in: 5 + al out: + bit 7: was mouse packet + if bit 7: + bit 0: left mouse button down + bit 1: right mouse button down + bit 2: middle mouse button down + if bit 7: + di out: mouse x change (signed) + si out: mouse y change (signed) + else: + edi out: key packet + +create private socket: + rax in: 6 + rax out: end 1 stream handle + rdi out: end 2 stream handle + +create socket listener: + rax in: 7 + rdi in: pointer to id string + rsi in: id string length + rax out: stream result + rdi out: listener handle (if rax = 0) + +stop socket listener: + rax in: 8 + rdi in: listener handle + +accept socket connection: + rax in: 9 + rdi in: listener handle + rax out: stream result + rdi out: stream handle + +connect to socket: + rax in: 10 + rdi in: pointer to id string + rsi in: id string length + rax out: stream result + rdi out: stream handle (if rax = 0) + if the listener is closed while this syscall is blocked, rax is + set to "socket id not in use" and not "socket listener closed" + +close stream: + rax in: 11 + rdi in: stream handle + +seek stream: + returns "not seekable" for sockets + rax in: 12 + rdi in: stream handle + sil in: + 0 = relative to beginning + 1 = relative to end + 2 = relative to current position + rdx in: offset (signed) + rax out: stream result + +read from stream: + rax in: 13 + rdi in: stream handle + rsi in: count + rdx in: pointer to buffer + rax out: stream result + +write to stream: + rax in: 14 + rdi in: stream handle + rsi in: count + rdx in: pointer to buffer + rax out: stream result + +get stream length: + returns "not sized" for sockets + rax in: 15 + rdi in: stream handle + rax out: stream result + rdi out: stream length (if rax = success) + +start process: + rax in: 16 + rdi in: pointer to process start info struct + rax out: stream result + rdi out: process handle (if rax = success) + process start info struct: + qword: file path length + qword: pointer to file path + qword: count of environment variables + qword: pointer to array of environment variable structs + qword: count of gifted stream ends + qword: pointer to array of gifted stream structs + environment variable struct: + qword: name length + qword: pointer to name + qword: value length + qword: pointer to value + gifted stream struct: + qword: stream handle here + qword: new stream handle in child + new handle must be < 65536 + +end this process: + rax in: 17 + edi in: exit code (signed) + +set stream length: + returns "not sized" for sockets + rax in: 18 + rdi in: stream handle + rsi in: new length + rax out: stream result |