community-oriented enforcers have vetted uncounted thousands of ``Complete,

Corresponding Source'' CCS candidates from hundreds of companies, the CCS

release describes the first one CCS experts have declared a ``pristine

example''.

% FIXME (above): link to a further discussion of CCS in the compliance guide

% when a good spot exists, then (below) link to a ``CCS iteration''

% discussion in compliance-guide.tex when one exists.  (the ``iteration

% process'' is discussed in~\ref{} of this guide)

Of course, most CCS examined for the last decade has (eventually) complied

with the GPL, perhaps after many iterations of review by the enforcer.

However, in the experience of the two primary community-oriented enforcers,

Conservancy and the FSF, such CCS results routinely fix the description of

``barely complies with GPL's requirements''.  To use an academic analogy:

while a ``C'' is certainly a passing grade, any instructor prefers to

disseminate to the class an exemplar sample that earned an ``A''.

Fortunately, thanks in large part to the FSF's

``Respects Your Freedom'' (RYF) certification campaign\footnote{\href{http://www.fsf.org/resources/hw/endorsement/respects-your-freedom}{RYF is

    a campaign by FSF to certify products that truly meet the principles of

    software freedom}.  Products must meet

  \href{http://www.fsf.org/resources/hw/endorsement/criteria}{strict

    standards for RYF certification}, and among them is a pristine example of

held to a higher standard of copyleft compliance.  As such, for the first

time in the history of copyleft, CCS experts have pristine examples to study

and present as exemplars worthy of emulation.

This case study therefore examines the entire life-cycle of a GPL compliance

investigation: from product purchase, to source request, to CCS review.

Specifically, this chapter discusses the purchase, CCS provision, and a

step-by-step build and installation analysis of a specific, physical,

embedded electronics product.  The product in question is

\href{https://www.thinkpenguin.com/gnu-linux/free-software-wireless-n-broadband-router-gnu-linux-tpe-nwifirouter}{the

  ``TPE-NWIFIROUTER'' wireless router by ThinkPenguin}.\footnote{The FSF of

  course performed a thorough CCS check as part of the certification process.

  The analysis discussed herein was independently performed by Software

  Freedom Conservancy without reviewing any findings of the FSF, and thus the

  analysis provides a ``true to form'' analysis as it occurs when Conservancy

  investigates a potential GPL violation.  In this case, obviously, no

  violation was uncovered.}

\section{Consumer Purchase and Unboxing}

The process for copyleft compliance investigation, when properly conducted,

determines whether users inclined to exercise their rights under a copyleft

license will be successful in their attempt.  Therefore, at every stage, the

investigator seeks to take actions that reasonably technically knowledgeable

This instruction actually goes above and beyond the requirements of GPL\@.

Specifically, the instruction guides users in their first step toward

exercising the freedom to modify the software.  While the GPL does contain

requirements that facilitate the freedom to modify (such as ensuring the CCS is

in the ``preferred form \ldots for making modifications to it'' form), it

does not require that you write specific instructions explaining how

modifications might be undertaken.  This instruction therefore exemplifies

the exceptional quality of this particular CCS\@.

%FIXME: add a \hyperref to some ``preferred for for modification'' stuff above.

However, for purposes of the CCS verification process, typically the

investigator avoids any unnecessary changes to the source code during the

build process, lest the investigator err and cause the build to fail through

his own modification, and thus incorrectly identify the CCS as inadequate.

Therefore, the investigator proceeded to simply run:

\lstset{tabsize=2}

\begin{lstlisting}[language=bash]

  $ cd libCMC

  $ make

\end{lstlisting}

and waited approximately 40 minutes for the build to complete\footnote{Build

kept a

\href{https://gitorious.org/copyleft-org/tutorial/source/master:enforcement-case-studies_log-output/thinkpenguin_librecmc-complete.log}{full

  log of the build}, which is not included herein due its size (approximately

7.2K of text).

\label{thinkpenguin-main-build}

Upon completion of the ``make'' process, the investigator immediately found

(almost to his surprise) several large firmware files in the ``bin/ar71xx''

directory.  Typically, this step in the CCS verification process is

harrowing.  In most cases, the ``make'' step will fail due to a missing

package or because toolchain paths are not setup correctly.

From experience, the investigator is sure that ThinkPenguin's engineers did

the most important step in self-CCS verification: use one's own instructions

on a clean system.  Ideally, an employee with similar skills but

unfamiliar with the specific product can most easily verify CCS  and identify

problems before a violation occurs.

% FIXME: Is there stuff about the above in the compliance guide?  If so, link

% to it.  If not, write it, then link to it. :)

However, upon completing the ``make'', the investigator was unclear which

filesystem and kernel images to install on the TPE-NWIFIROUTER hardware.

Ideally, the original ``README'' would indicate which image is appropriate

for the included hardware.  However, this was ultimately an annoyance rather

than a compliance issue due to other information available.  Specifically,

the web UI (see next section) on the TPE-NWIFIROUTER performs firmware image

installation.  Additionally, the router's version number was specified on the

bottom of the device, which indicated which of the differently-versioned images

we should install.  It would be ideal to find

\href{http://librecmc.org/librecmc/wiki?name=Tp+MR3020}{instructions similar

  to these} in the README itself.  However, application of the reasonableness

standard indicates compliance, since a knowledgeable user was able to

determine the proper course of action.

\section{U-Boot Compilation}

%FIXME: link to u-boot reflash, maybe put it in log-output dir?

The investigator then turned his attention to the file,

``u-boot\verb0_0reflash'' instructions.  These instructions explained how to

build and install the bootloader for the device.

them quite straight-forward.  The investigator discovered two minor

annoyances, however, while building U-Boot:

\begin{itemize}

   of the extracted source directory.  This was easy to surmise and was not a

   compliance issue (per the reasonableness standard), but explicitly stating

   that at the top of the instructions would be helpful.

\label{thinkpenguin-glibc-214-issue}

\item Toolchain binaries were included and used by default by the build

  process.  These binaries were not the appropriate ones for the

  investigator's host system, and the build failed with the following error:

\lstset{tabsize=2}

\begin{lstlisting}

mips-librecmc-linux-uclibc-gcc.bin: /lib/libc.so.6:

   version `GLIBC`_2.14' not found

     (required by mips-librecmc-linux-uclibc-gcc.bin)

\end{lstlisting}

   (The

\href{https://gitorious.org/copyleft-org/tutorial/source/master:enforcement-case-studies_log-output/thinkpenguin_u-boot-build_fail.log}{complete

  log output from the failure} is too lengthy to include herein.)

   This issue is an annoyance, not a compliance problem.  It was clear from

   context that these binaries were simply for a different architecture, and

   utilize the toolchain already built earlier (during the compilation

   discussed in \S~\ref{thinkpenguin-main-build}):

\lstset{tabsize=2}

\begin{lstlisting}

  $ ln -s \

  ../../staging_dir/toolchain-mips_34kc_gcc-4.6-linaro_uClibc-0.9.33.2/bin \

  toolchain/bin

\end{lstlisting}

   After this change, the U-Boot build completed successfully.

\end{itemize}

The

\href{https://gitorious.org/copyleft-org/tutorial/source/master:enforcement-case-studies_log-output/thinkpenguin_u-boot-finish_build.log}{full

  log of the build} is not included herein due its size (approximately 3.8K

of text).  After that, the investigator found a new U-Boot image in the

``bin'' directory.

\section{Root Filesystem and Kernel Installation}

The investigator next tested installation of the firmware.  In particular,

the investigator connected the TPE-NWIFIROUTER to a local network, and

%%   receive the startup messages.  We could replicate the same behavior by

%%   omitting the power cable from the USB serial adapter (red wire) and connecting

%%   the main power adapter to the router instead.

%% * While we did see the U-Boot and kernel boot logs in our serial console, we

%%   were unable to interrupt the boot process as u-boot\verb0_0reflash indicated we

%%   should.  We suspect this is a misconfiguration of our serial console, but it's

%%   unclear exactly how it is misconfigured, as we were able to receive data fine

%%   (we just couldn't send data to the router).

%% * As a result, we were unable to complete the U-Boot installation test.  We did

%%   appreciate that installation instructions were included, though these

%%   instructions should be updated to include more specifics about connecting the

%%   serial cable.  Since ThinkPenguin does have the option to ship a serial

%%   adapter with the router, it would be helpful if instructions specific to that

%%   adapter were included, as the wiring configuration one should use was unclear.

%% * Additionally, instructions for removing the router's case should be included.

%%   We found that the two screws that needed removal to open the case were hidden

%%   underneath rubber feet on the case.  Indicating which feet need removal to

%%   unscrew the case would be helpful.  The instructions should also note that the

%%   case needs to be carefully separated once the screws are removed; it

%%   effectively snaps apart, but care must be taken to avoid breaking the plastic

%%   fasteners that keep the case together after the screws are removed.

\section{Firmware Comparison}

installed on the TPE-NWIFIROUTER, the investigator compared the built

firmware image with the filesystem originally found on the device itself.

\begin{enumerate}

\item Extract the filesystem from the image we built by running

  \href{https://gitorious.org/copyleft-org/gpl-compliance-scripts/source/master:find-firmware.pl}{find-firmware.pl}

  on ``bin/ar71xx/librecmc-ar71xx-generic-tl-wr841n-v8-squashfs-factory.bin''

  \href{http://www.binaryanalysis.org/en/content/show/download}{bat-extratools}'

  comparison.

\item Login to the router's web interface (at \url{http://192.168.10.1/ }) from a computer that is

  connected to the router.

\item Set a password using the provided link at the top (since the router's

  UI warns that no password is set and asks the user to change it).

\item Login to the router via SSH, using the root user with the

  aforementioned password.

\item Compare representative directory listings and binaries to ensure the set of

  included files (on the router) is similar to those found in the firmware image

  we created (whose contents are now in the local squashfs-root directory).  In

  particular, we did the following comparisons:

  \begin{enumerate}

  \item List the /bin folder (``ls -l /bin'') and confirm the list of files is the same

    and that the file sizes are similar.

   places (similar number of lines and content of lines).  (One cannot directly

   compare the binaries because the slight compilation variations will cause

   some bits to be different.)

 \item Do the above two steps for ``/lib/modules'', ``/usr/bin'', and other directories with

   a significant number of binaries.

 \item Check that the kernel is sufficiently similar.  The investigator

   compared the "dmesg" output both before and after flashing the new

   firmware.  As the investigator expected, the kernel version string was

   similar, but had a different build date and user@host indicator.  (The

   kernel binary itself is not easily accessible from an SSH login, but was

   retrievable using the U-Boot console (the start address of the kernel in

  \end{enumerate}

\end{enumerate}

\section{Minor Annoyances}

As discussed in detail above, there were a few minor annoyances, none of

which were GPL violations.  Rather, the annoyances briefly impeded the

build and installation.  However, the investigator, as a reasonably skilled

build engineer for embedded devices, was able to complete the process with

the instructions provided.

To summarize, no GPL compliance issues were found, and the CCS release was

one of the best ever reviewed by an investigator.  However, the following

annoyances were discovered:

\begin{itemize}

\item Failure to explain how to extract the source tarball and then where to run the

  ``make'' command.

\item Failure to explain how to install the kernel and root filesystem on the

  device; the user must assume the web UI must be used.

\item Including pre-built toolchain binaries that don't work on all systems,

\end{itemize}

\section{Lessons Learned}

Companies that seek to redistribute copylefted software can benefit greatly

from ThinkPenguin's example.  Here are just a few of the many lessons that

can be learned here:

\begin{enumerate}

\item Even though copyleft licenses have them,

  \hyperref[thinkpenguin-included-ccs]{\bf avoid the offer-for-source

    provisions.}  Not only does including the CCS alongside binary

  distribution make violation investigation and compliance confirmation

  substantially easier, but more importantly it also

  \hyperref[offer-for-source]{completes the distributor's CCS compliance

    obligations at the time of distribution} (provided, of course, that the

\item {\bf Include top-level build instructions in a natural language (such

  as English) in a \hyperref[thinkpenguin-toplevel-readme]{clear and

    conspicuous place}.}  Copyleft licenses require that someone reasonably

  skilled in the art can reproduce your work.  Ultimately, sometimes

  instructions written in English are necessary, and often easier than trying

  to write programmed scripts to do everything.  The ``script'' included can

  certainly be more like the script of a play and less like a Bash script.

\item {\bf Write build/install instructions to the appropriate level of

  specificity}.  The upstream engineers

  in this case study \hyperref[thinkpenguin-specific-host-system]{clearly did

    additional work to ensure functionality on a wide variety of host build

    systems}; this is quite rare.  When in doubt, include the maximum level

  of detail build engineers can provide with the CCS instructions.

\item {\bf Seek to adhere to the spirit of copyleft, not just the letter of

  the license}.  ThinkPenguin uses encouragement of  users to improve and

  users who seek hackable devices continues to grow.  By going beyond the

  mere minimal requirements of GPL, companies can immediately reap the

  benefits in that target market.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Bortez: Modified GCC SDK}

In our first case study, we will consider Bortez, a company that

produces software and hardware toolkits to assist OEM vendors, makers

of consumer electronic devices.

\section{Facts}

One of Bortez's key products is a Software Development Kit (``SDK'')

designed to assist developers building software for a specific class of

consumer electronics devices.

FSF received a report that the SDK may be based on the GNU Compiler

Collection (which is an FSF-copyrighted collection of tools for software

development in C, C++ and other popular languages). FSF investigated the

claim, but was unable to confirm the violation. The violation reporter

was unresponsive to follow-up requests for more information.