From 7283bb67027f1e7831a34d8a077e59306213d761 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 29 May 2024 10:24:34 +0000 Subject: [PATCH 1/6] doc: Initialize the repository documentation Before slicing this repository from meta-cassini, the LICENSE and README were provided by the parent folder (the root of meta-cassini) Create new LICENSE and README for this repository Signed-off-by: Adam Johnston --- LICENSE.rst | 45 +++++++++++++++++++++++++ README | 5 --- README.md | 57 ++++++++++++++++++++++++++++++++ qa-checks/cassini-bsp-dictionary | 2 ++ 4 files changed, 104 insertions(+), 5 deletions(-) create mode 100644 LICENSE.rst delete mode 100644 README create mode 100644 README.md diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 0000000..fcd3a4d --- /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 42a870a..0000000 --- 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 0000000..820fa77 --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ + + +# 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. + +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/qa-checks/cassini-bsp-dictionary b/qa-checks/cassini-bsp-dictionary index fba8dc9..43ee843 100644 --- a/qa-checks/cassini-bsp-dictionary +++ b/qa-checks/cassini-bsp-dictionary @@ -69,6 +69,7 @@ packagegroup posix ptable readlink +README requireinclude requirenotfound RPROVIDER @@ -83,6 +84,7 @@ TF-A THISDIR udev unitdir +upstreamed usbgadget usbhost util -- GitLab From 395beb6c985602af51243f646721a60cccf24746 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 29 May 2024 13:01:46 +0000 Subject: [PATCH 2/6] doc: Add Corstone-1000 to list of supported platforms Add `Corstone-1000 FVP` and `Corstone-1000 for MPS3 to list of supported platforms. Signed-off-by: Adam Johnston --- README.md | 4 ++++ qa-checks/cassini-bsp-dictionary | 1 + 2 files changed, 5 insertions(+) diff --git a/README.md b/README.md index 820fa77..4b32924 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,10 @@ 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) + 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 diff --git a/qa-checks/cassini-bsp-dictionary b/qa-checks/cassini-bsp-dictionary index 43ee843..6f57c8a 100644 --- a/qa-checks/cassini-bsp-dictionary +++ b/qa-checks/cassini-bsp-dictionary @@ -51,6 +51,7 @@ mdev meta-cassini-bsp mickledore modutils +MPS3 msdos mtrace multiconfig -- GitLab From 246322ab470d9c958d5b396288ec768d9d562ad7 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 29 May 2024 10:26:12 +0000 Subject: [PATCH 3/6] doc: Add N1SDP to list of supported platforms Add `Neoverse N1 System Development Platform` to list of supported platforms. Signed-off-by: Adam Johnston --- README.md | 1 + qa-checks/cassini-bsp-dictionary | 1 + 2 files changed, 2 insertions(+) diff --git a/README.md b/README.md index 4b32924..70f26ba 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ 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: diff --git a/qa-checks/cassini-bsp-dictionary b/qa-checks/cassini-bsp-dictionary index 6f57c8a..80f9e21 100644 --- a/qa-checks/cassini-bsp-dictionary +++ b/qa-checks/cassini-bsp-dictionary @@ -60,6 +60,7 @@ multilineident N1SDP nanbield nativesdk +Neoverse netbase networkd no_cloud -- GitLab From 92b8d2e686f181bfef49933fb7e1eca4b33b45cc Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Thu, 30 May 2024 07:45:23 +0000 Subject: [PATCH 4/6] doc: Copy Corstone-1000 documentation from meta-cassini The platform documentation will not be built here. It is intended that, when building the documentation for meta-cassini, the build process will fetch or otherwise link-to the sources maintained here, rather than maintaining platform documentation in meta-cassini. The build changes to meta-cassini will be done later - for now we just copy the sources here. Changelog: other Signed-off-by: Adam Johnston --- .../developer_manual/corstone1000.rst | 22 +++ .../developer_manual/corstone1000fvp.rst | 25 +++ documentation/user_manual/corstone1000.rst | 184 ++++++++++++++++++ documentation/user_manual/corstone1000fvp.rst | 124 ++++++++++++ documentation/variables.py | 83 ++++++++ qa-checks/cassini-bsp-dictionary | 13 +- 6 files changed, 450 insertions(+), 1 deletion(-) create mode 100644 documentation/developer_manual/corstone1000.rst create mode 100644 documentation/developer_manual/corstone1000fvp.rst create mode 100644 documentation/user_manual/corstone1000.rst create mode 100644 documentation/user_manual/corstone1000fvp.rst create mode 100644 documentation/variables.py diff --git a/documentation/developer_manual/corstone1000.rst b/documentation/developer_manual/corstone1000.rst new file mode 100644 index 0000000..d584610 --- /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 0000000..10ab71b --- /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/user_manual/corstone1000.rst b/documentation/user_manual/corstone1000.rst new file mode 100644 index 0000000..b6e66d8 --- /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 0000000..5bf6bf6 --- /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/variables.py b/documentation/variables.py new file mode 100644 index 0000000..3aadbcc --- /dev/null +++ b/documentation/variables.py @@ -0,0 +1,83 @@ +# 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: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 diff --git a/qa-checks/cassini-bsp-dictionary b/qa-checks/cassini-bsp-dictionary index 80f9e21..0823a61 100644 --- a/qa-checks/cassini-bsp-dictionary +++ b/qa-checks/cassini-bsp-dictionary @@ -5,6 +5,8 @@ alsa AUTOFS AUTOFS4 +AUTOQSPI +AUTORUN backend bmap bmaptool @@ -22,6 +24,7 @@ configfile corstone cpio crypto +dialout distro DISTROOVERRIDES efidisk @@ -32,6 +35,7 @@ FILESEXTRAPATHS flashfw fstype FSTYPES +fvps gcsections gettext gitlab @@ -46,10 +50,12 @@ LAYERSERIES LAYERSERIES_COMPAT LIBC Linaro +linuxboot mandatoryvar mdev meta-cassini-bsp mickledore +minicom modutils MPS3 msdos @@ -65,11 +71,14 @@ netbase networkd no_cloud nooelint +OCVM opkg optee packagegroup +picocom posix ptable +QSPI readlink README requireinclude @@ -84,6 +93,7 @@ suggestedvar tarbz2 TF-A THISDIR +TOTALIMAGES udev unitdir upstreamed @@ -94,5 +104,6 @@ utils VIRT wchar WIDEC +XNVM xtests -zeroconf \ No newline at end of file +zeroconf -- GitLab From 1eef7358ebb2fa6fdaa2925734df8472a9231c0e Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 29 May 2024 17:11:19 +0000 Subject: [PATCH 5/6] doc: Copy N1SDP documentation from meta-cassini The platform documentation will not be built here. It is intended that, when building the documentation for meta-cassini, the build process will fetch or otherwise link-to the sources maintained here, rather than maintaining platform documentation in meta-cassini. The build changes to meta-cassini will be done later - for now we just copy the sources here. Changelog: other Signed-off-by: Adam Johnston --- documentation/developer_manual/n1sdp.rst | 42 ++++ documentation/user_manual/n1sdp.rst | 275 +++++++++++++++++++++++ documentation/variables.py | 6 + qa-checks/cassini-bsp-dictionary | 6 + 4 files changed, 329 insertions(+) create mode 100644 documentation/developer_manual/n1sdp.rst create mode 100644 documentation/user_manual/n1sdp.rst diff --git a/documentation/developer_manual/n1sdp.rst b/documentation/developer_manual/n1sdp.rst new file mode 100644 index 0000000..92c43ac --- /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/n1sdp.rst b/documentation/user_manual/n1sdp.rst new file mode 100644 index 0000000..44e4fcb --- /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 index 3aadbcc..c5154ac 100644 --- a/documentation/variables.py +++ b/documentation/variables.py @@ -38,6 +38,12 @@ 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": diff --git a/qa-checks/cassini-bsp-dictionary b/qa-checks/cassini-bsp-dictionary index 0823a61..83312aa 100644 --- a/qa-checks/cassini-bsp-dictionary +++ b/qa-checks/cassini-bsp-dictionary @@ -27,12 +27,15 @@ crypto dialout distro DISTROOVERRIDES +EEPROM efidisk eglibc envparse extfs FILESEXTRAPATHS flashfw +fname +fout fstype FSTYPES fvps @@ -52,6 +55,7 @@ LIBC Linaro linuxboot mandatoryvar +MBPMIC mdev meta-cassini-bsp mickledore @@ -76,6 +80,7 @@ opkg optee packagegroup picocom +PMIC posix ptable QSPI @@ -86,6 +91,7 @@ requirenotfound RPROVIDER SAST scarthgap +sdcard SDHC sourceparams srcurifile -- GitLab From 9e4bb1608ff319c7b3ef403377ea51c8d6ad3532 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 29 May 2024 13:03:07 +0000 Subject: [PATCH 6/6] ci: Move dictionary to align with meta-cassini Move dictionary from qa-checks/cassini-bsp-dictionary to .dictionary to align with meta-cassini and tidy up the repository structure. Changelog: other Signed-off-by: Adam Johnston --- .codeclimate.yml | 4 ++-- qa-checks/cassini-bsp-dictionary => .dictionary | 2 ++ Dangerfile | 4 ++-- 3 files changed, 6 insertions(+), 4 deletions(-) rename qa-checks/cassini-bsp-dictionary => .dictionary (99%) diff --git a/.codeclimate.yml b/.codeclimate.yml index 8261238..2439de4 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 99% rename from qa-checks/cassini-bsp-dictionary rename to .dictionary index 83312aa..8cb533b 100644 --- a/qa-checks/cassini-bsp-dictionary +++ b/.dictionary @@ -12,6 +12,7 @@ bmap bmaptool bootimg bootloader +bsp buildable BUILDIN cassini @@ -83,6 +84,7 @@ picocom PMIC posix ptable +qa QSPI readlink README diff --git a/Dangerfile b/Dangerfile index bd2dd49..6fda6d7 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 -- GitLab