User manual update - OS image section update compact, x8 fundamentals and flashing - partial

Author: TaddyHC

content/hardware/04.pro/boards/portenta-x8/tutorials/01.user-manual/content.md

@@ -478,100 +478,13 @@ More information about Waves can be found in the official Foundries documentatio
 
 ### Update Using `uuu` Tool
 
-An alternative method to updating the Portenta X8 with the latest OS image is to use the `uuu` command (`uuu_mac` command in case you use MAC OS).
+An alternative method to update the Portenta X8 with the latest OS image is to use the `uuu` tool (or `uuu_mac` for macOS). This approach is particularly useful for users who have built a custom image or prefer a manual update process. The image files can be downloaded from the [Arduino repository](https://downloads.arduino.cc/portentax8image/image-latest.tar.gz) and extracted into a specific directory.
 
-This flash method is helpful if you have built a custom image or desire a more manual approach. Nonetheless, you will need to prepare the OS image files, and the board must be set to programming mode for this flashing process.
+Depending on the carrier being used (e.g., Max Carrier, Breakout, Hat, or Mid Carrier), DIP switch settings must be adjusted to enter programming mode or specific commands can be executed via ADB for a barebone setup. Once the board is in programming mode, you can navigate to the extracted image files and run the `uuu full_image.uuu` command to begin the flashing process.
 
-***To learn more about creating a custom image for Portenta X8, please check out [How To Build a Custom Image for Your Portenta X8](https://docs.arduino.cc/tutorials/portenta-x8/image-building) tutorial.***
+If not using a carrier, ensure the tool is running before cycling the power on the Portenta X8. Upon successful completion, reset the DIP switches or recycle the power to confirm the update.
 
-You will need to download the latest OS image file via [Arduino Download repository](https://downloads.arduino.cc/portentax8image/image-latest.tar.gz) and extract the files in a desired directory.
-
-The structure should be similar as follows after also extracting `mfgtool-files-portenta-x8.tar.gz` and `lmp-partner-arduino-image-portenta-x8.wic.gz` that came within the original compressed file:
-
-```
-Unzipped folder
-├── mfgtool-files-portenta-x8/
-├── imx-boot-portenta-x8
-├── lmp-partner-arduino-image-portenta-x8.wic
-├── lmp-partner-arduino-image-portenta-x8.wic.gz **(Compressed)**
-├── mfgtool-files-portenta-x8.tar.gz **(Compressed)**
-├── sit-portenta-x8.bin
-└── u-boot-portenta-x8.itb
-```
-
-#### Set Flashing Mode with Carrier
-
-The Portenta X8 can be set into programming mode using a carrier platform, such as Max Carrier, Breakout, or Hat Carrier, which provides DIP switches for convenient access, or a few more lines of command with barebone Portenta X8 via ADB.
-
-If you plan to use a carrier, please check the carrier's configuration to be paired with Portenta X8.
-
-For the **Portenta Max Carrier**, set the `BOOT SEL` and `BOOT` DIP switches to the ON position as depicted in the figure:
-
-![Portenta Max Carrier DIP switches](assets/max-carrier-dip-switches.png)
-
-Upon executing the `uuu` tool and ensuring the DIP switches are correctly configured, the Portenta Max Carrier will automatically start the flashing operation for the Portenta X8.
-
-For the **Portenta Breakout**, the `BT_SEL` and `BOOT` DIP switches should be set to the ON position, as illustrated in the figure:
-
-![Portenta Breakout DIP switches](assets/breakout-dip-switches.png)
-
-After running the `uuu` tool, perform a long press on the `ON` button of the Portenta Breakout to begin the flashing process. This action enables the tool to identify and connect with the device, continuing with the flashing operation.
-
-For the **Portenta Hat Carrier**, power cycle the Portenta X8, press and hold the `BOOT` button within the first 2 - 3 seconds after powering on, then press the Reset button, and release both buttons to start the flash process.
-
-You can also turn the `BTSEL` DIP switch to the ON position and power cycle the Portenta X8 to start flash process, as depicted in the figure below:
-
-![Portenta Hat Carrier DIP switches](assets/hatCarrier-dip-switches.png)
-
-The `ETH CENTER TAP` DIP switch position does not affect the flashing mode state for the Portenta Hat Carrier.
-
-For the **Portenta Mid Carrier**, the `BOOT SEL` DIP switch should be set to the ON position, as shown in the image below:
-
-![Portenta Mid Carrier DIP switches](assets/midCarrier-dip-switches.png)
-
-Like with the Portenta Max Carrier, the flashing process will commence once the `uuu` tool is run and starts searching for the device.
-
-#### Set Flashing Mode without Carrier
-
-If you decide to flash Portenta X8 without using the carrier, use the following command sequence inside the Portenta X8's terminal via ADB while you are in the root environment with root permission to reset Portenta X8's bootloader sector:
-
-```bash
-echo 0 > /sys/block/mmcblk2boot0/force_ro
-```
-
-```bash
-dd if=/dev/zero of=/dev/mmcblk2boot0 bs=1024 count=4096 && sync
-```
-
-```bash
-echo 0 > /sys/block/mmcblk2boot1/force_ro
-```
-
-```bash
-dd if=/dev/zero of=/dev/mmcblk2boot1 bs=1024 count=4096 && sync
-```
-
-#### Flashing the Portenta X8 Using `uuu` Command
-
-Now that we have the Portenta X8 in programming mode, we need to flash the OS image. Within the previously described OS image file structure, you need to navigate to the `mfgtool-files-portenta-x8` directory. You will find the `uuu` executable and its components inside the directory. Here, you will open a terminal and run the following command:
-
-```bash
-uuu full_image.uuu
-```
-
-If Portenta X8 is to be flashed without a carrier, you will want to execute the command **first** to let it search for the board. Subsequently, you will recycle the power source for Portenta X8 by unplugging and reconnecting the USB-C® cable.
-
-It will let the board begin its boot sequence, allowing it to enter programming mode as set with the defaulted internal bootloader. When the active `uuu` instance detects board has entered programming mode, it will continue with its flashing process.
-
-Once the flashing operation finishes, you will be greeted with a similar message in the terminal as the following figure:
-
-![Successful uuu flashing operation](assets/uuu-flashing-success.png)
-
-This applies to both flashing scenarios. If you have the carrier attached and decide to continue using docked with the platform, you must reset the DIP switch positions for either `BOOT SEL`, `BTSEL`, or `BT_SEL` and `BOOT` to OFF state. Reconnect the board and wait approximately 10 seconds until the Blue LED blinks, confirming the boot was successful.
-
-In case the Portenta X8 was flashed barebone, you will need to recycle the power and should be ready with the latest OS image.
-
-***For more in-depth tutorial for flashing Portenta X8, please check out [How To Flash Your Portenta X8](https://docs.arduino.cc/tutorials/portenta-x8/image-flashing) tutorial.***
+***For a detailed guide, refer to the [Flashing Portenta X8 tutorial](https://docs.arduino.cc/tutorials/portenta-x8/image-flashing).***
 
 ## First Use Of Your Portenta X8
 

content/hardware/04.pro/boards/portenta-x8/tutorials/02.x8-fundamentals/assets/Embedded_Linux_Start.png

@@ -31,12 +31,68 @@ If you need help setting up your board, please have a look at the [Portenta X8 U
 
 ## Embedded Linux
 
+The term **Embedded Linux** refers to embedded systems that use the Linux kernel and other open-source components. Linux has become a leading choice for operating systems on embedded devices due to its open-source nature and the fact that it is freely available.
+
+An **Embedded Linux** system is composed of the following items:
+
+* **Bootloader:** The first program executed right after powering the board. It has the task of initializing the hardware and the operating system, loading the **device tree** and its configuration file into the RAM.
+
+  The **device tree** is a database containing information on the hardware components of the board, which is used to forward information from the bootloader to the Kernel at the hardware level.
+
+* **Linux Kernel:** The core of the operating system. It deals with resource management, scheduling, hardware access and all the low-level operations the user does not want to worry about.
+
+  In particular, the Linux Kernel manages all the hardware resources, like CPU, memory, and I/Os, and it provides a set of APIs that abstracts those resources, allowing the user applications and libraries to be easily deployed.
+
+* **Root Filesystem:** It contains all system programs and utilities, configurations and user data (roughly speaking, the equivalent of the `C:\` drive on Windows). The Root Filesystem can be mounted from a USB stick, SD card or flash memory, being the case of the Portenta X8.
+
+![Embedded Linux Start-Up](assets/Embedded_Linux_Start.png "Embedded Linux Start-Up")
+
 There are a few things to consider to work in an embedded Linux environment. When approaching Linux-based embedded devices software solutions, you need to provide a base distribution, a mechanism to update it, and some applications that can run on the board. The X8 uses a Linux distribution built with the Yocto Project® as the base platform, with applications that are installed and packaged as confined containers.
 
 A readily-available Linux distribution that packages everything seems most attractive for end users but you need to find a distribution that implements the function that you need. If you need to tweak them, you may end up in a mess of patches on the top of someone else's build system. On the other hand, a generic distribution has some problems since installing software over it may pollute the original system and cause issues when updating the base platform. For example, if you install a new application, the older one no longer works.
 
 In addition, you have to implement lots of things like cybersecurity functions and system updates. Finally, your solution may rely on a too "generic" distribution, with tons of software you don't need. So you may end up removing a lot of software on the target and turning features on and off. Until you break the configuration or need to update the system and begin restarting with a new fresh image, consequently beginning everything from zero again.
 
+### Linux Yocto Distribution
+
+To install a Linux operating system on a board, you need to decide which packages, applications, and libraries you want to use, so basically, you need to decide which Linux distribution better suits your needs.
+
+As a matter of fact, a Linux distribution is an operating system consisting of the Linux Kernel, GNU tools, additional software, and a package manager. It may also include a display server and a desktop environment for using it as a regular desktop operating system. More than 300 Linux distributions are available on the market, including Ubuntu, Debian, Fedora, Red Hat, etc.
+
+Portenta X8 is running a [Yocto Linux distribution](https://www.yoctoproject.org/). Yocto is built based on [OpenEmbedded (OE)](http://www.openembedded.org/wiki/Main_Page), which uses [BitBake](https://docs.yoctoproject.org/bitbake/) build to generate a full Linux image. BitBake and OE are combined to form the Yocto reference project, historically called [Poky](https://www.yoctoproject.org/software-item/poky/).
+
+In addition, a full metadata selection is defined to select which tasks to perform. The following metadata is used in a Yocto project:
+
+* **Recipes:** They deliver information regarding each package (i.e. author, homepage, license, etc.), recipe version, existing dependencies, source code location and how to retrieve it, configuration settings, and target path where the created package will be saved. Files with the `.bb` extension are recipe files.
+
+* **Configuration file:** They contain metadata that define how to perform the build process. These files (with the `.conf` file extension) determine the configuration options for the machine, the compiler, the distribution, and general and user configurations. They allow you to set the target where you want to create the image and where you want to save the downloaded sources and other particular configurations.
+
+* **Classes:** Class files with the extension `.bbclass` contain common functionalities that can be shared between various recipes within the distribution. When a recipe inherits a class, it also inherits its settings and functions.
+
+* **File append:** With the extension `.bbappend`, File append extends or overwrites information for an existing recipe.
+
+OpenEmbedded Core contains a recipe layer, classes, and associated files common to all OE-based systems, including Yocto. This metadata set is maintained by both the Yocto project and the OpenEmbedded project.
+
+The Yocto distribution is a development environment that comprises various functional areas, as shown in the figure below.
+
+![Yocto Distribution Architecture](assets/Yocto_Architecture.png "Yocto Distribution Architecture")
+
+* **Layer:** The layers allow you to separate metadata by differentiating them according to software, hardware information, metadata concerning distribution, and adopted policies. Within each layer are the `conf` (with layer-specific configuration files) and `recipes-` directories. To illustrate how to use layers to maintain modularity, consider the example of recipes to support a specific target, which usually resides in a BSP layer.
+
+  In this scenario, those recipes should be isolated from other recipes and supporting metadata, like a new Graphical User Interface (GUI). You would then have a couple of layers: one for the machine's configurations and one for the GUI environment. This would allow a specific machine to present special GUI features within the BSP layer without affecting the recipes inside the GUI layer itself. All of this is possible via an append file.
+
+* **Source file:** To cross-compile any software module, be it a distribution or an application, we must have access to various source files. The latter can be sourced from three different upstream areas: Upstream Project Releases (archived at a specific location), Local Projects (available at a certain local path), and Source Control Managers (like GitHub).
+
+* **Package feeds:** This area contains packages generated by the build system, which will be used later to generate operating system images or Software Development Kits (SDKs).
+
+* **Build System:** The Build System macroblock is the heart of the Yocto distribution. It contains various processes controlled by BitBake, a tool written in Python language. The Build System parses the metadata, extracting the list of tasks to be performed. BitBake checks the software build process by using the recipes. It writes a *stamp* file in the Build Directory for each successfully completed task.
+
+* **Images:** They are compressed forms of the Root Filesystem, ready to be installed on the target. BitBake releases multiple lists of images saved into the Build Directory, including *kernel-image*, *root-filesystem-image*, and *bootloaders*.
+
+* **SDK:** From the SDK generation process you can get a standard SDK or an extensible SDK. In both cases, the output is an installation script of the SDK, which installs a cross-development toolchain, a set of libraries, and headers files, generating an environment setup script. The toolchain can be considered as part of the build system. In contrast, libraries and headers are target parts since they are generated for the target hardware.
+
+***If you want to learn more about how to work with Yocto Distribution on your Portenta X8, please check the [Portenta X8's user manual](https://docs.arduino.cc/tutorials/portenta-x8/user-manual/#working-with-linux) of this user manual.***
+
 ### Benefits of Foundries.io
 
 Foundries.io™ created their custom distribution based on Yocto with minimal software installed, by default implementing top-level cybersecurity features like OP-TEE and OSTREE that makes their solution ideal for professional applications.