Merge pull request #33 from redox-os/political_correctness

Changes to try and improve public relations

.gitignore

@@ -0,0 +1 @@
+book/

src/design/kernel/advantages.md

@@ -15,17 +15,17 @@ Modern monolithic kernels try to solve this issue, using kernel modules, but do
 Security
 --------
 
-Microkernels are undoubtedly _a lot_ more secure than monolithic kernels. The minimality principle of microkernels is a direct consequence of the principle of least privilege, according to which all components should have only the privileges absolutely needed to provide the needed functionality.
+Microkernels are undoubtedly more secure than monolithic kernels. The minimality principle of microkernels is a direct consequence of the principle of least privilege, according to which all components should have only the privileges absolutely needed to provide the needed functionality.
 
-The vast majority of security-critical bugs in monolithic kernels stems from drivers running unrestricted in kernel mode, without any form of protection.
+Many security-critical bugs in monolithic kernels stem from services and drivers running unrestricted in kernel mode, without any form of protection.
 
 In other words: **drivers can do whatever, without restrictions, when running in ring 0**.
 
 Less crashes
 ------------
 
-Monolithic kernels are, when compared to microkernels, relatively crash-prone. Simple logic bugs can result in a crashed driver, which will, for a kernel space driver, crash the whole system.
+Monolithic kernels are, when compared to microkernels, crash-prone. Simple logic bugs can result in a crashed driver, which can, for a kernel space driver, crash the whole system.
 
 In Linux, this is often seen by errors with drivers dereferencing bad pointers, ultimately resulting in kernel panics.
 
