Added IPC design to doc.txt

diff --git a/doc.txt b/doc.txt
index 0f85efe564b4a2e032b6db2cde5ecbe1a845bb82..b450d6b051290d6d0a23c8c7e2fdcdbff11a1b8b 100644 (file)
--- 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 its 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, or is closed on the other side.
+// Returns the corresponding port_t.
+// 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();