Copyright (c) 2018-2019 ARRIS Enterprises, LLC.
All rights reserved.
##############################################################
OSS components of the Touchstone TG3452 Cable Voice Gateway
FW Version AR.01.02.025
##############################################################
README.txt - This file explains the OSS package contents and how to build.
== CONTENTS==
Overview
Package Info
Open Source Toolchain
Build Environment
System Requirements for the Build Computer
Installation
Build Instructions
End
== Overview ==
The Touchstone TG3452 is a DOCSIS 3.1 home telephony gateway supporting 2x192 MHz OFDM in
the downstream and 2x96MHz OFDMA in the upstream along with 32x8 channel bonding for up to
2.5 Gbps of broadband data. It combines two FXS ports of carrier grade VoIP, a 4-port
gigabit router and a dual band 802.11n and 802.11ac Wave2 wireless accent point
with battery backup into a single integrated device.
This package contains the files used in the AR.01.02.025 firmware version on TG3452 that
are open source and meant for re-distribution to the community.
== Package Info ==
A brief description of the files included in the TG3452_AR.01.02.025.tar.gz package is shown
below:
README.txt : This README file.
buildserversetup.sh : The auto-install script.
packages.sh : An auxiliary shell script, executed by buildserversetup.sh,
to install packages specified in package.list.
package.list : Used to specify which additional software packages to install.
install.config : Used to specify build configuration options.
mirrors.tar.gz : Tarball of open source packages, including toolchain for building
workspace.tar.gz : The build workspace tarball, containing additional open source
software and build scripts.
== Open Source Toolchain ==
The auto-install script will install all software packages required to build in a yocto
environment. The yocto environment will build the toolchain, so you do not build the toolchain
independently of the rest of the packages. That is, the open source packages are dependent
on the toolchain for both Atom and Arm builds.
== Build Environment ==
Yocto/BitBake tools are used to build the platform code in this re-distribution package.
Yocto version 1.6 (Daisy) is the recommended version to use when building this package.
Refer to https://www.yoctoproject.org/docs/1.6/mega-manual/mega-manual.html for documentation
on the Daisy release of Yocto.
The build uses bash. Therefore, the build machine setup instructions and auto-install script
set bash as the defult shell.
The build environment uses Git extensively. As such, a name and email address is required
by git to perform some of the operations, because some of the components fetched are git
repos (compressed in the mirrors folder). The name and email address is not shared with any
entity when setting up the build machine. They are merely saved to the git configuration and
used as such to satisfy Git's requirements for those operations for which it needs that
information. If you already have a Git name and email, you may use those. However, there is
no reason you could not use an alias for both of these.
== System Requirements for the Build Computer ==
Using Yocto/BitBake to build the open source software requires more resources from the
build computer than building the software from the legacy tools. It requires more memory,
more space on the file system, and more time to build the kernel and rootfs images.
These are the reasons for the increased resources:
- The open source elements (kernel, drivers, applications, etc.) are built from scratch,
with a few exceptions, using source code from their respective open source Git
repositories that are available online.
Moreover, for each workspace, the tool chain and other required native binaries are built
before the platform open source packages. The build computer requires more system resources
to build all of these components.
- The Yocto/BitBake system permits the user to configure the parallel tasks needed to run
concurrently during the BitBake build process. These concurrent tasks can reduce the
build time, depending on the number of cores available in the user's build computer,
but it puts a heavier load on the available memory and the file system.
- The Yocto/BitBake build system uses a different toolchain, which are faster or slower,
depending on the details of the components built. The BitBake recipes offer a higher
level of build abstraction, such as retrieving missing components automatically from
the source repositories over the network, but has a higher build overhead. This extra
overhead is usually small, but if the network connection is slow it becomes significant.
In an effort to mitigate excessive network bandwidth consumption, the required Git
repositories are mirrored locally and have been provided in this re-distribution package.
The system requirements to build the open source re-distribution package with the
Yocto/BitBake tools include:
Memory
The build computer typically requires 4 GB of main memory for each instance of a running
BitBake build. 8 GB of main memory is recommended.
File Space
The build computer must have a minimum of 80 GB of file storage space to run a single
instance of the BitBake build with no task parallelism configured in the local.conf file.
Elapsed Time
The time required to complete a build from scratch depends on the HW platform used,
including the number of available cores, free memory, and the available file space.
Elapsed time for a build from scratch can vary from under an hour to more than five
hours. After the initial build is complete, incremental builds occur much faster
because most of the components do not need to be rebuilt.
Network
While a network connection (i.e., Internet) is required to prepare the environment
(i.e., install required software packages) for the build machine, no netowrk connection
is required to build the components for this open source redistribution package. That is,
once your build machine has been fully set up, you may go offline to perform the build.
== Installation ==
The following installation and build instructions have been verified on an Ubuntu
14.04.5 LTS 64-bit host. Make sure you have an Internet connection to create the host
environment setup. For your convenience, a couple of shell scripts are provided, with
an associated package.list file which specifies the additional software packages to
install on the build machine. When configuring a build machine from scratch, these
scripts should simplify the environment installation process by automating the steps
involved. To use the scripts, download/copy them to a folder on the build machine.
Note that you must have sudo access to install the additional software packages.
* OS Installation
-----------------------------------
Download and install Ubuntu 14.04.5 LTS 64-bit OS. We recommend, when you install Ubuntu,
that you select the checkbox to "Download updates while installing." If you are asked if
you would like to upgrade to a newer version of Ubuntu after installation has completed,
select "Don't Upgrade."
* Yocto-related Package Installation
-----------------------------------
-- Unpack the main tarball --
1) Download the TG3452_AR.01.02.025.tar.gz file to a location in user file space (in
which the current user has read-write-execute permissions).
2) Change to the directory where "TG3452_AR.01.02.025.tar.gz" was downloaded.
3) Untar the contents using the command: tar -xzf TG3452_AR.01.02.025.tar.gz
This will create a directory named TG3452_AR.01.02.025.
4) Change to the TG3452_AR.01.02.025 directory. In it you will see the following:
README.txt (this file)
buildserversetup.sh
install.config
mirrors.tar.gz
packages.sh
package.list
workspace.tar.gz
-- Automated Installation and Setup --
Before you proceed, make a note of which partition contains your grub installation, as
grub may be updated (e.g., if you have cloned a VM), requiring you to decide to which
partition the grub update should be installed.
Steps to complete the installation of the Yocto-related packages using
the scripts are as follows:
1) Copy the following four files to a location on your build machine where you have
read-write-execute permission (home folder should be fine):
buildserversetup.sh
packages.sh
package.list
install.config
NOTES:
Alternately, you may simply change to the directory where these files already
reside. They must all exist in the same folder in which the buildserversetup.sh
script is run. You must have Internet access while running the script.
The package.list file contains a list of all the packages (required by
Yocto/BitBake and ARRIS, as well as some recommended packages) to be installed on
the build machine. These packges are automatically installed when the user
invokes the buildserversetup.sh script. The script logs various steps to
buildserversetup.log as it progresses through the installation.
2) If the scripts (with .sh file extension) are not already executable, make them so
using the chmod command.
3) If not already in the script directory, change to that directory.
4) Execute the buildserversetup.sh script with no parameters as follows:
./buildserversetup.sh
NOTES:
The script will abort if there are any errors in your configuration.
This is an interactive script, so you will go through a series of several prompts
asking if you wish to continue. It will also prompt you for your Git name and
email address, which are required. At the interactive prompts, the default
answer is indicated by a capital letter. To select the default answer, you may
simply press "enter." Otherwise, select the desired letter and press "enter."
5) When the script successfully completes, you will see the message "Installation
completed!" It will also call to your attention the paths used for the local
mirrors and the user download cache. Those are the paths you will need in creating
symlinks in new workspaces.
NOTES:
If you see any errors in the installation of software packages, such as packages
being held or kept (reported by pkgProblemResolver::Resolve), you might want to
try to resolve them before proceeding. You may follow the advice offered here:
https://superuser.com/questions/1107334/apt-says-packages-have-been-kept-back-what-to-do,
where you alternately issue the following two commands until there are no remaining
upgradeable packages.
sudo apt list --upgradable
sudo apt-get install -y <package-to-upgrade>
Otherwise, you may need to installed the failed packages manually.
If you do not end up with the minimum version of Git, then you will need to remove Git
with the following command:
sudo apt-get autoremove --purge git
and then perform the following steps to install the latest version:
sudo apt-add-repository ppa:git-core/ppa
sudo apt-get update
sudo apt-get install git
The buildserversetup.sh script may be re-run as desired.
== Workspace Setup ==
1) Copy the mirrors.tar.gz file to your home folder. Then untar the contents of
mirrors.tar.gz using the command: tar -xzf mirrors.tar.gz
You will now see a "mirrors" subfolder in your home folder.
You may now delete the mirrors.tar.gz file from your home folder.
2) From your home folder, create a subfolder named "workspaces" as in the following
example:
mkdir workspaces
3) Copy the workspace.tar.gz file to the "workspaces" subfolder.
4) Change to the "workspaces" folder and untar the workspace.tar.gz file using
the following command:
tar -xzf workspace.tar.gz
A folder named "workspace" will be created, containing all the source and recipes
not in the "mirrors" and "yocto-downloads" locations.
4) Change to your "workspace" folder. Prior to executing the build script, you should
see the following in your "workspace" folder.
arris-source
bld_d31 -> yocto/meta-arris-intel/bld_d31*
intel-source
intel-tools
setup-environment -> yocto/meta-arris-intel/setup-environment*
yocto
== Build Instructions ==
* Before you build the first time in any workspace
-----------------------------------
When the build script is executed, it creates two symbolic links in your workspace
as follows:
localmirrors => /home/$USER/mirrors
downloads => /home/$USER/yocto-downloads
A note about the "downloads" location:
A yocto build, as configured in this delivery, will automatically populate the
"downloads" location with tarballs, repos, and files the first time a build is
conducted. Thereafter, the fetch tasks will take less time for subsequent
builds. If you delete files from this location, those fetch tasks will have to
be repeated. Do NOT delete anything under the "git2" symlink under "downloads,"
as the build scripts require these files.
A word of caution for advanced bitbake users:
If the user were to execute a bitbake -c cleanall for a recipe, the fetched
components for that recipe would be removed from "yocto-downloads." The build
scripts require the existence of everything under "downloads/git2," which is a
symbolic link to a corresponding folder in the actual "yocto-downloads" folder.
The execution of bitbake -c cleanall for a recipe could wipe out some of these
required files, necessitating a re-unpacking of the mirrors tarball.
* Building the open source software/firmware
-----------------------------------
1) In the workspace folder, source the bld_d31 script using the command:
. bld_d31
2) Execute the following command to build all components:
./bld_d31 pc20 mono
This will build Atom and Arm recipes, in that order.
You will see various warnings in the build output. You should ignore these.
You will also see, for the Atom build (which comes first if you are executing a monolithic
build), errors as follows:
fatal: Not a git repository (or any of the parent directories): .git
You may also ignore these "fatal" errors. They are a result of forcing the build to use local
mirrors, as the fetcher is designed to try the network for git repos, and when that fails, try
the mirrors.
3) The results of the build will be in the build-arrisatom and build-arrisarm folders.
The build output will be contained in an "image" subfolder for each recipe.
BUILD OPTIONS
--------------------------------
In producing this buildable open source redistribution package, the environment variable
BB_NO_NETWORK has been set to 1 in both the atom and arm local.conf.sample files. These conf
files may be found in the meta-arris-intel meta layer (under the meta-arris-arm/conf and
meta-arris-atom/conf subfolders, respectively). As documented in the yocto project mega manual
for Daisy v1.6 (https://www.yoctoproject.org/docs/1.6/mega-manual/mega-manual.html),
BB_NO_NETWORK is used to force yocto to fetch packages from local mirrors, rather than going
out to network URLs for the associated packages.
= END =
