Getting started with Peppercon's Device SDK
(c) 2005 Peppercon 4/5/2005
=======================================================

I. Content
----------
1. Version
2. Requirements
3. Content of SDK
4. Don't get confused
5. Installing the SDK
6. Boot device from SDK
7. Creating Applications
8. Changing the firmware file

1. Version
----------
This SDK has been created for a particular hardware version of an ERLA-device.
Please check the file VERSION and make sure this SDK suites the hardware you
are trying to use with it.

This SDK supports a network development mode of an erla device using tftp and
nfs and also tools to update the firmware file corresponding to this SDK.

2. Requirements
---------------
This SDK is intended to be used on an x86 Linux workstation having the 
following installed;
  - glibc 2.3
  - development environment and supportive tools, i.e. make, perl etc.
  - tftpserver having its document root at '/tftpboot'
  - nfsserver (for configuration, see below)
  - terminal program, kermit is recommended
  - configured 'sudo', so root-commands can executed without entering password
  - peppercon powerpc (for kim) or arm (for kira) toolchain 
Most of those tools are installed by default on linux development systems.
The peppercon compiler toolchain can be obtained in RPM format from peppercon.

3. Don't get confused
---------------------
When browsing through this SDK you will find many things like certain
names or directory structures that seem not to make sense or that could
be arranged and named more sensibly. The reason is, that this SDK is basically
an extract from our original source tree which is used to build many different
products and versions for different platforms. This means, the general 
structure of the tree and the scripts have not been changed in order to 
stay as close to the original tree as possible. So in case you wonder about 
strange things, just accept them as they are, except they are bugs!

4. Content of SDK
-----------------
The SDK contains the basic Linux system including all useful libraries
and tools. In detail you will find the following in its directories:

  - build_sys:
    build scripts and compiler wrappers used by the SDK

  - cfg_conv, config_rtceep, eric_config, flex, get_config, iptables,
    liberic_pthread, libesmtp, libjpeg, pplinux, pp_shared, ...:
    These directories contain binaries of some form. Read section 3
    and don't get confused.
    
  - include:
    contains headers for all libraries that are not part of libc

  - rtsys: 
    the tared linux root file system and the linux kernel binary

  - mkfirmware
    tools to alter an existing firmware

  - helloworld:
    trivial example for developing an application

  - tools:
    supportive scripts

  - doc:
    Build system examples, other examples

  - OEM:
    OEM dependend files

  - *:
    depending on the kind of SDK it may contain additional folders 
    containing selected source code or libraries. These folders 
    will be included into the build configuration also. Refer to the
    file VERSION to find out which additional sources are included.

5. Installing the SDK
---------------------
The SDK may be untared at any location. If your are using the build environment
the destination must be within its root filesystem.

     Setup SDK and compile helloworld example with
     (note: this requires already the sudo cmd to work and 
     the tftpboot directory to be set up (see 2.)):

     $ build_fw build

     this command creates:
     - root-fs in 'install_root_devel'
     - kernel  at '/tftpboot/zImage.lara.kim.<username>'

