Summary:
    DaCS API example code

Target:
    DaCS on CBE-Linux PPE and SPE (HW or simulator)

Description:
    The included application is a new spin on "hello world" that utilizes most
    of the DaCS interfaces on both the PPE and SPE.  The program is neither
    intended to be a performance model for "hello world" nor for DaCS, but
    rather to provide a verbose sample of how to use many of the DaCS APIs.

How to build:
    To build dacs_hello, simply do the following at the command line:

        $ make

    In addition to building the standard DaCS application, there are two other 
    varieties.  The below environment variables enable the other varieties of
    DaCS applications and are exclusive. 

        + DEBUG - The debug flavor adds additional error checking to the DaCS
                  APIs.  This is intended for use during development of a DaCS
                  program.  To build the debug version of dacs_hello do the
                  following:

                  $ DEBUG=1 make

        + TRACE - The trace flavor enables PDT performance and debug hooks for
                  use when debugging and troubleshooting a DaCS application.

                  In order to build the trace version of dacs_hello, certain
                  pre-requisites must be met.  Refer to the Cell SDK
                  Installation Guide for details on how to add these packages.

                  The optional PDT packages must be installed.

                  $ yum install pdt\*

                  The optional DaCS trace packages must be installed.

                  $ yum install dacs-trace\*
                  
                  To build the trace version of dacs_hello do the following:

                  $TRACE=1 make

How to run:
    To run the dacs_hello application follow the below steps.

    If running a TRACE version of dacs_hello, it is necessary to first define
    the location of the PDT config file:

        $ export PDT_CONFIG_FILE=/usr/share/pdt/config/pdt_dacs_config_cell.xml

    If built natively (and running out of build directory):

        $ ./dacs_hello

    Otherwise, both the PPU and SPU executables must be copied to their 
    respective locations.  The dacs_hello application depends on the SPU 
    executable being in an "spu" subdirectory relative to where it is executed.

        $ mkdir -p <remote_location>/spu
        $ cp dacs_hello <remote_location>
        $ cp spu/dacs_hello_spu <remote_location>/spu

Errors:
    Please note that the dacs_hello example will intentionally encounter an
    error as a demonstration of how the DaCS error handling facilities work.
    This is a controlled error as indicated in the output in the application.
    The expected error output will be:

    SPE 0: **** Inducing a DACS_ERR_INVALID_WID failure... ****
    SPE: dacs_wid_reserve: DACS_ERR_INVALID_WID
    PPE: Uh-oh ... we took a DACS_STS_PROC_FAILED (96) error on DE/PID <de/pid>

    Any error other than the above is unexpected.
  
    
