diff options
Diffstat (limited to 'docs')
| -rwxr-xr-x | docs/n1sdp/Prepare_distro_image_for_N1SDP.rst | 1 | ||||
| -rwxr-xr-x | docs/n1sdp/ccix-accelerator.rst | 119 | ||||
| -rwxr-xr-x | docs/n1sdp/change-log.rst | 24 | ||||
| -rwxr-xr-x | docs/n1sdp/multichip.rst | 2 | ||||
| -rwxr-xr-x | docs/n1sdp/pcie-sr-iov.rst | 3 | ||||
| -rwxr-xr-x | docs/n1sdp/release-notes.rst | 30 | ||||
| -rwxr-xr-x | docs/n1sdp/run-on-n1sdp.rst | 172 | ||||
| -rw-r--r-- | docs/n1sdp/user-guide.rst | 518 |
8 files changed, 555 insertions, 314 deletions
diff --git a/docs/n1sdp/Prepare_distro_image_for_N1SDP.rst b/docs/n1sdp/Prepare_distro_image_for_N1SDP.rst index 4cbbaf7..f1bb3f6 100755 --- a/docs/n1sdp/Prepare_distro_image_for_N1SDP.rst +++ b/docs/n1sdp/Prepare_distro_image_for_N1SDP.rst @@ -132,6 +132,7 @@ Content of the provided installation script (assumes that network is up): echo "LABEL=ESP /boot/efi vfat defaults 0 0" >> etc/fstab mkdir /boot/efi mount /boot/efi + mount -t efivarfs efivarfs /sys/firmware/efi/efivars/ grub-install || true [ -e /linux-image-n1sdp.deb ] && dpkg -i /linux-image-n1sdp.deb [ -e /linux-headers-n1sdp.deb ] && dpkg -i /linux-headers-n1sdp.deb diff --git a/docs/n1sdp/ccix-accelerator.rst b/docs/n1sdp/ccix-accelerator.rst deleted file mode 100755 index a2042df..0000000 --- a/docs/n1sdp/ccix-accelerator.rst +++ /dev/null @@ -1,119 +0,0 @@ -CCIX Accelerator support on Neoverse N1SDP -========================================== - -.. section-numbering:: - :suffix: . - -.. contents:: - - -CCIX Overview -------------- -Cache Coherent Interconnect for Accelerators (CCIX) is an architecture for data -sharing between a host(N1SDP) and peripheral attached memory and accelerators -connected to the CCIX aware PCIe Slot. CCIX provides coherency between -accelerators, processors and memory, enabling seamless data movement among them. -The CCIX architecture relieves the operating system, or drivers, from having to -execute cache management operations in either processor or accelerator caches, -when data is being shared between them. - -For detailed description refer to `CCIX-consortium`_ to get the CCIX base -specification and software guide. - -The CCIX PoC (Proof of Concept) software framework for N1SDP is based on the -Alveo-U280 FPGA and reliant on bit files and software deliverables from Xilinx. -These components are are not included in this release. Please contact Xilinx for -more information and for Alveo-U280 specific support issues using `Xilinx-Lounge`_ - -Alveo U280 card Installation ----------------------------- - -**Prerequisites** - -The following hardware is required - - N1SDP as the host - - Xilinx Alveo U280 as the Accelerator Card - -**Connect Alveo U280 card to N1SDP** - -Follow the below steps to connect the Alveo U280 on N1SDP board: - 1. Switch off the SMPS switch on N1SDP to power off the board. - 2. Connect the Alevo U280 into the CCIX Slot. - 3. Connect power supply to the Alveo U280. Refer to `Xilinx-Lounge`_ on how - to connect power supply to the card. - 4. Connect a micro USB cable between the Alveo U280 and the host preferably - an x86 Ubuntu machine. - 5. Ensure software tools required by Alveo U280 are installed on the Host - machine. Refer to `Xilinx-Lounge`_ on how to install them. - -**Flash bitfiles on Alveo U280 Card** - - 1. Refer to `Xilinx-Lounge`_ to power on Alveo U280 card. - 2. Refer to `run-on-n1sdp`_ to power ON the N1SDP board. - 3. Refer to `Xilinx-Lounge`_ to program the bitfiles on Alveo U280. - 4. Once the bitfiles have been flashed reboot the N1SDP board using - ``REBOOT`` command in MCC console. - -How to build CCIX on N1SDP ---------------------------- -Refer to the `user-guide`_ to sync the software stack. Select the appropriate -option for CCIX accelerator usecase while syncing the software stack through the -sync script. -Refer to `Xilinx-Lounge`_ to apply patches on the stack required for the bitfile. -Refer to `run-on-n1sdp`_ to build the software stack. - -Verification of CCIX Accelerator Framework ------------------------------------------- -Refer to `run-on-n1sdp`_ to boot the N1SDP board. Once the board has booted edit -the file /etc/default/grub. Add pcie_acs_override=id:13b5:0100 option to the -GRUB_CMDLINE_LINUX_DEFAULT. Save this file and run update-grub command. - -Install the below utility if not already present:: - - $ apt-get install memtester - -If the bit file has only Request Agent(RA), then there can be two traffic flows -which can be tested. These are: - - 1. Host RA to Host HA - 2. Remote RA to Host HA - -The above traffic flows are described in detail below. - -**Host RA to Host HA** - -This is the traffic within the host(N1SDP) and the traffic flow happens between -Host RA and Host HA. This can be tested with the following command:: - - $ memtester 1M 1 - -In the above command, memtester utility is used to allocate and stress test 1 MB -of memory once. Refer to the memtester linux man page for the list of supported -options. - -**Remote RA to Host HA** - -This is the traffic between the Host(N1SDP) and Remote(Alveo U280) and the -traffic flow happens between Remote RA and Host HA. This can be tested with the -following commands for the relevant bitfiles:: - - $ ./bind_tst -n <VFIO_ID> - $ ./pri_tst -n <VFIO_ID> - -Refer `Xilinx-Lounge`_ to get the binaries *<bind_tst>*, *<pri_tst>* and source code -of the proprietary test applications along with the *<VFIO_ID>* to be used for the -relevant bitfiles. - -References ----------- -- http://infocenter.arm.com/help/topic/com.arm.doc.101489_0000_01_en/arm_neoverse_n1_system_development_platform_technical_reference_manual_101489_0000_01_en.pdf - -.. _CCIX-consortium: https://www.ccixconsortium.com/ccix-library/ -.. _Xilinx-Lounge: https://www.xilinx.com/member/ccix.html - ----------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* - -.. _user-guide: ../../user-guide.rst -.. _run-on-n1sdp: ../run-on-n1sdp.rst diff --git a/docs/n1sdp/change-log.rst b/docs/n1sdp/change-log.rst index 7e81eba..0e0d6ab 100755 --- a/docs/n1sdp/change-log.rst +++ b/docs/n1sdp/change-log.rst @@ -9,6 +9,28 @@ Change Log This document contains a summary of the incremental features, changes, fixes and known issues in each release of N1SDP stack. It is listed in the order of latest to oldest +Tagged Version - N1SDP-2020.12.15 +---------------------------------------- +New Features +^^^^^^^^^^^^ +- Yocto based BSP build to generate Poky image. +- Streamlining of build-scripts to build only ubuntu image and perf package. Use yocto framework for other components. +- Enable PCIe devices on secondary chip. + +Known Issues and Limitations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- If either of the two boards needs to boot-up in a single chip mode with a C2C setup, + then the other board should be powered off. +- PCIe root port is limited to GEN3 speed due to the on-board PCIe switch itself only supporting + upto GEN3 speed. +- Page Request Interface (PRI) feature is not available in both SMMUs interfacing with the + PCIe root ports. +- Currently only Micron 8GB single Rank DIMM (part number: MTA9ASF1G72PZ-2G6D1) and + 16GB dual Rank DIMMs (part number:MTA18ASF2G72PDZ-2G6E1) are supported. +- Stability issues have been observed on long stress tests of the system. +- On-board HDMI connection is not supported for graphics output. A PCIe graphics card can be used + for graphics support. + Tagged Version - N1SDP-2020.07.27 ---------------------------------------- New Features @@ -52,7 +74,7 @@ New Features - Multichip SMP support over CCIX/PCIe link. - Dual socket SMP boot with two N1SDP boards connected over CCIX/PCIe link. - - Linux sees 8 cores and DDR memories from both master and slave N1SDP boards. + - Linux sees 8 cores and DDR memories from both primary and secondary N1SDP boards. - CCIX/PCIe link running at GEN3 x16 speed. - PCIe GEN4 x16 support in CCIX slot. GEN4 x16 link verified with Mellanox Card (MCX516A-CDAT). diff --git a/docs/n1sdp/multichip.rst b/docs/n1sdp/multichip.rst index 685d3af..369fd4c 100755 --- a/docs/n1sdp/multichip.rst +++ b/docs/n1sdp/multichip.rst @@ -114,4 +114,4 @@ References *Copyright (c) 2020, Arm Limited. All rights reserved.* -.. _user-guide: ../user-guide.rst +.. _user-guide: user-guide.rst diff --git a/docs/n1sdp/pcie-sr-iov.rst b/docs/n1sdp/pcie-sr-iov.rst index c3c5135..ceeb48f 100755 --- a/docs/n1sdp/pcie-sr-iov.rst +++ b/docs/n1sdp/pcie-sr-iov.rst @@ -49,6 +49,5 @@ References *Copyright (c) 2020, Arm Limited. All rights reserved.* -.. _user-guide: ../user-guide.rst -.. _run-on-n1sdp: run-on-n1sdp.rst +.. _user-guide: user-guide.rst .. _pcie-support: pcie-support.rst diff --git a/docs/n1sdp/release-notes.rst b/docs/n1sdp/release-notes.rst index bd40de1..98db13c 100755 --- a/docs/n1sdp/release-notes.rst +++ b/docs/n1sdp/release-notes.rst @@ -9,13 +9,13 @@ Release Notes Features and Fixes ------------------ -The following is a summary of the key software features of the tagged N1SDP-2020.07.27 release. +The following is a summary of the key software features of the tagged N1SDP-2020.12.15 release. -- Stability improvement over the GEN4 x16 link on CCIX slot. Verified with Mellanox Card (MCX516A-CDAT). -- Switched to user space dhcp client from the kernel space dhcp client for the initial ubuntu boot. -- Updated MCC firmware (mbb_v107) – This prompt for the recommended PMIC firmware. -- Added new PMIC firmware (300k_8c2) – This supports for boards manufactured post Nov 2019. -- Added latest PCC firmware (pcc_v050) – This allows to update of older boards. +- Yocto based BSP build to generate Poky distribution image and board firmware binary package. +- Restructuring the ubuntu build and packaging scripts to generate the custom ubuntu image. +- Support for both single and multi-chip configurations. + +This release is made to restructure the N1SDP profile majorly considering the single and multi-chip profiles, for CCIX accelerator profile please refer to `N1SDP community portal`_. Precautions ----------- @@ -33,18 +33,11 @@ Precautions - Avoid touching the component pins or any other metallic elements. - Update/Change board firmware only if MCC FW ask to do so, - see here for more information - https://community.arm.com/developer/tools-software/oss-platforms/w/docs/604/notice-potential-damage-to-n1sdp-boards-if-using-latest-firmware-release + refer to `potential damage`_ page for more information - Note: The case front panel USB 3.0 ports and & audio jacks are NOT connected/usable. They will be removed on later versions. -PCIe Testing ------------- -Limited PCIe testing done on: -- Mellanox ConnectX-5 -- Xilinx U280 CCIX card - Known Issues or limitations --------------------------- - If either of the two boards needs to boot-up in a single chip mode with a C2C setup, @@ -52,12 +45,9 @@ Known Issues or limitations - To boot a standard distribution on N1SDP platform the kernel must be patched with the PCIe quirks. See the article `PCIE`_ - PCIe root port is limited to GEN3 speed due to the on-board PCIe switch supporting maximum GEN3 speed. -- GEN4 x16 link in CCIX slot has not been performance tested. -- CCIX usecases (Accelerator/Multichip) is limited to GEN3 speed. -- Page Request Interface (PRI) feature is not available in both SMMUs interfaced with PCIe & CCIX root ports. +- Page Request Interface (PRI) feature is not available in both SMMUs interfaced with PCIe root ports. - Currently only Micron 8GB single Rank DIMM (part number: MTA9ASF1G72PZ-2G6D1) and 16GB dual Rank DIMMs (part number:MTA18ASF2G72PDZ-2G6E1) are supported. -- Multichip usecase does not enable peripheral access in the slave chip. - Stability issues have been observed on long stress tests of the system. - On-board HDMI connection is not supported for graphics output. PCIe graphics card can be used for graphics support. @@ -74,4 +64,6 @@ For support email: support-subsystem-enterprise@arm.com *Copyright (c) 2019-2020, Arm Limited. All rights reserved.* -.. _PCIE: pcie-support.rst +.. _PCIE: pcie-support.rsti +.. _N1SDP community portal: https://community.arm.com/developer/tools-software/oss-platforms/w/docs/458/neoverse-n1-sdp +.. _potential damage: https://community.arm.com/developer/tools-software/oss-platforms/w/docs/604/notice-potential-damage-to-n1sdp-boards-if-using-latest-firmware-release diff --git a/docs/n1sdp/run-on-n1sdp.rst b/docs/n1sdp/run-on-n1sdp.rst deleted file mode 100755 index 6534cb7..0000000 --- a/docs/n1sdp/run-on-n1sdp.rst +++ /dev/null @@ -1,172 +0,0 @@ -Running the software on N1SDP -============================= - - -.. section-numbering:: - :suffix: . - -.. contents:: - - -Introduction ------------- - -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 . - -These instructions assumes you have already followed the `user-guide`_ to sync and build an Arm Reference Platforms -software stack for N1SDP. - -The synced workspace includes several board files and prebuilt binaries under the *<workspace/board_firmware/>* directory. - -Setup Preparation ------------------ - -**Preparing a bootable disk** - -A bootable disk (USB stick or SATA drive) can be prepared by formatting it with the prebuilt image located at -*<workspace/grub-ubuntu.img>* or the source build image at the location *<workspace/output/n1sdp/build_artifact/grub-ubuntu.img>* -after the source build. - -This is a bootable GRUB image comprising LINUX and an Ubuntu 18.04 file system. The partitioning and packaging is performed -during the build. - -Use the following commands to burn the GRUB image to a USB stick or SATA drive: - - :: - - $ lsblk - $ sudo dd if=grub-ubuntu.img of=/dev/sdX bs=1M - $ sync - -Note: Replace ``/dev/sdX`` with the handle corresponding to your USB stick or SATA drive, as identified by the ``lsblk`` command. - -Connect the bootable media to the N1SDP platform; USB sticks should be inserted into to one of the four USB3.0 ports, while -SATA drives should be connected to one of the two SATA ports. - - -**Configure COM Ports** - -Connect a USB-B cable between your host PC and N1SDP's DBG USB port, then power ON the board. The DBG USB connection will enumerate -as four virtual COM ports assigned to the following processing entities, in order - - :: - - COM<n> - Motherboard Configuration Controller (MCC) - COM<n+1> - Application Processor (AP) - COM<n+2> - System Control Processor (SCP) - COM<n+3> - Manageability Control Processor (MCP) - -Please check Device Manager in Windows or ls /dev/ttyUSB* in Linux to identify <n>. - -Use a serial port application such as *PuTTy* or *minicom* to connect to all virtual COM ports with the following settings: - - :: - - 115200 baud - 8-bit word length - No parity - 1 stop bit - No flow control - -Note: Some serial port applications refer to this as "115200 8N1" or similar. - -Running the deliverables on N1SDP ---------------------------------- - -Ensure both BOOT CONF switches are in the OFF position, then issue the following -command in the MCC console: - - Cmd> USB_ON - -This will mount the on-board microSD card as a USB Mass Storage Device on the -host PC with the name N1SDP; how you then proceed will depend on whether you -built from source or chose a prebuilt configuration. - -Ensure that time is correctly set on N1SDP board through following command in -the MCC console if not set then change it accordingly: - - :: - - Cmd> debug - Debug> time - Debug> date - Debug> exit - - - - -**Prebuilt configuration** - -Copy the contents of -<workspace/n1sdp-board-firmware-${RELEASE_TAG}/n1sdp-board-firmware-${RELEASE_TAG}/ -onto the mounted microSD card, then skip to the ** Booting the board ** -section. - - -**Built from source** - -Copy the contents of <workspace/board_firmware/> onto the mounted microSD card, -then copy the .bin files mcp_fw.bin, mcp_rom.bin, scp_fw.bin, and scp_rom.bin from <workspace/output/n1sdp/build_artifact/> to the -<SOFTWARE/> directory on the mounted microSD card, overwriting the existing files. - -**Booting the board** - -Insert the bootable disk created earlier, and connect an ethernet cable to the -Gigabit Ethernet port to avoid DHCP timeouts during boot. - -Shutdown and reboot the board by issuing the following commands to the MCC -console: - - :: - - Cmd> SHUTDOWN - Cmd> REBOOT - -On rebooting, the board will copy the new binaries and firmware images from -the microSD card into either on-board QSPI flash or DDR3 memory via the IOFPGA; -see <MB/images.txt> on the microSD card. - -Enter the UEFI menu by pressing Esc on the AP console as the edk2 logs start -appearing; from here, enter the UEFI Boot Manager menu and then select media -having Ubuntu 18.04 bootable image. -Ubuntu 18.04 will boot in two stages, onces first boot is finished reboot the board -from MCC console. - - :: - - Cmd> REBOOT - -The system will boot into a minimal Ubuntu 18.04 environment. -Login as root and install any required packages from the console -# apt-get install <package-name> - -Building Kernel Modules Natively --------------------------------- -Native building of kernel modules typically require kernel headers to be installed on the platform. -However, a bug in deb-pkg packs the host executables rather than the target executables. This can be -worked around by building and installing the kernel natively on the platform. - - 1. Boot the N1SDP board with Ubuntu filesystem and login as root. - 2. Install build packages using following command: - apt-get install -y git build-essential bc bison flex libssl-dev - 3. git clone -b n1sdp http://git.linaro.org/landing-teams/working/arm/kernel-release.git - 4. git clone http://git.linaro.org/landing-teams/working/arm/n1sdp-pcie-quirk.git - 5. cd kernel-release/ - 6. git am ../n1sdp-pcie-quirk/linux/\*.patch - 7. mkdir out - 8. cp -v /boot/config-5.4.0+ out/.config - 9. make O=out -j4 - 10. make O=out modules_install - 11. make O=out install - 12. update-grub - 13. sync - 14. Reboot the board and when Grub menu appears, select the Advanced Boot Options -> 5.4.0 kernel - for booting. - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* - -.. _user-guide: ../user-guide.rst - diff --git a/docs/n1sdp/user-guide.rst b/docs/n1sdp/user-guide.rst new file mode 100644 index 0000000..cefbca9 --- /dev/null +++ b/docs/n1sdp/user-guide.rst @@ -0,0 +1,518 @@ +User Guide +========== + +.. section-numbering:: + :suffix: . + +.. contents:: + +Introduction +------------ + +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 fetch, build from source, and run an Arm Reference Platforms +software stack on N1SDP, including a Linux distribution based on either the `Yocto project`_'s Poky +Linux, or on Ubuntu Server. + +The synced workspace includes: + + * Scripts to build the board firmware, Linux kernel, and Ubuntu Server distro image + * Yocto `Bitbake`_ layers for building the Board Support Package (BSP) and Poky Linux distro + * Other supporting board files and prebuilt binaries. + +Prerequisites +------------- + +These instructions assume that: + * Your host PC is running Ubuntu Linux 18.04 LTS and should have at least 50GB free storage space + * You are running the provided scripts in a ``bash`` shell environment. + +The following utilities must be available on your host PC: + * chrpath + * compression library + * diffstat + * gawk + * makeinfo + * openssl headers + * pip + * repo + * yocto + +To ensure that all the required packages are installed, run: + +:: + + sudo apt-get update + sudo apt-get install chrpath gawk texinfo libssl-dev diffstat wget git-core unzip gcc-multilib \ + build-essential socat cpio python python3 python3-pip python3-pexpect xz-utils debianutils \ + iputils-ping python3-git python3-jinja2 libgl1-mesa-dev libsdl1.2-dev pylint3 xterm git-lfs \ + openssl curl libncurses-dev libz-dev python-pip + +**Install repo tool** + +Follow the instructions provided in the `repo README file`_ to install the ``repo tool``. + +NOTE: The repo tool which gets installed using apt-get command sometimes return errors, in such a case its recommended to install repo using the ``curl`` method. + +Syncing and building the source code +------------------------------------ + +The N1SDP software stack supports two software distributions: + * Poky Linux, a minimal BusyBox-like environment + * Ubuntu Server. + +The instructions below provide the necessary steps to sync and build these distributions. + +First, create a new folder that will be your workspace and will henceforth be referred to as +``<n1sdp_workspace>`` in these instructions: + +:: + + mkdir <n1sdp_workspace> + cd <n1sdp_workspace> + export N1SDP_RELEASE=refs/tags/N1SDP-2020.12.15 + +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 from the ``repo init`` commands 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 BSP without Ubuntu +########################## + +Choose this option if you intend to run the provided Poky Linux distro, or your own alternative +software solution. + +To sync a specific tagged release:: + + repo init -u https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms-manifest.git -m n1sdp-v2.xml -g bsp -b ${N1SDP_RELEASE} + repo sync -j$(nproc) + +Or to sync the latest untagged features and bug fixes:: + + repo init -u https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms-manifest.git -m n1sdp-v2.xml -g bsp + repo sync -j$(nproc) + +To sync both the BSP and Ubuntu +############################### + +Choose this option if you intend to run the provided Ubuntu Server distro. + +To sync a specific tagged release:: + + repo init -u https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms-manifest.git -m n1sdp-v2.xml -g ubuntu -b ${N1SDP_RELEASE} + repo sync -j$(nproc) + +Or to sync the latest untagged features and bug fixes:: + + repo init -u https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms-manifest.git -m n1sdp-v2.xml -g ubuntu + repo sync -j$(nproc) + +To build the BSP and Poky Linux distro +###################################### + +Mandatory for *all* users. + +:: + + cd <n1sdp_workspace>/bsp + export DISTRO="poky" + export MACHINE="n1sdp" + source setup-environment + bitbake core-image-base + +The initial clean build is expected to take a long time, as all host tools and utilities are built +from source before the target images. This includes host executables (python, cmake, etc.) and the +required toolchain(s). + +Once the build is successful, all images will be placed in the +``<n1sdp_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp`` directory. + +To build the Ubuntu Server distro +################################# + +Only required if intending to run the provided Ubuntu Server distro. + +The Ubuntu Server distro image is built using the script provided in +``<n1sdp_workspace>/ubuntu/build-scripts``. + +:: + + cd <n1sdp_workspace>/ubuntu + ./build-scripts/build-ubuntu.sh + + Options that can be passed to script are: + <path to build-ubuntu.sh> [OPTIONS] + OPTIONS: + cleanall remove all the sources fetched during previous build, removing all binaries from sub folders. + clean remove all binaries from sub folders generated in previous build. + build build linux, linux-firmware, busybox, grub binaries and Ubuntu distribution image + package package all the above listed components into one single Ubuntu grub image + + NOTE: If no option specified then script will execute cleanall, build and package. + The final image grub-ubuntu.image can be located in ubuntu/output/n1sdp + + +Provided components +------------------- + +Within the Yocto project, each component included in the N1SDP software stack is specified as +a `Bitbake`_ recipe. The N1SDP recipes are located at ``<n1sdp_workspace>/bsp/layers/meta-arm/``. + +**Steps for baking Images from unstaged source code** + +Yocto allows modifying the fetched source code of each recipe component in the +workspace, by applying patches. This is however not a convenient approach for +developers, since creating patches and updating recipes is time-consuming. +To make that easier, Yocto provides the devtool utility. devtool creates a +new workspace, in which you can edit the fetched source code and bake images +with the modifications + +:: + + cd <n1sdp_workspace>/bsp + MACHINE=n1sdp DISTRO=poky . ./conf/setup-environment-n1sdp + # create a workspace for a given recipe component + # recipe-component-name can be of: + # trusted-firmware-a / scp-firmware / edk2-firmware / grub-efi / linux-linaro-arm + devtool modify <recipe-component-name> + # This creates a new workspace for recipe-component-name and fetches source code + # into "build-poky/workspace/sources/{trusted-firmware-a,scp-firmware,edk2-firmware,grub-efi,linux-linaro-arm}" + # edit the source code in the newly created workspace + # build images with changes on workspace + # recipe-component-name can be of: scp-firmware / edk2-firmware / grub-efi / linux-yocto + bitbake <recipe-component-name> + +Software Components +################### + +Trusted Firmware-A +****************** + +Based on `Trusted Firmware-A`_. + ++--------+----------------------------------------------------------------------------------------------------------------+ +| Recipe | <n1sdp_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a-n1sdp.inc | ++--------+----------------------------------------------------------------------------------------------------------------+ +| Files | * <n1sdp_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp/bl31-n1sdp.bin | ++--------+----------------------------------------------------------------------------------------------------------------+ + + +System Control Processor (SCP) +****************************** + +Based on `SCP Firmware`_. + ++--------+----------------------------------------------------------------------------------------------------+ +| Recipe | <n1sdp_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-bsp/scp-firmware/scp-firmware-n1sdp.inc | ++--------+----------------------------------------------------------------------------------------------------+ +| Files | * <n1sdp_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp/scp_ramfw.bin | +| | * <n1sdp_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp/scp_romfw.bin | +| | * <n1sdp_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp/mcp_ramfw.bin | +| | * <n1sdp_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp/mcp_romfw.bin | ++--------+----------------------------------------------------------------------------------------------------+ + + +uefi edk2 +********* + +Based on `UEFI edk2`_. + ++--------+---------------------------------------------------------------------------------------------+ +| Recipe | <n1sdp_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-bsp/uefi/edk2-firmware-n1sdp.inc | ++--------+---------------------------------------------------------------------------------------------+ +| Files | * <n1sdp_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp/uefi.bin | ++--------+---------------------------------------------------------------------------------------------+ + + +Linux +***** + +Based on `Linux 5.4 for N1SDP`_. + ++--------+-------------------------------------------------------------------------------------------------+ +| Recipe | <n1sdp_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-kernel/linux/linux-linaro-arm_5.4.bb | ++--------+-------------------------------------------------------------------------------------------------+ +| Files | * <n1sdp_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp/Image | ++--------+-------------------------------------------------------------------------------------------------+ + + +Poky Linux distribution +*********************** + +The layer is based on the `Poky`_ Linux distro, which is itself based on BusyBox and built using +glibc. + ++--------+---------------------------------------------------------------------------------------------------+ +| Recipe | <tc0_workspace>/bsp/layers/openembedded-core/meta/recipes-core/images/core-image-base.bb | ++--------+---------------------------------------------------------------------------------------------------+ +| Files | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/n1sdp/core-image-base-n1sdp.wic | ++--------+---------------------------------------------------------------------------------------------------+ + + +Ubuntu Linux distribution +************************* + +Ubuntu is built as a separate project using the ``build-scripts/``, then booted using the BSP built +by Yocto. The generated distro image is placed at ``output/n1sdp/grub-ubuntu.img``. + + +Running the software distribution on N1SDP +------------------------------------------ + +This section provides steps for: + * Setting up the N1SDP with the required board firmware + * Preparing a bootable disk + * Boot the supported software distributions (Poky Linux or Ubuntu Server). + +Setting up the N1SDP +#################### + +After powering up or rebooting the board, any firmware images placed on the board's microSD will be +flashed into either on-board QSPI flash copied into DDR3 memory via the IOFPGA. + +**Configure COM Ports** + +Connect a USB-B cable between your host PC and N1SDP's DBG USB port, then power ON the board. The +DBG USB connection will enumerate as four virtual COM ports assigned to the following processing +entities, in order + + :: + + COM<n> - Motherboard Configuration Controller (MCC) + COM<n+1> - Application Processor (AP) + COM<n+2> - System Control Processor (SCP) + COM<n+3> - Manageability Control Processor (MCP) + +Please check Device Manager in Windows or ``ls /dev/ttyUSB*`` in Linux to identify <n>. + +Use a serial port application such as *PuTTy* or *minicom* to connect to all virtual COM ports with +the following settings: + + :: + + 115200 baud + 8-bit word length + No parity + 1 stop bit + No flow control + +Note: Some serial port applications refer to this as "115200 8N1" or similar. + +Before running the deliverables on N1SDP, ensure both BOOT CONF switches are in the OFF position, +then issue the following command in the MCC console: + + Cmd> USB_ON + +This will mount the on-board microSD card as a USB Mass Storage Device on the host PC with the name +"N1SDP". + +Enter the following command on the MCC console window 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 + +Update firmware on microSD card +############################### + +The board firmware files are located in ``<n1sdp_workspace/bsp/build-poky/tmp-poky/deploy/images/n1sdp/>`` +after the BSP source build. + +Single chip mode:: + + n1sdp-board-firmware_primary.tar.gz : firmware to be copied to microSD of N1SDP board in 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. + +There are two methods for populating the microSD card: + 1. The microSD card from the N1SDP can be removed from N1SDP and can be mounted on a host machine + using a card reader, + 2. The USB debug cable when connected to host machine will show the microSD partition on host + machine which can be mounted. + + :: + + $> sudo mount /dev/sdx1 /mnt + $> sudo rm -rf /mnt/* + $> sudo tar --no-same-owner -xzf n1sdp-board-firmware_primary.tar.gz -C /mnt/ + $> sudo umount /mnt``` + +NOTE: replace ``sdx1`` with the device and partition of the SD card. + +Option (2) above is typically preferred, as removing the microSD card requires physical access to +the motherboard inside the N1SDP's tower case. + +Firmware tarball contains iofpga configuration files, SCP, TF-A, and UEFI binaries. + +**NOTE**: +Please ensure to use the recommended PMIC binary. Refer to page `potential-damage`_ for more info. + +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 + + +Boot Poky on N1SDP +################## + +**Preparing a bootable Poky disk** + +A bootable disk (USB stick or SATA drive) can be prepared by flashing the image generated from the +source build. The image will be available at the location +``<n1sdp_workspace/bsp/build-poky/tmp-poky/deploy/images/n1sdp/core-image-base-n1sdp.wic>``. + +This is a bootable GRUB wic image comprising Linux kernel and Poky distro. The partitioning and +packaging is performed during the build based on the wks file located at +``<n1sdp_workspace/bsp/layers/meta-arm/meta-arm-bsp/wic/n1sdp-efidisk.wks>``. + +Use the following commands to burn the GRUB image to a USB stick or SATA drive: + + :: + + $ lsblk + $ sudo dd if=core-image-base-n1sdp.wic of=/dev/sdx conv=fsync bs=1M + $ sync + +Note: Replace ``/dev/sdx`` with the handle corresponding to your USB stick or SATA drive, as +identified by the ``lsblk`` command. + +**Booting the board with Poky image** + +Insert the bootable disk created earlier. Shutdown and reboot the board by issuing the following +commands to the MCC console: + + :: + + Cmd> SHUTDOWN + Cmd> REBOOT + +Enter the UEFI menu by pressing Esc on the AP console as the edk2 logs start appearing; from here, +enter the UEFI Boot Manager menu and then select the burned disk. + +By default the Linux kernel will boot with ACPI, though Device Tree can also be specified:: + + *ARM reference image boot on N1SDP (ACPI) + ARM reference image boot on Single-Chip N1SDP (Device Tree) + ARM reference image boot on Multi-Chip N1SDP (Device Tree) + +The system will boot into a base image environment of Poky Linux. + +The N1SDP login password is *root* + +Boot Ubuntu on N1SDP +#################### + +**Preparing a bootable Ubuntu disk** + +A bootable disk (USB stick or SATA drive) can be prepared by formatting it with the distro image +created during source build. The image will be available at the location location +``<n1sdp_workspace/ubuntu/output/n1sdp/grub-ubuntu.img>``. + +This is a bootable GRUB image comprising Linux kernel and an Ubuntu Server 18.04 file system. The +partitioning and packaging is performed during the build. + +Use the following commands to burn the GRUB image to a USB stick or SATA drive: + + :: + + $ lsblk + $ sudo dd if=grub-ubuntu.img of=/dev/sdX bs=1M + $ sync + +Note: Replace ``/dev/sdX`` with the handle corresponding to your USB stick or SATA drive, as +identified by the ``lsblk`` command. + +**Booting the board with Ubuntu image** + +Insert the bootable disk created earlier and connect the ethernet cable to a working internet +connection. This is *REQUIRED* on first boot in order to successfully download and install necessary +Ubuntu packages. Installation will fail if an internet connection is not available. + +Shutdown and reboot the board by issuing the following commands to the MCC console: + + :: + + Cmd> SHUTDOWN + Cmd> REBOOT + + +Enter the UEFI menu by pressing Esc on the AP console as the edk2 logs start appearing; from here, +enter the UEFI Boot Manager menu and then select the burned disk. + +Ubuntu 18.04 will boot in two stages; the first boot is an installation pass, after which a second +boot is required to actually enter the Ubuntu Server environment. + +To reboot the board after the first boot installation pass has completed, from MCC console: + + :: + + Cmd> REBOOT + +The system will boot into a minimal Ubuntu 18.04 environment. + +Login as user ``root`` with password *root*, and install any desired packages from the console:: + + # apt-get install <package-name> + +Building Kernel Modules Natively +******************************** + +Native building of kernel modules typically requires kernel headers to be installed on the platform. +However, a bug in deb-pkg currently causes host executables to be packed rather than the target +executables. + +This can be worked around by building and installing the kernel natively on the platform. + +Boot the N1SDP board with Ubuntu filesystem and login as root. + + :: + + apt-get install -y git build-essential bc bison flex libssl-dev + git clone -b n1sdp http://git.linaro.org/landing-teams/working/arm/kernel-release.git + git clone http://git.linaro.org/landing-teams/working/arm/n1sdp-pcie-quirk.git + cd kernel-release/ + git am ../n1sdp-pcie-quirk/linux/\*.patch + mkdir out + cp -v /boot/config-5.4.0+ out/.config + make O=out -j4 + make O=out modules_install + make O=out install + update-grub + sync + +Reboot the board and when Grub menu appears, select the Advanced Boot Options -> 5.4.0 kernel for +booting. + +.. _potential-damage: https://community.arm.com/developer/tools-software/oss-platforms/w/docs/604/notice-potential-damage-to-n1sdp-boards-if-using-latest-firmware-release +.. _Yocto project: https://www.yoctoproject.org +.. _Bitbake: https://www.yoctoproject.org/docs/1.6/bitbake-user-manual/bitbake-user-manual.html +.. _Trusted Firmware-A: https://trustedfirmware-a.readthedocs.io/en/latest/ +.. _SCP Firmware: https://github.com/ARM-software/SCP-firmware +.. _UEFI edk2: https://github.com/tianocore/edk2 +.. _Linux 5.4 for N1SDP: https://git.linaro.org/landing-teams/working/arm/kernel-release.git +.. _Poky: https://www.yoctoproject.org/software-item/poky +.. _repo README file: https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md + +---------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* |