From 519f19182dc009697a5b2adbdecde49280db63d9 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Thu, 8 Jun 2023 14:30:55 +0000 Subject: [PATCH 01/11] doc: Correct usage of `cassini-sdk.yml` in documentation `cassini-sdk.yml` is one of two base configs for cassini (the other being `cassini.yml`). As `cassini-sdk.yml` includes `cassini.yml` the intended use is `kas build \ meta-cassini-config/kas/cassini-sdk.yml:\ meta-cassini-config/kas/n1sdp.yml` ... rather than... `kas build \ meta-cassini-config/kas/cassini.yml:\ meta-cassini-config/kas/cassini-sdk.yml:\ meta-cassini-config/kas/n1sdp.yml` Update `Build, Deploy and Validate Cassini Image` to make this clearer Signed-off-by: Adam Johnston --- documentation/user_manual/build.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/user_manual/build.rst b/documentation/user_manual/build.rst index bbb18cf..6cefcce 100644 --- a/documentation/user_manual/build.rst +++ b/documentation/user_manual/build.rst @@ -1,6 +1,6 @@ .. - # Copyright (c) 2022-2023 Arm Limited and/or its affiliates. - # + # SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its + # affiliates # # SPDX-License-Identifier: MIT @@ -28,15 +28,15 @@ configuration files contain default parameter settings for a Cassini distributio build. Here, the files are briefly introduced, classified into three ordered categories: - * **Base Config**: Configures common software components + * **Base Configs**: Configures common software components - * ``cassini.yml`` to prepare an image for the Cassini distribution. + * ``cassini.yml`` to build an image for the Cassini distribution. + * ``cassini-sdk.yml`` to build an SDK image for the Cassini distribution. * **Build Modifier Configs**: Set and configure features of the Cassini distribution * ``tests.yml`` to include run-time validation tests into the image. - * ``cassini-sdk.yml`` to build an SDK image for the Cassini distribution. * ``security.yml`` to build a security-hardened Cassini distribution image. * **Target Platform Configs**: Set the target platform -- GitLab From b671307081a6755f3e4a99128e44cd44ae7257fd Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Fri, 9 Jun 2023 08:15:22 +0000 Subject: [PATCH 02/11] doc: Align header styles in Corstone-1000 guides The Corstone-1000 guides use a different header/outline markup to the rest of the documentation (although they are rendered in the same way). Re-align the Corstone-1000 header/outline markup style with the rest of the documentation Signed-off-by: Adam Johnston --- documentation/user_manual/corstone1000.rst | 14 ++++++++------ documentation/user_manual/corstone1000fvp.rst | 10 ++++++---- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/documentation/user_manual/corstone1000.rst b/documentation/user_manual/corstone1000.rst index 695c6da..8f742a7 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -1,6 +1,6 @@ .. - # Copyright (c) 2023 Arm Limited and/or its affiliates. - # + # SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its + # affiliates # # SPDX-License-Identifier: MIT @@ -13,8 +13,9 @@ This document explains how to boot the Cassini distro on the Arm Corstone-1000 f **NOTE:** We require a micro SD card (4GB) and USB drive (32 GB) +*************************************************** 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``. @@ -86,9 +87,9 @@ The binaries are present in OUTPUT_DIR = ``<_workspace>/build/tmp/deploy/images/ **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. @@ -98,8 +99,9 @@ Use the ``lsblk`` command to determine USB drive and bmap tool to copy the cassi sudo bmaptool copy --bmap cassini-image-base-corstone1000-mps3.wic.bmap cassini-image-base-corstone1000-mps3.wic /dev/ +**************************** Running the software on FPGA ----------------------------- +**************************** Insert SD card and USB drive before switching ON the device. diff --git a/documentation/user_manual/corstone1000fvp.rst b/documentation/user_manual/corstone1000fvp.rst index 8d9265d..c6825de 100644 --- a/documentation/user_manual/corstone1000fvp.rst +++ b/documentation/user_manual/corstone1000fvp.rst @@ -1,5 +1,6 @@ .. - # Copyright (c) 2023 Arm Limited or its affiliates. All rights reserved. + # SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its + # affiliates # # SPDX-License-Identifier: MIT @@ -25,9 +26,9 @@ that are targeting the Corstone-1000 FVP. export FVP_CORSTONE1000_EULA_ACCEPT=True - +******************* Building FVP images -=================== +******************* To build a Corstone-1000 FVP image: @@ -48,8 +49,9 @@ Run The resulting Cassini distribution image can be logged into as ``root`` user. +*************** Running the FVP -=============== +*************** To start the FVP and get the console: -- GitLab From 35f17e4f79acf76f7bf73140a443f1dd4256c0c0 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Fri, 9 Jun 2023 08:16:20 +0000 Subject: [PATCH 03/11] doc: Fix capitalization in title of the build guide `validate` -> `Validate` for consistency with other docs Signed-off-by: Adam Johnston --- documentation/introduction.rst | 5 +++-- documentation/user_manual/build.rst | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/documentation/introduction.rst b/documentation/introduction.rst index d6e6325..8d2217e 100644 --- a/documentation/introduction.rst +++ b/documentation/introduction.rst @@ -1,5 +1,6 @@ .. - # Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. + # SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its + # affiliates # # SPDX-License-Identifier: MIT @@ -27,7 +28,7 @@ Cassini aims to facilitate the deployment of application workloads via Docker and K3s use-case on the supported target platforms. Instructions for achieving these use-cases are given in the -:ref:`build ` +:ref:`build ` section, subject to relevant assumed technical knowledge as listed later in :ref:`documentation assumptions `. diff --git a/documentation/user_manual/build.rst b/documentation/user_manual/build.rst index 6cefcce..1fb7b23 100644 --- a/documentation/user_manual/build.rst +++ b/documentation/user_manual/build.rst @@ -5,7 +5,7 @@ # SPDX-License-Identifier: MIT ######################################## -Build, Deploy and validate Cassini Image +Build, Deploy and Validate Cassini Image ######################################## The recommended approach for image build setup and customization is to use the -- GitLab From 8999cb0aeef45b24c7c9dca7744b5ce199ba8138 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Fri, 9 Jun 2023 08:17:55 +0000 Subject: [PATCH 04/11] cassini-config: Update dictionary Adds: - 2gb - 8n1 - baud - corstone1000-image-corstone1000-fvp.wic.nopt - dialout - distro - unmount Removes: - diego.sueiro Signed-off-by: Adam Johnston --- meta-cassini-config/qa-checks/cassini-dictionary | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/meta-cassini-config/qa-checks/cassini-dictionary b/meta-cassini-config/qa-checks/cassini-dictionary index 3e40c82..915240d 100644 --- a/meta-cassini-config/qa-checks/cassini-dictionary +++ b/meta-cassini-config/qa-checks/cassini-dictionary @@ -1,11 +1,13 @@ 1.0.0+rc93+git0+249bca0a13 1.1.0+git0+b9460f26b4 20.10.12+ce+git906f57f +2gb 3.2.1+git0+ab4d0cf908 3rd 4.16+stable0+f265444922 4gb 512kb +8n1 aarch64 aem api @@ -24,6 +26,7 @@ baremetal baremetal_architecture.png baremetal-sdk.yml baremetal.yml +baud bblayers.conf binaries bitbake @@ -71,6 +74,7 @@ contributing_documentation_build_validation corstone-1000 corstone1000 corstone1000fvp +corstone1000-image-corstone1000-fvp.wic.nopt corstone1000-image-corstone1000-mps3.wic.nopt corstone1000-mps3 corstone1000-mps3.yml @@ -91,8 +95,9 @@ developer.example.org developer-facing developer_manual devicetree -diego.sueiro +dialout distributions +distro distro_features docker's docs.lavasoftware.org @@ -314,6 +319,7 @@ ua_test_log_dir ubuntu ubuntu-based umask +unmount upstreamed upto urls -- GitLab From c544f0c8d32993bbfe0ba9bab1b380c9637d390f Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Fri, 9 Jun 2023 08:18:52 +0000 Subject: [PATCH 05/11] doc: Move platform specific instructions to `Getting Started` guides Build, deployment and reset instructions vary between N1SDP, Corstone-1000 for MPS3, and Corstone-1000 FVP so they should be in one of the platform specific documents (`Getting Started with...`). Conversely, login instructions are platform independent and should be moved from the platform specific documents to the generic user guide. A `Getting Started with...` document is created for the N1SDP and all platform specific instructions in the generic user guide are moved to the relevant platform guide (N1SDP, Corstone-1000 MPS3, or Corstone-1000 FVP). Each `Getting Started with...` document starts with a section which: - names the platform kas config file - shows the command used to build a base image for that platform - shows the image files created (firmware and distro) The structure of this section is aligned across all supported platforms The generic build instructions in the user guide now contains links to each of the platform specific `Getting Started` guides. Changelog: other Signed-off-by: Adam Johnston --- documentation/user_manual/build.rst | 293 +----------------- documentation/user_manual/corstone1000.rst | 31 +- documentation/user_manual/corstone1000fvp.rst | 13 +- documentation/user_manual/index.rst | 5 +- documentation/user_manual/n1sdp.rst | 269 ++++++++++++++++ 5 files changed, 313 insertions(+), 298 deletions(-) create mode 100644 documentation/user_manual/n1sdp.rst diff --git a/documentation/user_manual/build.rst b/documentation/user_manual/build.rst index 1fb7b23..e2084cb 100644 --- a/documentation/user_manual/build.rst +++ b/documentation/user_manual/build.rst @@ -103,299 +103,24 @@ The ``meta-cassini`` repository can be downloaded using Git, via: .. _build_label: -***** -Build -***** +**************** +Build and Deploy +**************** -To build Cassini distribution image for the N1SDP hardware target platform: +Refer to the platform guides instructions on how to build and deploy the Cassini images +on supported platforms: - .. code-block:: console - - kas build meta-cassini-config/kas/cassini.yml:meta-cassini-config/kas/n1sdp.yml - - The resulting Cassini distribution image will be produced at: - ``build/tmp/deploy/images/n1sdp/cassini-image-base-n1sdp.*`` - -To build Cassini distribution image with the Cassini SDK for the N1SDP -hardware target platform: - - .. code-block:: console - - kas build meta-cassini-config/kas/cassini-sdk.yml:meta-cassini-config/kas/n1sdp.yml - - The resulting Cassini distribution image will be produced at: - ``build/tmp/deploy/images/n1sdp/cassini-image-sdk-image-n1sdp.*`` - -Cassini distribution images can be modified by adding run-time -validation tests and security hardening to the distribution. This can be done -by including ``meta-cassini-config/kas/tests.yml`` and -``meta-cassini-config/kas/security.yml`` kas configuration file as a Build -Modifier. - -****** -Deploy -****** - -Instructions for deploying a Cassini distribution image on the supported N1SDP -hardware target platform is divided into two parts: - - * `Load the Image onto an USB Storage Device`_ - * `Update the N1SDP MCC Configuration MicroSD Card`_ - -.. note:: - As the image filenames vary depending on the base config and the SDK, the - precise commands to deploy a Cassini distribution image vary. The following - documentation denotes required instructions with sequentially numbered - indexes (e.g., 1, 2, ...), and distinguishes alternative instructions by - denoting the alternatives alphabetically (e.g., A, B, ...). - -Load the Image onto an USB Storage Device -========================================= - -Cassini distribution images are produced as files with the ``.wic.bmap`` and -``.wic.gz`` extensions. They must first be loaded to the USB storage device, as -follows: - -1. Prepare the USB storage device (minimum size of 64 GB). - - Identify the USB storage device using ``lsblk`` command: - - .. code-block:: shell - - lsblk - - This will output, for example: - - .. code-block:: console - - NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT - sdc 8:0 0 64G 0 disk - ... - -.. warning:: - In this example, the USB storage device is the ``/dev/sdc`` device. As this - may vary on different machines, care should be taken when copying and pasting - the following commands. - -2. Prepare for the image copy: - - .. code-block:: console - - sudo umount /dev/sdc* - cd build/tmp/deploy/images/n1sdp/ - -.. warning:: - The next step will result in all prior partitions and data on the USB storage - device being erased. Please backup before continuing. - -3. Flash the image onto the USB storage device using ``bmap-tools``: - - A. Cassini distribution image: - - .. code-block:: console - - sudo bmaptool copy --bmap cassini-image-base-n1sdp.wic.bmap cassini-image-base-n1sdp.wic.gz /dev/sdc - - B. Cassini-SDK distribution image: - - .. code-block:: console - - sudo bmaptool copy --bmap cassini-image-sdk-n1sdp.wic.bmap cassini-image-sdk-n1sdp.wic.gz /dev/sdc - -The USB storage device can then be safely ejected from the Build Host, and -plugged into one of the USB 3.0 ports on the N1SDP. - -Update the N1SDP MCC Configuration MicroSD Card -=============================================== - -.. note:: - This process doesn't need to be performed every time the USB Storage Device - gets updated. It is only necessary to update the MCC configuration microSD - card when the Cassini major version changes. - -This guidance requires a physical connection able to be established between the -N1SDP and a PC that can be used to interface with it, here assumed to be the -Build Host. The instructions are as follows: - -1. Connect a USB-B cable between the Build Host and the DBG USB port of the - N1SDP back panel. - -2. Find four TTY USB devices in the ``/dev`` directory of 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 - - By default the four ports are connected to the following devices: - - ttyUSB Motherboard Configuration Controller (MCC) - - ttyUSB Application processor (AP) - - ttyUSB System Control Processor (SCP) - - ttyUSB Manageability Control Processor (MCP) - - In this guide the ports are: - - ttyUSB0: MCC - - ttyUSB1: AP - - ttyUSB2: SCP - - ttyUSB3: MCP - - The ports are configured with the following settings: - - 115200 Baud - - 8N1 - - No hardware or software flow support - -3. Connect to the N1SDP's MCC console. Any terminal applications such as - ``putty``, ``screen`` or ``minicom`` will work. The ``screen`` utility is - used in the following command: - - .. code-block:: shell - - sudo screen /dev/ttyUSB0 115200 - -4. Power-on the N1SDP via the power supply switch on the N1SDP tower. The MCC - window will be shown. Type the following command at the ``Cmd>`` prompt 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 | - +---------------------------+-------------------------------------------+ - -5. In the MCC window at the ``Cmd>`` prompt, enable USB via: - - .. code-block:: console - - USB_ON - -6. Mount the N1SDP's internal microSD card over the DBG USB connection to the - Build Host and copy the required files. - - The microSD card is visible on the Build Host as a disk device after issuing - the ``USB_ON`` command in the MCC console, as performed in the previous step. - This can be found using the ``lsblk`` command: - - .. 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 - - .. 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. - - 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 /tmp/sdcard - - This should output, for example: - - .. code-block:: console - - config.txt ee0316a.txt LICENSES LOG.TXT MB SOFTWARE - -7. 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/ && sync - sudo umount /tmp/sdcard - sudo rmdir /tmp/sdcard - - .. note:: - If the N1SDP board was manufactured after November 2019 (Serial Number - greater than ``36253xxx``), a different PMIC firmware image must be used to - prevent potential damage to the board. 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 umount /dev/sdb1 - sudo mkdir -p /tmp/sdcard - sudo mount /dev/sdb1 /tmp/sdcard - 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 umount /tmp/sdcard - sudo rmdir /tmp/sdcard + * :ref:`Getting Started with the N1SDP ` + * :ref:`Getting Started with Arm Corstone-1000 for MPS3 ` + * :ref:`Getting Started with Arm Corstone-1000 FVP ` *** Run *** To run the deployed Cassini distribution image, simply boot the target platform. -For example, on the MCC console accessed via the connected machine described in -`Deploy`_, reset the target platform and boot into the deployed Cassini -distribution image via: - - .. code-block:: console - - REBOOT -The resulting Cassini distribution image can be logged into as ``cassini`` user. +The Cassini distribution image can be logged into as ``cassini`` user. The distribution can then be used for deployment and orchestration of application workloads in order to achieve the desired use-cases. diff --git a/documentation/user_manual/corstone1000.rst b/documentation/user_manual/corstone1000.rst index 8f742a7..f9481cf 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -8,10 +8,34 @@ Getting Started with Arm Corstone-1000 for MPS3 ############################################### -This document explains how to boot the Cassini distro on the 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:** We require a micro SD card (4GB) and USB drive (32 GB) +***** +Build +***** + +The kas configuration file ``meta-cassini-config/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 meta-cassini-config/kas/cassini.yml:meta-cassini-config/kas/corstone1000-mps3.yml + +This will produce a Corstone-1000 firmware image here: + ``build/tmp-firmware/deploy/images/corstone1000-mps3/corstone1000-image-corstone1000-mps3.wic.nopt`` + +And a Cassini distribution image here: + ``build/tmp/deploy/images/corstone1000-mps3/cassini-image-base-corstone1000-mps3.wic`` + ``build/tmp/deploy/images/corstone1000-mps3/cassini-image-base-corstone1000-mps3.wic.bmap`` *************************************************** Prepare the firmware image for FPGA (Micro SD card) @@ -120,8 +144,3 @@ Run following commands to open minicom sessions on Linux each on new terminal: sudo picocom -b 115200 /dev/ttyUSB0 sudo picocom -b 115200 /dev/ttyUSB1 sudo picocom -b 115200 /dev/ttyUSB2 - -Once the system boot is completed, you should see console -logs on the minicom sessions. Once the HOST(Cortex-A35) is -booted completely, user can login to the shell using -**"root"** login. diff --git a/documentation/user_manual/corstone1000fvp.rst b/documentation/user_manual/corstone1000fvp.rst index c6825de..5a42d2c 100644 --- a/documentation/user_manual/corstone1000fvp.rst +++ b/documentation/user_manual/corstone1000fvp.rst @@ -8,7 +8,8 @@ Getting Started with Arm Corstone-1000 FVP ########################################## -This document explains how to boot the Cassini distro on the Arm Corstone-1000 FVP. +This document explains how to build and boot the Cassini distro on the Arm +Corstone-1000 FVP. ***** Build @@ -30,7 +31,7 @@ that are targeting the Corstone-1000 FVP. Building FVP images ******************* -To build a Corstone-1000 FVP image: +To build Corstone-1000 FVP images: .. code-block:: console @@ -43,11 +44,11 @@ Or if using kas-container: kas-container --runtime-args "-e FVP_CORSTONE1000_EULA_ACCEPT=True" build \ meta-cassini-config/kas/cassini.yml:meta-cassini-config/kas/corstone1000-fvp.yml -*** -Run -*** +This will produce a Corstone-1000 firmware image here: + ``build/tmp-firmware/deploy/images/corstone1000-fvp/corstone1000-image-corstone1000-fvp.wic.nopt`` -The resulting Cassini distribution image can be logged into as ``root`` user. +And a Cassini distribution image here: + ``build/tmp/deploy/images/corstone1000-fvp/cassini-image-base-corstone1000-fvp.wic`` *************** Running the FVP diff --git a/documentation/user_manual/index.rst b/documentation/user_manual/index.rst index f7b7ae2..f8a34f1 100644 --- a/documentation/user_manual/index.rst +++ b/documentation/user_manual/index.rst @@ -1,6 +1,6 @@ .. - # Copyright (c) 2022-2023 Arm Limited and/or its affiliates. - # + # SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its + # affiliates # # SPDX-License-Identifier: MIT @@ -12,5 +12,6 @@ User Manual :maxdepth: 1 build + n1sdp corstone1000 corstone1000fvp diff --git a/documentation/user_manual/n1sdp.rst b/documentation/user_manual/n1sdp.rst new file mode 100644 index 0000000..fd0e546 --- /dev/null +++ b/documentation/user_manual/n1sdp.rst @@ -0,0 +1,269 @@ +.. + # SPDX-FileCopyrightText: Copyright 2023 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 (2GB) and USB drive (64 GB) + +********************* +Building N1SDP images +********************* + +The kas configuration file ``meta-cassini-config/kas/n1sdp.yml`` can be used to +build images which target the N1SDP. To build N1SDP images: + +.. code-block:: console + + kas build --update meta-cassini-config/kas/cassini.yml:meta-cassini-config 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.wic.gz`` + ``build/tmp/deploy/images/n1sdp/cassini-image-base-n1sdp.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 N1SDP serial console(s) using any terminal client (``putty``, ``screen`` or ``minicom`` will 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, to use ``screen`` to connect to the AP console: + + .. code-block:: shell + + sudo screen /dev/ttyUSB1 115200 + + .. 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 screen /dev/ttyUSB0 115200 + +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 must be used to + prevent potential damage to the board. 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.wic.bmap cassini-image-base-n1sdp.wic.gz /dev/ + + Or if deploying an SDK image + + .. code-block:: console + + sudo bmaptool copy --bmap cassini-image-sdk-n1sdp.wic.bmap cassini-image-sdk-n1sdp.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 -- GitLab From dd88652e2c078cc9fbf0ca8cfb098bdb08cb64dd Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Tue, 6 Jun 2023 20:26:57 +0000 Subject: [PATCH 06/11] doc: Add usage of `cassini-dev.yml` to user manual In the User Manual, add a brief description of `cassini-dev.yml` as one of the three supported Base Configs. Signed-off-by: Adam Johnston --- documentation/user_manual/build.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/user_manual/build.rst b/documentation/user_manual/build.rst index e2084cb..e3d59f4 100644 --- a/documentation/user_manual/build.rst +++ b/documentation/user_manual/build.rst @@ -31,7 +31,9 @@ categories: * **Base Configs**: Configures common software components * ``cassini.yml`` to build an image for the Cassini distribution. - * ``cassini-sdk.yml`` to build an SDK image for the Cassini distribution. + * ``cassini-dev.yml`` to build a Cassini image suitable for development (e.g. allowing + root login without password) + * ``cassini-sdk.yml`` to build a Cassini image with additional tools for software development. * **Build Modifier Configs**: Set and configure features of the Cassini distribution -- GitLab From 81d1367304ee8be41cae843744743e9d9ba35dcb Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Fri, 9 Jun 2023 08:22:26 +0000 Subject: [PATCH 07/11] cassini-config: Align YML files for base configs For clarity, the YML files for the three cassini base configs should all have the same structure. Align cassini-dev.yml/dev.yml and cassini-sdk.yml/sdk.yml with cassini.yml such that: - cassini-.yml includes cassini-base.yml and sets the target - cassini-.yml includes .yml - .yml adds the distro feature cassini- Signed-off-by: Adam Johnston --- meta-cassini-config/kas/cassini-dev.yml | 7 ++----- meta-cassini-config/kas/cassini-sdk.yml | 5 +++-- meta-cassini-config/kas/include/dev.yml | 7 ++++++- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/meta-cassini-config/kas/cassini-dev.yml b/meta-cassini-config/kas/cassini-dev.yml index f5e5a34..abd34e4 100644 --- a/meta-cassini-config/kas/cassini-dev.yml +++ b/meta-cassini-config/kas/cassini-dev.yml @@ -1,4 +1,5 @@ -# Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. +# SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its +# affiliates # # SPDX-License-Identifier: MIT @@ -9,9 +10,5 @@ header: - meta-cassini-config/kas/include/cassini-base.yml - meta-cassini-config/kas/include/dev.yml -local_conf_header: - cassini-dev: | - DISTRO_FEATURES:append = " cassini-dev" - target: - cassini-image-base diff --git a/meta-cassini-config/kas/cassini-sdk.yml b/meta-cassini-config/kas/cassini-sdk.yml index ff051f8..6d5baac 100644 --- a/meta-cassini-config/kas/cassini-sdk.yml +++ b/meta-cassini-config/kas/cassini-sdk.yml @@ -1,4 +1,5 @@ -# Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. +# SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its +# affiliates # # SPDX-License-Identifier: MIT @@ -6,7 +7,7 @@ header: version: 11 includes: - - meta-cassini-config/kas/cassini.yml + - meta-cassini-config/kas/include/cassini-base.yml - meta-cassini-config/kas/include/sdk.yml target: diff --git a/meta-cassini-config/kas/include/dev.yml b/meta-cassini-config/kas/include/dev.yml index bf4f0a9..b11a42e 100644 --- a/meta-cassini-config/kas/include/dev.yml +++ b/meta-cassini-config/kas/include/dev.yml @@ -1,4 +1,5 @@ -# Copyright (c) 2022-2023 Arm Limited or its affiliates. All rights reserved. +# SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its +# affiliates # # SPDX-License-Identifier: MIT @@ -19,5 +20,9 @@ repos: poky: refspec: mickledore +local_conf_header: + cassini-dev: | + DISTRO_FEATURES:append = " cassini-dev" + env: CASSINI_VERSION: "vNext" -- GitLab From b822a762ab7fa070fe84c516d2581df4b4c8cad3 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 7 Jun 2023 17:23:06 +0000 Subject: [PATCH 08/11] doc: Align USB storage requirements for Arm platforms For both Corstone-1000 and N1SDP, specify a minimum 16GB for USB storage. This should be sufficient for the rootfs. Signed-off-by: Adam Johnston --- documentation/user_manual/corstone1000.rst | 2 +- documentation/user_manual/n1sdp.rst | 2 +- meta-cassini-config/qa-checks/cassini-dictionary | 1 - 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/documentation/user_manual/corstone1000.rst b/documentation/user_manual/corstone1000.rst index f9481cf..0d4ef45 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -11,7 +11,7 @@ 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:** We require a micro SD card (4GB) and USB drive (32 GB) +**NOTE:** Requires a micro SD card (4 GB) and a USB drive (at least 16 GB) ***** Build diff --git a/documentation/user_manual/n1sdp.rst b/documentation/user_manual/n1sdp.rst index fd0e546..8f4f14c 100644 --- a/documentation/user_manual/n1sdp.rst +++ b/documentation/user_manual/n1sdp.rst @@ -11,7 +11,7 @@ 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 (2GB) and USB drive (64 GB) +**NOTE:** Requires a micro SD card (2 GB) and a USB drive (at least 16 GB) ********************* Building N1SDP images diff --git a/meta-cassini-config/qa-checks/cassini-dictionary b/meta-cassini-config/qa-checks/cassini-dictionary index 915240d..a832260 100644 --- a/meta-cassini-config/qa-checks/cassini-dictionary +++ b/meta-cassini-config/qa-checks/cassini-dictionary @@ -5,7 +5,6 @@ 3.2.1+git0+ab4d0cf908 3rd 4.16+stable0+f265444922 -4gb 512kb 8n1 aarch64 -- GitLab From b63bb3b3b6eb3f6e634e0021eca382f2d3c0c053 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 7 Jun 2023 18:29:58 +0000 Subject: [PATCH 09/11] doc: Align terminal client usage for Arm platforms For both Corstone-1000 and N1SDP, show examples for picocom but make it clear any terminal client should work fine (giving picocom, minicom, and screen as examples). Remove the statement about port names being different on Windows as the rest of the documentation just assumes a Linux host is being used. Signed-off-by: Adam Johnston --- documentation/user_manual/corstone1000.rst | 21 +++++++++++++++++---- documentation/user_manual/n1sdp.rst | 9 +++++---- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/documentation/user_manual/corstone1000.rst b/documentation/user_manual/corstone1000.rst index 0d4ef45..6fde8fa 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -129,18 +129,31 @@ 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 and open 3 minicom sessions. -In case of Linux machine it will be ttyUSB0, ttyUSB1, ttyUSB2 and it might -be different on Windows machine. +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) -Run following commands to open minicom sessions on Linux each on new terminal: +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 diff --git a/documentation/user_manual/n1sdp.rst b/documentation/user_manual/n1sdp.rst index 8f4f14c..85c6f03 100644 --- a/documentation/user_manual/n1sdp.rst +++ b/documentation/user_manual/n1sdp.rst @@ -65,7 +65,7 @@ Connecting to the N1SDP The rest of this guide assumes there are no other TTY USB devices on the build host -3. Connect to the N1SDP serial console(s) using any terminal client (``putty``, ``screen`` or ``minicom`` will all work). +3. Connect to the serial console(s) using any terminal client (``picocom``, ``minicom``, or ``screen`` should all work). All ports are configured with: @@ -75,11 +75,12 @@ Connecting to the N1SDP * No hardware or software flow control - For example, to use ``screen`` to connect to the AP console: + For example, run the following command to open a new picocom session for + the AP console: .. code-block:: shell - sudo screen /dev/ttyUSB1 115200 + sudo picocom -b 115200 /dev/ttyUSB1 .. note:: @@ -93,7 +94,7 @@ Updating the MCC firmware (Micro SD image) .. code-block:: shell - sudo screen /dev/ttyUSB0 115200 + 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: -- GitLab From d51b88b64ae791688ff438346a1ccdcf01182277 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Thu, 8 Jun 2023 11:53:34 +0000 Subject: [PATCH 10/11] doc: Relax micro SD card requirement for Corstone-1000 There does not appear to be any specific size requirement for the micro SD card used with the Arm Corstone-1000 for MPS3. Relax the wording to allow any card which is `at least 4 GB` as cards which are exactly 4 GB may now be difficult to source. Signed-off-by: Adam Johnston --- documentation/user_manual/corstone1000.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/user_manual/corstone1000.rst b/documentation/user_manual/corstone1000.rst index 6fde8fa..bcb1e37 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -11,7 +11,8 @@ 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 (4 GB) and a USB drive (at least 16 GB) +**NOTE:** Requires a micro SD card (at least 4 GB) and a USB drive (at +least 16 GB) ***** Build -- GitLab From 9fbdd443f95934f84e4eaa411afd457b58c26a0b Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Fri, 9 Jun 2023 14:07:19 +0000 Subject: [PATCH 11/11] cassini-config: Update dictionary Adds: - spdx-filecopyrighttext Signed-off-by: Adam Johnston --- meta-cassini-config/qa-checks/cassini-dictionary | 1 + 1 file changed, 1 insertion(+) diff --git a/meta-cassini-config/qa-checks/cassini-dictionary b/meta-cassini-config/qa-checks/cassini-dictionary index a832260..a24a180 100644 --- a/meta-cassini-config/qa-checks/cassini-dictionary +++ b/meta-cassini-config/qa-checks/cassini-dictionary @@ -285,6 +285,7 @@ soafee.io sourceforge spdx spdx.dev +spdx-filecopyrighttext spdx-license-identifier spdx.org spdx-specification-21-web-version -- GitLab