prerequisities and contributions updated

README.md

@@ -12,7 +12,7 @@ For more information about project goals and history, please read the [Introduct
 * **[Contribution guide](https://github.com/s-matyukevich/raspberry-pi-os/blob/master/docs/Contributions.md)**
 * **[Prerequsities](https://github.com/s-matyukevich/raspberry-pi-os/blob/master/docs/Prerequisites.md)**
 * **Lesson 1: Kernel Initialization** 
-  * 1.1 [Introducing RPi OS, or bare metal "Hello, world!"](https://github.com/s-matyukevich/raspberry-pi-os/blob/master/docs/lesson01/rpi-os.md)
+  * 1.1 [Introducing the RPi OS, or bare metal "Hello, world!"](https://github.com/s-matyukevich/raspberry-pi-os/blob/master/docs/lesson01/rpi-os.md)
   * Linux
     * 1.2 [Project structure](https://github.com/s-matyukevich/raspberry-pi-os/blob/master/docs/lesson01/linux/project-structure.md)
     * 1.3 [Kernel build system](https://github.com/s-matyukevich/raspberry-pi-os/blob/master/docs/lesson01/linux/build-system.md) 

docs/Contributions.md

@@ -2,23 +2,22 @@
 
 The general workflow is the following:
 
-1. Find an [issue](https://github.com/s-matyukevich/raspberry-pi-os/issues) that you want to start working on or create a new one.
-1. In the comments claim that you want to start working on the issue. The first person who did this will be assigned to the issue. In some circumstancies I may reasing the issue to somebody elase after contacting the original person.
+1. Find an [issue](https://github.com/s-matyukevich/raspberry-pi-os/issues) that you want to start working on, or create a new one.
+1. In comments claim that you want to start working on the issue. The first person who does this will be assigned to the issue.
 1. [Fork the repository](https://help.github.com/articles/fork-a-repo/).
-1. Make all necesary changes.
+1. Make all necessary changes.
 1. [Send pull request](https://help.github.com/articles/about-pull-requests/). 
-1. After a review your changes will be merged.
+1. After review, your changes will be merged.
 
-The following types of contributions are particulary helpfull for the project.
+The following types of contributions are particularly needed for the project.
 
-1. Validating source code and text of the lessons for errors.
-1. Helping to make lessons content more accurate and easier to understand.
-1. Working on sorce code and description for new lessons.
+1. Validating source code and text of the lessons, fixing bugs and errors.
+1. Help in making lessons content more accurate and easier to understand.
+1. Working on the source code and description for the new lessons.
 1. Sharing source code of the completed exercises.
 1. Suggesting new exercises.
 1. Anything else that can help the project to become a perfect starting point for OS developers.
 
-### Contributing completed exercises.
-
-If you successfully completed any of the suggested exercises you can share your source code. The code should be place in the following folder `/exercises/lessonXX/<exercise number>/<your github username>/` Such folder structure allows to accept pull requests for the same exercise from different people.
+### Contributing completed exercises
 
+If you successfully completed any of the suggested exercises you can share your source code. The code should be placed in the following folder `/exercises/lessonXX/<exercise number>/<your github username>/` Such folder structure allows to accept pull requests for the same exercise from different people.

docs/Introduction.md

@@ -14,9 +14,9 @@ You may be wondering why do I need to learn operating system development in the
 
 Next question you may ask is why Linux? Probably, other operating systems would be easier to approach? The answer is that I want my knowledge to be, at least in some way, relevant to what I am currently doing and may realistically expect to be doing in the future. Linux is perfect in this regard because nowadays everything starting from small IoT devices to large servers tend to run Linux.
 
-When I told that most of the books about Linux kernel development didn't work well for me - I wasn't quite honest. There was one book that I was capable to fully understand, even being a novice in OS development, and that also explains some essential concepts using the actual source code. This book is "Linux Device Drivers", and no wonder it is one of the most famous technical books about Linux. It starts with introducing source code of a simple driver that you can compile and play around with. Then it begins to introduce new driver related concepts one by one and explains how to modify the source code of the driver to use new concepts. That is exactly what I refer to as a "good learning experience". The only problem with this book is that it focuses explicitly on driver development and tells very little about core kernel implementation details.
+When I told that most of the books about Linux kernel development didn't work well for me - I wasn't quite honest. There was one book that I was capable to fully understand, even being a novice in OS development, and that also explains some essential concepts using the actual source code. This book is "Linux Device Drivers", and no wonder it is one of the most famous technical books about Linux kernel. It starts with introducing source code of a simple driver that you can compile and play around with. Then it begins to introduce new driver related concepts one by one and explains how to modify the source code of the driver to use new concepts. That is exactly what I refer to as a "good learning experience". The only problem with this book is that it focuses explicitly on driver development and tells very little about core kernel implementation details.
 
-But why did nobody created a similar book for kernel developers, not device driver authors? I think this is because if you use the current Linux kernel source code as a base for your book, this is just not possible. There is no function, structure or module that can be used as a simple starting point because there is nothing simple about Linux source. You also can't introduce new concepts one at a time because in the source code they are very closely related one to another. When I realized this an idea came to me: if Linux kernel is too vast and too complicated to use it as a starting point for learning operating system development, why not implement my own OS that will be explicitly designed for learning purposes. In this way, I can make the OS simple enough to provide a good learning experience. Also if this OS will be implemented mostly by copying and simplifying different parts of the Linux kernel source, it would be straightforward to use it as a starting point to learn Linux kernel as well.
+But why did nobody created a similar book for kernel developers, not device driver authors? I think this is because if you use the current Linux kernel source code as a base for your book, this is just not possible. There is no function, structure or module that can be used as a simple starting point because there is nothing simple about Linux source. You also can't introduce new concepts one at a time because in the source code they are very closely related one to another. After I realized this an idea came to me: if Linux kernel is too vast and too complicated to be used as a starting point for learning OS development, why don't implement my own OS that will be explicitly designed for learning purposes? In this way, I can make the OS simple enough to provide a good learning experience. Also if this OS will be implemented mostly by copying and simplifying different parts of the Linux kernel source, it would be straightforward to use it as a starting point to learn Linux kernel as well.In addition to the OS I decided to write a series of lectures that teaches major OS development concepts and fully explains the OS source code.
 
 ### OS requirements
 
@@ -25,7 +25,7 @@ So I decided to start working on the project, which later becomes the [RPi OS](h
 1. Run user processes in isolation.
 1. Provide each user process with a unified view of the machine hardware.
 
-To satisfy the first requirement, RPi OS needs to have its own scheduler. If I want to implement a scheduler, I also have to handle timer interrupts. The second requirement implies that the OS should support some kind of drivers and provide system calls to expose them to user applications. From the beginning, I don't want to work with complicated hardware, so the only drivers I care about are drivers that can write something to screen and read user input from a keyboard. Also, the OS needs to be able to load and execute a user program, so naturally it needs to support some file system and be capable of understanding some executable file format. It also would be nice if the OS can support some basic networking, but I don't want to focus on this from the beginning. So that is basically the things that I can identify as "core concepts of any operating system".
+To satisfy the first requirement, RPi OS needs to have its own scheduler. If I want to implement a scheduler, I also have to handle timer interrupts. The second requirement implies that the OS should support some kind of drivers and provide system calls to expose them to user applications. From the beginning, I don't want to work with complicated hardware, so the only drivers I care about are drivers that can write something to screen and read user input from a keyboard. Also, the OS needs to be able to load and execute a user program, so naturally it needs to support some file system and be capable of understanding some executable file format. It also would be nice if the OS can support basic networking, but I don't want to focus on this from the beginning. So that is basically the things that I can identify as "core concepts of any operating system".
 
 Now let's take a look at the things that I want to ignore. 
 1. **Performance** I don't want to use any sophisticated algorithms in the OS. I am also going to disable all caches and other performance optimization techniques for simplicity.
@@ -36,7 +36,7 @@ Now let's take a look at the things that I want to ignore.
 
 ### How Raspberry Pi comes into play
 
-I already mentioned that I don't want the PRi OS to support multiple computer architectures and even a lot of different devices. This decision becomes even stronger after I dig into Linux kernel driver model. It appears that even devices with similar purposes can hugely vary in implementation details. This makes it very difficult to come up with simple abstractions around different driver types and reuse driver source code. To me, this seems like one of the primary sources of complexity in Linux kernel, and definitely, I want to avoid it in the RPi OS. Ok, but what kind of computer should I use then? I clearly don't want to test my bare metal programs using my working laptop, because I honestly not sure that it is going to survive after this. More importantly, I don't want people to buy an expensive laptop just to follow my OS development exercises - I don't think anybody will do this. Emulators look like more or less good choice, but I want to work with a real device because it gives me different feeling - feeling that I am doing something real rather than playing with bare metal programming.
+I already mentioned that I don't want the PRi OS to support multiple computer architectures and even a lot of different devices. This decision becomes even stronger after I dig into Linux kernel driver model. It appears that even devices with similar purposes can largely vary in implementation details. This makes it very difficult to come up with simple abstractions around different driver types and reuse driver source code. To me, this seems like one of the primary sources of complexity in Linux kernel, and definitely, I want to avoid it in the RPi OS. Ok, but what kind of computer should I use then? I clearly don't want to test my bare metal programs using my working laptop, because I honestly not sure that it is going to survive. More importantly, I don't want people to buy an expensive laptop just to follow my OS development exercises - I don't think anybody will do this. Emulators look like more or less good choice, but I want to work with a real device because it gives me different feeling - feeling that I am doing something real rather than playing with bare metal programming.
 
 I ended up by using raspberry PI, in particular [Raspberry Pi 3 Model B](https://www.raspberrypi.org/products/raspberry-pi-3-model-b/). Using this device looks like an ideal choice for a number of reasons.
 
@@ -48,5 +48,5 @@ The OS is not compatible with older versions of Raspberry PI, because neither of
 
 ### Working with community
 
-One major drawback of any technical book is that very soon after release each book becomes obsolete. Technology nowadays is evolving so fast that it is almost impossible for book writers to keep up with it. That's why I like the idea of "open source book" - a book that is freely available on the internet and that encourages its readers to participate in content creation and validation. If book content is available on github this makes it very easy for any reader to fix and develop new code samples, update book content and participate in writing new chapters. I understand that right now the project is not perfect and at the time of writing it is even not finished. But I still want to publish it now, because I hope that with the help of the community I will be able not only to complete the project faster but to make it much better and much more useful that it was from the beginning. 
+One major drawback of any technical book is that very soon after release each book becomes obsolete. Technology nowadays is evolving so fast that it is almost impossible for book writers to keep up with it. That's why I like the idea of "open source book" - a book that is freely available on the internet and that encourages its readers to participate in content creation and validation. If book content is available on github this makes it very easy for any reader to fix and develop new code samples, update book content and participate in writing new chapters. I understand that right now the project is not perfect and at the time of writing it is even not finished. But I still want to publish it now, because I hope that with the help of the community I will be able not only to complete the project faster but to make it much better and much more useful than it was from the beginning. 
 

docs/Prerequisites.md

@@ -2,14 +2,19 @@
 
 ### 1. [Raspberry Pi 3 model b](https://www.raspberrypi.org/products/raspberry-pi-3-model-b/) 
 
-Older versions of Raspberry Pi are not going to work with this tutorial, because all lessons are designed to use 64 bit processor that supports ARMv8 architecture and such processor is only available in Raspberry Pi 3 model.
+Older versions of Raspberry Pi are not going to work with this tutorial because all lessons are designed to use a 64-bit processor that supports ARMv8 architecture and such processor is only available in Raspberry Pi 3. Newer versions, including [Raspberry Pi 3 model b +](https://www.raspberrypi.org/products/raspberry-pi-3-model-b-plus/) should work fine, though I haven't tested it yet.
 
 ### 2. [USB to TTL serial cable](https://www.amazon.com/s/ref=nb_sb_noss_2?url=search-alias%3Daps&field-keywords=usb+to+ttl+serial+cable&rh=i%3Aaps%2Ck%3Ausb+to+ttl+serial+cable) 
 
-After you get serial cable you need to test you connection. If you never done this before I recommend you to follow [this guide](https://cdn-learn.adafruit.com/downloads/pdf/adafruits-raspberry-pi-lesson-5-using-a-console-cable.pdf) It describes the process of connecting your raspberry Pi via serial cabel in great details. One thin that I can recomment you to do is to use your serial cable to power your Raspberry Pi. How to do this is described in the previous link.
+After you get serial cable, you need to test your connection. If you never did this before I recommend you to follow [this guide](https://cdn-learn.adafruit.com/downloads/pdf/adafruits-raspberry-pi-lesson-5-using-a-console-cable.pdf) It describes the process of connecting your Raspberry PI via serial cable in great details. One thing that I can recommend you to do is to use your serial cable to power your Raspberry Pi. How to do this is described in the link above.
 
-### 3. Docker
+### 3. [SD card](https://www.raspberrypi.org/documentation/installation/sd-cards.md) with installed [Raspbian OS](https://www.raspberrypi.org/downloads/raspbian/)
 
-Strictly speaking Docker is not a required dependency. It is just convinient to use docker to build source code of the lessons, especially for Mac and Windows users. Each lesson has `build.sh` script (or `build.bat` for windows users) This script uses docker to build source code of the lesson. Instructions how to install docker for you platform can be found on the [official docker website](https://docs.docker.com/engine/installation/)  
+We need Raspbian to test USB to TTL cable connectivity initially. Another reason is that after installation it leaves the SD card formatted in the way we need.
+
+### 4. Docker
+
+Strictly speaking, Docker is not a required dependency. It is just convenient to use Docker to build source code of the lessons, especially for Mac and Windows users. Each lesson has `build.sh` script (or `build.bat` for windows users) This script uses Docker to build source code of the lesson. Instructions how to install docker for your platform can be found on the [official docker website](https://docs.docker.com/engine/installation/)  
+
+If for some reasons you want to avoid using Docker, you can install [make utility](http://www.math.tau.ac.il/~danha/courses/software1/make-intro.html) as well as  `aarch64-linux-gnu` toolchain. If you are using Ubuntu you just need to install `gcc-aarch64-linux-gnu` and `build-essential` packages.
 
-If for some reasons you want to avoid using Docker, you can install [make utility](http://www.math.tau.ac.il/~danha/courses/software1/make-intro.html) as well as  `aarch64-linux-gnu` toolchain. If you are using ubuntu you just need  to install `gcc-aarch64-linux-gnu` and `build-essential` packages.

docs/lesson01/rpi-os.md

@@ -1,12 +1,12 @@
-## Lesson 1: Introducing RPi OS, or bare metal "Hello, world!"
+## 1.1: Introducing the RPi OS, or bare metal "Hello, world!"
 
-We are going to start our journey to OS development world by writing a simple bare metal "Hello, world" application. I assume that at this point you have already gone through [Prerequisites](https://github.com/s-matyukevich/raspberry-pi-os/docs/Prerequisites.md) and have everything ready for the work. If not - now is the right time to do this.
+We are going to start our journey to the OS development world by writing a simple bare metal "Hello, world" application. I assume that at this time you have gone through the [Prerequisites](https://github.com/s-matyukevich/raspberry-pi-os/docs/Prerequisites.md) and have everything ready for the work. If not - now is the right time to do this.
 
 ### Project structure
 
-All source code samples in this tutorial have the same structure. You can take a look at the sources for this particular lesson [here](https://github.com/s-matyukevich/raspberry-pi-os/src/lesson01/). Let's briefly describe its components
+Source code for each lesson in this tutorial has the same structure. You can find the sources for this particular lesson [here](https://github.com/s-matyukevich/raspberry-pi-os/src/lesson01/). Let's briefly describe the major components of this folder.
 
-1. *Makefile*. We are using [make utility](http://www.math.tau.ac.il/~danha/courses/software1/make-intro.html) to build our kernel. A makefile contains instructions how to compile and link the sources. More on this in the next section.
+1. **Makefile**. We are using [make utility](http://www.math.tau.ac.il/~danha/courses/software1/make-intro.html) to build the kernel. A makefile contains instructions how to compile and link the sources. More on this in the next section.
 1. *build.sh or build.bat*. You need those files if you want to build the kernel using Docker. In this way, you don't need to have make utility and compiler toolchain installed on your laptop.
 1. *src*. This folder contains all source code files.
 1. *include*. All header files should be placed here.