[[PageOutline]] = Building OpenWrt for Gateworks Products = Gateworks uses the OpenWrt Linux Distribution for its Board Support Package (BSP). From time to time, Gateworks may have patches against upstream OpenWrt to support some features which have not made it upstream or perhaps are not suitable for upstream OpenWrt. Additionally Gateworks provides a Makefile wrapper around OpenWrt to aid in pinning versions of Opensource tree's to versions that Gateworks has tested with. Please do not allow this to dissuade you from building mainline OpenWrt, particularly if being current is of importance. There are only a small number of features you will find in Gateworks-OpenWrt that do not exist in mainline, generally related to the GSC. When using upstream OpenWrt be aware it will be necessary for your boot firmware to be updated to the latest version Gateworks offers. [=#branches] == OpenWrt BSP Branches == The Gateworks OpenWrt repository consist of a snapshot of upstream OpenWrt at specific points, with a few additional patches added on top that either had not made it upstream by that time, or add a gateworks directory consisting of Gateworks tested config files and JTAG flash image creation scripts. The repository can be found on the [https://github.com/Gateworks/openwrt Gateworks ​GitHub openwrt page]. Our branch naming policy is as follows: * Each new bump of 'master' will cause a new branch to be created: bump date_openwrt revision. This is the bleeding edge OpenWrt software from Gateworks and thus includes Gateworks patches on top. * When we decide to cut a stable release, the branch name will be: last two char of year.numerical month.version * master - **This branch is not recommended to be used**. It only serves as a reference point for the latest dated branch and is missing any patches that Gateworks has that have not been submitted or accepted upstream as well as the Gateworks support scripts and default config files. Our ​http://github.com/Gateworks/openwrt repository branches currently include: * '''Gateworks 20.06 !OpenWrt Release''' - Is the latest OpenWrt software from Gateworks (**recommended**) - Latest build: ​http://dev.gateworks.com/openwrt/20.06/ * Please view the .manifest file per target to inspect installed packages + their respective versions - Based on OpenWrt fd0cc72d9 (2020-06-09) * Linux 5.4.45 * Wireless drivers from linux backports-5.7-rc3-1 * busybox-1.31.1 * gcc-8.4.0 * binutils-2.31.1 * Package feeds pinned to 2020-06-15 - General: * Added Gateworks System Controller drivers * dropped laguna support * dropped GW16083 support - Newport: * Bump to linux 5.4.45 Kernel from 4.14.13 * squashfs+f2fs overload for sysupgrade/factory-reset support - Ventana: * Bump to linux 5.4.45 Kernel from 4.4.0 - log: ​https://github.com/Gateworks/openwrt/commits/20.06 [[CollapsibleStart(18.0x)]] * Gateworks 18.0x !OpenWrt Release (for Newport) * Linux 4.14.13 * busybox-1.27.2 * Wireless drivers from linux backports-2017.11.01 * gcc-5.5.0 * binutils-2.28 * Package feeds pinned to 2018-05-24 - Add Newport (octeontx) support - missing GSC support - missing accelerometer/IMU support [[CollapsibleEnd]] [[CollapsibleStart(16.02)]] * Gateworks 16.02 !OpenWrt Release - Nightly: ​http://dev.gateworks.com/openwrt/16.02/ * Please view the .manifest file per target to inspect installed packages + their respective versions - Based on OpenWrt r48868 (2016-02-17) - General: * Moved to git for SCM of choice * Gateworks System Controller drivers * Feeds bumped to 2016-02-17 * Updated to latest wireless drivers (backports-20151218) * IEEE802.11 adhoc throughput increased for HT rates (iw 4.3) * Bump to linux 4.4.0 Kernel * busybox-1.24.1 * gcc-5.2.0 * binutils-2.25.1 * Moved from uclibc to musl-1.1.12 - Ventana: * Bump to linux 4.4.0 Kernel from 3.14.16 * ~50% increased FEC driver performance * l2cache enabled * Hardware crypto support * squashfs+ubifs overlay for recovery * dsa/swconfig support for GW16083 * HDMI out, no VPU/GPU * LVDS out, no VPU/GPU * Low-Latency RS485 support - Laguna: * Bump to linux 4.4.0 Kernel from 3.10.49 * Added GW2393 Support * Added GW2383 Support - log: ​https://github.com/Gateworks/openwrt/commits/16.02 [[CollapsibleEnd]] [[CollapsibleStart(14.08)]] * Gateworks 14.08 !OpenWrt Release - Nightly: ​http://dev.gateworks.com/openwrt/14.08/ * Please view the .manifest file per target to inspect installed packages + their respective versions - Based on OpenWrt r42297 (2014-08-25) - General: * Refreshed Gateworks patches * Refreshed Gateworks config files * Updated all feeds to latest versions as of 2014-08-27 * Updated to latest wireless drivers * 80211ac support (ath10k/iwlabgn) * DFS Support in ath * Added HID Support to Ventana and Laguna * Added Bluetooth support (both btusb and ath3k) to Ventana and Laguna * Added ibt and ath3k Bluetooth firmwares to Ventana and Laguna - Ventana: * Add support for GW54xx/GW53xx/GW52xx/GW51xx/GW552x * Add gsc-daemon support for above boards * Add support for GW16081/GW16082/GW16082 * Kernel: 3.14.16 * Added sysupgrade support - Laguna * Kernel: 3.10.49 [[CollapsibleEnd]] == Revision Log == You can see a revision history using the Github web interface: * [https://github.com/Gateworks/openwrt/commits/20.06 20.06] * [https://github.com/Gateworks/openwrt/commits/18.0x ​18.0x] * [https://github.com/Gateworks/openwrt/commits/16.02 ​16.02] * [https://github.com/Gateworks/openwrt/commits/14.08 ​14.08] == OpenWrt BSP Pre-Built Binaries == To get an already built image to flash onto the SBC, please visit the following: * [http://dev.gateworks.com/newport/images/ Latest Newport OpenWrt Pre-Built Image] * [http://dev.gateworks.com/openwrt/ Ventana/Laguna OpenWrt Pre-Built Images] == Building Pre-requisites == These instructions require having a desktop or laptop computer with Ubuntu installed to compile Gateworks OpenWrt. Gateworks has tested with desktop systems with LTS Ubuntu Releases. The suggested Ubuntu releases are 16.04 or 18.04. On an Ubuntu desktop development system for example the following should install all necessary pre-requisites: {{{#!bash sudo apt-get install subversion build-essential ;# std dev tools sudo apt-get install zlib1g-dev libncurses5-dev gawk flex git-core unzip gettext quilt libssl-dev ;# other libs/tools needed by OpenWrt Buildroot }}} * **NOTE**: If you are experiencing difficulties, Here is a list of the pre-requisites from the general OpenWrt Site. OpenWrt buildroot prerequisites listed ​here Ubuntu 14.04/16.04 Notes: * **Note**: There is a known bug with Ubuntu 14.04/16.04 when building Python 2.7. that may occur. Because the system Python is used during this build, you may encounter the following error: {{{#!bash ImportError: No module named _sysconfigdata_nd configure: error: python2.7 interpreter not found make[3]: *** [~/openwrt-next/build_dir/target-arm_cortex-a9+neon_musl-1.1.11_eabi/Python-2.7.11/.configured_yy yyyyyyy] Error 1 }}} * In order to fix it, please execute the following: {{{#!bash sudo ln -s /usr/lib/python2.7/plat-*/_sysconfigdata_nd.py /usr/lib/python2.7/ }}} Please ensure your development system has **all of the listed packages installed before proceeding** and note that your development box will need **access to the internet** in order to download the files for the development tree. ** WARNING! Building with GCC 4.7.x is not fully supported. Please use 4.8.2+ or 4.6.x and below. We have also found 6.2+ to have some issues.** == Downloaded Source Files == OpenWrt uses a Linux build system called {{{buildroot}}}. Like all Linux build systems it consists of recipes that go through the process of fetching, patching, compiling, packaging various applications. The 'fetching' process involves downloading source tarballs from the Internet (which is why an Internet connection is required). OpenWrt will fetch all sources into the 'dl' directory in the OpenWrt tree (ie 14.08/dl from the Gateworks directory). To avoid downloading sources each time you do a clean build it is recommended that you create a static location on your development host to store downloaded packages and symlink this to the dl directory. The Gateworks Makefile which fetches OpenWrt and patches it, will create this link for you if the {{{/usr/src/dl}}} directory exists on your development host, so if you create that and make it writable by your development user all downloads will go there automatically and be able to be used for subsequent builds. This not only helps reduce build time but it can also help if a package's source isn't available because of a site or mirror being down. == Step by Step Instructions == Video: [https://youtu.be/cnObX6tErhw] To support OpenWrt for the Gateworks products, we maintain a patchset that is generic to all our standard product families. The below instructions are primarily for Ventana and Laguna. *** Note, for all Newport related building, please follow these instructions: [wiki:newport/bsp#BuildingtheBSPfromsource Newport OpenWrt BSP Instructions] 1. Getting Source Code: * There are multiple code branches (see above for recommended branch per product), please checkout the one you prefer with the following commands: - Gateworks 20-06 branch {{{#!bash git clone https://github.com/Gateworks/openwrt/ gateworks-openwrt -b 20.06 cd gateworks-openwrt }}} - Gateworks 16-02 branch {{{#!bash git clone https://github.com/Gateworks/openwrt/ gateworks-openwrt -b 16.02 cd gateworks-openwrt }}} - Gateworks 14-08 branch {{{#!bash git clone https://github.com/Gateworks/openwrt/ gateworks-openwrt -b 14.08 cd gateworks-openwrt }}} - Upstream OpenWrt 18.06 branch {{{#!bash git clone git://git.openwrt.org/openwrt/openwrt.git -b openwrt-18.06 cd openwrt/ make package/symlinks make menuconfig }}} - In menuconfig: - Target system: - Ventana: Freescale i.MX6 - Laguna: Cavium Networks Econa CNS3xxx - Newport: Octeon-TX - Profile: Multiple devices (in order to build both large/normal ubi images for Ventana ( Which ubi size to use, normal or large, has to do with the flash geometry size (see [wiki:/linux/ubi/#flashgeometry here] to determine your flash geometry) )) - Devices: (only available with Profile: Multiple devices) Devices will be automatically selected depending on target system. Be sure to double check this setting. For Ventana you will need "Gateworks Ventana large/normal" - Target Images: check this setting is correct, Ventana will require squashfs and ubifs - install whatever packages you want - Packages can be added to packages/feeds/packages and must contain a Makefile. 2. Building: * Our OpenWrt Git repository has a 'gateworks' directory added consisting of a Makefile providing targets that aim to simplify the entire process of: - using a (per target) Gateworks provided .config file - producing JTAG binary images compatible with the Gateworks JTAG dongle * Once the branch has been checked out from the ​Gateworks GitHub account, you are ready to build. The Gateworks Makefile provides the following targets: - all : Built imx6 and cns3xxx targets. - imx6 : build BSP for the imx6 target (Ventana product family) - cns3xxx : build BSP for the cns3xxx target (Laguna product family) - images : build binary flash images (suitable for JTAG flashing) for supported product families (Ventana / Laguna). - dirclean : remove all downloaded and built directories - In order to build the imx6 target for the Ventana product family, the following steps would occur: {{{#!bash # Build the imx6 target, using the configuration from gateworks/configs/imx6/.config. # This will take a while make -C gateworks/ imx6 }}} - In order to build the cns3xxx target for the Laguna product family, the following steps would occur: {{{#!bash # Build the cns3xxx target, using the configuration from gateworks/configs/cns3xxx/.config. # This will take a while make -C gateworks/ cns3xxx }}} - Mainline OpenWrt-18.06: {{{#!bash make #This is the only command you need after make menuconfig }}} - The build process will take some time depending on your Internet connection and host system. On an Intel Quad Core @ 3.10GHz the build takes a couple of hours to build all product families and takes appx 15GB of disk space. 3. Artifacts - The resulting kernel/rootfs files will be in the {{{bin/}}} directory. - For Example, a Ventana flash image is located at: {{{bin/targets/imx6/generic/gateworks-imx6-ventana-squashfs-nand.ubi}}} - Which ubi size to use, normal or large, has to do with the flash geometry size (see [wiki:/linux/ubi/#flashgeometry here] to determine your flash geometry) 4. Installing: * To install the OpenWrt image onto the Gateworks SBC, please follow the instructions: - [wiki:ventana/openwrt#Step2.InstallingFirmware Ventana Instructions]: - Typical methods include flashing a .ubi file over TFTP or creating a JTAG binary and flashing using the USB JTAG dongle - [wiki:laguna/openwrt#InstallingFirmware Laguna Instructions] - Note - For Laguna boards, please do not flash a squashfs file to the board. A proper JTAG binary must be created with instructions below. - Typical methods include creating a JTAG binary file using the below instructions and flashing to the board via the USB JTAG programmer == Building JTAG Binary File == Creating JTAG Binaries to flash with the GW16042 is easily done with the targets in the makefile within the gateworks directory: {{{#!bash # Make a 'jtagable' images for Ventana NAND FLASH make -C gateworks/ images/ventana # Make a 'jtagable' image for Laguna NOR FLASH make -C gateworks/ images/laguna # Make both Ventana and Laguna 'jtagable' images make -C gateworks/ images }}} * The resulting flash firmware image will be {{{gateworks/images/}}}. == Building MMC Disk Image == If you wish to create an MMC 'disk image' for Ventana boards that boot from eMMC or microSD: {{{#!bash # create a filesystem image OUTFS=owrt.ext4 SIZEFSMB=256M MNT=$(mktemp -d -p/tmp) truncate -s $SIZEFSMB $OUTFS sudo mkfs.ext4 -q -F -O ^64bit -L rootfs $OUTFS sudo mount $OUTFS $MNT sudo tar -C $MNT -xf bin/targets/imx6/generic/gateworks-imx6-ventana-squashfs-bootfs.tar.gz sudo tar -C $MNT -xf bin/targets/imx6/generic/gateworks-imx6-rootfs.tar.gz sudo umount $MNT # create a disk image SIZEMB=7248M OUTIMG=ventana.img truncate -s $SIZEMB $OUTIMG # partition disk - single ext partition printf "2048,,L,,\n" | sudo sfdisk -uS $OUTIMG sudo dd if=ventana/images/SPL of=$OUTIMG bs=512 seek=2 sudo dd if=ventana/images/u-boot.img of=$OUTIMG bs=512 seek=138 sudo dd if=$OUTFS of=$OUTIMG bs=1M seek=1 # create a compressed disk image that can be installed via U-Boot's gzwrite gzip -f -k $OUTIMG && ls -lh $OUTIMG* # create a jtag binary image mkimage_jtag --emmc -e --partconf=user $OUTIMG@user:erase_all:0x0- > $OUTIMG.bin }}} * SIZEFSMB above is the size of the filesystem to create in MB - this needs to be large enough to accommodate the files you are putting there... a good rule of thumb is to keep it as small as possible and use {{{resize2fs}}} on it to grow it to the size of the partition you place it in after first boot * SIZEMB above is the size of the disk image to create in MB which needs to be large enough to fit the filesystem + the 1MB offset of the partition table yet small enough to fit the actual device you will copy this to in the future (such as microSD or eMMC). Note that 7248M is the appropriate size for the 8GiB eMMC's that Gateworks uses * ventana.img is a non-compressed disk image containing SPL, U-Boot and the ext4 partition which can be copied directly to a microSD or eMMC via: - U-Boot with a 'mmc write' - Linux with a 'dd if=ventana.img.gz of=$blockdev' * ventana.img.gz is a compressed disk image which can be flashed onto an MMC device via: - U-Boot for example with a 'gzwrite mmc $dev $loadaddr $filesize' - Linux for example with a 'zcat ventana.img.gz | sudo dd of=$blockdev' * ventana.bin is a JTAG'able binary image containing SPL, U-Boot and the ext4 partition To flash the file to the board, please see this link: [wiki:jtag_instructions#Instructions JTAG Programming Instructions] == Customizing == Video: https://youtu.be/HHhT6z0J5TU Once a target has been built using the above instructions, a user may customize their image. OpenWrt can be customized by running the {{{make menuconfig}}} command. In this new window, you can select/deselect packages you want installed. If kernel customization is required, a {{{make kernel_menuconfig}}} will open the make menu for the kernel. Once complete, a simple {{{make -j8 V=s}}} will re-run the make command to re-create the rootfs. Please read more at this page [wiki:OpenWrt/Configuration here]. == Updating to Latest Gateworks Source == The steps to update your current project to the latest Gateworks patches varies depending on the branch you're trying to update. Please see the below two sections that help to detail this out. However, please note that using Git is the most developer friendly. * To update to the latest patches on the same branch: {{{#!bash # Make sure you have latest ref's git remote update # This will update the current working branch to the latest upstream, # then attempt to rebase any local patches on top. git pull --rebase }}} * To change to a new branch, using 16.02 as an example branch: {{{#!bash # Make sure you have latest ref's git remote update # Checkout upstream branch 16.02 and create local branch named 16.02 git checkout remotes/origin/16.02 -b 16.02 }}} After this is complete, please continue to build as normal. For more detail on working with git, please refer to ​[http://git-scm.com/ this site]. For information on {{{git pull}}}, please refer to ​[http://git-scm.com/docs/git-pull this page]. For information about {{{git rebase}}}, please refer to [https://git-scm.com/docs/git-rebase ​this page]. == Troubleshooting Build Failures == One of the most commonly occurring errors that we have run into are source URL's disappearing which causes the source files to not be there during build-time. To help alleviate this, Gateworks has put up source tarballs at [http://dev.gateworks.com/sources ​our development site]. Our build environment takes advantage of this by uploading files for feeds that we require and automatically selecting them if all other options fail. In general, it will 1: look for the tarball locally; 2: try the original source URL; and 3: try [http://dev.gateworks.com/sources our ​dev] site. Below are other issues that may crop up: 1. **Finding an Error** - Often the error will be 'reported' at the end of the build. However, the error will have actually occurred earlier on. Scroll up in the logs and look for an error. Typically it is from a package or dependency that was not able to be downloaded. 2. **Missing Dependencies** - The build will pull files from mirrors around the web including a Gateworks mirror at ​http://dev.gateworks.com/sources. If for some reason you can't download dependencies then you likely have a network issue. Note that files can be placed manually in the dl directory to avoid downloading. 3. **Errors** - By default, the build is ran on many threads with the parameter -j8. To achieve better debugging information after a failure, re-run the build with the following -j1 flag from the trunk directory: {{{#!bash make -j1 V=s }}} == More OpenWrt Information == For more information about OpenWrt see: [[TitleIndex(OpenWrt)]]