src/SUMMARY.md

@@ -7,10 +7,11 @@
 - [Introducing Redox](./ch01-00-introducing-redox.md)
   - [Our Goals](./ch01-01-our-goals.md)
   - [Our Philosophy](./ch01-02-philosophy.md)
-  - [Why a New OS?](./ch01-03-why-redox.md)
-  - [Comparing Redox to Other OSes](./ch01-04-how-redox-compares.md)
-  - [Why Rust?](./ch01-05-why-rust.md)
-  - [Side projects](./ch01-06-side-projects.md)
+  - [Why a New OS?](./ch01-03-why-a-new-os.md)
+  - [Redox Use Cases](./ch01-04-redox-use-cases.md)
+  - [Comparing Redox to Other OSes](./ch01-05-how-redox-compares.md)
+  - [Why Rust?](./ch01-06-why-rust.md)
+  - [Side projects](./ch01-07-side-projects.md)
 
 - [Getting started](./ch02-00-getting-started.md)
   - [Running Redox in a virtual machine](./ch02-01-running-vm.md)

src/ch01-03-why-a-new-os.md

+# Why a New OS?
+
+The essential goal of the Redox project is to build a robust, reliable and safe general purpose operating system. To that end, the following key design choices have been made.
+
+## Written in Rust
+
+Wherever possible, Redox code is written in [Rust](https://www.rust-lang.org/). Rust enforces a set of rules and checks on the use, sharing and deallocation of memory references. This almost entirely eliminates the potential for memory leaks, buffer overruns, use after free, and other [memory errors](https://en.wikipedia.org/wiki/Memory_safety#Types_of_memory_errors) that arise during development. The vast majority of security vulnerabilities in operating systems originate from memory errors. The Rust compiler prevents this type of error before the developer attempts to add it to the code base.
+
+## Microkernel Architecture
+
+The [Microkernel Architecture](https://en.wikipedia.org/wiki/Microkernel) moves as much software as possible out of the operating system kernel. Drivers, application services and other operating system functionality run as independent processes. The kernel's main responsibility is the coordination of these processes, and the allocation of system resources to the processes.
+
+Most kernels, other than some real-time operating systems, use an event-handler design. Hardware interrupts and application system calls each trigger an event, invoking the appropriate handler. The kernel runs in supervisor mode, with access to all the system's resources. In [Monolithic Kernels](https://en.wikipedia.org/wiki/Monolithic_kernel), the operating system's entire response to an event must be completed in supervisor mode. An error in the kernel, or even a misbehaving piece of hardware, can cause the system to enter a state where it is unable to respond to *any* event. And because of the large amount of code in the kernel, the potential for vulnerabilities while in supervisor mode is vastly greater than for a microkernel design.
+
+In Redox, drivers and many application services can run in user mode, similar to user applications, and the system can restrict them so they can only access the resources they require for their designated purpose. If a driver fails or panics, it can be ignored or restarted with no impact on the rest of the system. A misbehaving piece of hardware might impact system performance or cause the loss of a service, but the kernel will continue to function and to provide whatever services remain available.
+
+## Advanced Filesystem
+
+Redox provides an advanced filesystem, [RedoxFS](https://gitlab.redox-os.org/redox-os/redoxfs). It includes many of the attributes of [ZFS](https://en.wikipedia.org/wiki/OpenZFS), but in a more modular design. 
+
+TODO: Additional details on RedoxFS features.
+
+## Unix-like Utilities and API
+
+Redox provides a Unix-like command interface, with many everyday utilities written in Rust but with familiar names and options. As well, Redox application services include a programming interface that is a subset of the [POSIX](https://en.wikipedia.org/wiki/POSIX) API, via [relibc](https://gitlab.redox-os.org/redox-os/relibc). This means that many Unix/Linux/POSIX programs can run on Redox with only recompilation. While the Redox team has a strong preference for having essential applications and utilities written in Rust, we are agnostic about the programming language for applications of the user's choice. This means an easy migration path for systems and applications previously developed for a Unix platform.

src/ch01-03-why-redox.md

-Why Redox?
-==========
-
-There are plenty of operating systems out there. It's natural to wonder why we should build a new one. Wouldn't it be better to contribute to an existing project?
-
-The Redox community believes that existing projects fall short, and that our goals are best served by a new project built from scratch.
-
-Let's consider 3 existing projects.
-
-### Linux
-
-Linux runs the world, and boots on everything from high performance servers to tiny embedded devices. Indeed, many Redox community members run Linux as their main workstations. However, Linux is not an ideal platform for new innovation in OS development.
-
-- Legacy until infinity: Old syscalls stay around forever, drivers for long-unbuyable hardware stay in the kernel as mandatory parts. 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.
-- Non-permissive license: Linux is licensed under GPL2, preventing the use of other free software licenses inside of the kernel. For more on why, see [Our Philosophy](./ch01-02-philosophy.md).
-- 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.
-
-### BSD
-
-It is no secret that we're more in favor of BSD. The BSD community has led the way in many innovations in the past 2 decades. Things like [jails] and [ZFS] yield more reliable systems, and other operating systems are still catching up.
-
-That said, BSD doesn't meet our needs either:
-
-- It still has a monolithic kernel. This means that a single buggy driver can crash, hang, or, in the worst case, cause damage to the system.
-- The use of C in the kernel makes it probable to write code with memory safety issues.
-
-### MINIX
-
-And what about MINIX? Its microkernel design is a big influence on the Redox project, especially for reasons like [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. Compared to monolithic kernels, Minix is actually a very well-written and manageable code base, but it is still prone to memory unsafety bugs, for example. These classes of bugs can unfortunately be quite fatal, due to their unexpected nature.
-- Lack of driver support - MINIX does not work well on real hardware, partly due to having less focus on real hardware.
-- Less focus on "Everything is a File" - MINIX does focus less on "Everything is a File" than various other operating systems, like Plan9. We are particularly focused on this idiom, for creating a more uniform program infrastructure.
-
-The Need for Something New
---------------------------
-
-We have to admit, that we do like the idea of writing something that is our own (Not Invented Here syndrome). There are numerous places in the MINIX 3 source code where we 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 [TFS] implementation in progress
-- User space written mostly in Rust
-- [Orbital], a new GUI
-
-[jails]: https://www.freebsd.org/doc/handbook/jails.html
-[ZFS]: https://www.freebsd.org/doc/handbook/zfs.html
-[reliability]: http://wiki.minix3.org/doku.php?id=www:documentation:reliability
-[TFS]: https://gitlab.redox-os.org/redox-os/tfs
-[Orbital]: https://gitlab.redox-os.org/redox-os/orbital

src/ch01-04-redox-use-cases.md

+# Redox Use Cases
+
+Redox is a general purpose operating system that can be used in many situations. Some of the key use cases for Redox are as follows.
+
+## Server Room
+
+Redox has the potential to be a secure server platform for cloud services and web hosting. The improved safety and reliability Redox can provide, as it matures, makes it an excellent fit for the server room. Work remains to be done on support for key server technologies such as databases and web servers, as well as compatibility with high-end server hardware.
+
+Redox has plans underway for [virtualization](https://en.wikipedia.org/wiki/OS-level_virtualization) support. Although running an instance of Linux in a container on Redox will lose some of the benefits of Redox, it can limit the scope of vulnerabilities. Redox-on-Redox and Redox-on-Linux virtualization have the potential to be much more secure than Linux-on-Linux. These capabilities are still a ways off, but are among the objectives for the Redox team.
+
+## Desktop
+
+The development of Redox for the desktop is well underway. Although support for accelerated graphics is limited at this time, Redox does include a graphical user interface, and integration with GUI libraries like [Iced](https://github.com/iced-rs/iced) and [Slint](https://github.com/slint-ui/slint) are ongoing efforts.
+
+A Demo version of Redox is available with several games and applications to try. However, the most important objective for desktop Redox is for hosting the development of Redox. We are working through issues with some of our build tools, and other developer tools such as editors have not been tested under daily use, but we continue to make this a priority.
+
+Due to a fairly limited list of currently supported hardware, once self-hosted development is available, developers may need to obtain a Redox-specific development machine. We are adding more hardware compatibility as quickly as we can, and we hope to be able to support Redox development on a wide array of workstations and laptops in the near future.
+
+## Infrastructure
+
+Redox's modular architecture make it ideal for many telecom infrastructure applications, such as routers, telecom components, edge servers, etc., especially as more functionality is added to these devices. There are no specific plans for remote management yet, but Redox's potential for security and reliability make it ideal for this type of application.
+
+## Embedded and IoT
+
+For embedded systems with complex user interfaces and broad feature sets, Redox has the potential to be an ideal fit. As everyday appliances become Internet-connected devices with sensors, microphones and cameras, they have the potential for attacks that violate the privacy of consumers in the sanctity of their homes. Redox can provide a full-featured, reliable operating system while limiting the likelihood of malicious attack. At this time, Redox does not yet have touchscreen support, video capture, or support for sensors and buttons, but these are well-understood technologies and can be added as it becomes a priority.
+
+## Mission-Critical Applications
+
+Although there are no current plans to create a version of Redox for mission-critical applications such as satellites or air safety systems, it's not beyond the realm of possibility. As tools for correctness proofs of Rust software improve, it may be possible to create a version of Redox that is proven correct, within some practical limits.
\ No newline at end of file

src/ch09-02-coding-and-building.md

@@ -118,6 +118,17 @@ Congratulations! You have modified a program and built the system! Next, create
   ```
 In the directory `build/x86_64/myfiles`, you will find the file `livedisk.iso`. Follow the instructions for [Running on Real Hardware](./ch02-02-real-hardware.md) and test out your change.
 
+## A Note about Drivers
+
+Drivers are a special case for rebuild. The source for drivers is fetched both for the `drivers` recipe and the `drivers-initfs` recipe. The `initfs` recipe also copies some drivers from `drivers-initfs` during the build process. If your driver is included in `initfs`, you need to keep all three in sync. The easiest solution is to write a build shell script something like the following, which should be run in your `redox` base directory. (**Note**: This assumes your driver code edits are in the directory `cookbook/recipes/drivers`. Don't accidentally remove your edited code.)
+
+```sh
+rm -rf cookbook/recipes/drivers-initfs/{source,target} cookbook/recipes/initfs/target
+cp -R cookbook/recipes/drivers/source cookbook/recipes/drivers-initfs
+
+make rebuild qemu
+```
+
 ## Shortening the Rebuild Cycle
 
 To skip some of the steps in a full `rebuild`, here are some tricks.

src/ch13-01-chat.md

 # Chat
 
-The best way to communicate with the Redox team is on Matrix Chat. The [Redox Support Room](https://matrix.to/#/#redox-support:matrix.org) is open and does not require a password, and is the best place to get help with building, installing and running Redox. [Redox OS/Dev](https://matrix.to/#/#redox-dev:matrix.org) is for those that wish to contribute to Redox, or who want deeper technical assistance with developing on Redox. There is also [Redox OS/General](https://matrix.to/#/#redox-general:matrix.org) for general discussions about our use of Matrix and other non-technical topics. There may be additional Redox rooms on Matrix, but some of them may not be official, so connect with us on Redox OS/General before joining other rooms.
+The best way to communicate with the Redox team is on Matrix Chat. You can join the [Redox Space](https://matrix.to/#/#redox:matrix.org) and see the  rooms that are available. The [Redox Support Room](https://matrix.to/#/#redox-support:matrix.org) is the best place to get help with building, installing and running Redox. [Redox OS/Dev](https://matrix.to/#/#redox-dev:matrix.org) is for those that wish to contribute to Redox, or who want deeper technical assistance with developing on Redox. There is also [Redox OS/General](https://matrix.to/#/#redox-general:matrix.org) for general discussions about our use of Matrix and other less-technical topics.
 
-Until recently, we have been using a [Mattermost](https://www.mattermost.org/) chat server, which we are currently maintaining for historical purposes. Currently, the only way to join it is by sending an email to [info@redox-os.org](mailto:info@redox-os.org), which might take a little while, since it's not automated. Contact us on Redox OS/General before doing this.
+Until recently, we have been using a [Mattermost](https://www.mattermost.org/) chat server, which we are currently maintaining for historical purposes. Contact us on Redox OS/General if you need access to the Mattermost server.