-> TODO
+[There is very good documentation in MINIX about how this can be addressed by a microkernel](http://wiki.minix3.org/doku.php?id=www:documentation:reliability)

src/design/kernel/disadvantages.md

@@ -13,6 +13,6 @@ Any modern operating system needs basic security mechanisms such as virtualizati
 
 These operations take some time and might be happening more than once. On microkernel systems this time adds up since compared to a monolithic kernel functionality is split off in several processes, often requiring several context switches to do the same task.
 
-With a good approach and some time spend optimizing for performance this should no longer be an issue, but Redox is not there yet.
+With a good approach and some time spend optimizing for performance this should be a minimal issue, but Redox is not there yet.
 
 See also: [Wikipedia on performance of minikernels](https://en.wikipedia.org/wiki/Kernel_%28operating_system%29#Performance)

src/design/kernel/kernel.md

@@ -1,4 +1,4 @@
 The kernel of Redox
 ===================
 
-The kernel of Redox largely derives from the concept of microkernels, particularly with inspiration from L4, Mach, and Minix. This chapter will discuss the design of the Redox kernel.
+The kernel of Redox largely derives from the concept of microkernels, particularly with inspiration from MINIX. This chapter will discuss the design of the Redox kernel.

src/introduction/how_redox_compares_to_other_operating_systems.md

@@ -8,18 +8,18 @@ Syscalls
 
 The syscall interface is very Unix-y. For example, we have `open`, `pipe`, `pipe2`, `lseek`, `read`, `write`, `brk`, `execv`, and so on. Currently, we support the 31 most common Linux syscalls.
 
-Compared to Linux, our syscall interface is much more minimal. This is not because of the stage in development. This is a matter of design. Linux has a lot of unnecessary, bloated syscalls (try to run `man syscalls`, and an almost infinite list appears).
+Compared to Linux, our syscall interface is much more minimal. This is not because of the stage in development, but because of a minimalist design.
 
 "Everything is a URL"
 ----------------------
 
 This is an generalization of "Everything is a file", largely inspired by Plan 9. In Redox, "resources" (will be explained later) can be both socket-like and file-like, making them fast enough for using them for virtually everything.
 
-This way we get a more unified system API.
+This way we get a more unified system API. We will explain this later, in [URLs, schemes, and resources](./design/urls_schemes_resources.html)
 
 The kernel
 ----------
 
-Redox's kernel is a microkernel. The architecture is largely inspired by L4 and Minix.
+Redox's kernel is a microkernel. The architecture is largely inspired by MINIX.
 
-In contrast to Linux or BSD, Redox is a microkernel, giving it numerous advantages (I'll explain these later on).
+In contrast to Linux or BSD, Redox has only 16,000 lines of kernel code, a number that is often decreasing. Most services are provided in userspace

src/introduction/unsafes.md

@@ -1,12 +1,10 @@
 Unsafes
 =======
 
-`unsafe` is a way to tell Rust that "I know what I'm doing!", which is necessary when writing extremely low-level code. You cannot write a kernel without `unsafe`s.
+`unsafe` is a way to tell Rust that "I know what I'm doing!", which is necessary when writing low-level code. You cannot write a kernel without `unsafe`s.
 
 In that light, a kernel cannot be 100% safe, however the unsafe parts have to be marked with an `unsafe`, which keeps the unsafe parts segregated from the safe code. We seek to eliminate the `unsafe`s where we can, and when we use `unsafe`s, we are extremely careful.
 
 A quick grep gives us some stats: The kernel has 16.52% unsafe code, a 50% improvement in the last three weeks. Userspace has roughly ~0.2%.
 
-In constrast to Linux, which has a code base with 100% unsafe code, due to the nature of C.
-
-> TODO: Expand
+This contrasts with kernels written in C, which cannot make guarantees about safety without costly formal analysis.

src/introduction/what_is_redox.md

@@ -3,37 +3,20 @@ What is Redox?
 
 You might still have the question: What is Redox actually?
 
-Redox is an attempt to make a complete, fully-functioning, general-purpose operating system with a focus on safety, correctness, and pragmatism. Redox isn't afraid of dropping the bad parts of POSIX, while preserving modest Linux API compatibility.
-
-Because of certain design choices, we cannot reach complete 1:1 POSIX compatibility. I will expand on this later.
-
-Most importantly, **we will not replicate the mistakes made by others.** This is probably the most important tenet of Redox. In the past, bad design choices were made by Linux, Unix, BSD, HURD, and so on. We all make mistakes, that's no secret, but there is no reason to repeat others' mistakes.
-
-It should be obvious to the reader that this entails a trade-off, namely compatibility versus correctness. As you can see, breaking certain standards does break compatibility. We take a very pragmatic approach to these:
-
-We do not reinvent things, just to reinvent them. Don't fix things that are already fixed, fix things which are broken.
-
-To the extent of correctness, we keep Linux compatibility.
-
-How can we be sure not to make mistakes?
-----------------------------------------
-
-Hah! We cannot.
-
-We can do certain things to prevent it, however:
-
-Linux has been way too fast to stabilize things, and way too slow to deprecate them. This meant that old, legacy drivers are a mandatory part of the Linux kernel. We want a slow release model to avoid doing bad design decisions. We will not stabilize before they are well-tested and known to work.
-
-We will not sacrifice correctness for compatibility. We are not afraid of looking at the mistakes that were made during the development of other operating systems, and then learning from them.
+Redox is an attempt to make a complete, fully-functioning, general-purpose operating system with a focus on safety, reliability, correctness, and pragmatism.
 
 The goals of Redox
 ------------------
 
-We want to be able to use it, without obstructions, as a alternative to Linux on our computers. It should be able to run pretty much all Linux executables with only minimal modifications.
+We want to be able to use it, without obstructions, as a alternative to Linux on our computers. It should be able to run pretty most Linux programs with only minimal modifications.
+
+We're aiming towards a complete, safe Rust ecosystem. This is a design choice, which hopefully improves correctness and security (see `Why Rust?`).
 
-We're aiming towards a complete, safe pure Rust ecosystem. This is a design choice, which hopefully improves correctness and security (see `Why Rust?`).
+We want to improve the security design when compared to other Unix-like kernels by using safe defaults and disallowing insecure configurations where possible.
 
 The non-goals of Redox
 ----------------------
 
-We are not a Unix clone, nor are we crazy scientists, who wants to redesign everything. Generally, we stick to the well-tested and proven correct designs. If it ain't broken don't fix it.
+We are not a Linux clone, or POSIX-compliant, nor are we crazy scientists, who wants to redesign everything. Generally, we stick to the well-tested and proven correct designs. If it ain't broken don't fix it.
+
+This means that a large number of standard programs and libraries will be compatible with Redox. Some things that do not align with our design decisions will have to be ported.

src/introduction/why_mit.md

@@ -3,21 +3,28 @@ Why MIT?
 
 As licensing is rather controversial, this is a frequently asked question.
 
-The GPL is good for forcing people who make changes to the source to contribute back. This would be okay if you were developing a program, but never ideal for libraries or operating systems, because the GPL forces any code that even remotely uses or links to the GPL'd source, to become GPL'd.
+The GPL is good for forcing people who make changes to the source to contribute back. GPL stipulates that source code that is modified, compiled, and then distributed must be published under the GPL license. This prevents a company like Google, for example, from keeping most modifications to the Linux kernel for Android private.
 
-Since operating systems are such an integrated part of our lives, we want as little restriction as possible. Restrictive licenses are quite a big disadvantage for OS projects. The MIT license opens up a lot of possibilities, which are simply not plausible with, say, the GPL.
+Since operating systems are such an integrated part of our lives, we want as little restriction as possible.
 
-The GPL is upstream-centric, the MIT license is downstream-centric. We happen to prioritize downstream more than upstream, since downstream is what really matters: the userbase, the community, the availability.
+The MIT license opens up a lot of possibilities, which are simply not plausible with, say, the GPL:
+- It allows for the distribution of proprietary changes to the Redox operating system. FreeBSD, for example, has been used in both Apple OS X and the Sony PS4
+- It allows for the incorporation of GPL-incompatible code into the kernel, like OpenZFS
+- MIT is compatible with GPL - Projects licensed as GPL can still be distributed with Redox
+- Microkernel architecture means that driver maintainers could choose their own license to meet their needs
 
-We wanted to encourage the use, modification, and packaging of Redox in absolutely all realms. Open source should be open, for everyone. There's absolutely no reason for limiting the usage of the software. Therefore, MIT was the license of choice.
+We wanted to encourage the use, modification, and packaging of Redox in absolutely all realms. Open source should be open, for everyone. We do not desire limiting the usage of the software. Therefore, MIT was the license of choice.
 
 But what if someone "steals" the source code?
 ---------------------------------------------
 
-We wouldn't mind if somebody did that. In order to successfully steal a project, you'd have to make _some_ improvements over the upstream version. You can't sell an apple for $2, if another person stands right next to you, giving them away for free. For this reason, making a (potentially proprietary) fork interesting requires putting some time and money into it.
+What if Apple comes along and decides that Redox would be a good base for their next OS X?
 
-There is nothing wrong with building on top of Redox. You can't _unfairly_ steal a project. That's simply not possible. For a fork to gain interest, you will have to put effort into it no matter what.
+We wouldn't mind if they did that. In order to successfully steal a project, you'd have to make _some_ improvements over the upstream version. You can't sell an apple for $2, if another person stands right next to you, giving them away for free. For this reason, making a (potentially proprietary) fork interesting requires putting some time and money into it.
+
+There is nothing wrong with building on top of Redox. You can't _unfairly_ abuse our project by making proprietary extensions. That's simply not possible. For a fork to gain interest, you will have to put effort into it no matter what.
 
 Building on top of Redox, whether it gets to upstream or not, is a thing we appreciate.
+---------------------------------------------------------------------------------------
 
 We like to have a decentralized structure of the project, allowing people to do whatever they want, no matter how they intend to share it.

src/introduction/why_redox.md

@@ -5,22 +5,45 @@ A natural question this raises is: why do we need yet another OS? There are plen
 
 The answer is: you don't. No-one _needs_ an OS.
 
-Why not contribute somewhere else? Linux? Plan 9? A BSD? Maybe even HURD? Or even go proprietary?
+Why not contribute somewhere else? Linux? BSD? MINIX?
 -------------------------------------------------------------------------------------------------
 
+### Linux
 There are numerous other OS's, kernels, whatever that lack for contributors, and are in desperate need of more coders. Many times, this is for a good reason. Failures in management, a lack of money, inspiration, or innovation, or a limited set of applications have all caused projects to dwindle and eventually fail.
 
 All these have numerous short-fallings, vulnerability, and bad design choices. Redox isn't and won't be perfect, but we seek to improve over other OSes.
 
 Take Linux for example:
 
-- Legacy until infinity: Old syscalls stay around forever, drivers for long-unbuyable hardware stay in the kernel as a mandatory part. While they can be disabled, running them in kernel space is essentially unnecessary, and is, by far, the biggest source of system crashes, security issues, and unexpected bugs.
+- Legacy until infinity: Old syscalls stay around forever, drivers for long-unbuyable hardware stay in the kernel as a mandatory part. While they can be disabled, running them in kernel space is unnecessary, and can be a source of system crashes, security issues, and unexpected bugs.
 - Huge codebase: To contribute, you must find a place to fit in to nearly _25 million lines of code_, in just the kernel. This is due to Linux's monolithic architecture.
-- Restrictive license: Linux is licensed under GPL2. More on this in `Why MIT?`.
-- Lack of memory safety: Linux has had numerous issues with memory safety throughout time. C is a fine language, but for such a security critical system, C doesn't fit.
+- Restrictive license: Linux is licensed under GPL2, preventing some use cases that we would like to allow. More on this in `Why MIT?`.
+- Lack of memory safety: Linux has had numerous issues with memory safety throughout time. C is a fine language, but for such a security critical system, C is difficult to use safely.
 
-Compared to BSD, Linux is relatively poorly designed. The code base is very hackish, and contains numerous bugs. Microkernels are no panacea, but they tend to be more well-written, due to a managable number of lines.  We would like to avoid the monolithic, uncoordinated design of Linux.
+### BSD
 
-It is no secret that we're more in favor of BSD, than Linux (although most of us are still Linux users, for various reasons). But BSD isn't quite there yet: most importantly, **it has a monolithic kernel, written in C**. This means that a single buggy driver can crash, hang, or cause damage to the system.
+It is no secret that we're more in favor of BSD, than Linux (although most of us are still Linux users, for various reasons). This is because of certain security features that allow the construction of a more reliable system, things like [jails](https://www.freebsd.org/doc/handbook/jails.html) and [ZFS](https://www.freebsd.org/doc/handbook/zfs.html).
 
-> TODO: Rewrite this
+BSD isn't quite there yet:
+
+- It still has a monolithic kernel. This means that a single buggy driver can crash, hang, or cause damage to the system.
+- The use of C in the kernel makes it probable to write code with memory safety issues
+- Driver support, when compared to Linux, is poor
+
+### MINIX
+
+And what about MINIX? It's microkernel design is a big influence on the Redox project, especially for reasons like [reliability](http://wiki.minix3.org/doku.php?id=www:documentation:reliability). MINIX is the most in line with Redox's philosophy. It has a similar design, and a similar license.
+
+- Use of C - again, we would like drivers and the kernel to be written in Rust, to improve readability and organization, and to catch more potential safety errors
+- Lack of driver support - MINIX does not work well on real hardware
+
+The Need for Something New
+--------------------------
+
+I will admit, I like the idea of writing something that is my own (Not Invented Here syndrome). There are numerous places in the MINIX 3 source code where I would like to make changes, so many that perhaps a rewrite in Rust makes the most sense.
+
+- Different VFS model, based on URLs, where a program can control an entire segmented filesystem
+- Different driver model, where drivers interface with filesystems like network: and audio: to provide features
+- Different file system, RedoxFS, with a ZFS implementation in progress
+- Userspace written mostly in Rust
+- Orbital, a new GUI