|
| 1 | +# Tutoriales de desarrollo de Sistemas Operativos en Rust con la Raspberry Pi |
| 2 | + |
| 3 | +     |
| 4 | + |
| 5 | +<br/> |
| 6 | + |
| 7 | +<img src="doc/header.jpg" height="372"> <img src="doc/minipush_demo_frontpage.gif" height="372"> |
| 8 | + |
| 9 | +## ℹ️ Introducción |
| 10 | + |
| 11 | +Esto es una serie de tutoriales para los desarrolladores aficionados a los Sistemas Operativos (OS) |
| 12 | +que se están adentrando a la nueva arquitectura ARM de 64 bits [ARMv8-A |
| 13 | +architecture]. Los tutoriales darán una guía paso a paso en cómo escribir un Sistema Operativo |
| 14 | +[monolítico] desde cero. |
| 15 | +Estos tutoriales cubren la implementación común de diferentes tareas de Sistemas Operativos, como |
| 16 | +escribir en una terminal serie, configurar la memoria virtual y manejar excepciones de hardware (HW). |
| 17 | +Todo mientras usamos la seguridad y velocidad que `Rust` nos proporciona. |
| 18 | + |
| 19 | +¡Divértanse! |
| 20 | + |
| 21 | +_Atentamente, <br>Andre ([@andre-richter])_ |
| 22 | + |
| 23 | +P.S.: Para otros lenguajes, por favor busquen los diferentes archivos README. Por ejemplo, [`README.CN.md`](README.CN.md) o [`README.ES.md`](README.ES.md). Muchas gracias a nuestros |
| 24 | +[traductores](#traducciones-de-este-repositorio) 🙌. |
| 25 | + |
| 26 | +[ARMv8-A architecture]: https://developer.arm.com/products/architecture/cpu-architecture/a-profile/docs |
| 27 | +[monolítico]: https://en.wikipedia.org/wiki/Monolithic_kernel |
| 28 | +[@andre-richter]: https://github.com/andre-richter |
| 29 | + |
| 30 | +## 📑 Estructura |
| 31 | + |
| 32 | +- Cada tutorial contiene un solo binario arrancable correspondiente al núcleo. |
| 33 | +- Cada tutorial nuevo extiende el tutorial anterior. |
| 34 | +- Cada tutorial tendrá un `README` y cada `README` tendrá un pequeña sección de [`tl;dr`](https://es.wikipedia.org/wiki/TL;DR) en donde se dará una pequeña perspectiva general de los cambios y se mostrará el código fuente `diff` del tutorial anterior para que se puedan inspeccionar los cambios/adiciones que han ocurrido. |
| 35 | + - Algunos tutoriales además de tener un `tl;dr` también tendrán una sección en la que se dará una explicación con todo lujo de detalle. |
| 36 | + El plan a largo plazo es que cada tutorial tenga una buena explicación además del `tl;dr` y el `diff`; pero por el momento los únicos tutoriales |
| 37 | + que gozan de una son los tutoriales en los que creo que el `tl;dr` y el `diff` no son suficientes para comprender lo que está pasando. |
| 38 | +- El código que se escribió en este tutorial soporta y corre en la **Raspberry Pi 3** y en la **Raspberry 4** |
| 39 | + - Del tutorial 1 hasta el 5 son tutoriales "preparatorios", por lo que este código solo tendrá sentido ejecutarlo en [`QEMU`](https://www.qemu.org/). |
| 40 | + - Cuando llegues al [tutorial 5](05_drivers_gpio_uart) podrás comenzar a cargar y a ejecutar el núcleo en una |
| 41 | + Raspeberry de verdad, y observar la salida serie (`UART`). |
| 42 | +- Aunque la Raspberry Pi 3 y 4 son las principales placas este código está escrito en un estilo modular, |
| 43 | + lo que permite una fácil portabilidad a otras arquitecturas de CPU o/y placas. |
| 44 | + - Me encantaría si alguien intentase adaptar este código en una arquitectura **RISC-V**. |
| 45 | +- Para la edición recomiendo [Visual Studio Code] con [Rust Analyzer]. |
| 46 | +- En adición al texto que aparece en los tutoriales también sería recomendable revisar |
| 47 | + el comando `make doc` en cada tutorial. Este comando te deja navegar el código documentado de una manera cómoda. |
| 48 | + |
| 49 | +### Salida del comando `make doc` |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | +[Visual Studio Code]: https://code.visualstudio.com |
| 54 | +[Rust Analyzer]: https://rust-analyzer.github.io |
| 55 | + |
| 56 | +## 🛠 Requisitos del sistema |
| 57 | + |
| 58 | +Estos tutoriales están dirigidos principalmente a distribuciones de **Linux**. |
| 59 | +Muchas de las cosas vistas aquí también funcionan en **macOS**, pero esto solo es _experimental_. |
| 60 | + |
| 61 | +### 🚀 La versión tl;dr |
| 62 | + |
| 63 | +1. [Instala Docker Desktop][install_docker]. |
| 64 | +2. (**Solo para Linux**) Asegúrate de que la cuenta de tu usuario está en el [grupo `docker`][docker group]. |
| 65 | +3. Prepara la `Rust` toolchain. La mayor parte se hará automáticamente durante el primer uso del archivo [rust-toolchain](rust-toolchain). |
| 66 | + Todo lo que nos queda hacer a nosotros es: |
| 67 | + |
| 68 | + i. Si ya tienes una versión de Rust instalada: |
| 69 | + ```bash |
| 70 | + cargo install cargo-binutils rustfilt |
| 71 | + ``` |
| 72 | + |
| 73 | + ii. Si necesitas instalar Rust desde cero: |
| 74 | + ```bash |
| 75 | + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh |
| 76 | +
|
| 77 | + source $HOME/.cargo/env |
| 78 | + cargo install cargo-binutils rustfilt |
| 79 | + ``` |
| 80 | + |
| 81 | +4. En caso de que uses `Visual Studio Code`, recomiendo que instales la extensión [Rust Analyzer extension]. |
| 82 | +5. (**Solo para macOS**) Instala algunas `Ruby` gems. |
| 83 | + |
| 84 | + Ejecuta esto en la carpeta root del repositorio: |
| 85 | + |
| 86 | + ```bash |
| 87 | + bundle install --path .vendor/bundle --without development |
| 88 | + ``` |
| 89 | + |
| 90 | +[docker group]: https://docs.docker.com/engine/install/linux-postinstall/ |
| 91 | +[Rust Analyzer extension]: https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer |
| 92 | + |
| 93 | +### 🧰 Más detalles: Eliminando Lios con Toolchains |
| 94 | + |
| 95 | +Esta serie trata de enfocarse lo máximo posible en tener una experiencia agradable para el usario. |
| 96 | +Por lo tanto, se han dirigido muchos esfuerzos a eliminar la parte más difícil del desarrollo de |
| 97 | +los sistemas incorporados (embedded) tanto como se pudo. |
| 98 | + |
| 99 | +Rust por sí mismo ya ayuda mucho, porque tiene integrado el soporte para compilación cruzada. |
| 100 | +Todo lo que necesitamos para compilar desde una máquina con una arquitectura `x86` a una Raspberry Pi |
| 101 | +con arquitectura `AArch64` será automáticamente instalado por `rustup`. Sin embargo, además de usar |
| 102 | +el compilador de Rust, también usaremos algunas otras herramientas, entre las cuales están: |
| 103 | + |
| 104 | +- `QEMU` para emular nuestro núcleo en nuestra máquina principal. |
| 105 | +- Una herramienta llamada `Minipush` para cargar el núcleo en una Raspberry Pi cuando queramos usando `UART`. |
| 106 | +- `OpenOCD` y `GDB` para hacer depuración ("debugging") en la máquina a instalar. |
| 107 | + |
| 108 | +Hay muchas cosas que pueden salir mal mientras instalamos y/o compilamos las versiones correctas de cada |
| 109 | +herramienta en tu máquina. Por ejemplo, tu distribución de Linux tal vez podría no proporcionar las versiones más |
| 110 | +recientes de paquetes que se necesiten. O tal vez te falten algunas dependencias para la compilar estas herramientas. |
| 111 | + |
| 112 | +Esta es la razón por la cual usaremos [Docker][install_docker] mientras sea posible. Te |
| 113 | +estamos proporcionando un contenedor que tiene todas las herramientas o dependencias preinstaladas. |
| 114 | +Si quieres saber más acerca de Docker y revisar el contenedor proporcionado, por favor revisa la carpeta |
| 115 | +[docker](docker) del repositorio. |
| 116 | + |
| 117 | +[install_docker]: https://docs.docker.com/get-docker/ |
| 118 | + |
| 119 | +## 📟 Puerto Serie USB |
| 120 | + |
| 121 | +Ya que el núcleo desarrollado en este tutorial se ejecuta en hardware real, se recomienda que tengas un adaptador de puerto serie USB cable para sentir la experiencia completa. |
| 122 | + |
| 123 | +- Puedes encontrar estos cables que deberían funcionar sin ningún problema en [\[1\]] [\[2\]], pero |
| 124 | + hay muchos otros que pueden funcionar. Idealmente, tu cable estaría basado en el chip `CP2102`. |
| 125 | +- Lo conectas a los pines `GND` y `GPIO` `14/15` como se muestra en la parte inferior. |
| 126 | +- [Tutorial 5](05_drivers_gpio_uart) es la primera vez en la que lo vas usar. Revisa las instrucciones |
| 127 | + sobre cómo preparar una tarjeta SD para arrancar en tu núcleo desde ahí. |
| 128 | +- Empezando con el [tutorial 6](06_uart_chainloader), arrancar núcleos en tu Raspberry Pi comienza a ser |
| 129 | + más fácil. En este tutorial se desarrolla un `chainloader`, que será el último archivo que necesitarás |
| 130 | + copiar de manera manual a la tarjeta SD por el momento. Esto te permitirá cargar los núcleos de los tutoriales |
| 131 | + durante el arranque usando `UART`. |
| 132 | + |
| 133 | + |
| 134 | + |
| 135 | +[\[1\]]: https://www.amazon.de/dp/B0757FQ5CX/ref=cm_sw_r_tw_dp_U_x_ozGRDbVTJAG4Q |
| 136 | +[\[2\]]: https://www.adafruit.com/product/954 |
| 137 | + |
| 138 | +## 🙌 Agradecimientos |
| 139 | + |
| 140 | +La versión original de estos tutoriales empezó como un fork de los increíbles |
| 141 | +[tutoriales de programación en hardware en la RPi3](https://github.com/bztsrc/raspi3-tutorial) en `C` |
| 142 | +de [Zoltan Baldaszti](https://github.com/bztsrc). ¡Gracias por darme un punto de partida! |
| 143 | + |
| 144 | +### Traducciones de este repositorio |
| 145 | + |
| 146 | + - **Chino:** |
| 147 | + - [@colachg] y [@readlnh]. |
| 148 | + - Necesitan actualizaciones. |
| 149 | + - **Español:** |
| 150 | + - [@zanezhub]. |
| 151 | + - En el futuro habrán tutoriales traducidos al español. |
| 152 | + |
| 153 | +[@colachg]: https://github.com/colachg |
| 154 | +[@readlnh]: https://github.com/readlnh |
| 155 | +[@zanezhub]: https://github.com/zanezhub |
| 156 | + |
| 157 | +## Licencia |
| 158 | + |
| 159 | +Este proyecto está licenciado por cualquiera de las siguientes licencias como alguna de tus dos opciones |
| 160 | + |
| 161 | +- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) |
| 162 | +- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) |
| 163 | + |
| 164 | + |
| 165 | +### Contribución |
| 166 | + |
| 167 | +A menos de que lo menciones, cualquier contribución enviada por ti para su inclusión en este trabajo, |
| 168 | +tal como se define en la licencia Apache-2.0, deberá tener doble licencia como se muestra en la parte superior, sin ningún |
| 169 | +cambio de términos o condiciones. |
| 170 | + |
| 171 | + |
0 commit comments