[[PageOutline]]

= Newport Board Support Package (BSP)
Gateworks provides a Board Support Package for Newport which provides source code and an easy mechanism to build different images, including Ubuntu and OpenWrt.

Gateworks uses the term 'BSP' to describe one 'image' file, that contains everything, including all boot firmware, operating system (rootfs and kernel). 

The Gateworks BSP is the easiest comprehensive software process because it contains everything. If a deep dive, expert path is desired, each piece of the BSP (boot firmware, rootfs, kernel) can all be built separately. 

 * [#kernel Gateworks Newport Linux Kernel]
 * [wiki:newport/boot Gateworks Newport Boot Firmware]

[=#images]
== BSP Pre-Built Firmware Images

Pre-built firmware images can be found on http://dev.gateworks.com/newport.

A sampling includes:

 * ''' Entire Board Software (recommended), including boot firmware, bootloader, OS, kernel, etc: '''
  * [http://dev.gateworks.com/newport/images/ Newport Images] - Compressed Disk Image containing Firmware and kernel and OS ( .img.gz files )
   * Ubuntu version details are available [wiki:newport/ubuntu here]
   * !OpenWrt
 * ''' Newport GSC '''
  * [http://dev.gateworks.com/newport/images/ GSC firmware image]
 * '''Only Boot Firmware '''
  * [http://dev.gateworks.com/newport/boot_firmware/firmware-newport.img firmware-newport.img] - Boot Firmware (everything up to and including the bootloader stored on the embedded FLASH boot device) (see [wiki:newport/boot newport/boot] for details)
 * '''Only Newport Kernel '''
  * [http://dev.gateworks.com/newport/kernel/linux-newport.tar.xz linux-newport.tar.xz] - Compressed TAR archive of pre-built Linux kernel

''' Installation ''' instructions are at the following URL: [wiki:/newport/firmware#UpdateFirmwareviaSerialConsoleandEthernetfromBootloader Newport Flashing Instructions] 


[=#source]
== BSP Source Code
Newport Source code for the firmware, bootloader and kernel are hosted at !GitHub. We highly recommend you create a !GitHub account and 'Watch' these repositories to keep abreast of important feature additions, bugfixes, and firmware-releases. You can configure your !GitHub account to e-mail you when changes are made to repositories [https://github.com/settings/notifications here].

The following !GitHub repos are used for Newport:
 * [https://github.com/Gateworks/bsp-newport] - Newport BSP support scripts and Makefile  ([https://github.com/Gateworks/bsp-newport/subscription watch])
 * [https://github.com/Gateworks/manifest-newport] - Newport BSP repo Manifest  ([https://github.com/Gateworks/manifest-newport/subscription watch])
 * [https://github.com/Gateworks/uboot-newport uboot-newport] - Newport Bootloader ([https://github.com/Gateworks/uboot-newport/subscription watch)]
 * [https://github.com/Gateworks/linux-newport linux-newport] - Newport Linux Kernel ([https://github.com/Gateworks/linux-newport/subscription watch)]
 * [https://github.com/Gateworks/dts-newport dts-newport] - Newport Linux Device-Tree ([https://github.com/Gateworks/dts-newport/subscription watch)]
 * [https://github.com/Gateworks/bdk-newport bdk-newport] - Newport BDK (used as Secondary Program Loader) ([https://github.com/Gateworks/bdk-newport/subscription watch)]
 * [https://github.com/Gateworks/atf-newport atf-newport] - Newport ATF (ARM Trusted Firmware) ([https://github.com/Gateworks/atf-newport/subscription watch)]
 * [https://github.com/Gateworks/openwrt openwrt] - Gateworks OpenWrt ([https://github.com/Gateworks/openwrt/subscription watch)]


[=#build]
== Building the BSP from source
Below are instructions for building the entire BSP, which includes all of the bootloader components and Linux kernel and Ubuntu or OpenWrt.  Pre-built images are available [#images above].

The Gateworks Venice Board Support Package uses the Google [https://gerrit.googlesource.com/git-repo/git-repo git-repo] tool to manage multiple code repositories.

The following pre-requisites are needed to build the Newport BSP:
 * Linux Development host (desktop or laptop computer) (Ubuntu 16.04 is used by Gateworks and tested)
 * Python 2.x (required by the 'repo' tool and imaging tools)
 * Git (used for source code repositories)
 * repo (used to manage multiple git repos)
 * libssl-dev (used for signing images)
** NOTE: Building images requires root privileges

Installing pre-requisites:
{{{#!bash
# install packages
sudo apt-get install build-essential git python2 python3 python-is-python3 python3-setuptools python3-distutils python3-dev swig libssl-dev ncurses-dev kmod bison flex device-tree-compiler wget cpio unzip rsync bc fdisk file -y
# configure git
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
git config --global color.ui true
}}}

Install the latest version of {{{repo}}} (Do not rely on Ubuntu apt package being up to date):
{{{#!bash
sudo wget https://storage.googleapis.com/git-repo-downloads/repo -O /usr/local/bin/repo
sudo chmod a+rx /usr/local/bin/repo
}}}

To obtain the code:
 1. Initialize repo (fetch the repo manifest)
{{{#!bash
mkdir $HOME/newport
cd $HOME/newport
repo init -u https://github.com/Gateworks/manifest-newport.git
}}}
 1. Sync repositories (repeat this when you want to fetch the latest code updates)
{{{#!bash
repo sync --fail-fast -v
}}}
  * This will fetch/update the source repos described [#source above]. The first time it can take several minutes depending on your Internet connection and will take approximately ~2.5GB of disk space
 1. Setup build environment (***repeat this each time you open shell***)
{{{#!bash
source newport/setup-environment
}}}
 1. Build the BDK (this only needs to be done once).  
{{{#!bash
make bdk
}}}
 1. Build desired software target as defined below. For example:
{{{#!bash
make -j8 ubuntu-image
}}}

The '''build targets''' supported by the Newport BSP include:
  * **ubuntu-image** - builds ubuntu-newport.img.gz: A Compressed Disk Image which includes the 16MB [wiki:newport/boot Boot Firmware] (BDK/ATF/U-Boot and Device-Tree images) as well as the Kernel and Ubuntu root filesystem. 
   * [wiki:newport/ubuntu Ubuntu on Newport Wiki Page] - more details, versions, etc
   * [wiki:newport/firmware#serial-ethernet-uboot Installation Instructions]
  * **openwrt-image** - Using Newport-BSP is not recommended for building OpenWrt. We recommend building openwrt directly from the git repo, using instructions here: [wiki:OpenWrt/building]
   * [wiki:newport/firmware#serial-ethernet-uboot Installation Instructions]
  * **firmware-image** - builds 'firmware-newport.img': 16MB [wiki:newport/boot Boot Firmware] which includes the BDK/ATF/U-Boot and Device-Tree images - (takes about 2 mins on a modern development system).
  * **kernel_image** - builds linux-newport.tar.xz - A compressed tarball of the kernel (boot/Image) and kernel modules (lib/modules/*) which can be used on top of any compatible root filesystem 

 General installation instructions: 
  * [wiki:newport/firmware Flashing / Updating software on Newport SBC]
  * [wiki:/newport/boot#BuildingaBootableDiskImages Creating Entire Disk Images for Booting]


[=#repo]
=== Working with the repo tool
The {{{repo}}} tool unifies Git repositories into a single project by specifying Git repos and directories they exist in. The tool was created for the Android project as Android is comprised of hundreds of repos however it has since been used by many projects that benefit from its git repo management tool.

See:
 - https://source.android.com/setup/develop#repo
 - https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md
 - https://source.android.com/setup/develop/repo

==== Updating to the latest code
When working with the {{{repo}}} tool you can update to the latest code using the {{{repo sync}}} command:
{{{#!bash
$ repo sync
Fetching: 100% (8/8), done in 5.258s
Garbage collecting: 100% (8/8), done in 0.188s
repo sync has finished successfully.
}}}

The {{{repo}}} tool works off of a manifest file in {{{.repo/manifests/default.xml}}} which specifies the various projects, what repo they are in, and where they are checked out in your directory structure. If a branch has changed, a project added, or a project removed the manifest file will be updated when you run {{{repo sync}}} then it will update the various project repos. If a branch has changed to something new you can encounter an error such as:
{{{#!bash
$ repo sync
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (1/1), done.
remote: Total 3 (delta 1), reused 3 (delta 1), pack-reused 0
Unpacking objects: 100% (3/3), done.
project .repo/manifests/
Updating 5c981dac1797..0b0055e7445e
Fast-forward

error: in `sync`: revision v5.10.76-venice in Gateworks/linux-venice not found
}}}

This specific error is saying that the 'v5.10.76-venice' revision (or branch) is not in the current working copy of the repo. To resolve this you need to do a {{{git remote update}}} for that project. You can also use {{{repo foreach}}} to update all projects:
{{{#!bash
repo forall -c git remote update # update all projects
git -C linux remote update # update just the project in the linux path
}}}  


==== Showing diffs for all projects (repo diff)
You can show all the diffs for each project using {{{repo diff}}} 

==== Using the latest version
The {{{repo}}} tool is updated frequently. While it is rarely necessary to have the latest version it will inform you if there is an update and how to install that update in the current working directory:
{{{#!bash
$ repo sync

... A new version of repo (2.17) is available.
... You should upgrade soon:
    cp /usr/src/venice/bsp/.repo/repo/repo /home/user/bin/repo
...
}}}

To update the {{{repo}}} tool just copy the file as mentioned above:
{{{#!bash
cp .repo/repo/repo $HOME/bin/repo
}}}



[=#kernel]
=== Modifying the stand-alone Linux Kernel (ie for Ubuntu)
The Gateworks Newport BSP instructions [#build above] create an environment for building the Linux kernel among other targets.

Some additional instructions for common actions (make sure you have already installed the BSP and setup your shell environment as specified above):
 * Make standard Gateworks Newport kernel with Gateworks newport_defconfig
{{{#!bash
make linux # first build the kernel with the standard newport_defconfig
}}}
 * Modify Kernel configuration (enabling modules etc):
{{{#!bash
make -C linux menuconfig # make your changes
make -C linux savedefconfig # once satisfied create a defconfig
cp linux/defconfig linux/arch/arm64/configs/newport_defconfig # and copy it to the newport_defconfig
}}}
 * Build kernel tarball:
{{{#!bash
make kernel_image # builds the kernel and modules and tarball
}}}
 * Build new disk image using the updated kernel tarball:
{{{#!bash
make ubuntu-image
}}}


=== Modifying OpenWrt (toolchain, apps, kernel, filesystem)
The OpenWrt build system includes building its own toolchain and kernel (so the kernel and toolchain directories in the bsp directory are not used)

Modifying OpenWrt toolchain, installed applications, and general configuration:
{{{#!bash
make -C openwrt menuconfig # configure toolchain, installed applications and general configuration
}}}
 - this results in a custom {{{.config}}} file in the {{{openwrt}}} directory which you may want to save away

Modifying OpenWrt kernel:
{{{#!bash
make -C openwrt kernel_menuconfig
}}}
 - this results in modifying {{{target/linux/octeontx/config-*}}} in the {{{openwrt}}} directory which you may want to save away
 - Note that some kernel configurations get over-written by OpenWrt despite what you may select here

Build/rebuild OpenWrt (with your customizations):
{{{#!bash
make openwrt
}}}
 - results in build artifacts in {{openwrt/bin/targets/octeontx/generic/}}} including rootfs tarball, linux kernel, and squashfs filesystem


If you would like to change the filesystem size for the image being created you will need to edit gen_image.sh:

https://github.com/Gateworks/openwrt/blob/20.06/target/linux/octeontx/image/gen_image.sh#L47

The path to this configuration script is established here:

https://github.com/Gateworks/openwrt/blob/20.06/target/linux/octeontx/image/Makefile




[=#toolchain]
== Toolchain

=== Marvell toolchain
The Newport BSP uses a Marvell toolchain to build the kernel and boot firmware based on gcc v7.3.0.

The specific details can be shown by running 'gcc -v' for example:
{{{#!bash
user@host:/usr/src/newport/bsp$ . ./setup-environment # configure PATH and CROSS_COMPILER env vars
user@host:/usr/src/newport/bsp$ ${CROSS_COMPILE}gcc -v
Using built-in specs.
COLLECT_GCC=aarch64-marvell-linux-gnu-gcc
COLLECT_LTO_WRAPPER=/usr/src/newport/bsp/marvell-tools-238.0/bin/../libexec/gcc/aarch64-marvell-linux-gnu/7.3.0/lto-wrapper
Target: aarch64-marvell-linux-gnu
Configured with: /home/jenkins/workspace/BuildToolchainAARCH64_Marvell7/toolchain/scripts/../src/configure --disable-fixed-point --without-ppl --without-python --disable-werror --enable-plugins --with-lto-plugin-source=/home/jenkins/workspace/BuildToolchainAARCH64_Marvell7/toolchain/scripts/../gits/gcc/lto-plugin --with-system-zlib --enable-initfini-array --with-sysroot --with-local-prefix=/home/jenkins/workspace/BuildToolchainAARCH64_Marvell7/toolchain/scripts/../marvell-tools/aarch64-marvell-linux-gnu/sys-root --disable-sim --enable-symvers=gnu --enable-__cxa_atexit --enable-symvers=gnu --enable-__cxa_atexit --disable-sim --with-multilib-list=lp64,ilp32 --enable-gnu-indirect-function --target=aarch64-marvell-linux-gnu --enable-languages=c,c++,fortran --prefix=/home/jenkins/workspace/BuildToolchainAARCH64_Marvell7/toolchain/scripts/../marvell-tools --with-pkgversion='Marvell Inc. Version: Marvell GCC7 build 238.0' --with-bugurl=http://www.marvell.com/support/ --with-libexpat-prefix=/home/jenkins/workspace/BuildToolchainAARCH64_Marvell7/toolchain/scripts/../libs
Thread model: posix
gcc version 7.3.0 (Marvell Inc. Version: Marvell GCC7 build 238.0) 
}}}

The buildroot based toolchain is used by virtue of sourcing the [https://github.com/Gateworks/bsp-newport/blob/master/setup-environment setup-environment] file which adds to your PATH and sets the CROSS_COMPILE variable.

=== Cross compile examples

Examples of cross-compiling using the buildroot toolchain
 * ANSI-C hello world:
{{{#!bash
cat << EOF > helloworld.c
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char **argv)
{
        printf("hello world!\n");

        return 0;
}
EOF
. ./setup-environment # setup environment for buildroot toolchain
${CROSS_COMPILE}gcc helloworld.c -o helloworld
}}}
 * C++ hello world:
{{{#!bash
cat << EOF > helloworld.cpp
#include <iostream>

using namespace std;

int main() {
        cout << "Hello World!";
        return 0;
}
EOF
. ./setup-environment # setup environment for buildroot toolchain
${CROSS_COMPILE}gcc helloworld.cpp -lstdc++ -o helloworld
}}}
 * kernel module:
{{{#!bash
. ./setup-environment # setup environment for buildroot toolchain
make kernel_image # first build the kernel
make -C linux M=$PWD/my-module modules
}}}
  - Note that some out-of-tree kernel modules do not follow the suggested Makefile standards and may need to be modified to use the CROSS_COMPILE prefix and/or specify the kernel directory (as opposed to the above example where you do a make in the linux dir and set M to the path of your module)