Implement fapiGetSpyImage and fapiPutSpyImage functions

Change-Id: Ib09d018ab2f4f2a953e0496512e5d8307d27e43c
RTC:61362
Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/3438
Tested-by: Jenkins Server
Reviewed-by: Daniel M. Crowell <dcrowell@us.ibm.com>
Reviewed-by: Brian H. Horton <brianh@linux.ibm.com>
Reviewed-by: A. Patrick Williams III <iawillia@us.ibm.com>

2 files changed, 185 insertions, 29 deletions

diff --git a/src/include/usr/hwpf/fapi/fapiHwAccess.H b/src/include/usr/hwpf/fapi/fapiHwAccess.H
index f0a26a2b3..c4613b3ec 100644
--- a/src/include/usr/hwpf/fapi/fapiHwAccess.H
+++ b/src/include/usr/hwpf/fapi/fapiHwAccess.H
@@ -5,7 +5,7 @@
 /*                                                                        */
 /* IBM CONFIDENTIAL                                                       */
 /*                                                                        */
-/* COPYRIGHT International Business Machines Corp. 2011,2012              */
+/* COPYRIGHT International Business Machines Corp. 2011,2013              */
 /*                                                                        */
 /* p1                                                                     */
 /*                                                                        */
@@ -43,11 +43,16 @@
  *                          mjjones     07/12/2012  Add mode options to Ring funcs
  *                          rjknight    09/20/2012  Update fapiSpy interfaces to
  *                                                  allow string inputs for cronus
+ *                          jknight     04/02/2013  Add fapi get/setSpyImage
  */
 
 #ifndef FAPIHWACCESS_H_
 #define FAPIHWACCESS_H_
 
+#ifdef FAPI_SUPPORT_SPY_AS_ENUM
+#include <fapiSpyIds.H>
+#endif
+
 #include <stdint.h>
 #include <ecmdDataBufferBase.H>
 #include <fapiReturnCode.H>
