CONTENTS OF THIS FILE
---------------------
   
 * Introduction
 * Requirements
 * Recommended modules
 * Installation
 * Configuration
 * Troubleshooting
 * Maintainers


INTRODUCTION
------------

  This Model tool is designed to take the user supplied inputs such as Model name, commit ID, path where the image to be build and compilation mode
  and build the corresponding model SBE image of EKB and verify the image if needed using CI build script methods.

  By default Model name MUST be supplied to the tool as an argument, while rest arguments are optional.

  The tool is designed to take hit due to build break. The build work flow is split into three separate workflow.
  Thus checkpoints are maintained to re-start for last known good checkpoint of the build run.

  First part intializing and setting up the sandboxes, Repo and other logs.

  Second part validating the PPE models.

  Third part does the compiling and triggering CI. In case the build break due to ERRORS, a build ACTION file is generated.
  This build Action file is used to continue skipping the first part of intialization and directly starts building it with patches if needed.


  -------------------------------------------------------------------------------------------------------------
  :: Command line USAGE options for building FW SBE image ::

  buildSBEImage.py  -m <model_name> -c < Commit log id> -i <abc,xyz> -p < PPE build path> -b <Auto|Manual|Force>


   +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
   | NOTE: Please use VALID input string since validation in code is a tideous task. |
   |       By default user MUST pass a VALID Model ID.                               |
   +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

  ***** Options Supported  *****
          -m,--model        = Target Model to be used to build the image
          -c,--commit       = Base commit id of the patch to be checkout
          -i,--cherry-pick  = refs id of the patch to be cherry pick
          -p,--path         = Path where user wants the image to be built
          -b,--build        = Default is Auto, user can pass Manual/Force
                              Auto   : CI build and test
                              Manual : Only compiles No Simics run
                              Force  : Rebuild Repo
          -e,--env          = User ENV build exports

  ***** Allowed options example  *****
   [ Only Model as an input ]
   buildSBEImage.py -m n10_e9027_tp026_soa_sc_u285_01


   [ Model and PPE commit id as an input ]
   buildSBEImage.py -m n10_e9027_tp026_soa_sc_u285_01 -c c1980f5a4de0bac8922260ed827fe37a124b2b0a


   [ Model and PPE commit id and cherry pick refs as an input ]
   [ ** Coma ',' separated cherry pick patch refs **]
   buildSBEImage.py -m n10_e9027_tp026_soa_sc_u285_01 -c c1980f5a4de0bac8922260ed827fe37a124b2b0a -i refs/changes/57/21157/3, refs/changes/35/22535/2


   [ Model, PPE commit id and PPE image build path as an input ]
   buildSBEImage.py -m n10_e9027_tp026_soa_sc_u285_01 -c c1980f5a4de0bac8922260ed827fe37a124b2b0a -p <user path>


   [ Choosing to compile ONLY option - By Default it run in Auto mode and trigger CI build and simics run test ]
   buildSBEImage.py -m n10_e9027_tp026_soa_sc_u285_01 -b Manual


   [ Choosing to do fresh Force build ]
   buildSBEImage.py -m n10_e9027_tp026_soa_sc_u285_01 -b Force

   [ Facility to -ONLY- Build PPE with ENV passed and run simcis without EKB models ]
   buildSBEImage.py -m <model> -c b85fe14bd0c86ff223ac15e261ead4877949084c -i refs/changes/57/21157/3,refs/changes/35/22535/2 -e '__FAPI_DELAY_SIM__=1'
  -------------------------------------------------------------------------------------------------------------


  [ Model Tool work flow layout ]
  ------------------------------

  **************************************************************************************************************
  [START][ Main module ]   <Model Name>   < base Commit >   <Patches>            <Build Path>                <Build Mode>
              |                 |                |              |                     |                          |
              |                 |                |              |                     |                          |
        buildSBEImage.py -m  XXXXXXXX  -c   YYYYYYYYYYY   -i refs/xxx,refs/yyy   -p /home/somelocation/   -b    Manual/Auto/Force
              |
              |
        [ Pre-req's & Cleanup stale data ] <- ** -> [ Applies by-pass action if pending from previous build failure run]
              |                                                                                   |
              |                                                                                   |
        [ Create Working Sandbox/Repo for EKB/PPE ]   <---- uses Library utility                  |
              |                                                                                   |
              \                                                                         [ Skips & Jumps ahead ]
               \                                                                                  |
              sbeGitUtility.py   <-- uses sbeConstants.py for constants paths & codes             |
                  |                                                                               |
                  |                                                                               | 
              [ PPE specific Model check, patches cherry pick ]  <-- ppeModel.py                  | 
                  |                                                                               |
                  |                                                                               |
                  |                                                                               /
                  |                                                                              /
              [ Setup hooks to EKB env.bash ]  <-- sbeContinue.py      <------------------------/
                  |
                  |
              [ Loads the ENV and workon EKB ]
                  |
                  \
                  Triggers [ sbeContinue.py ]  <-- Uses Library utility
                       |
                       |
                   [ Loads sbeGitUtility.py ] <-- To validate Models and comits
                       |
                       |
                   [ Model EKB checkout ] 
                           |
                           |
                   [ Stage files for Compilation ]  <-- Copy EKB to PPE
                           |
                           |
                     -------------
                     |           |
                     |           |
                [ Manual ]     [ CI build ]
                    |                |
                    |                |
            [ 'make all' ]       [ loads ./src/test/framework/build-script ]
                    |                |
                    |                |
                    ------------------
                           |
                           |
                     [ Returns the control to sbeContinue.py ]
                           |
                           |
                     [ Returns the control to buildSBEImage.py ]
                           |
                           |
                        [ Tool Exits ]
                           |
                           |
                        [ END ]

  **************************************************************************************************************
                                                               

REQUIREMENTS
------------

  This need python version 2.6 or above to work.
  The user is assumed to have access tokens and Gerrit setup in the configuration for EKB and PPE and Sandbox.


RECOMMENDED MODULES
-------------------

  This uses in background the EKB mirroring tool and compilers from scl devtoolset to switch between the git Repo during compilation.

INSTALLATION
------------

  This has no installable needed by the tool. Checkout the code from production repo for latest updates.


CONFIGURATION
-------------

  Permission access location directory to where the image needs to be build.
  
  Access tokens needed before launching this tool. 
  Example if you type 'tokens', at minimal, it must have these AFS Austin and AWD tokens

  Tokens held by the Cache Manager:

  User's (AFS ID 69515) tokens for afs@rchland.ibm.com [Expires Dec  8 23:32]
  User's (AFS ID 21061) tokens for afs@awd.austin.ibm.com [Expires Dec  8 23:32]
  User's (AFS ID 21060) tokens for afs@austin.ibm.com [Expires Dec  8 23:32]
   --End of list--

  Configuration in SSH must be setup for gerrit access. Example
  By default : "gerrit-server" is needed

  $ cat ~/.ssh/config
  Host hw.gerrit
        Hostname gfw160.aus.stglabs.ibm.com
        Port 29418
        AFSTokenPassing no
  Host gerrit-server
        Hostname gfw160.aus.stglabs.ibm.com
        Port 29418
        AFSTokenPassing no
  Host fsp.gerrit
        Hostname fspbld06.in.ibm.com
        Port 29418
        AFSTokenPassing no
  Host hostboot.gerrit
        Hostname gfw160.aus.stglabs.ibm.com
        Port 29418
        AFSTokenPassing no


  !! NOTE : Host hw.gerrit order has to be first in config in case you are using this tool, since the EKB model env needs its that way. !!
  To confirm ./workon ekb
  echo $GERRIT_SRV
  hw.gerrit
  $


TROUBLESHOOTING
---------------

  It is observed during a CI build which in turns starts the NIMBUS simics sometimes failed to start if simic is ran for the first time.

  It is advised to start the simics manaually once and acccept the WindRiver license prompted on the simics console. Post that re-run the 
  tool and it will allow your simics to be started by the script onwards.

  The error codes are uniquely encoded and displayed when failed. Refer the RC code for identifying the issues.

  At glance these are the RC code setup up and subject to changes and update.

  '''
   Generic RC code
  '''
  SUCCESS_EXIT   = 0
  SHELL_EXIT     = 1
  HELP_EXIT      = 10
  NEW_MODEL_EXIT = 11
  NO_PENDING_MODEL_EXIT = 12
  VALIDATE_EXIT  = 13
  FILES_EXIST    = 14
  DIR_EMPTY      = 15

  BYPASS_EXIT  = 20
  PATCH_IGNORE_EXIT = 21
  PPE_MODEL_NOT_EXIST = 22
  PPE_MODEL_SKIP_EXIT = 23

  EKB_MODEL_NOT_EXIST = 40

  ERROR_SYS_ERROR_EXIT = 100

  ERROR_PREP_GIT_FAILED         = 1000
  ERROR_PREP_TOKEN_SETUP_FAILED = 1001
  ERROR_PREP_GIT_SETUP_FAILED   = 1002

  ERROR_PREP_COM_FAILED     = 2000
  ERROR_PREP_CHANGE_FAILED  = 2001
  ERROR_GIT_CHANGEID_FAILED = 2002

  ERROR_LOAD_ENV = 5000
  ERROR_MODEL_NOT_EXIST = 256  # hacked RC code exit from bash

  # Build failures Manual or CI
  BUILD_CI_FAILED      = 10000
  BUILD_MANUAL_FAILED  = 10001

  Note : The user exception handling are not done as a part of this changes. For future enhancement.

  Important log files : Check under base ~/GIT_REPO_SB/logs/

  -----------------
  buildActionHooks : 
  -----------------
  By default this file will be written for the build script to re-start skipping initialization.
  This file is persistent if there is a failure else it will get cleared.

  ----------------------------------
  buildPPE_out_20151202-123355.log : 
  ----------------------------------
  This is has the date and time run of the build and good for debugging during failure.
  This file is persistent until next run.

  ----------------------
  PATCH_ACTION_TEMPLATE:
  ----------------------
  This files is generated on build or CI failure. Add extra step needed in the build step.
  This is intended to be persistent per model or until cleared manaully.


MAINTAINERS
-----------

Original Tool Designer/Developer:
  * George Keishing (Hostboot) - http://faces.tap.ibm.com/bluepages/profile.html?email=gkeishin@in.ibm.com

Current maintainers:
  * Sachin Gupta ( SBE ) - http://faces.tap.ibm.com/bluepages/profile.html?email=sgupta2m@in.ibm.com
  * Sunil Kumar  ( SBE ) - http://faces.tap.ibm.com/bluepages/profile.html?email=skumar8j@in.ibm.com