Changes between Version 2 and Version 3 of OpenWrt/building


Ignore:
Timestamp:
01/15/2018 10:34:31 AM (6 weeks ago)
Author:
Tim Harvey
Comment:

convert restored html to wiki markup

Legend:

Unmodified
Added
Removed
Modified
  • OpenWrt/building

    v2 v3  
    1 {{{#!html
    2           <div id="wikipage" class="trac-content"><p>
    3 </p><div class="wiki-toc">
    4 <ol>
    5   <li>
    6     <a href="#BuildingOpenWrtforGateworksProducts">Building OpenWrt for Gateworks Products</a>
    7     <ol>
    8       <li>
    9         <a href="#OpenWrtBSPBranches">OpenWrt BSP Branches</a>
    10       </li>
    11       <li>
    12         <a href="#RevisionLog">Revision Log</a>
    13       </li>
    14       <li>
    15         <a href="#OpenWrtBSPPre-BuiltBinaries">OpenWrt BSP Pre-Built Binaries</a>
    16       </li>
    17       <li>
    18         <a href="#BuildingPre-requisites">Building Pre-requisites</a>
    19       </li>
    20       <li>
    21         <a href="#DownloadedSourceFiles">Downloaded Source Files</a>
    22       </li>
    23       <li>
    24         <a href="#StepbyStepInstructions">Step by Step Instructions</a>
    25         <ol>
    26           <li>
    27             <a href="#Step1:GettingSourceCode">Step 1: Getting Source Code</a>
    28           </li>
    29           <li>
    30             <a href="#Step2:Building">Step 2: Building</a>
    31             <ol>
    32               <li>
    33                 <a href="#Artifacts">Artifacts</a>
    34               </li>
    35             </ol>
    36           </li>
    37           <li>
    38             <a href="#Step3:Installing">Step 3: Installing</a>
    39           </li>
    40         </ol>
    41       </li>
    42       <li>
    43         <a href="#BuildingJTAGBinaryFile">Building JTAG Binary File</a>
    44       </li>
    45       <li>
    46         <a href="#Customizing">Customizing</a>
    47       </li>
    48       <li>
    49         <a href="#UpdatingtoLatestGateworksSource">Updating to Latest Gateworks Source</a>
    50       </li>
    51       <li>
    52         <a href="#TroubleshootingBuildFailures">Troubleshooting Build Failures</a>
    53       </li>
    54     </ol>
    55   </li>
    56 </ol>
    57 </div><p>
    58 </p>
    59 <h1 id="BuildingOpenWrtforGateworksProducts">Building <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> for Gateworks Products</h1>
    60 <p>
    61 Gateworks uses the <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> Linux Distribution for its Board Support Package (BSP). From time to time, Gateworks may have patches against upstream <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> to support some features which have not made it upstream or perhaps are not suitable for upstream <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a>. Additionally Gateworks provides a <tt>Makefile</tt> wrapper around <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> to aid in pinning versions of Opensource tree's to versions that Gateworks has tested with.
    62 </p>
    63 <p>
    64 For more information about the <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> SDK and other features, visit <a class="wiki" href="/wiki/OpenWrt">Gateworks OpenWrt Wiki Page</a>
    65 </p>
    66 <p>
    67 <span class="wikianchor" id="branches"></span> <span class="wikianchor" id="releases"></span>
    68 </p>
    69 <h2 id="OpenWrtBSPBranches"><a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> BSP Branches</h2>
    70 <p>
    71 The Gateworks <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> repository consist of a snapshot of upstream <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> 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 Gateworks <a class="ext-link" href="https://github.com/Gateworks/openwrt"><span class="icon">​</span>GitHub openwrt</a> page.
    72 </p>
    73 <p>
     1[[PageOutline]]
     2
     3= Building OpenWrt for Gateworks Products =
     4Gateworks 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.
     5
     6For more information about the OpenWrt SDK and other features, visit the [wiki:OpenWrt Gateworks OpenWrt Wiki Page].
     7
     8
     9
     10[=#branches]
     11== OpenWrt BSP Branches ==
     12The 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].
     13
    7414Our branch naming policy is as follows:
    75 </p>
    76 <ul><li>Each new bump of 'master' will cause a new branch to be created: <em>bump date</em>_<em>openwrt revision</em>. This is the bleeding edge <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> software from Gateworks and thus includes Gateworks patches on top.
    77 </li><li>When we decide to cut a stable release, the branch name will be: <em>last two char of year</em>.<em>numerical month</em>.<em>version</em>
    78 </li><li>master - <strong>This branch is not to be used</strong>. It only serves as a reference point for the latest dated branch and has no Gateworks patches on top of it.
    79 </li></ul><p>
    80 Our <a class="ext-link" href="https://github.com/Gateworks/openwrt/"><span class="icon">​</span>Git</a> branches currently include:
    81 </p>
    82 <ul><li><strong>16.02</strong> - Is the latest <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> software from Gateworks
    83 <ul><li>Nightly: <a class="ext-link" href="http://dev.gateworks.com/openwrt/16.02/"><span class="icon">​</span>http://dev.gateworks.com/openwrt/16.02/</a>
    84 <ul><li>Please view the <tt>.manifest</tt> file per target to inspect installed packages + their respective versions
    85 </li></ul></li><li>Based on <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> <a class="missing changeset" title="No changeset 48868 in the repository">r48868</a> (2016-02-17)
    86 </li><li>General:
    87 <ul><li>Moved to git for SCM of choice
    88 </li><li>Gateworks System Controller drivers
    89 </li><li>Feeds bumped to 2016-02-17
    90 </li><li>Updated to latest wireless drivers (backports-20151218)
    91 </li><li>IEEE802.11 adhoc throughput increased for HT rates (iw 4.3)
    92 </li><li>Bump to linux 4.4.0 Kernel
    93 </li><li>busybox-1.24.1
    94 </li><li>gcc-5.2.0
    95 </li><li>binutils-2.25.1
    96 </li><li>Moved from uclibc to musl-1.1.12
    97 </li></ul></li><li>Ventana:
    98 <ul><li>Bump to linux 4.4.0 Kernel from 3.14.16
    99 </li><li>~50% increased FEC driver performance
    100 </li><li>l2cache enabled
    101 </li><li>Hardware crypto support
    102 </li><li>squashfs+ubifs overlay for recovery
    103 </li><li>dsa/swconfig support for GW16083
    104 </li><li>HDMI out, no VPU/GPU
    105 </li><li>LVDS out, no VPU/GPU
    106 </li><li>Low-Latency RS485 support
    107 </li></ul></li><li>Laguna:
    108 <ul><li>Bump to linux 4.4.0 Kernel from 3.10.49
    109 </li><li>Added GW2393 Support
    110 </li><li>Added GW2383 Support
    111 </li></ul></li><li>Avila / Cambria:
    112 <ul><li>Support dropped
    113 </li></ul></li><li>Known Issues:
    114 <ul><li>
    115 </li></ul></li><li>log: <a class="ext-link" href="https://github.com/Gateworks/openwrt/commits/16.02"><span class="icon">​</span>https://github.com/Gateworks/openwrt/commits/16.02</a>
    116 </li></ul></li></ul><p>
    117 </p><div> <h3 class="foldable">14.08 - required for Avila/Cambria</h3><div><p>
    118 </p>
    119 <ul><li><strong>14-08</strong> - Uses <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> pinned from Aug 2014 (r42297)
    120 <ul><li>Nightly: <a class="ext-link" href="http://dev.gateworks.com/openwrt/14.08/"><span class="icon">​</span>http://dev.gateworks.com/openwrt/14.08/</a>
    121 <ul><li>Please view the <tt>.manifest</tt> file per target to inspect installed packages + their respective versions
    122 </li></ul></li><li>Based on <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> <a class="missing changeset" title="No changeset 42297 in the repository">r42297</a> (2014-08-25)
    123 </li><li>General:
    124 <ul><li>Refreshed Gateworks patches
    125 </li><li>Refreshed Gateworks config files
    126 </li><li>Updated all feeds to latest versions as of 2014-08-27
    127 </li><li>Updated to latest wireless drivers
    128 </li><li>80211ac support (ath10k/iwlabgn)
    129 </li><li>DFS Support in ath
    130 </li><li>Added HID Support to Ventana and Laguna
    131 </li><li>Added Bluetooth support (both btusb and ath3k) to Ventana and Laguna
    132 </li><li>Added ibt and ath3k Bluetooth firmwares to Ventana and Laguna
    133 </li></ul></li><li>Ventana:
    134 <ul><li>Add support for GW54xx/GW53xx/GW52xx/GW51xx/GW552x
    135 </li><li>Add gsc-daemon support for above boards
    136 </li><li>Add support for GW16081/GW16082/GW16082
    137 </li><li>Kernel: 3.14.16
    138 </li><li>Added sysupgrade support
    139 </li></ul></li><li>Laguna
    140 <ul><li>Kernel: 3.10.49
    141 </li></ul></li><li>Avila / Cambria:
    142 <ul><li>Kernel: to 3.10.49
    143 </li></ul></li></ul></li></ul><p>
    144 </div></div>
    145 </p>
    146 <p>
    147 If you are looking for our old <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> BSP's such as the 13.06 or 12.08 from our old SVN repository please see <a class="wiki" href="/wiki/OpenWrt/building?version=96">on older revision of this page</a>
    148 </p>
    149 <h2 id="RevisionLog">Revision Log</h2>
    150 <p>
     15 * 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.
     16 * When we decide to cut a stable release, the branch name will be: last two char of year.numerical month.version
     17 * master - **This branch is not to be used**. It only serves as a reference point for the latest dated branch and has no Gateworks patches on top of it.
     18
     19
     20Our ​Git branches currently include:
     21 * 16.02 - Is the latest OpenWrt software from Gateworks
     22  - Nightly: ​http://dev.gateworks.com/openwrt/16.02/
     23    * Please view the .manifest file per target to inspect installed packages + their respective versions
     24  - Based on OpenWrt r48868 (2016-02-17)
     25  - General:
     26    * Moved to git for SCM of choice
     27    * Gateworks System Controller drivers
     28    * Feeds bumped to 2016-02-17
     29    * Updated to latest wireless drivers (backports-20151218)
     30    * IEEE802.11 adhoc throughput increased for HT rates (iw 4.3)
     31    * Bump to linux 4.4.0 Kernel
     32    * busybox-1.24.1
     33    * gcc-5.2.0
     34    * binutils-2.25.1
     35    * Moved from uclibc to musl-1.1.12
     36  - Ventana:
     37    * Bump to linux 4.4.0 Kernel from 3.14.16
     38    * ~50% increased FEC driver performance
     39    * l2cache enabled
     40    * Hardware crypto support
     41    * squashfs+ubifs overlay for recovery
     42    * dsa/swconfig support for GW16083
     43    * HDMI out, no VPU/GPU
     44    * LVDS out, no VPU/GPU
     45    * Low-Latency RS485 support
     46  - Laguna:
     47    * Bump to linux 4.4.0 Kernel from 3.10.49
     48    * Added GW2393 Support
     49    * Added GW2383 Support
     50  - Avila / Cambria:
     51    * Support dropped
     52  - log: ​https://github.com/Gateworks/openwrt/commits/16.02
     53[[CollapsibleStart(14.08 - required for Avila / Cambria)]]
     54 * 14.08 - required for Avila / Cambria
     55  - Nightly: ​http://dev.gateworks.com/openwrt/14.08/
     56    * Please view the .manifest file per target to inspect installed packages + their respective versions
     57  - Based on OpenWrt r42297 (2014-08-25)
     58  - General:
     59    * Refreshed Gateworks patches
     60    * Refreshed Gateworks config files
     61    * Updated all feeds to latest versions as of 2014-08-27
     62    * Updated to latest wireless drivers
     63    * 80211ac support (ath10k/iwlabgn)
     64    * DFS Support in ath
     65    * Added HID Support to Ventana and Laguna
     66    * Added Bluetooth support (both btusb and ath3k) to Ventana and Laguna
     67    * Added ibt and ath3k Bluetooth firmwares to Ventana and Laguna
     68  - Ventana:
     69    * Add support for GW54xx/GW53xx/GW52xx/GW51xx/GW552x
     70    * Add gsc-daemon support for above boards
     71    * Add support for GW16081/GW16082/GW16082
     72    * Kernel: 3.14.16
     73    * Added sysupgrade support
     74  - Laguna
     75    * Kernel: 3.10.49
     76  - Avila / Cambria:
     77    * Kernel: to 3.10.49
     78[[CollapsibleEnd]]
     79
     80== Revision Log ==
    15181You can see a revision history using the Github web interface:
    152 </p>
    153 <ul><li><a class="ext-link" href="https://github.com/Gateworks/openwrt/commits/16.02"><span class="icon">​</span>16.02</a>
    154 </li><li><a class="ext-link" href="https://github.com/Gateworks/openwrt/commits/14.08"><span class="icon">​</span>14.08</a>
    155 </li></ul><h2 id="OpenWrtBSPPre-BuiltBinaries"><a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> BSP Pre-Built Binaries</h2>
    156 <p>
     82 * [https://github.com/Gateworks/openwrt/commits/16.02 ​16.02]
     83 * [https://github.com/Gateworks/openwrt/commits/14.08 ​14.08]
     84
     85
     86== OpenWrt BSP Pre-Built Binaries ==
    15787To get an already built image to flash onto the SBC, please visit the following:
    158 </p>
    159 <ul><li><a class="wiki" href="/wiki/ventana/openwrt">Ventana OpenWrt Pre-Built Images</a>
    160 </li><li><a class="wiki" href="/wiki/laguna/openwrt">Laguna OpenWrt Pre-Built Images</a>
    161 </li></ul><h2 id="BuildingPre-requisites">Building Pre-requisites</h2>
    162 <p>
     88 * [wiki:ventana/openwrt Ventana OpenWrt Pre-Built Images]
     89 * [wiki:laguna/openwrt Laguna OpenWrt Pre-Built Images]
     90
     91
     92== Building Pre-requisites ==
    16393Gateworks has tested with LTS Ubuntu Releases. The suggested Ubuntu releases are 14.04 or 16.04. At the time of this writing, Gateworks does not recommend using Ubuntu 16.10.
    164 </p>
    165 <p>
    166 On an Ubuntu (11.10, 14.04, 16.04)  system for example the following should install all necessary pre-requisites:
    167 </p>
    168 <div class="code"><pre>sudo apt-get install subversion build-essential  ;<span class="c"># std dev tools
    169 </span>sudo apt-get install zlib1g-dev libncurses5-dev gawk flex git-core gettext quilt libssl-dev ;<span class="c"># other libs/tools needed by OpenWrt Buildroot
    170 </span></pre></div><ul><li><strong>NOTE</strong> If you are experiencing difficulties, Here is a list of the pre-requisites from the general <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> Site. <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> buildroot prerequisites listed <a class="ext-link" href="http://wiki.openwrt.org/doc/howto/buildroot.exigence"><span class="icon">​</span>here</a>
    171 </li></ul><p>
    172 </p><div> <h3 class="foldable">Ubuntu 14.04 Notes</h3><div><p>
    173 <strong>Note: Ubuntu 14.04</strong> There is a known bug with Ubuntu 14.04 when building Python 2.7. that may occur. Because the system Python is used during this build, you may encounter the following error:
    174 </p>
    175 <div class="code"><pre>ImportError: No module named _sysconfigdata_nd
     94
     95On an Ubuntu (11.10, 14.04, 16.04) system for example the following should install all necessary pre-requisites:
     96{{{#!bash
     97sudo apt-get install subversion build-essential  ;# std dev tools
     98sudo apt-get install zlib1g-dev libncurses5-dev gawk flex git-core gettext quilt libssl-dev ;#  other libs/tools needed by OpenWrt Buildroot
     99}}}
     100 * **NOTE**: If you are experiencing difficulties, Here is a list of the pre-requisites from the general OpenWrt Site. OpenWrt buildroot prerequisites listed ​here
     101
     102
     103Ubuntu 14.04 Notes:
     104 * **Note**: Ubuntu 14.04 There is a known bug with Ubuntu 14.04 when building Python 2.7. that may occur. Because the system Python is used during this build, you may encounter the following error:
     105{{{#!bash
     106ImportError: No module named _sysconfigdata_nd
    176107configure: error: python2.7 interpreter not found
    177 make<span class="o">[</span>3<span class="o">]</span>: *** <span class="o">[</span>~/openwrt-next/build_dir/target-arm_cortex-a9+neon_musl-1.1.11_eabi/Python-2.7.11/.configured_yy
    178 yyyyyyy<span class="o">]</span> Error 1
    179 </pre></div><p>
    180 In order to fix it, please execute the following:
    181 </p>
    182 <div class="code"><pre>sudo ln -s /usr/lib/python2.7/plat-*/_sysconfigdata_nd.py /usr/lib/python2.7/
    183 </pre></div><p>
    184 </div></div>
    185 </p>
    186 <p>
    187 Please ensure your development box has <strong>all of the listed packages installed before proceeding</strong> and note that your development box will need <strong>access to the internet</strong> in order to download the files for the development tree.
    188 </p>
    189 <p>
    190 <strong>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</strong>
    191 </p>
    192 <p>
    193 <strong> Note</strong> The following pre-requisites must be met in order to build <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> firmware for the Gateworks product families:
    194 </p>
    195 <h2 id="DownloadedSourceFiles">Downloaded Source Files</h2>
    196 <p>
    197 <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> uses a Linux build system called <tt>buildroot</tt>. 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). <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> will fetch all sources into the 'dl' directory in the <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> 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 <tt>dl</tt> directory. The Gateworks Makefile which fetches <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> and patches it, will create this link for you if the <tt>/usr/src/dl</tt> 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.
    198 </p>
    199 <h2 id="StepbyStepInstructions">Step by Step Instructions</h2>
    200 <p>
    201 To support <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> for the Gateworks products, we maintain a patchset that is generic to all our standard product families.
    202 </p>
    203 <h3 id="Step1:GettingSourceCode">Step 1: Getting Source Code</h3>
    204 <p>
    205 There are multiple code branches (<a class="wiki" href="/wiki/OpenWrt/building#branches">see above</a> for recommended branch per product), please checkout the one you prefer with the following commands<strong>:
    206 </strong></p>
    207 <ul><li>16-02 branch
    208 <div class="code"><pre>git clone https://github.com/Gateworks/openwrt/ gateworks-openwrt -b 16.02
    209 <span class="nb">cd </span>gateworks-openwrt
    210 </pre></div></li><li>14-08 branch
    211 <div class="code"><pre>git clone https://github.com/Gateworks/openwrt/ gateworks-openwrt -b 14.08
    212 <span class="nb">cd </span>gateworks-openwrt
    213 </pre></div></li></ul><h3 id="Step2:Building">Step 2: Building</h3>
    214 <p>
    215 Our <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> Git repository has a 'gateworks' directory added consisting of a Makefile providing targets that aim to simplify the entire process of:
    216 </p>
    217 <ul><li>using a (per target) Gateworks provided .config file
    218 </li><li>producing JTAG binary images compatible with the Gateworks JTAG dongle
    219 </li></ul><p>
    220 Once the branch has been checked out from the <a class="ext-link" href="https://github.com/Gateworks/openwrt"><span class="icon">​</span>Gateworks GitHub</a> account, you are ready to build. The Gateworks <tt>Makefile</tt> provides the following targets:
    221 </p>
    222 <ul><li>all      : Built <tt>imx6</tt> and <tt>cns3xxx</tt> targets.
    223 </li><li>imx6     : build BSP for the imx6 target (Ventana product family)
    224 </li><li>cns3xxx  : build BSP for the cns3xxx target (Laguna product family)
    225 </li><li>images   : build binary flash images (suitable for JTAG flashing) for supported product families (Ventana / Laguna).
    226 </li><li>dirclean : remove all downloaded and built directories
    227 </li></ul><ul><li>In order to build the <tt>imx6</tt> target for the Ventana product family, the following steps would occur:
    228 <div class="code"><pre><span class="c"># Build the imx6 target, using the configuration from gateworks/configs/imx6/.config.
     108make[3]: *** [~/openwrt-next/build_dir/target-arm_cortex-a9+neon_musl-1.1.11_eabi/Python-2.7.11/.configured_yy
     109yyyyyyy] Error 1
     110}}}
     111 * In order to fix it, please execute the following:
     112{{{#!bash
     113sudo ln -s /usr/lib/python2.7/plat-*/_sysconfigdata_nd.py /usr/lib/python2.7/
     114}}}
     115
     116Please 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.
     117
     118** 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.**
     119
     120
     121== Downloaded Source Files ==
     122OpenWrt 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.
     123
     124
     125== Step by Step Instructions ==
     126To support OpenWrt for the Gateworks products, we maintain a patchset that is generic to all our standard product families.
     127
     1281. Getting Source Code:
     129 * There are multiple code branches (see above for recommended branch per product), please checkout the one you prefer with the following commands:
     130  - 16-02 branch
     131{{{#!bash
     132git clone https://github.com/Gateworks/openwrt/ gateworks-openwrt -b 16.02
     133cd gateworks-openwrt
     134}}}
     135  - 14-08 branch
     136{{{#!bash
     137git clone https://github.com/Gateworks/openwrt/ gateworks-openwrt -b 14.08
     138cd gateworks-openwrt
     139}}}
     140
     1412. Building:
     142 * Our OpenWrt Git repository has a 'gateworks' directory added consisting of a Makefile providing targets that aim to simplify the entire process of:
     143  - using a (per target) Gateworks provided .config file
     144  - producing JTAG binary images compatible with the Gateworks JTAG dongle
     145 * Once the branch has been checked out from the ​Gateworks GitHub account, you are ready to build. The Gateworks Makefile provides the following targets:
     146  - all : Built imx6 and cns3xxx targets.
     147  - imx6 : build BSP for the imx6 target (Ventana product family)
     148  - cns3xxx : build BSP for the cns3xxx target (Laguna product family)
     149  - images : build binary flash images (suitable for JTAG flashing) for supported product families (Ventana / Laguna).
     150  - dirclean : remove all downloaded and built directories
     151  - In order to build the imx6 target for the Ventana product family, the following steps would occur:
     152{{{#!bash
     153# Build the imx6 target, using the configuration from gateworks/configs/imx6/.config.
    229154# This will take a while
    230 </span>make -C gateworks/ imx6
    231 </pre></div></li></ul><ul><li>In order to build the <tt>cns3xxx</tt> target for the Laguna product family, the following steps would occur:
    232 <div class="code"><pre><span class="c"># Build the cns3xxx target, using the configuration from gateworks/configs/cns3xxx/.config.
     155make -C gateworks/ imx6
     156}}}
     157  - In order to build the cns3xxx target for the Laguna product family, the following steps would occur:
     158{{{#!bash
     159# Build the cns3xxx target, using the configuration from gateworks/configs/cns3xxx/.config.
    233160# This will take a while
    234 </span>make -C gateworks/ cns3xxx
    235 </pre></div></li></ul><h4 id="Artifacts">Artifacts</h4>
    236 <p>
    237 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.
    238 </p>
    239 <p>
    240 The resulting kernel/rootfs files will be in the <tt>bin/&lt;target&gt;</tt> directory.
    241 For Example, a 256MB flash Ventana image is located at:
    242 </p>
    243 <pre class="wiki">bin/imx6/gateworks-imx6-ventana-squashfs-nand_normal.ubi
    244 </pre><p>
    245 For information about loading the resulting firmware onto a board see the per-board instructions:
    246 </p>
    247 <ul><li><a class="wiki" href="/wiki/ventana/openwrt">Ventana OpenWrt Specific</a>
    248 </li><li><a class="wiki" href="/wiki/laguna/openwrt">Laguna OpenWrt Specific</a>
    249 </li><li><a class="wiki" href="/wiki/rincon/openwrt">Rincon OpenWrt Specific</a>
    250 </li><li><a class="wiki" href="/wiki/avila/openwrt">Avila OpenWrt Specific</a>
    251 </li><li><a class="wiki" href="/wiki/cambria/openwrt">Cambria OpenWrt Specific</a>
    252 </li></ul><h3 id="Step3:Installing">Step 3: Installing</h3>
    253 <p>
    254 To install the <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> image onto the Gateworks SBC, please follow the instructions:
    255 </p>
    256 <ul><li><a class="wiki" href="/wiki/ventana/openwrt#Step2.InstallingFirmware">Ventana Instructions</a>
    257 <ul><li>Typical methods include flashing a .ubi file over TFTP or creating a JTAG binary and flashing using the USB JTAG dongle
    258 </li></ul></li><li><a class="wiki" href="/wiki/laguna/openwrt#InstallingFirmware">Laguna Instructions</a>
    259 <ul><li>Note - For Laguna boards, please do not flash a squashfs file to the board. A proper JTAG binary must be created with instructions below.
    260 </li><li>Typical methods include creating a JTAG binary file using the below instructions and flashing to the board via the USB JTAG programmer
    261 </li></ul></li></ul><p>
    262  
    263 </p>
    264 <h2 id="BuildingJTAGBinaryFile">Building JTAG Binary File</h2>
    265 <p>
    266 Creating JTAG Binaries to flash with the <a class="wiki" href="/wiki/jtag_instructions">GW16042</a> is easily done with the targets in the makefile within the gateworks directory:
    267 </p>
    268 <div class="code"><pre><span class="c"># Make a 'jtagable' images for Ventana
    269 </span>make -C gateworks/ images/ventana
    270 
    271 <span class="c"># Make a 'jtagable' image for Laguna
    272 </span>make -C gateworks/ images/laguna
    273 
    274 <span class="c"># Make both Ventana and Laguna 'jtagable' images
    275 </span>make -C gateworks/ images
    276 </pre></div><p>
    277 The resulting flash firmware image will be <tt>gateworks/images/</tt>.
    278 </p>
    279 <p>
    280 To flash the file to the board, please see this link:
    281 <a class="wiki" href="/wiki/jtag_instructions#Instructions">JTAG Programming Instructions</a>
    282 </p>
    283 <h2 id="Customizing">Customizing</h2>
    284 <p>
     161make -C gateworks/ cns3xxx
     162}}}
     163  - 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.
     164  - The resulting kernel/rootfs files will be in the {{{bin/<target>}}} directory. For Example, a 256MB flash Ventana image is located at: {{{bin/imx6/gateworks-imx6-ventana-squashfs-nand_normal.ubi}}}
     165  - For information about loading the resulting firmware onto a board see the per-board instructions:
     166   * [wiki:ventana/openwrt Ventana OpenWrt Specific]
     167   * [wiki:laguna/openwrt Laguna OpenWrt Specific]
     168   * [wiki:rincon/openwrt Rincon OpenWrt Specific]
     169   * [wiki:avila/openwrt Avila OpenWrt Specific]
     170   * [wiki:cambria/openwrt Cambria OpenWrt Specific]
     171
     1723. Installing:
     173 * To install the OpenWrt image onto the Gateworks SBC, please follow the instructions:
     174  - [wiki:ventana/openwrt#Step2.InstallingFirmware Ventana Instructions]:
     175   - Typical methods include flashing a .ubi file over TFTP or creating a JTAG binary and flashing using the USB JTAG dongle
     176  - [wiki:laguna/openwrt#InstallingFirmware Laguna Instructions]
     177   - Note - For Laguna boards, please do not flash a squashfs file to the board. A proper JTAG binary must be created with instructions below.
     178   - Typical methods include creating a JTAG binary file using the below instructions and flashing to the board via the USB JTAG programmer
     179
     180
     181== Building JTAG Binary File ==
     182Creating JTAG Binaries to flash with the GW16042 is easily done with the targets in the makefile within the gateworks directory:
     183{{{#!bash
     184# Make a 'jtagable' images for Ventana
     185make -C gateworks/ images/ventana
     186
     187# Make a 'jtagable' image for Laguna
     188make -C gateworks/ images/laguna
     189
     190# Make both Ventana and Laguna 'jtagable' images
     191make -C gateworks/ images
     192}}}
     193
     194The resulting flash firmware image will be {{{gateworks/images/}}}.
     195
     196To flash the file to the board, please see this link: [wiki:jtag_instructions#Instructions JTAG Programming Instructions]
     197
     198
     199== Customizing ==
    285200Once a target has been built using the above instructions, a user may customize their image.
    286 </p>
    287 <p>
    288 <a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> can be customized by running the <tt>make menuconfig</tt> command. In this new window, you can select/deselect packages you want installed. If kernel customization is required, a <tt>make kernel_menuconfig</tt> will open the make menu for the kernel.
    289 </p>
    290 <p>
    291 Once complete, a simple <tt>make -j8 V=s</tt> will re-run the make command to re-create the rootfs.
    292 </p>
    293 <p>
    294 Please read more at this page <a class="wiki" href="/wiki/OpenWrt/Configuration">here</a>.
    295 </p>
    296 <h2 id="UpdatingtoLatestGateworksSource">Updating to Latest Gateworks Source</h2>
    297 <p>
     201
     202OpenWrt 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.
     203
     204Once complete, a simple {{{make -j8 V=s}}} will re-run the make command to re-create the rootfs.
     205
     206Please read more at this page [wiki:OpenWrt/Configuration here].
     207
     208
     209== Updating to Latest Gateworks Source ==
    298210The 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.
    299 </p>
    300 <ul><li>To update to the latest patches on the same branch:
    301 <div class="code"><pre><span class="c"># Make sure you have latest ref's
    302 </span>git remote update
    303 
    304 <span class="c"># This will update the current working branch to the latest upstream,
     211
     212 * To update to the latest patches on the same branch:
     213{{{#!bash
     214# Make sure you have latest ref's
     215git remote update
     216
     217# This will update the current working branch to the latest upstream,
    305218# then attempt to rebase any local patches on top.
    306 </span>git pull --rebase
    307 </pre></div></li><li>To change to a new branch, using 16.02 as an example branch:
    308 <div class="code"><pre><span class="c"># Make sure you have latest ref's
    309 </span>git remote update
    310 
    311 <span class="c"># Checkout upstream branch 16.02 and create local branch named 16.02
    312 </span>git checkout remotes/origin/16.02 -b 16.02
    313 </pre></div></li></ul><p>
    314 After this is complete, please continue to build as normal. For more detail on working with git, please refer to <a class="ext-link" href="http://git-scm.com/"><span class="icon">​</span>this site</a>. For information on <tt>git pull</tt>, please refer to <a class="ext-link" href="http://git-scm.com/docs/git-pull"><span class="icon">​</span>this page</a>. For information about <tt>git rebase</tt>, please refer to <a class="ext-link" href="https://git-scm.com/docs/git-rebase"><span class="icon">​</span>this page</a>.
    315 </p>
    316 <h2 id="TroubleshootingBuildFailures">Troubleshooting Build Failures</h2>
    317 <p>
    318 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 <a class="ext-link" href="http://dev.gateworks.com/sources"><span class="icon">​</span>our development site</a>. 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 our <a class="ext-link" href="http://dev.gateworks.com/sources"><span class="icon">​</span>dev site</a>. Below are other issues that may crop up:
    319 </p>
    320 <ol><li><strong>Finding an Error</strong> - 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.
    321 </li><li><strong>Missing Dependencies</strong> - The build will pull files from mirrors around the web including a Gateworks mirror at <a class="ext-link" href="http://dev.gateworks.com/sources"><span class="icon">​</span>http://dev.gateworks.com/sources</a>. 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 <tt>dl</tt> directory to avoid downloading.
    322 </li><li><strong>Errors</strong> - 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:
    323 <div class="code"><pre>make -j1 <span class="nv">V</span><span class="o">=</span>s
    324 </pre></div></li></ol
    325 }}}
     219git pull --rebase
     220}}}
     221
     222 * To change to a new branch, using 16.02 as an example branch:
     223{{{#!bash
     224# Make sure you have latest ref's
     225git remote update
     226
     227# Checkout upstream branch 16.02 and create local branch named 16.02
     228git checkout remotes/origin/16.02 -b 16.02
     229}}}
     230
     231After 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].
     232
     233
     234== Troubleshooting Build Failures ==
     235One 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:
     236 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.
     237 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.
     238 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:
     239{{{#!bash
     240make -j1 V=s
     241}}}