%% --------------------------------------------------------------  
%% (C)Copyright 2007,2008,                                         
%% International Business Machines Corporation                     
%% All Rights Reserved.                                            
%%                                                                 
%% Redistribution and use in source and binary forms, with or      
%% without modification, are permitted provided that the           
%% following conditions are met:                                   
%%                                                                 
%% - Redistributions of source code must retain the above copyright
%%   notice, this list of conditions and the following disclaimer. 
%%                                                                 
%% - Redistributions in binary form must reproduce the above       
%%   copyright notice, this list of conditions and the following   
%%   disclaimer in the documentation and/or other materials        
%%   provided with the distribution.                               
%%                                                                 
%% - Neither the name of IBM Corporation nor the names of its      
%%   contributors may be used to endorse or promote products       
%%   derived from this software without specific prior written     
%%   permission.                                                   
%%                                                                 
%% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND          
%% CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,     
%% INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF        
%% MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE        
%% DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR            
%% CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,    
%% SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT    
%% NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;    
%% LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)        
%% HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN       
%% CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR    
%% OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,  
%% EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.              
%% --------------------------------------------------------------  
%% PROLOG END TAG zYx                                              
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:

                  $ make DEBUG=1

        + 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:

                  $ make TRACE=1


    The default builds produce 64-bit PPE code (using the 64-bit compilers and
    linking in the 64-bit DaCS libraries). In order to build a 32-bit
    dacs_hello application, you can build with the following option. This
    option works along with the other types (default, DEBUG and TRACE), and
    requires the 32-bit DaCS libraries be installed.

       + 32BIT - This builds the 32-bit version of the PPE code. To build this
                 version of dacs_hello do one of the following:

                  $ make 32BIT=1

                  $ make 32BIT=1 DEBUG=1
		
                  $ make 32BIT=1 TRACE=1


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.