From bb8b9f2edd8f26e93ed18301cc90af5f725a3276 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Tue, 6 Jun 2023 07:10:11 +0000 Subject: [PATCH 01/10] 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 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/user_manual/build.rst b/documentation/user_manual/build.rst index ca71628..30fd337 100644 --- a/documentation/user_manual/build.rst +++ b/documentation/user_manual/build.rst @@ -1,5 +1,5 @@ .. - # Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. + # Copyright (c) 2022-2023 Arm Limited or its affiliates. All rights reserved. # # SPDX-License-Identifier: MIT @@ -27,15 +27,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 ac8c3419c06c754ad0812d88a7fc717de28be13f Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Tue, 6 Jun 2023 07:30:55 +0000 Subject: [PATCH 02/10] 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 | 10 ++++++---- documentation/user_manual/corstone1000fvp.rst | 7 ++++--- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/documentation/user_manual/corstone1000.rst b/documentation/user_manual/corstone1000.rst index 18a0a3d..92677ef 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -12,8 +12,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``. @@ -85,9 +86,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. @@ -97,8 +98,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..a130cf9 100644 --- a/documentation/user_manual/corstone1000fvp.rst +++ b/documentation/user_manual/corstone1000fvp.rst @@ -25,9 +25,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 +48,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 d5a67e56de7fff13ccbc8b2caf83153d1fa3a600 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Tue, 6 Jun 2023 07:12:28 +0000 Subject: [PATCH 03/10] doc: Fix capitalization in title of the build guide `validate` -> `Validate` for consistency with other docs Signed-off-by: Adam Johnston --- documentation/introduction.rst | 4 ++-- documentation/user_manual/build.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/introduction.rst b/documentation/introduction.rst index d6e6325..13cb879 100644 --- a/documentation/introduction.rst +++ b/documentation/introduction.rst @@ -1,5 +1,5 @@ .. - # Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. + # Copyright (c) 2022-2023 Arm Limited or its affiliates. All rights reserved. # # SPDX-License-Identifier: MIT @@ -27,7 +27,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 30fd337..f0669b4 100644 --- a/documentation/user_manual/build.rst +++ b/documentation/user_manual/build.rst @@ -4,7 +4,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 23c693fa07e1542c00365c784fc0ad9aa90e7926 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 7 Jun 2023 20:28:06 +0000 Subject: [PATCH 04/10] 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 36b2e65..fa2f490 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 CASSINI CHANGELOG.md FF-A @@ -29,6 +31,7 @@ baremetal baremetal-sdk.yml baremetal.yml baremetal_architecture.png +baud bblayers.conf binaries bitbake @@ -74,6 +77,7 @@ containers_kernelcfg_check.bbclass contributing_documentation_build_validation corstone-1000 corstone1000 +corstone1000-image-corstone1000-fvp.wic.nopt corstone1000-image-corstone1000-mps3.wic.nopt corstone1000-mps3 corstone1000-mps3.yml @@ -94,8 +98,9 @@ developer-facing developer.example.org developer_manual devicetree -diego.sueiro +dialout distributions +distro distro_features do_fetch docker's @@ -307,6 +312,7 @@ ua_test_log_dir ubuntu ubuntu-based umask +unmount upstreamed upto urls -- GitLab From 792a27f43e4d95c7ca562c5004507a5afcc3c56d Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 7 Jun 2023 19:35:17 +0000 Subject: [PATCH 05/10] 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 | 1 + documentation/user_manual/n1sdp.rst | 268 ++++++++++++++++ 5 files changed, 310 insertions(+), 296 deletions(-) create mode 100644 documentation/user_manual/n1sdp.rst diff --git a/documentation/user_manual/build.rst b/documentation/user_manual/build.rst index f0669b4..7ba114b 100644 --- a/documentation/user_manual/build.rst +++ b/documentation/user_manual/build.rst @@ -102,299 +102,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 92677ef..2b794e4 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -7,10 +7,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) @@ -119,8 +143,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 a130cf9..a66059d 100644 --- a/documentation/user_manual/corstone1000fvp.rst +++ b/documentation/user_manual/corstone1000fvp.rst @@ -7,7 +7,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 @@ -29,7 +30,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 @@ -42,11 +43,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 1bf88c6..9b785e9 100644 --- a/documentation/user_manual/index.rst +++ b/documentation/user_manual/index.rst @@ -11,5 +11,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..3b399d7 --- /dev/null +++ b/documentation/user_manual/n1sdp.rst @@ -0,0 +1,268 @@ +.. + # Copyright (c) 2023 Arm Limited or its affiliates. All rights reserved. + # + # 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 6882642e9a9d2147eb9a4d7454164c8ca3f90482 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Tue, 6 Jun 2023 20:26:57 +0000 Subject: [PATCH 06/10] 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 7ba114b..322bc96 100644 --- a/documentation/user_manual/build.rst +++ b/documentation/user_manual/build.rst @@ -30,7 +30,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 caa8b0d3a6e1458cf52a66c3c49bcf5de50ad439 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Tue, 6 Jun 2023 21:14:26 +0000 Subject: [PATCH 07/10] 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 | 6 +----- meta-cassini-config/kas/cassini-sdk.yml | 4 ++-- meta-cassini-config/kas/include/dev.yml | 6 +++++- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/meta-cassini-config/kas/cassini-dev.yml b/meta-cassini-config/kas/cassini-dev.yml index f5e5a34..6ee3c9a 100644 --- a/meta-cassini-config/kas/cassini-dev.yml +++ b/meta-cassini-config/kas/cassini-dev.yml @@ -1,4 +1,4 @@ -# Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. +# Copyright (c) 2022-2023 Arm Limited or its affiliates. All rights reserved. # # SPDX-License-Identifier: MIT @@ -9,9 +9,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..8f8d5b1 100644 --- a/meta-cassini-config/kas/cassini-sdk.yml +++ b/meta-cassini-config/kas/cassini-sdk.yml @@ -1,4 +1,4 @@ -# Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. +# Copyright (c) 2022-2023 Arm Limited or its affiliates. All rights reserved. # # SPDX-License-Identifier: MIT @@ -6,7 +6,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 8eae8e9..a13e3e2 100644 --- a/meta-cassini-config/kas/include/dev.yml +++ b/meta-cassini-config/kas/include/dev.yml @@ -1,4 +1,4 @@ -# Copyright (c) 2022 Arm Limited or its affiliates. All rights reserved. +# Copyright (c) 2022-2023 Arm Limited or its affiliates. All rights reserved. # # SPDX-License-Identifier: MIT @@ -19,5 +19,9 @@ repos: poky: refspec: langdale +local_conf_header: + cassini-dev: | + DISTRO_FEATURES:append = " cassini-dev" + env: CASSINI_VERSION: "vNext" -- GitLab From af4b3b423c5cc737e5863159bc214333db483708 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 7 Jun 2023 17:23:06 +0000 Subject: [PATCH 08/10] 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 2b794e4..5783be1 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -10,7 +10,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 3b399d7..25b729e 100644 --- a/documentation/user_manual/n1sdp.rst +++ b/documentation/user_manual/n1sdp.rst @@ -10,7 +10,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 fa2f490..ac8686a 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 CASSINI -- GitLab From de1e6536d072a10e71d51b16520428fb892aaf5c Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Wed, 7 Jun 2023 18:29:58 +0000 Subject: [PATCH 09/10] 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 5783be1..79d834c 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -128,18 +128,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 25b729e..5430b2a 100644 --- a/documentation/user_manual/n1sdp.rst +++ b/documentation/user_manual/n1sdp.rst @@ -64,7 +64,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: @@ -74,11 +74,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:: @@ -92,7 +93,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 f99e39f744aacdbee70e1ea8e758c94901d61974 Mon Sep 17 00:00:00 2001 From: Adam Johnston Date: Thu, 8 Jun 2023 11:53:34 +0000 Subject: [PATCH 10/10] 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 79d834c..f53ca72 100644 --- a/documentation/user_manual/corstone1000.rst +++ b/documentation/user_manual/corstone1000.rst @@ -10,7 +10,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