From 134353d273af2ee00087765b193b1c2c492b93b9 Mon Sep 17 00:00:00 2001
From: Ticki <Ticki@users.noreply.github.com>
Date: Tue, 1 Mar 2016 21:08:31 +0100
Subject: [PATCH] :tada: Resources
---
design/resource/file_like.md | 1 +
design/resource/resources.md | 28 +++++++++++++++++++++
design/resource/socket_like.md | 1 +
design/scheme/schemes.md | 29 ++++++++++++++++++++++
design/scheme/writing_a_scheme.md | 1 +
design/url/how_it_works.md | 26 +++++++++++++++++++
design/{ => url}/urls.md | 0
design/{ => url}/urls_schemes_resources.md | 0
index.txt | 1 +
9 files changed, 87 insertions(+)
create mode 100644 design/resource/file_like.md
create mode 100644 design/resource/resources.md
create mode 100644 design/resource/socket_like.md
create mode 100644 design/scheme/schemes.md
create mode 100644 design/scheme/writing_a_scheme.md
create mode 100644 design/url/how_it_works.md
rename design/{ => url}/urls.md (100%)
rename design/{ => url}/urls_schemes_resources.md (100%)
diff --git a/design/resource/file_like.md b/design/resource/file_like.md
new file mode 100644
index 0000000..1333ed7
--- /dev/null
+++ b/design/resource/file_like.md
@@ -0,0 +1 @@
+TODO
diff --git a/design/resource/resources.md b/design/resource/resources.md
new file mode 100644
index 0000000..3191af2
--- /dev/null
+++ b/design/resource/resources.md
@@ -0,0 +1,28 @@
+Resources
+=========
+
+Resources are opened schemes. You can think of them like an established connection between the scheme provider and the client.
+
+Resources are closely connect to schemes, and are sometimes intertwined with schemes. But the different is subtle, yet crucial.
+
+Resource operations
+-------------------
+
+A resource can be defined as a data type with following methods defined on it:
+
+1. `read` - read N bytes to a buffer provided as argument. Defaults to `EBADF`
+2. `write` - write a buffer to the resource. Defaults to `EBADF`.
+3. `seek` - seek the resource, that is move the "cursor" without writing. Many resources do not support this operation. Defaults to `EBADF`.
+4. `close` - close the resource, potentially releasing a lock. Defaults to `EBADF`.
+
+TODO add F-operations
+
+The resource type
+-----------------
+
+There are two types of resources:
+
+1. File-like resources. These behaves a lot like files. They act in a blocking manner, reads and writes are "buffer-like".
+2. Socket-like resources. These behaves like sockets. They act in a non-blocking manner, reads and writes are more "stream-like".
+
+I will expand on this later.
diff --git a/design/resource/socket_like.md b/design/resource/socket_like.md
new file mode 100644
index 0000000..1333ed7
--- /dev/null
+++ b/design/resource/socket_like.md
@@ -0,0 +1 @@
+TODO
diff --git a/design/scheme/schemes.md b/design/scheme/schemes.md
new file mode 100644
index 0000000..83a33c6
--- /dev/null
+++ b/design/scheme/schemes.md
@@ -0,0 +1,29 @@
+Schemes
+=======
+
+Schemes are the natural counter-part to URLs. As described before, URLs are opened to schemes, which can then be communicated with, through scheme operations.
+
+Schemes are named so that the kernel is able to identify them. This name is used in the `scheme` part of the URL.
+
+Schemes are a generalization of file systems. It should be noted that schemes are not necessarily representing normal files; often they are "virtual file", that is, an abstract unit with certain operations defined on it.
+
+Throughout the whole ecosystem of Redox, schemes are used as the main communication primitive, because they are a really powerful abstraction. Namely, we have one unified interface.
+
+Schemes can be defined both in userspace and in kernelspace, although, when possible, userspace is preferred.
+
+Scheme operations
+-----------------
+
+What makes a scheme a scheme? Scheme operations!
+
+A scheme is just a data structure with certain function defined on it:
+
+1. `open` - open the scheme. `open` is used for initially opening the communication with a scheme, it is an optional method, and will default to returning `ENOENT`.
+
+2. `mkdir` - make a new sub-structure. Note that the name is a little misleading (and it might even be renamed in the future), since in many schemes `mkdir` won't make a `directory`, but instead perform some form of substructure creation.
+
+Less important optional methods are:
+
+1. `unlink` - remove a link (that is a binding from one substructure to another).
+
+2. `link` - add a link.
diff --git a/design/scheme/writing_a_scheme.md b/design/scheme/writing_a_scheme.md
new file mode 100644
index 0000000..1333ed7
--- /dev/null
+++ b/design/scheme/writing_a_scheme.md
@@ -0,0 +1 @@
+TODO
diff --git a/design/url/how_it_works.md b/design/url/how_it_works.md
new file mode 100644
index 0000000..4a9328e
--- /dev/null
+++ b/design/url/how_it_works.md
@@ -0,0 +1,26 @@
+How URLs works under the hood?
+==============================
+
+The representation
+------------------
+
+Since it is impossible to go from userspace to ring 0 in a typed manner, we have to use some weakly typed representation (that is, we can't use an enum, unless we want to do transmutions and friends). Therefore, we use a string-like representation when moving to kernel space. This is basically just a raw pointer to a C-like, null-terminating string. To avoid further overhead, we use more efficient representations:
+
+# `Url<'a>`
+
+The first of the three representations is the simplest one. It consists of an `struct` containing two fat pointers, representing the scheme and the reference respectively.
+
+# `OwnedUrl`
+
+This is a `struct` containing two `String`s (that is, growable, heap-allocated UTF-8 string), being the scheme and the reference respectively.
+
+# `CowUrl<'a>`
+
+This is a Copy-on-Write (CoW) URL, which, when mutated, gets cloned to heap. This way, you get efficient conditional allocation of the URL.
+
+Not much fanciness here.
+
+Opening an URL
+--------------
+
+TODO
diff --git a/design/urls.md b/design/url/urls.md
similarity index 100%
rename from design/urls.md
rename to design/url/urls.md
diff --git a/design/urls_schemes_resources.md b/design/url/urls_schemes_resources.md
similarity index 100%
rename from design/urls_schemes_resources.md
rename to design/url/urls_schemes_resources.md
diff --git a/index.txt b/index.txt
index 400aa07..54e50f0 100644
--- a/index.txt
+++ b/index.txt
@@ -38,6 +38,7 @@ The design
........ Stitching it all together
............ "Everything is an URL"
................ vs "Everything is a file"
+............ An example
........ How it works under the hood
.... The kernel
........ Syscalls
--
GitLab