From 460f3c0109b682179b93b4ccc93d196ecac59e94 Mon Sep 17 00:00:00 2001 From: Amelia Coutard Date: Sat, 4 Mar 2023 03:12:34 +0100 Subject: [PATCH] Added basic API for IPC in doc.txt. Not implemented yet --- doc.txt | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 99 insertions(+), 2 deletions(-) diff --git a/doc.txt b/doc.txt index 0f85efe..55dfb57 100644 --- a/doc.txt +++ b/doc.txt @@ -2,11 +2,11 @@ isos documentation: "isos" means "Incompatible System from Outer Space". (Also, "Is Operating System". The double meaning is funny.) - +--------------------------- (Virtual) memory map: -0000'0000'0000'0000 ↔ 0000'0000'0000'1000 - unmapped: 4KiB ensure that nullptr causes a page fault if accessed. +0000'0000'0000'0000 ↔ 0000'0000'0000'1000 - unmapped: 4KiB ensure that NULL causes a page fault if accessed. 0000'0000'0000'1000 ↔ 0000'0010'0000'0000 - program segments (.text, .data, .bss, etc.): 64GiB - 4KiB 0000'0010'0000'1000 ↔ 0000'7FFF'FFFF'0000 - heap: 128TiB - 64GiB - 64KiB 0000'7FFF'FFFF'0000 ↔ 0000'8000'0000'0000 - stack: 64KiB @@ -14,3 +14,100 @@ isos documentation: FFFF'8000'0000'0000 ↔ FFFF'C000'0000'0000 - physical memory: 64TiB FFFF'C000'0000'0000 ↔ FFFF'FFFF'8000'0000 - unmapped: 64TiB - 2GiB FFFF'FFFF'8000'0000 ↔10000'0000'0000'0000 - kernel: 2GiB + +--------------------------- + +A port is a non-0 64-bit integer, that refers to another port that could be a part of the same +or a different process (however, since threads don't exist, sending a message through a port to +your own process will block it forever). +It allows for sending and receiving data through to its other side. + +--------------------------- + +Data types: + +port_t = uint64_t; +byte = unsigned char; + +--------------------------- + +The system calls: + +If a syscall fails, it will return a negative value in %rax between -255 and -1, and the error code is -%rax. (like Linux) +If it succeeds, if it returns a value, it returns it, otherwise it returns 0. +Errors: + 1: too many ports // The process has reached it's maximumwatching number of allowed ports. + 2: port doesn't exist // This port isn't allocated in this process, or has already been closed on this side. + 3: closed port // The port has been closed on the other side. + 4: other side refusal // Error sent by the other side's program. Won't ever be generated by the kernel. + +// Create two connected infinite-use ports. +// Possible errors: +// too many ports +void mkport(port_t* port_a, port_t* port_b); + +// Closes a port. This port now doesn't exist and its id is available for recycling. +// If the other side tries any operation but a close on this port, it shall fail with 'closed port' +// The port on the other side isn't closed, and can't be recycled, until the other side also calls close. +// Possible errors: +// port doesn't exist +void close(port_t port); + +// Send a message to the other side of the port. Block until you receive an answer. +// Returns the actual length of the reply (which can be more than what was written in +// the reply buffer, if it was too short for it). +// If no port was replied, *reply_port = 0. +// While you technically cannot reply without a message, a 0 length message is the same +// as no message (and allows for NULL as a pointer to the message). +// Possible errors: +// port doesn't exist +// closed port +// other side refusal +size_t call(port_t port, byte const* message, size_t message_size, byte* reply_message, size_t reply_message_size, port_t* reply_port); + +// Block until a message is being sent to port, then return it's length. +// Possible errors: +// port doesn't exist +// closed port +size_t recv_len(port_t port); + +// Block until a message is being sent to port, then copy it's contents to message. +// This should only be used after recv_len, lest you risk a buffer overflow. +// Possible errors: +// port doesn't exist +// closed port +void recv(byte* message); + +// Unblock the other side, loading up the corresponding values in the call arguments. +// Doesn't block this side at all, unless it is sent without the other side having called. +// If a port (!= 0) is sent, it no longer exists in this program. +// If reply_message_size is 0, reply_message is allowed to be NULL. +// reply_port is allowed to be a port closed on the other side, but it must be 0 or a port +// that still exists in this process. +// Possible errors: +// port doesn't exist +// closed port +void reply(port_t port, byte const* reply_message, size_t reply_message_size, port_t reply_port); + +// Unblock the other side, erroring with error code "other side refusal" +// Doesn't block this side at all, unless it is sent without the other side having called. +// Possible errors: +// port doesn't exist +// closed port +void reply_error(port_t port); + +// Block until any port receives a message. Returns the port_t a message +// was sent to. +// No possible errors. +port_t wait(); + + +Without comments: + void mkport(port_t* port_a, port_t* port_b); + void close(port_t port); + size_t call(port_t port, byte const* message, size_t message_size, byte* reply_message, size_t reply_message_size, port_t* reply_port); + size_t recv_len(port_t port); + void recv(byte* message); + void reply(port_t port, byte const* reply_message, size_t reply_message_size, port_t reply_port); + void reply_error(port_t port); + port_t wait(); -- 2.47.0