N1SDP Getting Started Guide

The Neoverse N1 System Development Platform (N1SDP) is an enterprise class reference board based on the Neoverse N1 core.

This document is a guide on how to run an Arm Reference Platforms software stack on N1SDP.

Disclaimer: From N1SDP-2023.06.22 the build-system has been validated in the included Docker container and directly in Ubuntu 20.04 LTS but only the Docker container is fully supported. Following steps list a new software sync and build process. 

Docker container

The build environment for the N1SDP software stack is now provisioned by an Ubuntu 20.04 based Docker container that once built can be used to build all the software components as mentioned in the following section. To install Docker on the system, follow the Standard Installation of Docker page.

Prerequisites

• Docker installed
• Minimum of 50 GB free storage space
• Bash shell environment for executing commands mentioned in this guide

Docker preparation

• Fetch and build the Docker container

$ git clone https://git.gitlab.arm.com/arm-reference-solutions/docker.git -b N1SDP-2024.06.14
$ docker build -t n1sdp-builder docker/

NOTE If facing permission issues, make sure to follow the post-installation steps.

• Create a workspace directory

$ mkdir <n1sdp_workspace>
$ cd <n1sdp_workspace>

• Create an alias for the docker run command as docker_run for re-usability

$ alias docker_run="docker run --rm \
                  --mount type=bind,source=<absolute_path_to_n1sdp_workspace>,target=/workspace \
                  -e TERM=$TERM \
                  --user $(id -u):$(id -g) \
                  -it n1sdp-builder"

The docker_run alias can now be appended at the start of each build (or repo) commands mentioned in this guide and all the builds will execute in the built Docker container environment.

The bind mounted <n1sdp_workspace> helps in binding the N1SDP workspace between the host system and Docker environment. This helps in having flexibility of developing in the host and building in the Docker environment where all the build dependencies are taken care of.

Software Stack preparation

• The N1SDP software stack supports two software distributions:
  • A minimal BusyBox root filesystem
  • Ubuntu server

Sync N1SDP software stack

$ mkdir <n1sdp_workspace>
$ cd <n1sdp_workspace>
$ export N1SDP_RELEASE=refs/tags/N1SDP-2024.06.14

NOTE: Sometimes new features and additional bug fixes will be made available in the git repositories and will not yet have been tagged as part of a release. To pickup these latest changes you can drop the -b <release tag> option and use n1sdp.xml for -m <> from the "repo init" command below, however please be aware that such untagged changes have not yet been formally verified and should be considered unstable until they are tagged in an official release.

To sync and build firmware only:

$ docker_run repo init \
    -u https://git.gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest.git \
    -b ${N1SDP_RELEASE} \
    -g bsp \
    -m pinned-n1sdp.xml \
    --depth=6
$ docker_run repo sync
$ docker_run ./build-scripts/build-all.sh -f none 

The board firmware files are located in <n1sdp_workspace/output/n1sdp/firmware/> after the firmware source build.

To sync and build both the firmware and Ubuntu:

Choose this option if you intend to run the provided Ubuntu Server distro.

$ docker_run repo init \
    -u https://git.gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest.git \
    -b ${N1SDP_RELEASE} \
    -g ubuntu \
    -m pinned-n1sdp.xml \
    --depth=6
$ docker_run repo sync
$ docker_run ./build-scripts/build-all.sh -f ubuntu

 
The image will be available at the location <n1sdp_workspace/output/n1sdp/ubuntu.img>

To sync and build both the firmware and Busybox:

$ docker_run repo init \
    -u https://git.gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest.git \
    -b ${N1SDP_RELEASE} \
    -g bsp,busybox \
    -m pinned-n1sdp.xml \
    --depth=6
$ docker_run repo sync
$ docker_run ./build-scripts/build-all.sh -f busybox

The image will be available at the location <n1sdp_workspace>/output/n1sdp/busybox.img>

You can find more details about sync and build N1SDP software stack in latest N1SDP user guide.

Prepare a bootable USB drive with Ubuntu Server

<n1sdp_workspace>/ubuntu/output/n1sdp/ubuntu.img needs to be flashed to your USB drive or PCIe SSD. In this example we are using a USB drive but the process is the same for a PCIe SSD, though it may take a while for the dd command to complete if your SSD is large.

Identify the USB drive device:

$ lsblk
NAME                MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sda                   8:0    0 931.5G  0 disk
|-sda1                8:1    0 931.5G  0 part
  |-g_sda-data_sda 253:2    0 931.5G  0 lvm  /data_sda
sdb                   8:16   1  14.6G  0 disk

In the given example the device file we need is /dev/sdb. Be cautious here and don't confuse your host PC's own hard drive with the USB drive.

$ sudo dd if=ubuntu.img of=/dev/sdb bs=1M conv=fsync
$ sync

Note that we dd the Ubuntu Server image directly to /dev/sdb, not to a partition on /dev/sdb such as /dev/sdb1.

Two partitions will be created on the USB drive. You can check this with fdisk:

$ sudo fdisk -l /dev/sdb
Disk /dev/sdb: 14.6 GiB, 15669919744 bytes, 30605312 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Device     Boot Start      End  Sectors  Size Id Type
/dev/sdb1        2048    40959    38912   19M  6 FAT16
/dev/sdb2       40960 30605311 30564352 14.6G 83 Linux

The bootable USB drive is ready. If the output of fdisk does not match the above, please check that you have not made a mistake with your dd command.

Booting and connect to the N1SDP

Connect the USB drive to a USB port on the N1SDP back panel (highlighted in the red box):

