/***************************************************************************
 *                                                                         *
 *                   SiRF Technology, Inc. GPS Software                    *
 *                                                                         *
 *    Copyright (c) 1996-2015 by SiRF Technology, Inc. a CSR plc Company   *
 *                          All rights reserved.                           *
 *                                                                         *
 *    This Software is protected by United States copyright laws and       *
 *    international treaties.  You may not reverse engineer, decompile     *
 *    or disassemble this Software.                                        *
 *                                                                         *
 *    WARNING:                                                             *
 *    This Software contains SiRF Technology Inc.s confidential and        *
 *    proprietary information. UNAUTHORIZED COPYING, USE, DISTRIBUTION,    *
 *    PUBLICATION, TRANSFER, SALE, RENTAL OR DISCLOSURE IS PROHIBITED      *
 *    AND MAY RESULT IN SERIOUS LEGAL CONSEQUENCES.  Do not copy this      *
 *    Software without SiRF Technology, Inc.s  express written             *
 *    permission.   Use of any portion of the contents of this Software    *
 *    is subject to and restricted by your signed written agreement with   *
 *    SiRF Technology, Inc.                                                *
 *                                                                         *
 ***************************************************************************/

All information on Aardvark is the property of Total Phase, Inc. 
("Total Phase").

SIRFFlashEngineEP SPI interface for LINUX PC Host
=================================================
SiRFflashEngineEP Software Package Kit is an easy to port package for programming
flash memories on SiRFStarV B01 and B02 targets based on CSR SiRF Technology.
This document describes the steps required to build and run
SIRFFlashEngineEP using Aardvark SPI based connection in LINUX PC Host.


TARGET AND LINUX PC HOST
========================
The instructions described below were tested with a PC running
Ubuntu 10.10 (32-bit) to program SiRFStarV B01 and B02 EVK using Totalphase 
Aardvark SPI host adapter.


Aardvark SUPPORT ON LINUX
=========================
Please see Aardvark support website for compatibility support for Linux
http://www.totalphase.com/support/kb/10054/


The Total Phase shared libraries (aardvark.so, beagle.so, and cheetah.so) dynamically link against the system libusb library at runtime. These libraries are designed to work with libusb-0.1.12. A newer version of libusb has been created (v1.0) which is not compatible with v0.1. To have backwards compatibility between the two API versions, a compatibility layer called libusb-compat-0.1 is available. However, customers have had issues with this compatibility library which can prevent Total Phase products from operating properly.
Customers have also had driver loading issues on 64-bit distributions when the libusb-0.1 library is in /lib32 instead of /lib.

Solution for compatibility issues
=================================
Uninstall libusb-compat-0.1 and install the 32-bit version of libusb-0.1.12. 
It is acceptable to have both libusb-1.0 and libusb-0.1 installed side-by-side.

The Total Phase libraries use an environment variable to allow the user to specify which libusb library they want loaded when using our tools. Use this environment variable to point to the libusb-0.1 library. For example, assuming libusb-0.1 has been installed in /libusb, setting LIBUSBTP as follows will instruct the Total Phase shared library to use this version of libusb instead of the system's libusb-1.0:
% export LIBUSBTP=/libusb/libusb-0.1.so.4
Solution for libusb location issues
By default, some Total Phase applications look in /lib to find the 32-bit version of libusb-0.1, but some Linux distributions put this library in /lib32. Use the LIBUSBTP environment variable to point to the 32-bit libusb library.
% export LIBUSBTP=/lib32/libusb.so 

NOTE: 
In our Ubuntu 10.10 (32-bit) PC host, it is 
% export LIBUSBTP=/lib/libusb-0.1.so.4
In another Ubuntu 12.04 LTS (32-bit) PC host, it is 
% export LIBUSBTP=/lib/i386-linux-gnu/libusb-0.1.so.4


PREREQUISITES
=============
It is assumed that users have good knowledge of C programming language,
gcc compiler and PC-based Linux.



BUILDING PROCESS
================
The SiRFFlashEngineEP software consists of two main components:
(a) SiRFFlashEngineEP library which supports a range of flash chips.
    (Please contact CSR support for current list flash chips supported).
(b) prgflash_spi main program which demonstrates the use of SiRFFlashEngineEP library
    for flash programming.

So the building process is separated into 2 stages.


Building the Library SiRFflashEngineEP_spi.a
============================================
1. Verify the files burner_spi.c and starter_spi.c are located at directory
   SiRFflashEngineEP/sw/host/library/src/
   If they are missing, then copy the two files from the directory
   SiRFflashEngineEP/sw/host/library/builds/linux_gcc/SiRFflashEngineEP/target_images/
2. To build the library, change directory to
   SiRFflashEngineEP/sw/host/library/builds/linux_gcc/SiRFflashEngineEP/spi/
3. Type "make clean<ENTER>" for a new clean build.
4. Then type "make<ENTER>" to build library SiRFflashEngineEP_spi.a.


Building the program prgflash_spi
=================================
1. Change directory to
   SiRFflashEngineEP/sw/host/prgflash/spi_via_aardvark_spi/linux_gcc/build/prgflash/Release/
2. Type "make clean<ENTER>" for a new clean build.
3. Then type "make<ENTER>" to build the executable programmer application prgflash_spi.




RUNNING THE PROGRAMMER prgflash_spi
===================================
1. In this demonstration, we are using Aardvark SPI host adapter (USB device)
   to interface with CSR SiRFStarV EVK target via SPI serial line.
2. To use Aardvark SPI host adapter as USB device, run with SUPERUSER permission (sudo). 
   (One of the workaround for running with user level permission is described in 
   Total Phase Aardvark user manual "UDEV" section.)
3. Point to the location of libusb-0.1.so.4. 
   In our UBUNTU 10.10 (32-bit) PC set-up, it is
   $ export LIBUSBTP=/lib/libusb-0.1.so.4   
4. Change directory to
   SiRFflashEngineEP/sw/host/prgflash/spi_via_aardvark_spi/linux_gcc/build/prgflash/Release/
5. Connect the Aardvark SPI cable to the SiRFStarV EVK target, change the EVK interface switch to
   SPI position and power-up the EVK. It is recommended that the Mode switch (if available)
   is set to FLASH position (instead of RUN). For some EVK, this switch is not available. 
   In this case the [-x] option must be used.
   Reset the EVK and toggle its POWER button.
6. Run the prgflash_spi executable application that was previously built to program
   the SiRFStarV EVK. The syntax is
   ./prgflash_spi <BINARY IMAGE FILE> <BIT-RATE> [-e] [-x]
   The [-e] is the option setting for erasing the whole flash before programming.
   Without the -e option, only the necessary sectors are erased before programming.
   The [-x] is the option setting to switch from Live to BOOT mode prior to programming.
   Without the -x option, the target is assumed to be in BOOT mode (this is the preferred method).
