> For the complete documentation index, see [llms.txt](https://carloss-organization-4.gitbook.io/tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://carloss-organization-4.gitbook.io/tech/design/provisioning/x-shield-module-of-the-embedded-boards-initialization.md).

# \[X-Shield] Module of the Embedded Boards initialization

## 1. Overview <a href="#id-1.-overview" id="id-1.-overview"></a>

The Embedded Boards initialization (EBIM) is a module of the X-Shield. It is used for initializing the embedded board containing the embedded board initialization, firmware updating by “one-key“. It is the GUI tool running on the Windows and Ubuntu systems. Now the board platforms can be supported as follows:

* [xilinx-zynq](https://autoxai.atlassian.net/wiki/spaces/SEC/pages/1983842083/ZYNQ+Introduction+to+ZYNQ+Series+Documents)
* [nxp-s32g](https://autoxai.atlassian.net/wiki/spaces/SEC/pages/1923055625/S32G+Safe+and+Secure+features+and+their+applications)
* nxp-layerscape

The repo is <https://github.com/carloscn/qt/tree/master/zynq_tool>

## 1. The EBIM High-Level Design <a href="#id-1.-the-ebim-high-level-design" id="id-1.-the-ebim-high-level-design"></a>

### 1.1 Firmware updating ways <a href="#id-1.1-firmware-updating-ways" id="id-1.1-firmware-updating-ways"></a>

For embedded devices, there are usually two ways to save the firmware (boot image, boot script, Linux kernel, Linux rootfs, ramdisk etc):

* Using the SD way;
* Using the onboard FLASH or eMMC.

#### 1.1.1 SD method <a href="#id-1.1.1-sd-method" id="id-1.1.1-sd-method"></a>

Many boards select the SD card as the firmware storage. According to the Xilinx zynq and NXP s32g booting rules, the zynq, s32g, and layerscape can be booted from an SD card. The function of the EBIM GUI tool is shown in the following figure:

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2FWBM2dRuRYJRGiNplIQxH%2Fimage.png?alt=media&amp;token=ac1302f5-e873-4cfb-99a6-c81f4785f102" alt=""><figcaption></figcaption></figure>

The Xilinx provides a way to burn the boot image to onboard flash using the JTAG: <https://www.centennialsoftwaresolutions.com/post/flashing-qspi-over-jtag-on-zynq-without-using-gui>

### 1.2 Architecture design <a href="#id-1.2-architecture-design" id="id-1.2-architecture-design"></a>

The EBIM is a GUI app for Windows OS and Ubuntu OS basing the [Qt framework](https://autoxai.atlassian.net/wiki/spaces/SEC/pages/2004616466/X-Shield+Walking+through+the+X-Shield#3.1-Qt). There are 4 classes for the EBIM and the 4 classes are dispatched by the `MainWindow` (The `MainWindow` class is the GUI class defined by the Qt framework), which contains the device scanning, the sd card operations, the flash operations, and files management. The class architecture is shown in the following figure:

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2F2h7cTGO7hoKBqG07SZNo%2Fimage.png?alt=media&amp;token=e205b0fe-93d0-4f2f-8b3b-d213eca93c1c" alt=""><figcaption></figcaption></figure>

Note, the name of the prefixed with the 'Q' Class is offered by the Qt framework. The figure only lists the main Qxxx class. The [QProcess](https://doc.qt.io/qt-5/qprocess.html) class is used to start external programs and to communicate with them. We make use of the QProcess to execute the external scripts. [QThread](https://doc.qt.io/qt-5/qthread.html) class provides a platform-independent way to manage threads. We declare the `sdops` and `flashops` as threads independent of MainWindow. The EBIM also calls various other Qt classes, including QFile, QMutex, QString, QByteArray, etc. in addition to QProcess and QThread. please refer to the EBIM code and Qt API document <https://doc.qt.io/qt-5/classes.html>

The functions of the EBIM contain the following:

* The class Device Scan: Identify and scan available devices and return device information. The device information will be inserted into the MainWindow `DeviceList`.
* The class SD card Operations: Responsible for executing scripts about SD card operations that contain the sd card formatting, the making filesystem for the sd card, and copying the files to the SD card.
* The class FLASH Operations: Responsible for executing the scripts about flash operations that contain flash initialization and flash writing.

### 1.3 Function diagram <a href="#id-1.3-function-diagram" id="id-1.3-function-diagram"></a>

The succinct UML figure is shown in the following figure. For detailed UML block, please refer to the corresponding low-level design.

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2FCykD2fryGDiMUknUf6bn%2Fimage.png?alt=media&amp;token=3a902cac-ac85-4dcd-a834-ab2978ebcb41" alt=""><figcaption></figcaption></figure>

aIn the nutshell, the EBIM will list all the available devices and run the corresponding scripts. The really touching and operating of the device is programmed in the bash/bat script. The following figure shows the task flow of the EBIM.

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2FpRIMotuLbTxB08L4fFit%2Fimage.png?alt=media&amp;token=5feebda6-6178-4bcd-9546-10f8813d2dd9" alt=""><figcaption></figcaption></figure>

### 1.4 The UI Design <a href="#id-1.4-the-ui-design" id="id-1.4-the-ui-design"></a>

The following screenshot is the GUI design of the EBIM:

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2FtZ4LmcQcFbv50LoGKIzH%2Fimage.png?alt=media&amp;token=ca103fda-f1e3-42e3-bf88-1ce11e863158" alt=""><figcaption></figcaption></figure>

## 2. The EBIM Low-Level Design <a href="#id-2.-the-ebim-low-level-design" id="id-2.-the-ebim-low-level-design"></a>

The functions of the EBIM contain the following:

* The class Device Scan
* The class SD card Operations
* The class FLASH Operations

### 2.1 The class of Device Scan <a href="#id-2.1-the-class-of-device-scan" id="id-2.1-the-class-of-device-scan"></a>

The class of Device Scan is to list all available devices that are connected to the host. The UML figure of the Device Scan is shown in the following figure:

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2FKKWbaMtCVmojSOZ3zLht%2Fimage.png?alt=media&amp;token=68836cf0-5722-444c-b9f8-7ee848872f7b" alt="" width="375"><figcaption></figcaption></figure>

#### 2.1.1 SD devices <a href="#id-2.1.1-sd-devices" id="id-2.1.1-sd-devices"></a>

For the Linux Device, the SD device list can be listed by `ll /dev/sd*`, and the corresponding model name is stored in the `/sys/block/dev/sdx/device/model`. Moreover, the size of the device can be obtained by Linux ioctl API. Finally, combine all the information, and return them.

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2FN00S8UcxELT1uO4tenRQ%2Fimage.png?alt=media&amp;token=879c770e-2846-4bd4-9523-90a3e2aeb770" alt="" width="375"><figcaption></figcaption></figure>

or the Window Device, `wmic diskdrive get name,interfacetype,size,model` command can help us to get the disk information. The information is shown in the following figure:

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2FjxId18y3UqIGSJVQu86H%2Fimage.png?alt=media&amp;token=f9602e48-dafc-4d25-99ac-854927c85e46" alt=""><figcaption></figcaption></figure>

The EBIM just extracts devices by the `InterfaceType` 'USB', the size and model name can be obtained.

#### 2.1.1 JTAG devices <a href="#id-2.1.1-jtag-devices" id="id-2.1.1-jtag-devices"></a>

For the burning flash devices, we need to get the information from the JTAG driver.

Reserve the interface, and add the module when necessary.

### 2.2 The class of Sd Operation <a href="#id-2.2-the-class-of-sd-operation" id="id-2.2-the-class-of-sd-operation"></a>

The class of the Sd Operation is to format the target available device that is inserted into the host. The UML figure of the Sd Operation is shown in the following figure:

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2FcE92u91fHnmpJusVIC80%2Fimage.png?alt=media&amp;token=7df6fe5d-9cee-4ec1-8949-78159eeb8fdc" alt="" width="375"><figcaption></figcaption></figure>

#### 2.2.1 Tarball mode <a href="#id-2.2.1-tarball-mode" id="id-2.2.1-tarball-mode"></a>

The tarball mode will recognize that the input file is a tar.gz file, and divide the task into five steps. The SD operation uses a series of scripts to finish the task. The developer shall add his scripts to the corresponding folder. The SD operation class will call it automatically.

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2F9ERgMuROWBE9ImpFXPCu%2Fimage.png?alt=media&amp;token=c7632257-b6c6-4270-bb35-df26fc21f184" alt=""><figcaption></figcaption></figure>

The scripts are listed in the following figure:

<figure><img src="https://1204947731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtqiX1ZbXhRorHX3bwk1r%2Fuploads%2Fa9jp9LP0tXU6MW6E8K67%2Fimage.png?alt=media&amp;token=845782f0-8e20-4bdf-b6c7-7e591d80a715" alt=""><figcaption></figcaption></figure>

#### 2.2.2 img mode <a href="#id-2.2.2-img-mode" id="id-2.2.2-img-mode"></a>

The img mode will recognize that the input file is an img format file and only run one step. The script will use the `dd` command to burn the img to the SD card. This mode will burn for a long time.

### 2.3 The class of Flash Operation <a href="#id-2.3-the-class-of-flash-operation" id="id-2.3-the-class-of-flash-operation"></a>

Reserve the interface, and add the module when necessary.