Connect the provided USB-B cable to the DBG USB port of the N1SDP back panel (highlighted in the red box) to your host PC:

Additional Windows 10 Host PC step: Install FDTI driver to get access to the N1SPD COM ports. See here (the same drivers are used for N1SDP and MPS3). COM ports will be visible at Control Panel->Device Manager->Ports (COM & LPT).

Find four TTY USB devices in your /dev directory:

By default the four ports are connected to the following devices:

• ttyUSB     Motherboard Configuration Controller (MCC)
• ttyUSB<n+1> Application processor (AP)
• ttyUSB<n+2> System Control Processor (SCP)
• ttyUSB<n+3> Manageability Control Processor (MCP)

In this guide the ports are: ttyUSB0 - MCC, ttyUSB1 - AP, ttyUSB2 - SCP, ttyUSB3 - MCP.

The port settings are:

• 115200 Baud
• 8N1
• No parity
• 1 stop bit
• No hardware or software flow support

Before running the deliverables on N1SDP, ensure both BOOT CONF switches are in the OFF position.

Connect to the MCC console. Any terminal applications such as PuTTy or minicom will work. In this guide we use the screen command:

$ sudo screen /dev/ttyUSB0 115200

Turn the main power switch on the power supply of the N1SDP tower. The MCC window is shown. Type ? to see MCC firmware version and a list of commands:

Cmd> ?

Arm N1SDP MCC Firmware v1.2.2
Build Date: Jul 29 2022
Build Time: 13:58:36

+ 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"    | SLOW, MEDIUM, FAST, 0%, 10%, 20%, .. 100% |
| 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                                |
+---------------------------+-------------------------------------------+
Cmd>

Enter the following command on the MCC console to ensure time is correctly set. This is required in order for the first distro boot to succeed:

Cmd> debug
Debug> time
Debug> date
Debug> exit

Enable USB:

Cmd> USB_ON

Mount the N1SDP's internal microSD card over the DBG USB connection to your host PC and copy the required files.

The microSD card is visible on your host PC as a disk device. To check using fdisk:

$ sudo fdisk -l
Disk /dev/sdb: 1.9 GiB, 2008023040 bytes, 3921920 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0xb5316100

Device     Boot Start     End Sectors  Size Id Type
/dev/sdb1         255 3921919 3921665  1.9G  c W95 FAT32 (LBA)

In the given example the SD card is listed as sdb block device with a single partition sdb1, so we need to mount /dev/sdb1.

$ mkdir sdcard
$ sudo mount /dev/sdb1 ./sdcard
$ ls ./sdcard
config.txt   ee0316a.txt   LICENSES   LOG.TXT   MB   SOFTWARE

The board firmware files are located in <n1sdp_workspace/output/n1sdp/firmware> after the firmware source build.

Single chip mode:
n1sdp-board-firmware_primary.tar.gz - firmware to be copied to microSD of N1SDP board in a single chip mode.

Multi chip mode:
n1sdp-board-firmware_primary.tar.gz     - firmware to be copied to microSD of primary board.
n1sdp-board-firmware_secondary.tar.gz -firmware to be copied to microSD of secondary board. 

Copy board firmware binaries to the mounted microSD card:

$ sudo rm -rf ./sdcard/*
$ sudo tar --no-same-owner -xzf n1sdp-board-firmware_primary.tar.gz -C ./sdcard/
$ sudo umount ./sdcard

It is important that you issue the sync command if running Linux on your host PC, and that you safely unmount & eject the microSD card before power cycling the N1SDP. Failure to do so may result in failure to boot.

NOTE:
Please ensure to use the recommended PMIC binary. Refer to page (+) Notice: Potential damage to N1SDP boards if using latest firmware release - Wiki - Open Source Software and Platforms - Arm Community for more information.

If a PMIC binary mismatch is detected, a warning message is printed in the MCC console recommending the user to switch to appropriate PMIC image. On MCC recommendation *ONLY*, please update the MB/HBI0316A/io_v123f.txt file on the microSD using the below commands:

Example command to switch to 300k_8c2.bin from the host PC:

$ sudo mount /dev/sdx1 /mnt
$> sudo sed -i '/^MBPMIC: pms_0V85.bin/s/^/;/g' /mnt/MB/HBI0316A/io_v123f.txt
$> sudo sed -i '/^;MBPMIC: 300k_8c2.bin/s/^;//g' /mnt/MB/HBI0316A/io_v123f.txt
$> sudo umount /mnt

Ensure that both configuration switches on the back panel are in the OFF position:

Connect to the AP console:

$ sudo screen /dev/ttyUSB1 115200

Connect an ethernet cable to the GbE port to avoid waiting for a 5 minute DHCP configuration timeout during the Ubuntu Server boot process:

NOTE: A working internet connection is required on the first boot in order to successfully download and install necessary Ubuntu packages. Installation will fail if an internet connection is not available.

Power on the main SoC using the MCC console:

Cmd> REBOOT

Or press the power button on the N1SDP front panel:

Check the AP console window. When first booting using a freshly prepared USB drive, Ubuntu Server will be installed and you will be dropped into a minimal shell environment. At this point you will need to power cycle the N1SDP board to reboot into the actual Ubuntu Server distro environment.

On the MCC console:

Cmd> REBOOT

On the second boot the grub menu will be shown with the Ubuntu option selected. After booting the Ubuntu prompt should be shown, indicating the system is operational.

Ubuntu 20.04.5 LTS n1sdp ttyAMA0

n1sdp login:

Use these credentials to login:
    user: root
    password: root