diff --git a/.codeclimate.yml b/.codeclimate.yml index 82612386e47331b31b1f49fb43613650d5ac0190..2439de43f8ebf66d9899aad386c83b1e2c7e4147 100644 --- a/.codeclimate.yml +++ b/.codeclimate.yml @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its +# SPDX-FileCopyrightText: Copyright 2023-2024 Arm Limited and/or its # affiliates # # SPDX-License-Identifier: MIT @@ -28,7 +28,7 @@ plugins: - "**.cfg" - "documentation/Makefile" - "**.patch" - dict_path: "qa-checks/cassini-bsp-dictionary" + dict_path: ".dictionary" yamllint: enabled: true oelint-adv: diff --git a/qa-checks/cassini-bsp-dictionary b/.dictionary similarity index 85% rename from qa-checks/cassini-bsp-dictionary rename to .dictionary index fba8dc9da177e50266b66e2b8048493a13d84bc0..8cb533b2afb9fa27f43ac569882a15600293e0c1 100644 --- a/qa-checks/cassini-bsp-dictionary +++ b/.dictionary @@ -5,11 +5,14 @@ alsa AUTOFS AUTOFS4 +AUTOQSPI +AUTORUN backend bmap bmaptool bootimg bootloader +bsp buildable BUILDIN cassini @@ -22,16 +25,21 @@ configfile corstone cpio crypto +dialout distro DISTROOVERRIDES +EEPROM efidisk eglibc envparse extfs FILESEXTRAPATHS flashfw +fname +fout fstype FSTYPES +fvps gcsections gettext gitlab @@ -46,11 +54,15 @@ LAYERSERIES LAYERSERIES_COMPAT LIBC Linaro +linuxboot mandatoryvar +MBPMIC mdev meta-cassini-bsp mickledore +minicom modutils +MPS3 msdos mtrace multiconfig @@ -59,21 +71,29 @@ multilineident N1SDP nanbield nativesdk +Neoverse netbase networkd no_cloud nooelint +OCVM opkg optee packagegroup +picocom +PMIC posix ptable +qa +QSPI readlink +README requireinclude requirenotfound RPROVIDER SAST scarthgap +sdcard SDHC sourceparams srcurifile @@ -81,8 +101,10 @@ suggestedvar tarbz2 TF-A THISDIR +TOTALIMAGES udev unitdir +upstreamed usbgadget usbhost util @@ -90,5 +112,6 @@ utils VIRT wchar WIDEC +XNVM xtests -zeroconf \ No newline at end of file +zeroconf diff --git a/Dangerfile b/Dangerfile index bd2dd49bb2efb193becdbd6eccb22d220fc5c1b8..6fda6d7c5f14f13a34a2e3b99fa7cb6225626b08 100644 --- a/Dangerfile +++ b/Dangerfile @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its +# SPDX-FileCopyrightText: Copyright 2023-2024 Arm Limited and/or its # affiliates # # SPDX-License-Identifier: MIT @@ -10,7 +10,7 @@ require 'embed-a-dangerfiles' Embed_A::Dangerfiles.for_project(self) do |dangerfiles| # Import all plugins from the gem dangerfiles.import_plugins - helper.config.dict_path = "qa-checks/cassini-bsp-dictionary" + helper.config.dict_path = ".dictionary" # Import all rules from the gem dangerfiles.import_dangerfiles end diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 0000000000000000000000000000000000000000..fcd3a4db08b59ec47279e50272c663a689f021f0 --- /dev/null +++ b/LICENSE.rst @@ -0,0 +1,45 @@ +####### +License +####### + +The software is provided under the MIT license (below). + +:: + + Copyright 2024 Arm Limited and/or its affiliates + + open-source-office@arm.com + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to + deal in the Software without restriction, including without limitation the + rights to use, copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + IN THE SOFTWARE. + +**************** +SPDX Identifiers +**************** + +Individual files contain the following tags instead of the full license text. + +:: + + SPDX-FileCopyrightText: Copyright + + SPDX-License-Identifier: MIT + +This enables machine processing of license information based on the SPDX +License Identifiers that are here available: http://spdx.org/licenses/ diff --git a/README b/README deleted file mode 100644 index 42a870ad84ea6a4a19a172129855148724a0c1ae..0000000000000000000000000000000000000000 --- a/README +++ /dev/null @@ -1,5 +0,0 @@ -# Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. -# -# SPDX-License-Identifier: MIT - -See ../README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..70f26bad52cfc278d2ef523d13a11972051f760d --- /dev/null +++ b/README.md @@ -0,0 +1,62 @@ + + +# Cassini BSP + +## Introduction + +This Yocto layer is used by +[meta-cassini](https://gitlab.com/Linaro/cassini/meta-cassini). + +It modifies some Arm-maintained machine definitions and recipes from +[meta-arm-bsp](https://git.yoctoproject.org/meta-arm/tree/meta-arm-bsp) so that +they can be used to build and boot Cassini distro images. + +Currently supported platforms include: +* Corstone-1000 FVP (corstone1000-fvp) +* Corstone-1000 for MPS3 (corstone1000-mps3) +* Neoverse N1 System Development Platform (n1sdp) + +At any given point in time, this repository may hold recipes, append-files, +config fragments, and/or out-of-tree patches which either: +- have not been upstreamed yet +- cannot be upstreamed (they are Cassini specific or otherwise inappropriate) + +For more details, see the Cassini documentation +[here](https://cassini.readthedocs.io/en/latest/index.html) + +Contributions to this repository are not accepted at this time + +## Repository License + +The repository's standard license is the MIT license, under which most of the +repository's content is provided. Exceptions to this standard license relate to +files that represent modifications to externally licensed works (for example, +patch files). These files may therefore be included in the repository under +alternative licenses in order to be compliant with the licensing requirements of +the associated external works. + +License details may be found in the [local license file](LICENSE.rst), or as +part of the project documentation. + +## Reporting Issues + +Please report problems using GitLab's "Issues" feature. + +## Reporting Security Issues + +If you find any security vulnerabilities, please do not report them via GitLab +Instead, send an email to the security team at psirt@arm.com stating that you +may have found a security vulnerability in meta-cassini-bsp. + +## Disclaimer + +Arm reference solutions are Arm public example software projects that track and +pull upstream components, incorporating their respective security fixes +published over time. Arm partners are responsible for ensuring that the +components they use contain all the required security fixes, if and when they +deploy a product derived from Arm reference solutions. diff --git a/documentation/developer_manual/corstone1000.rst b/documentation/developer_manual/corstone1000.rst new file mode 100644 index 0000000000000000000000000000000000000000..d584610ac2dee66a7a2f073fc0b3f949723bd36c --- /dev/null +++ b/documentation/developer_manual/corstone1000.rst @@ -0,0 +1,22 @@ +.. + # SPDX-FileCopyrightText: Copyright (c) 2023, Linaro Limited. + # + # SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its + # affiliates + # + # SPDX-License-Identifier: MIT + +Corstone-1000 for MPS3 +====================== + + * **Corresponding value for** ``MACHINE`` **variable**: ``corstone1000-mps3`` + * **Target Platform Config**: ``kas/corstone1000-mps3.yml`` + + This supported target platform is the Corstone-1000 for MPS3, implemented in + |meta-arm-bsp|_. + + To read documentation about the Corstone-1000, see the + |Arm Corstone-1000 Technical Overview|_. + + For more information about the software stack for the Corstone-1000, see + |Arm Corstone-1000 Software| diff --git a/documentation/developer_manual/corstone1000fvp.rst b/documentation/developer_manual/corstone1000fvp.rst new file mode 100644 index 0000000000000000000000000000000000000000..10ab71b4bfe7a5fbcec3fcd587a6bafd18201026 --- /dev/null +++ b/documentation/developer_manual/corstone1000fvp.rst @@ -0,0 +1,25 @@ +.. + # SPDX-FileCopyrightText: Copyright (c) 2023, Linaro Limited. + # + # SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its + # affiliates + # + # SPDX-License-Identifier: MIT + +Corstone-1000 FVP +================= + + * **Corresponding value for** ``MACHINE`` **variable**: ``corstone1000-fvp`` + * **Target Platform Config**: ``kas/corstone1000-fvp.yml`` + + This supported target platforms is the Corstone-1000 FVP, implemented in + |meta-arm-bsp|_. + + To read documentation about the Corstone-1000, see the + |Arm Corstone-1000 Technical Overview|_. + + For more information about the software stack for the Corstone-1000, see + |Arm Corstone-1000 Software| + + To read documentation about the Corstone-1000 FVP, see the + |Fast Models Fixed Virtual Platforms (FVP) Reference Guide|_. diff --git a/documentation/developer_manual/n1sdp.rst b/documentation/developer_manual/n1sdp.rst new file mode 100644 index 0000000000000000000000000000000000000000..92c43ac257d78ac5094b8ea4c0d90e5a2ffd8c73 --- /dev/null +++ b/documentation/developer_manual/n1sdp.rst @@ -0,0 +1,42 @@ +.. + # SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its + # affiliates + # + # SPDX-License-Identifier: MIT + +Neoverse N1 System Development Platform (N1SDP) +=============================================== + + * **Corresponding value for** ``MACHINE`` **variable**: ``n1sdp``. + * **Target Platform Config**: ``kas/n1sdp.yml``. + + This supported target platform is the Neoverse N1 System Development Platform + (N1SDP), implemented in |meta-arm-bsp|_. + + To read documentation about the N1SDP, see the + |N1SDP Technical Reference Manual|_. + +.. note:: + Support for the N1SDP platform in Cassini is primarily intended for + development, test, and demonstration of features for infrastructure + platforms which typically use EDK2 and Trusted Services without a + secure enclave. + + Due to a limitation of the platform hardware (it does not have + enough Secure world RAM) Trusted Services is configured to run + from Normal world RAM. This configuration is not compliant with + the PSA specifications. + + Platforms intended for production should be configured by the + platform provider to be compliant with the PSA specifications. + +.. warning:: + To avoid system hangs under testing, N1SDP firmware packages built in the + Cassini CI pipeline now use the newer PMIC firmware image which is not + compatible with older boards (with serial numbers before ``36253xxx``). + + As programming older boards with the newer PMIC firmware image can cause + component damage, please ensure any devices used in CI have serial numbers + later than ``36253xxx``. + + See `Potential firmware damage notice`_ for details diff --git a/documentation/user_manual/corstone1000.rst b/documentation/user_manual/corstone1000.rst new file mode 100644 index 0000000000000000000000000000000000000000..b6e66d81ed64fe719faea2578fb6679f5a7ae753 --- /dev/null +++ b/documentation/user_manual/corstone1000.rst @@ -0,0 +1,184 @@ +.. + # SPDX-FileCopyrightText: Copyright (c) 2023, Linaro Limited. + # + # SPDX-FileCopyrightText: Copyright 2023-2024 Arm Limited and/or its + # affiliates + # + # SPDX-License-Identifier: MIT + +############################################### +Getting Started with Arm Corstone-1000 for MPS3 +############################################### + +This document explains how to build, deploy, and boot the Cassini distro on the +Arm Corstone-1000 for MPS3. + +**NOTE:** Requires a micro SD card (at least 4 GB) and a USB drive (at +least 16 GB) + +.. note:: + Due to performance limitations, K3S is not currently supported on + the Arm Corstone-1000 for MPS3. + +***** +Build +***** + +The kas configuration file ``kas/corstone1000-mps3.yml`` +can be used to build images which target the Corstone-1000 for MPS3. + +******************** +Building MPS3 images +******************** + +To build Corstone-1000 MPS3 images: + + .. code-block:: console + + kas build --update kas/cassini.yml:kas/corstone1000-mps3.yml + +This will produce a Corstone-1000 firmware image here: + + ``build/tmp/deploy/images/corstone1000-mps3/corstone1000-flash-firmware-image-corstone1000-mps3.wic`` + +And a Cassini distribution image here: + + ``build/tmp/deploy/images/corstone1000-mps3/cassini-image-base-corstone1000-mps3.rootfs.wic.gz`` + + ``build/tmp/deploy/images/corstone1000-mps3/cassini-image-base-corstone1000-mps3.rootfs.wic.bmap`` + +*************************************************** +Prepare the firmware image for FPGA (Micro SD card) +*************************************************** + +The user should download the FPGA bit file image from `this link `__ +and under the section ``AN550: Arm® Corstone™-1000 for MPS3 Version 2.0``. + +Only copy the current directory structure shown below on to the Micro SD Card. + +.. code-block:: console + + config.txt + MB + ├── BRD_LOG.TXT + ├── HBI0309B + │ ├── AN550 + │ │ ├── AN550_v2.bit + │ │ ├── an550_v2.txt + │ │ └── images.txt + │ ├── board.txt + │ └── mbb_v210.ebf + └── HBI0309C + ├── AN550 + │ ├── AN550_v2.bit + │ ├── an550_v2.txt + │ └── images.txt + ├── board.txt + └── mbb_v210.ebf + SOFTWARE + ├── an550_st.axf + ├── bl1.bin + ├── cs1000.bin + └── ES0.bin + +To configure the board to boot automatically when powered on, edit +``./config.txt`` and change the value of ``AUTORUN`` from ``FALSE`` +to ``TRUE``. + +Depending upon the MPS3 board version (printed on the MPS3 board HBI0309B or HBI0309C) you should +update the ``./AN550/images.txt`` file so that the file points to the images under SOFTWARE directory. + +Here is an example + +.. code-block:: console + + ;************************************************ + ; Preload port mapping * + ;************************************************ + ; PORT 0 & ADDRESS: 0x00_0000_0000 QSPI Flash (XNVM) (32MB) + ; PORT 0 & ADDRESS: 0x00_8000_0000 OCVM (DDR4 2GB) + ; PORT 1 Secure Enclave (M0+) ROM (64KB) + ; PORT 2 External System 0 (M3) Code RAM (256KB) + ; PORT 3 Secure Enclave OTP memory (8KB) + ; PORT 4 CVM (4MB) + ;************************************************ + + [IMAGES] + TOTALIMAGES: 3 ;Number of Images (Max: 32) + + IMAGE0PORT: 1 + IMAGE0ADDRESS: 0x00_0000_0000 + IMAGE0UPDATE: RAM + IMAGE0FILE: \SOFTWARE\bl1.bin + + IMAGE1PORT: 0 + IMAGE1ADDRESS: 0x00_0000_0000 + IMAGE1UPDATE: AUTOQSPI + IMAGE1FILE: \SOFTWARE\cs1000.bin + + IMAGE2PORT: 2 + IMAGE2ADDRESS: 0x00_0000_0000 + IMAGE2UPDATE: RAM + IMAGE2FILE: \SOFTWARE\es0.bin + +The binaries are present in OUTPUT_DIR = ``<_workspace>/build/tmp/deploy/images/corstone1000-mps3`` directory. + +1. Copy ``bl1.bin`` from OUTPUT_DIR to SOFTWARE directory of the Micro SD card. +2. Copy ``corstone1000-flash-firmware-image-corstone1000-mps3.wic`` from OUTPUT_DIR directory to SOFTWARE + directory of the Micro SD card and rename the wic image to ``cs1000.bin``. +3. Copy ``es_flashfw.bin`` from OUTPUT_DIR directory to SOFTWARE directory of the Micro SD + card and rename to ``es0.bin``. + +**NOTE:** Renaming of the images are required because MCC firmware has +limitation of 8 characters before .(dot) and 3 characters after .(dot). + +********************************************* +Prepare the distro image for FPGA (USB image) +********************************************* + +Use the ``lsblk`` command to determine USB drive and bmap tool to copy the cassini distro to it. + +.. code-block:: console + + lsblk + sudo bmaptool copy --bmap cassini-image-base-corstone1000-mps3.rootfs.wic.bmap cassini-image-base-corstone1000-mps3.rootfs.wic.gz /dev/ + + +**************************** +Running the software on FPGA +**************************** + +Insert SD card and USB drive before switching ON the device. + +On the host machine, connect the board via USB. + +If there are no other TTY USB devices, then the three ports from the MPS3 +will be connected as follows: + + - ttyUSB0 for MCC, OP-TEE and Secure Partition + - ttyUSB1 for Boot Processor (Cortex-M0+) + - ttyUSB2 for Host Processor (Cortex-A35) + +The rest of this guide assumes there are no other TTY USB devices on the +host machine. + +Connect to the serial console(s) using any terminal client (``picocom``, +``minicom``, or ``screen`` should all work). + +For example, run the following commands to open new picocom sessions for +each port: + +.. code-block:: console + + sudo picocom -b 115200 /dev/ttyUSB0 + sudo picocom -b 115200 /dev/ttyUSB1 + sudo picocom -b 115200 /dev/ttyUSB2 + +.. note:: + + ``sudo`` should not be required if the current user is in the + ``dialout`` group + +.. note:: + See notes under :ref:`run-time_integration_tests_label` before running + validation steps. diff --git a/documentation/user_manual/corstone1000fvp.rst b/documentation/user_manual/corstone1000fvp.rst new file mode 100644 index 0000000000000000000000000000000000000000..5bf6bf6ea943149afe36e48f966586be6e333b9b --- /dev/null +++ b/documentation/user_manual/corstone1000fvp.rst @@ -0,0 +1,124 @@ +.. + # SPDX-FileCopyrightText: Copyright (c) 2023, Linaro Limited. + # + # SPDX-FileCopyrightText: Copyright 2023-2024 Arm Limited and/or its + # affiliates + # + # SPDX-License-Identifier: MIT + +########################################## +Getting Started with Arm Corstone-1000 FVP +########################################## + +This document explains how to build and boot the Cassini distro on the Arm +Corstone-1000 FVP (Fast Model Fixed Virtual Platform). + +.. note:: + Due to performance limitations, K3S is not currently supported on + the Arm Corstone-1000 FVP. + +***** +Build +***** + +The provided kas configuration file kas/corstone1000-fvp.yml can be used to build images +that are targeting the Corstone-1000 FVP. + +.. note:: + To build and run any image for the Corstone-1000 FVP the user has to + accept its |EULA|_, which can be done by executing + the following command in the build environment: + + .. code-block:: console + + export FVP_CORSTONE1000_EULA_ACCEPT=True + +******************* +Building FVP images +******************* + +To build Corstone-1000 FVP images: + + .. code-block:: console + + kas build --update kas/cassini.yml:kas/corstone1000-fvp.yml + +Or if using kas-container: + + .. code-block:: console + + kas-container --runtime-args "-e FVP_CORSTONE1000_EULA_ACCEPT=True" build \ + kas/cassini.yml:kas/corstone1000-fvp.yml + +This will produce a Corstone-1000 firmware image here: + + ``build/tmp/deploy/images/corstone1000-fvp/corstone1000-flash-firmware-image-corstone1000-fvp.wic`` + +And a Cassini distribution image here: + + ``build/tmp/deploy/images/corstone1000-fvp/cassini-image-base-corstone1000-fvp.rootfs.wic`` + +*************** +Running the FVP +*************** + +To start the FVP and get the console: + + .. code-block:: console + + kas shell -c "../layers/meta-arm/scripts/runfvp --console" \ + kas/cassini.yml:kas/corstone1000-fvp.yml + +Or if using kas-container: + + .. code-block:: console + + kas-container --runtime-args "-e FVP_CORSTONE1000_EULA_ACCEPT=True" \ + shell -c "/work/layers/meta-arm/scripts/runfvp --console" \ + kas/cassini.yml:kas/corstone1000-fvp.yml + +By default, the Corstone-1000 FVP is configured for user mode networking. For more +information and instructions on how to configure networking with Fixed Virtual Platforms, +refer to the |Fast Models Reference Guide|_. + +.. note:: + See notes under :ref:`run-time_integration_tests_label` before running + validation steps. + +.. _reproduce_run-time_integration_tests: + +********** +Validation +********** + +The following validation tests can be performed on the Cassini Reference Stack: + + * System Integration Tests: + + * Cassini Architecture Stack: + + .. code-block:: console + + TESTIMAGE_AUTO=1 kas build kas/cassini.yml:kas/corstone1000-fvp.yml + + Or if using kas-container: + + .. code-block:: console + + kas-container --runtime-args "-e FVP_CORSTONE1000_EULA_ACCEPT=True -e TESTIMAGE_AUTO=1" build \ + kas/cassini.yml:kas/corstone1000-fvp.yml + + The previous test takes around 2 minutes to complete. + + A similar output should be printed out: + + .. code-block:: console + + NOTE: Executing Tasks + Creating terminal default on host_terminal_0 + default: Waiting for login prompt + RESULTS: + RESULTS - linuxboot.LinuxBootTest.test_linux_boot: PASSED (23.70s) + SUMMARY: + cassini-image-base () - Ran 1 test in 23.704s + cassini-image-base - OK - All required tests passed (successes=1, skipped=0, failures=0, errors=0) diff --git a/documentation/user_manual/n1sdp.rst b/documentation/user_manual/n1sdp.rst new file mode 100644 index 0000000000000000000000000000000000000000..44e4fcb7f31eddc2ca8278ee38eab03a099248c2 --- /dev/null +++ b/documentation/user_manual/n1sdp.rst @@ -0,0 +1,275 @@ +.. + # SPDX-FileCopyrightText: Copyright (c) 2023, Linaro Limited. + # + # SPDX-FileCopyrightText: Copyright 2023-2024 Arm Limited and/or its + # affiliates + # + # SPDX-License-Identifier: MIT + +############################## +Getting Started with the N1SDP +############################## + +This document explains how to build, deploy, and boot the Cassini distro on the +Arm Neoverse N1 System Development Platform (N1SDP). + +**NOTE:** Requires a micro SD card (at least 2 GB) and a USB drive (at least 16 GB) + +********************* +Building N1SDP images +********************* + +The kas configuration file ``kas/n1sdp.yml`` can be used to +build images which target the N1SDP. To build N1SDP images: + +.. code-block:: console + + kas build --update kas/cassini.yml:kas/k3s.yml:kas/n1sdp.yml + +This will produce an N1SDP firmware image here: + + ``build/tmp/deploy/images/n1sdp/n1sdp-board-firmware_primary.tar.gz`` + +And a Cassini distribution image here: + + ``build/tmp/deploy/images/n1sdp/cassini-image-base-n1sdp.rootfs.wic.gz`` + + ``build/tmp/deploy/images/n1sdp/cassini-image-base-n1sdp.rootfs.wic.bmap`` + +*********************** +Connecting to the N1SDP +*********************** + +1. Connect a USB cable between the build host and the ``DBG USB`` port on the N1SDP back panel and power on the device + +2. Check four new TTY USB devices are seen by **the build host**, via: + + .. code-block:: shell + + ls /dev/ttyUSB* + + This will output, for example: + + .. code-block:: console + + /dev/ttyUSB0 + /dev/ttyUSB1 + /dev/ttyUSB2 + /dev/ttyUSB3 + + If there are no other TTY USB devices, then the four ports on the N1SDP will be + connected as follows: + + * ttyUSB0 Motherboard Configuration Controller (MCC) + + * ttyUSB1 Application processor (AP) + + * ttyUSB2 System Control Processor (SCP) + + * ttyUSB3 Manageability Control Processor (MCP) (or OP-TEE and Secure Partitions) + + The rest of this guide assumes there are no other TTY USB devices on the build host + +3. Connect to the serial console(s) using any terminal client (``picocom``, ``minicom``, or ``screen`` should all work). + + All ports are configured with: + + * 115200 Baud + + * 8 bits, No parity, 1 stop bit (8N1) + + * No hardware or software flow control + + For example, run the following command to open a new picocom session for + the AP console: + + .. code-block:: shell + + sudo picocom -b 115200 /dev/ttyUSB1 + + .. note:: + + ``sudo`` should not be required if the current user is in the ``dialout`` group + +****************************************** +Updating the MCC firmware (Micro SD image) +****************************************** + +1. Follow the instructions above and connect to the MCC console i.e. + + .. code-block:: shell + + sudo picocom -b 115200 /dev/ttyUSB0 + +2. In the MCC console, at the ``Cmd>`` prompt, type the following command to see MCC firmware version and a list of commands: + + .. code-block:: console + + ? + + This will output, for example: + + .. code-block:: console + + Arm N1SDP MCC Firmware v1.0.1 + Build Date: Sep 5 2019 + Build Time: 14:18:16 + + command ------------------+ function ---------------------------------+ + | CAP "fname" [/A] | captures serial data to a file | + | | [/A option appends data to a file] | + | FILL "fname" [nnnn] | create a file filled with text | + | | [nnnn - number of lines, default=1000] | + | TYPE "fname" | displays the content of a text file | + | REN "fname1" "fname2" | renames a file 'fname1' to 'fname2' | + | COPY "fin" ["fin2"] "fout"| copies a file 'fin' to 'fout' file | + | | ['fin2' option merges 'fin' and 'fin2'] | + | DEL "fname" | deletes a file | + | DIR "[mask]" | displays a list of files in the directory | + | FORMAT [label] | formats Flash Memory Card | + | USB_ON | Enable usb | + | USB_OFF | Disable usb | + | SHUTDOWN | Shutdown PSU (leave micro running) | + | REBOOT | Power cycle system and reboot | + | RESET | Reset Board using CB_nRST | + | DEBUG | Enters debug menu | + | EEPROM | Enters eeprom menu | + | HELP or ? | displays this help | + | | + | THE FOLLOWING COMMANDS ARE ONLY AVAILABLE IN RUN MODE | + | | + | CASE_FAN_SPEED "SPEED" | Choose from SLOW, MEDIUM, FAST | + | READ_AXI "fname" | Read system memory to file 'fname' | + | "address" | from address to end address | + | "end_address" | | + | WRITE_AXI "fname" | Write file 'fname' to system memory | + | "address" | at address | + +---------------------------+-------------------------------------------+ + +3. Type the following command to enable USB: + + .. code-block:: console + + USB_ON + +4. Check a new block device is seen by **the build host**, via: + + .. code-block:: shell + + lsblk + + This will output, for example: + + .. code-block:: console + + NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT + sdb 8:0 0 2G 0 disk + └─sdb1 8:1 0 2G 0 part + + If there are no similar block devices mounted on the build host, then it + should be possible to identify the Micro SD Card on the N1SDP by its' size. + In the output above, the Micro SD partition is clearly ``sdb1``. + +5. Mount the device and check its contents: + + .. code-block:: console + + sudo umount /dev/sdb1 && + sudo mkdir -p /tmp/sdcard && + sudo mount /dev/sdb1 /tmp/sdcard && + ls -l /tmp/sdcard + + This should output, for example: + + .. code-block:: console + + config.txt ee0316a.txt LIB LICENSES LOG.TXT MB + + .. warning:: + + In this example, the ``/dev/sdb1`` partition is being mounted. As this may + vary on different machines, care should be taken when copying and pasting + the following commands. Don't proceed unless the contents of the Micro SD + Card were as expected in the previous step. + +6. Wipe the mounted microSD card, then extract the contents of ``n1sdp-board-firmware_primary.tar.gz`` onto it: + + .. code-block:: console + + sudo rm -rf /tmp/sdcard/* && + sudo tar --no-same-owner -xf build/tmp/deploy/images/n1sdp/n1sdp-board-firmware_primary.tar.gz -C /tmp/sdcard/ && + sudo sync + + .. note:: + + If the N1SDP board was manufactured after November 2019 (Serial Number + greater than ``36253xxx``), a different PMIC firmware image should be used to + prevent system hangs. More details can be found in + `Potential firmware damage notice`_. The ``MB/HBI0316A/io_v123f.txt`` file + located in the microSD needs to be updated. To update it, set the PMIC image + (``300k_8c2.bin``) to be used in the newer models by running the following + commands on the Build Host: + + .. code-block:: console + + sudo sed -i '/^MBPMIC: pms_0V85.bin/s/^/;/g' /tmp/sdcard/MB/HBI0316A/io_v123f.txt + sudo sed -i '/^;MBPMIC: 300k_8c2.bin/s/^;//g' /tmp/sdcard/MB/HBI0316A/io_v123f.txt + sudo sync + +7. Unmount the device + + .. code-block:: console + + sudo umount /tmp/sdcard + sudo rmdir /tmp/sdcard + +************************************************** +Prepare the distro image for the N1SDP (USB image) +************************************************** + +1. Insert the USB storage device into the build host + +2. Check a new block device is seen by **the build host**, via: + + .. code-block:: shell + + lsblk + + This will output, for example: + + .. code-block:: console + + NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT + sdb 8:0 0 2G 0 disk + └─sdb1 8:1 0 2G 0 part + sdc 8:0 0 64G 0 disk + + If there are no similar block devices mounted on the build host, then it + should be possible to identify the USB storage device by its' size. In the + output above, the USB storage device is ``sdc``. + + .. warning:: + + The next step will result in all prior partitions and data on the USB + storage device being erased. Take care not to confuse your host PC's own + hard drive with the USB drive and backup any data on the USB storage device + before continuing. + +3. Flash the image onto the USB storage device using ``bmap-tools``: + + .. code-block:: shell + + sudo bmaptool copy --bmap cassini-image-base-n1sdp.rootfs.wic.bmap cassini-image-base-n1sdp.rootfs.wic.gz /dev/ + + Or if deploying an SDK image + + .. code-block:: console + + sudo bmaptool copy --bmap cassini-image-sdk-n1sdp.rootfs.wic.bmap cassini-image-sdk-n1sdp.rootfs.wic.gz /dev/ + +4. Eject the USB storage device from the build host and plug it into one of the USB 3.0 ports on the N1SDP + +5. Reboot the N1SDP device by power cycling it or typing the following at the MCC console + + .. code-block:: console + + REBOOT diff --git a/documentation/variables.py b/documentation/variables.py new file mode 100644 index 0000000000000000000000000000000000000000..c5154ac2cb31d920fc67fbaaf27c3508faad37e5 --- /dev/null +++ b/documentation/variables.py @@ -0,0 +1,89 @@ +# SPDX-FileCopyrightText: Copyright (c) 2023-2024, Linaro Limited. +# +# SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its +# affiliates +# +# SPDX-License-Identifier: MIT + +# This file centralizes the variables and links used throughout the +# documentation. The dictionaries are converted to a single string that is used +# as the rst_prolog (see the Sphinx Configuration documentation at +# https://www.sphinx-doc.org/en/master/usage/configuration.html for more info). + +# There are two types of key-value substitutions: +# 1. simple string replacements +# 2. replacement with a rendered hyperlink, where the key defines what the +# rendered hyperlink text will be + +# Prepend the key with "link:" to identify it as a Sphinx target name for use +# as a hyperlink. The "link:" prefix is dropped from the substitution name. +# +# For example: +# "link:This URL": "www.arm.com" +# "company name": "arm" +# Can be used as: +# The |company name| website can be found at |This URL|_. +# +# Note the "_" which renders the substitution as a hyperlink is only possible +# because the variable is defined as a link, to be resolved as a Sphinx target. + +""" Called from the parent (Cassini) documentation build to initialise +variables which are referenced from documentation sources in this repository +""" + +YOCTO_RELEASE = "scarthgap" + + +general_links = { + "link:meta-arm-bsp": + "https://git.yoctoproject.org/meta-arm/tree/meta-arm-bsp/" + f"documentation/n1sdp.md?h={YOCTO_RELEASE}", + "link:N1SDP Technical Reference Manual": + "https://developer.arm.com/documentation/101489/0000", + "link:Potential firmware damage notice": + "https://community.arm.com/developer/tools-software/oss-platforms/" + "w/docs/604/notice-potential-damage-to-n1sdp-boards-" + "if-using-latest-firmware-release", + "link:Arm Corstone-1000 Technical Overview": + "https://developer.arm.com/documentation/102360/0000", + "link:Arm Corstone-1000 Software": + "https://corstone1000.docs.arm.com/en/latest/", + "link:Fast Models Fixed Virtual Platforms (FVP) Reference Guide": + "https://developer.arm.com/documentation/100966/1119", + "link:Fast Models Reference Guide": + "https://developer.arm.com/documentation/100964/1119/" + "Introduction-to-Fast-Models/User-mode-networking", + "link:EULA": "https://developer.arm.com/downloads/" + "-/arm-ecosystem-fvps/eula", +} + + +def generate_replacement(key, value): + """ Generate simple string substitution """ + + replacement = f".. |{key}| replace:: {value}" + return f"{replacement}" + + +def generate_link(key, link): + """ Generate link substitution """ + + definition = f".. _{key}: {link}" + key_mapping = f".. |{key}| replace:: {key}" + return f"{definition}\n{key_mapping}" + + +def generate_rst_prolog(): + """ Generate all substitutions that should be available in every file """ + + rst_prolog = "" + + for variables_group in [general_links]: + for key, value in variables_group.items(): + if key.startswith("link:"): + rst_prolog += generate_link(key.split("link:") + [1], value) + "\n" + else: + rst_prolog += generate_replacement(key, value) + "\n" + + return rst_prolog