6. Boot device from SDK
-----------------------
Once 5. has been successfully performed you can start running the SDK
on your device, i.e. boot the installed kernel via tftpboot and mount the 
root filesystem via nfs. This requires the following preparations:

  1. make sure the flashed firmware version (the firmware that runs 
     from the flash of the device) in your device matches exactly 
     the firmware version this SDK was build for. This can be 
     accomplished by comparing the build numbers of SDK and firmware:

     - the build number of the SDK can be found in the VERSION file

     - the build number of the flashed firmware can be found on the web
       dialog 'Maintenance -> Device Information'.

     Both the build numbers must be _identical_.

     If the build numbers do not match, please update the device
     with the firmware that comes along with this SDK. This can be
     accomplished using  the 'Maintenance -> Update Firmware' 
     dialog in the web-frontend

     In case you are using your device already for nfs-development
     you may switch the device back to boot from flash (see point 6.),
     which is the savest way to run a firmware update or you may also 
     use the 'Maintenance -> Update Firmware' dialog of the nfs-booted
     firmware. After the firmware update the device will boot from flash
     unconditionally.
  
  2. Configure tftpserver to export /tftpboot/

  3. Configure nfs-server, so that it exports the root-fs with root
     permissions.

     Here is an example for a typical configuration of '/etc/exports':

     /home/thomas/sdk-lara-kim-1/install_root_devel *(rw,no_root_squash)

  4. Configure device for tftp/nfs boot
     - Connect Serial-1 of device with your terminal programm, 
       for instance kermit, using a NULL-modem-cable

     - Power-up device and press <ESC> in the terminal within a second.
       This will cause the boot-loader to stop from booting and to respond
       with a prompt '=>'.

     - Detach the terminal program and execute the terminal script
       provided in 'tools/lara_kim_tftp_env.km'. Call the script with 
       the following parameters, for instance:

       $ lara-kim-tftp-env.km 192.168.101.66 255.255.255.0 192.168.101.1 192.168.101.72 \
           /home/thomas/sdk-lara-kim-1/install_root_devel zImage.lara.kim.thomas

       whereas:
       - 192.168.101.66 :ip-address for device
       - 255.255.255.0  :netmask for device   
       - 192.168.101.1  :gateway address for device
       - 192.168.101.72 :ip-address of nfs-server
       - /home/thomas/sdk-lara-kim-1/install_root_devel: path to root-fs on nfs-server
       - zImage.lara.kim.thomas: name of kernel image with tftpboot-root

       Alternatively you may execute the required commands manually in the 
       same order as laid out in 'tools/lara_kim_tftp_env.km'

       This will setup the boot-loader for tftpboot and 
       the kernel for nfs-mounting the root-fs.

       ATTENTION: when running the script 'tools/lara_kim_tftp_env.km'
       for multiple devices in the same subnet, please make sure you 
       change the MAC-address that is given to the device. The MAC-address
       is set by the line 'setenv ethaddr <mac-addr>'. Enter a unique number 
       for <mac-addr>. Duplicate MAC-addresses will result in very obscure 
       networking problems and prevent booting via nfs.

     - Reconnect the terminal program in interactive mode and type 'reset'.
       The device will reset and boot the device as intended!

  5. Once the system has booted up, it will present a 'login:' where
     you're supposed to login using 'root' and no password.

     Type

     $ helloworld

     to check whether the already compiled example is working.

  6. In order to switch back from tftp/nfs-boot to flash boot
     you can run the script
  
     $ lara-kim-norm-env.km

     Alternatively you can flash the firmware binary that comes 
     along with the SDK using the 'Maintenance -> Update Firmware'
     dialog in the web-frontend. Flashing a firmware will always
     reset the boot-code options to their default values

7. Creating Applications
------------------------
The directory 'helloworld' provides an example for how to create an
application. It is recommended to use the build system coming along with 
the SDK.

Multiple projects might be built at once by adding them to the
'build_fw.cfg' configuration file. The 'build_fw' script will loop
over all named directories calling 'Build' in each one.

When calling 'build_fw' without parameters it will show a number of 
possible command-line-switches. Please ignore these switches since they 
do not apply in the SDK context. The three useful operations in the 
SDK context are 
  - build
  - clean
  - cleanbuild

8. Changing a Firmware file
---------------------------
Once an application has been developed it needs to be included into
an existing firmware. The corresponding firmware file will be 
shipped with the SDK. In contrast to earlier versions of the SDK,
the final firmware will be built automatically. The tools provided
to manipulate the firmware have changed. Although it is still 
possible to update a firmware manually, we recommend to use to
new automatic version to prevent errors.

Follow these steps to update the existing firmware file with the
compiled content of this SDK:

  1. Edit the file 'build_fw_target.cfg' and change the line
     'build_type = devel' to 'build_type = final'. This will
     update the firmware file instead of changing the nfs
     filesystem.
     
  2. cleanbuild the complete sdk: './build_fw cleanbuild'.
     The buildsystem will build the SDK as known. After building
     the last module, it will 'finalize' your firmware and copy
     the created binaries into the existing firmware.
     
  3. If firmware finalization succeeds, you will find an image
     with the updated firmware in the folder 'mkfirmware'. The
     firmware image will have the same name as the original
     firmware.
  
  4. Flash the firmware with the standard web dialog of eric.
     You can either use the development (nfs) firmware or the
     built-in firmware to do that. 

Common errors:
- The finalizing step fails and claims that 'inird.bin' exceeds the
  maximum filesize of 3145728 bytes. Please delete 'install_root_final'
  and repeat all steps. Check the output of the finalization step
  carefully for any errormessages.
  If the 'maximum filesize' error persists, please consult peppercon
  for help. Some firmwares have only very little space left and need
  additional actions to fit the limit.