@@ -222,11 +227,11 @@ fapi::ReturnCode fapiModifyRing(const fapi::Target& i_target,
  * @note:  The string version is only supported for cronus.
  *
  *         The fapi design to support both FSP and cronus use of get and
- *         put spy funcions is dependant on the SPY names being expanded
+ *         put spy functions is dependant on the SPY names being expanded
  *         to resemble a valid C identifier. This design places some
  *         restrictions on the SPY names which can be used.
  *
- *         1. if the spy name contains a # procedure writers should replade it
+ *         1. if the spy name contains a # procedure writers should replace it
  *         with an __P__ for example -
  *
  *         ABUS.RX0.RXPACKS#0.RXPACK.RD.LC.LC.ACT_DIS
@@ -234,7 +239,7 @@ fapi::ReturnCode fapiModifyRing(const fapi::Target& i_target,
  *         ABUS.RX0.RXPACKS__P__0.RXPACK.RD.LC.LC.ACT_DIS
  *
  *         2. if the spy name has a number following a "." it must have an
- *         uinderscore prepended to the number.
+ *         underscore prepended to the number.
  *
  *         EH.TPCHIP.2KX100_ARY_CLK_EDGES_DLY
  *         becomes
@@ -281,11 +286,11 @@ fapi::ReturnCode _fapiGetSpy(const fapi::Target& i_target,
  * @note:  The string version is only supported for cronus.
  *
  *         The fapi design to support both FSP and cronus use of get and
- *         put spy funcions is dependant on the SPY names being expanded
+ *         put spy functions is dependent on the SPY names being expanded
  *         to resemble a valid C identifier. This design places some
  *         restrictions on the SPY names which can be used.
  *
- *         1. if the spy name contains a # procedure writers should replade it
+ *         1. if the spy name contains a # procedure writers should replace it
  *         with an __P__ for example -
  *
  *         ABUS.RX0.RXPACKS#0.RXPACK.RD.LC.LC.ACT_DIS
@@ -293,7 +298,7 @@ fapi::ReturnCode _fapiGetSpy(const fapi::Target& i_target,
  *         ABUS.RX0.RXPACKS__P__0.RXPACK.RD.LC.LC.ACT_DIS
  *
  *         2. if the spy name has a number following a "." it must have an
- *         uinderscore prepended to the number.
+ *         underscore prepended to the number.
  *
  *         EH.TPCHIP.2KX100_ARY_CLK_EDGES_DLY
  *         becomes
@@ -322,8 +327,89 @@ fapi::ReturnCode _fapiPutSpy(const fapi::Target& i_target,
 fapi::ReturnCode _fapiPutSpy(const fapi::Target& i_target,
                             const char* const i_spyId,
                             ecmdDataBufferBase & i_data);
+
+#endif
+
+#ifdef FAPI_SUPPORT_SPY_AS_ENUM
+/**
+ * @brief Writes data into a ring image
+ * @param[in]   i_target      Target to operate on
+ * @param[in]   i_spyId       The spy's id
+ * @param[in]   i_data        ecmdDataBufferBase object that holds data to
+ *                            be written
+ * @param[out]  o_imageData   ecmdDataBufferBase object that holds data to
+ *                            write into
+ * @return ReturnCode. Zero on success, else platform specified error
+ *
+ * @note:  The string version is only supported for cronus.
+ *
+ *         The fapi design to support both FSP and cronus use of get and
+ *         put spy functions is dependent on the SPY names being expanded
+ *         to resemble a valid C identifier. This design places some
+ *         restrictions on the SPY names which can be used.
+ *
+ *         See fapiPutSpy for details on spy id specifics.
+ */
+#define fapiPutSpyImage(TARGET, ID, DATA1, DATA2) _fapiPutSpyImage(TARGET, \
+                                                    FAPI_SPY_NAMES::ID.value, \
+                                                    DATA1, DATA2)
+fapi::ReturnCode _fapiPutSpyImage(const fapi::Target& i_target,
+                                  const uint32_t i_spyId,
+                                  const ecmdDataBufferBase & i_data,
+                                  ecmdDataBufferBase & o_imageData);
+#endif
+
+#ifdef FAPI_SUPPORT_SPY_AS_STRING
+// fapiPutSpyImage function Cronus version
+#define fapiPutSpyImage(TARGET, ID, DATA1, DATA2) _fapiPutSpyImage(TARGET, #ID,\
+                                                             DATA1,DATA2)
+fapi::ReturnCode _fapiPutSpyImage(const fapi::Target& i_target,
+                                  const char* const i_spyId,
+                                  const ecmdDataBufferBase & i_data,
+                                  ecmdDataBufferBase & o_imageData);
 #endif
 
+#ifdef FAPI_SUPPORT_SPY_AS_ENUM
+/**
+ * @brief Reads data from a ring image
+ * @param[in]   i_target      Target to operate on
+ * @param[in]   i_spyId       The spy's id
+ * @param[out]  o_data        ecmdDataBufferBase object where data is
+ *                            returned
+ * @param[in]   i_imageData   ecmdDataBufferBase object that holds ring image
+ *                            to read data from
+ * @return ReturnCode. Zero on success, else platform specified error
+ *
+ * @note:  The string version is only supported for cronus.
+ *
+ *         The fapi design to support both FSP and cronus use of get and
+ *         put spy functions is dependent on the SPY names being expanded
+ *         to resemble a valid C identifier. This design places some
+ *         restrictions on the SPY names which can be used.
+ *
+ *         See fapiPutSpy for details on spy id specifics.
+ */
+#define fapiGetSpyImage(TARGET, ID, DATA1, DATA2) _fapiGetSpyImage(TARGET, \
+                                            FAPI_SPY_NAMES::ID.value, \
+                                            DATA1, DATA2)
+fapi::ReturnCode _fapiGetSpyImage(const fapi::Target& i_target,
+                                  const uint32_t i_spyId,
+                                  ecmdDataBufferBase & o_data,
+                                  const ecmdDataBufferBase & i_imageData);
+#endif
+
+#ifdef FAPI_SUPPORT_SPY_AS_STRING
+// fapiGetSpyImage function Cronus version
+#define fapiGetSpyImage(TARGET, ID, DATA1, DATA2) _fapiGetSpyImage(TARGET,\
+                                                    #ID, DATA1,DATA2)
+
+fapi::ReturnCode _fapiGetSpyImage(const fapi::Target& i_target,
+                                  const char* const i_spyId,
+                                  ecmdDataBufferBase & o_data,
+                                  const ecmdDataBufferBase & i_imageData);
+#endif
+
+
 } // extern "C"
 
 #endif // FAPIHWACCESS_H_
diff --git a/src/include/usr/hwpf/fapi/fapiPlatHwAccess.H b/src/include/usr/hwpf/fapi/fapiPlatHwAccess.H
index adcb3c877..2b217b798 100644
--- a/src/include/usr/hwpf/fapi/fapiPlatHwAccess.H
+++ b/src/include/usr/hwpf/fapi/fapiPlatHwAccess.H
@@ -5,7 +5,7 @@
 /*                                                                        */
 /* IBM CONFIDENTIAL                                                       */
 /*                                                                        */
-/* COPYRIGHT International Business Machines Corp. 2011,2012              */
+/* COPYRIGHT International Business Machines Corp. 2011,2013              */
 /*                                                                        */
 /* p1                                                                     */
 /*                                                                        */
@@ -23,22 +23,22 @@
 /**
  *  @file fapiPlatHwAccess.H
  *
- *  @brief Defines hardware-access functions for the platform layer.  
- *         Hardware procedure writers will not call these functions. 
- *       
+ *  @brief Defines hardware-access functions for the platform layer.
+ *         Hardware procedure writers will not call these functions.
+ *
  *         Implementors of platform code will provide worker routines
  *         for these functions in file hwpf/plat/fapiPlatHwAccess.C.
  *         fapi.H will not include this file, so platform implementors
- *         will have to include this file explicitly. 
- * 
- *         These platform entry points are called by fapi functions from 
- *         hwpf/fapi/fapiHwAccess.C which are wrapper functions that 
- *         output scand traces common to all platforms.  
- * 
+ *         will have to include this file explicitly.
+ *
+ *         These platform entry points are called by fapi functions from
+ *         hwpf/fapi/fapiHwAccess.C which are wrapper functions that
+ *         output scand traces common to all platforms.
+ *
  *         These functions have the same argument signatures as the
- *         fapi-level functions, but the function names her start with 
+ *         fapi-level functions, but the function names her start with
  *         "plat."
- *     
+ *
  */
 
 /*
@@ -48,7 +48,9 @@
  *                          monte       8sep2011    new
  *                          mjjones     11/10/2011  Use ecmdDataBufferBase
  *          836579          thi         May 22,2012 Spy/Ring supports
- *                          mjjones     07/12/2012  Add Pulse mode option to Ring funcs
+ *                          mjjones     07/12/2012  Add Pulse mode option to
+ *                                                  Ring funcs
+ *                          jknight     04/02/2013  Add fapi get/setSpyImage
  */
 
 #ifndef FAPIPLATHWACCESS_H_
@@ -71,8 +73,8 @@ extern "C"
 /**
  * @brief Platform-level implementation called by GetScom()
  * Hardware procedures writers will not call this function.
- * 
- * 
+ *
+ *
  * @param[in] i_target Target to operate on
  * @param[in] i_address Scom address to read from
  * @param[out] o_data ecmdDataBufferBase object that holds data read from
@@ -87,7 +89,7 @@ fapi::ReturnCode platGetScom(const fapi::Target& i_target,
 /**
  * @brief Platform-level implementation called by PutScom().
  * Hardware procedures writers will not call this function.
- * 
+ *
  * @param[in] i_target Target to operate on
  * @param[in] i_address Scom address to write to
  * @param[in] i_data ecmdDataBufferBase object that holds data to write into
@@ -102,7 +104,7 @@ fapi::ReturnCode platPutScom(const fapi::Target& i_target,
 /**
  * @brief Platform-level implementation called by PutScomUnderMask()
  * Hardware procedures writers will not call this function.
- * 
+ *
  * @param[in] i_target Target to operate on
  * @param[in] i_address Scom address to write to
  * @param[in] i_data ecmdDataBufferBase object that holds the data
@@ -119,7 +121,7 @@ fapi::ReturnCode platPutScomUnderMask(const fapi::Target& i_target,
 /**
  * @brief Platorm-level implementation called by GetCfamRegister()
  * Hardware procedures writers will not call this function.
- * 
+ *
  * @param[in] i_target Target to operate on
  * @param[in] i_address CFAM address to read from
  * @param[out] o_data ecmdDataBufferBase object that holds data read from
@@ -134,7 +136,7 @@ fapi::ReturnCode platGetCfamRegister(const fapi::Target& i_target,
 /**
  * @brief Platform-level implementation called by PutCfamRegister()
  * Hardware procedures writers will not call this function.
- * 
+ *
  * @param[in] i_target Target to operate on
  * @param[in] i_address CFAM address to write to
  * @param[in] i_data ecmdDataBufferBase object that holds data to write into
@@ -149,7 +151,7 @@ fapi::ReturnCode platPutCfamRegister(const fapi::Target& i_target,
 /**
  * @brief Platform-level implementation of ModifyCfamRegister()
  * Hardware procedures writers will not call this function.
- * 
+ *
  * @param[in] i_target Target to operate on
  * @param[in] i_address CFAM address to write to
  * @param[in] i_data ecmdDataBufferBase object that holds the modifying data
@@ -165,7 +167,7 @@ fapi::ReturnCode platModifyCfamRegister(const fapi::Target& i_target,
 /**
  * @brief Platform-level implementation called by fapiGetRing()
  * Hardware procedures writers will not call this function.
- * 
+ *
  * @param[in] i_target  Target to operate on
  * @param[in] i_address Ring address to read from
  * @param[out] o_data   ecmdDataBufferBase object that holds data read from
@@ -244,7 +246,7 @@ fapi::ReturnCode platGetSpy(const fapi::Target& i_target,
  * @return ReturnCode. Zero on success, else platform specified error
  *
  * @note:  This is only supported in the cronus environment
- *         it will not compile in FSP code 
+ *         it will not compile in FSP code
  */
 fapi::ReturnCode platGetSpy(const fapi::Target& i_target,
                              const char * const i_spyId,
@@ -273,7 +275,75 @@ fapi::ReturnCode platPutSpy(const fapi::Target& i_target,
                              const char * const i_spyId,
                              ecmdDataBufferBase & i_data);
 #endif
+#ifdef FAPI_SUPPORT_SPY_AS_ENUM
+/**
+ * @brief Platform-level implementation called by fapiGetSpyImage()
+ * Hardware procedures writers will not call this function.
+ *
+ * @param[in] i_target              Target to read spy from
+ * @param[in] i_spyId               The spy's id
+ * @param[out] o_data               Storage for output data
+ * @param[in] i_imageData           Input ring data
+ *
+ * @return ReturnCode. Zero on success, else platform specified error
+ */
+fapi::ReturnCode platGetSpyImage(const fapi::Target& i_target,
+                                 const uint32_t i_spyId,
+                                 ecmdDataBufferBase & o_data,
+                                 const ecmdDataBufferBase & i_imageData);
+#endif
+#ifdef FAPI_SUPPORT_SPY_AS_STRING
+/**
+ * @brief Platform-level implementation called by fapiGetSpyImage()
+ * Hardware procedures writers will not call this function.
+ *
+ * @param[in] i_target              Target to read spy from
+ * @param[in] i_spyId               The spy's id
+ * @param[out] o_data               Storage for output data
+ * @param[in] i_imageData           Input ring data
+ *
+ * @return ReturnCode. Zero on success, else platform specified error
+ */
+fapi::ReturnCode platGetSpyImage(const fapi::Target& i_target,
+                                 const char * const i_spyId,
+                                 ecmdDataBufferBase & o_data,
+                                 const ecmdDataBufferBase & i_imageData);
+#endif
+#ifdef FAPI_SUPPORT_SPY_AS_ENUM
+/**
+ * @brief Platform-level implementation called by fapiPutSpyImage()
+ * Hardware procedures writers will not call this function.
+ *
+ * @param[in]  i_target             Target to read spy from
+ * @param[in]  i_spyId              The spy's id
+ * @param[in]  i_data               Data to be written into the image
+ * @param[out] io_imageData         Holds ring image to write data into
+ *
+ * @return ReturnCode. Zero on success, else platform specified error
+ */
+fapi::ReturnCode platPutSpyImage(const fapi::Target& i_target,
+                                 const uint32_t i_spyId,
+                                 const ecmdDataBufferBase & i_data,
+                                 ecmdDataBufferBase & io_imageData);
+#endif
+#ifdef FAPI_SUPPORT_SPY_AS_STRING
+/**
+ * @brief Platform-level implementation called by fapiPutSpyImage()
+ * Hardware procedures writers will not call this function.
+ *
+ * @param[in]  i_target             Target to read spy from
+ * @param[in]  i_spyId              The spy's id
+ * @param[in]  i_data               Data to be written into the image
+ * @param[out] io_imageData         Holds ring image to write data into
+ *
+ * @return ReturnCode. Zero on success, else platform specified error
+ */
+fapi::ReturnCode platPutSpyImage(const fapi::Target& i_target,
+                                 const char* const i_spyId,
+                                 const ecmdDataBufferBase & i_data,
+                                 ecmdDataBufferBase & io_imageData);
 
+#endif
 } // extern "C"
 
 #endif // FAPIPLATHWACCESS_H_