Port UtilStream, UtilMem, UtilFile from FSP.

Change-Id: Id17617544a8c4ed646aa8410cb968ba9376dea68
RTC: 41638
Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/1097
Tested-by: Jenkins Server
Reviewed-by: Douglas R. Gilbert <dgilbert@us.ibm.com>
Reviewed-by: A. Patrick Williams III <iawillia@us.ibm.com>

4 files changed, 899 insertions, 0 deletions

diff --git a/src/include/usr/util/util_reasoncodes.H b/src/include/usr/util/util_reasoncodes.H
new file mode 100644
index 000000000..f9e1c0b01
--- /dev/null
+++ b/src/include/usr/util/util_reasoncodes.H
@@ -0,0 +1,45 @@
+//  IBM_PROLOG_BEGIN_TAG
+//  This is an automatically generated prolog.
+//
+//  $Source: src/include/usr/util/util_reasoncodes.H $
+//
+//  IBM CONFIDENTIAL
+//
+//  COPYRIGHT International Business Machines Corp. 2012
+//
+//  p1
+//
+//  Object Code Only (OCO) source materials
+//  Licensed Internal Code Source Materials
+//  IBM HostBoot Licensed Internal Code
+//
+//  The source code for this program is not published or other-
+//  wise divested of its trade secrets, irrespective of what has
+//  been deposited with the U.S. Copyright Office.
+//
+//  Origin: 30
+//
+//  IBM_PROLOG_END
+
+#ifndef __UTIL_REASONCODES_H
+#define __UTIL_REASONCODES_H
+
+#include <hbotcompid.H>
+
+namespace Util
+{
+    enum ModuleId
+    {
+        UTIL_MOD_MEM_READ,             // UtilMem::Read
+        UTIL_MOD_MEM_WRITE,            // UtilMem::Write
+    };
+
+    enum ReasonCode
+    {
+        UTIL_ERC_NONE           = UTIL_COMP_ID | 0x01,
+        UTIL_ERC_BAD_PTR        = UTIL_COMP_ID | 0x02,
+        UTIL_ERC_EOF            = UTIL_COMP_ID | 0x03,
+    };
+};
+
+#endif
diff --git a/src/include/usr/util/utilfile.H b/src/include/usr/util/utilfile.H
new file mode 100644
index 000000000..68433e348
--- /dev/null
+++ b/src/include/usr/util/utilfile.H
@@ -0,0 +1,307 @@
+//  IBM_PROLOG_BEGIN_TAG
+//  This is an automatically generated prolog.
+//
+//  $Source: src/include/usr/util/utilfile.H $
+//
+//  IBM CONFIDENTIAL
+//
+//  COPYRIGHT International Business Machines Corp. 2003-2012
+//
+//  p1
+//
+//  Object Code Only (OCO) source materials
+//  Licensed Internal Code Source Materials
+//  IBM HostBoot Licensed Internal Code
+//
+//  The source code for this program is not published or other-
+//  wise divested of its trade secrets, irrespective of what has
+//  been deposited with the U.S. Copyright Office.
+//
+//  Origin: 30
+//
+//  IBM_PROLOG_END
+
+#ifndef UTILFILE_H
+#define UTILFILE_H
+
+/**
+ * @file utilfile.H
+ *
+ * @brief File Stream manipulation
+ *
+ * Used for creating and manipulating file streams
+ *
+ */
+
+/*****************************************************************************/
+// I n c l u d e s
+/*****************************************************************************/
+
+// Utility Includes
+#include <util/utilstream.H>
+#include <util/utilmem.H>
+#include <util/util_reasoncodes.H>
+
+/*****************************************************************************/
+// File Stream class
+/*****************************************************************************/
+/**
+ *  @brief     Utility file stream class
+ *
+ *  Used for file streams
+ *
+ */
+class UtilFile : public UtilStream
+{
+  public:
+
+    /**
+     *  @brief Default Constructor
+     *
+     *  Initializes internals to NULL and will thus cause an exception if
+     *  an invalid operation is performed ( such as writing to the file
+     *  without opening it )
+     *
+     */
+    UtilFile();
+
+    /**
+     *  @brief Constructor
+     *
+     *  Initializes internals of the file stream object with the file path name.
+     *
+     */
+    UtilFile(const char * i_filePathName);
+
+    /**
+     *  @brief Destructor
+     *
+     *  1. Closes the file ( if it's open )
+     *  2. Deletes allocated resources
+     *  3. Deletes any pending error logs ( effectively aborting )
+     *
+     */
+    virtual ~UtilFile();
+
+    /**
+     *  @brief Determines if the file is available in the filesystem
+     *
+     *  Attempts to open the file for readonly to determine if it exists
+     *  in the file system.  Secondary failures are not reported by
+     *  this interface.
+     *
+     *  @return
+     *      Bool: true, the file exists.  false, it doesn't exist or a
+     *      secondary failure occurred while making the determination.
+     *
+     */
+    bool exists( void ) const;
+
+    /**
+     *  @brief Determines if the file is available in the filesystem
+     *
+     *  This is a static function that to determine if it exists
+     *  in the file system and is a REGULAR file.
+     *  Secondary failures are not reported by this interface.
+     *
+     *  @return
+     *      Bool: true, the file exists.  false, it doesn't exist or a
+     *      secondary failure occurred while making the determination.
+     *
+     */
+    static bool exists(const char * );
+
+    /**
+     *  @brief Open the file associated with the object
+     *
+     *  Opens the file based off of the file name associated with the object
+     *  with the specified file mode by calling Open with the flag set to false
+     *  to always open the flash file by default.
+     *
+     *  @return
+     *      Nothing. Errors are deferred until the user calls getLastError
+     *
+     */
+    void Open(
+        const char * i_mode ///<Mode file is to be opened in
+    );
+
+    /**
+     *  @brief Open the file associated with the object
+     *
+     *  Opens the file based off of the file name associated with the object
+     *  with the specified file mode calling the open with the flag set to false
+     *  to always open the flash file by default.
+     *
+     *  @return
+     *      A error handle specifying the failure ( if any ).
+     *
+     */
+    errlHndl_t open(
+        const char * i_mode ///<Mode file is to be opened in
+    )
+    {
+        Open(i_mode);
+        return getLastError();
+    }
+
+    /**
+     *  @brief Open a file for the specified access
+     *
+     *  If a file is currently open, it will be closed.  Then the
+     *  specified file will be opened for the given access mode.
+     *  Any failures are reported through the return code
+     *
+     *  @return
+     *      Nothing. Errors are deferred until the user calls getLastError
+     *
+     */
+    void Open(
+        const char * i_file,    ///< Path filename
+        const char * i_mode     ///< Mode file is to be opened in
+    );
+
+    /**
+     *  @brief Open a file for the specified access
+     *
+     *  If a file is currently open, it will be closed.  Then the
+     *  specified file will be opened for the given access mode.
+     *  Any failures are reported through the return code
+     *
+     *  @return
+     *      A error handle specifying the failure ( if any ).
+     *
+     */
+    errlHndl_t open(
+        const char * i_file,    ///< Path filename
+        const char * i_mode     ///< Mode file is to be opened in
+    )
+    {
+        Open(i_file,i_mode);
+        return getLastError();
+    }
+
+    /**
+     *  @brief Close the file associated with the object
+     *
+     *  Closes the file based off file pointer associated with the file.
+     *
+     *  @return
+     *      Nothing. Errors are deferred until the user calls getLastError
+     *
+     */
+    void Close();
+
+    /**
+     *  @brief Close the file associated with the object
+     *
+     *  Closes the file based off file pointer associated with the file.
+     *
+     *  @return
+     *      A error handle specifying the failure ( if any ).
+     *
+     */
+    errlHndl_t close()
+    {
+        Close();
+        return getLastError();
+    }
+
+    /**
+     *  @brief Reads data from current position of the stream
+     *
+     *  Reads data from the current postion of the stream for the
+     *  specified number of bytes.
+     *
+     */
+    uint32_t read(
+        void * o_buffer,    ///< Buffer data is read into
+        uint32_t i_size     ///< Size in bytes of data to be read
+    );
+
+    /**
+     *  @brief Writes data to current position of the stream
+     *
+     *  Writes data to the current postion of the stream for the
+     *  specified number of bytes.
+     *
+     *  @note This will assert in Hostboot! Writing of files is not supported.
+     *
+     */
+    uint32_t write(
+        const void *i_buffer,     ///< Source buffer data is written from
+        uint32_t    i_size        ///< Size in bytes of data to be written
+    );
+
+    /**
+     *  @brief Seek to the specified position in the stream
+     *
+     *  Performs a seek based on the specified position and offset.
+     *
+     */
+    uint32_t seek(
+        int i_pos,          ///< Seek offset in bytes
+        whence i_whence     ///< Position to seek from
+    );
+
+    /**
+     *  @brief Return the current size of the stream
+     *
+     *  Returns the current size of the stream.
+     *
+     */
+    uint32_t size() const;
+
+    /**
+     * @brief Query the file's open/closed state
+     *
+     * Determines if the file is currently open
+     *
+     * @return bool value indicating the open status of the file
+     *
+    */
+    bool isOpen( void ) const
+    {
+        return ( iv_contents.size() != 0 );
+    }
+
+    /**
+     *  @brief Expose the filename
+     *
+     *  Return a const char * to the filename
+     *
+     *  @return Filename pointer
+     *
+     */
+    const char * Name() const;
+
+private:
+
+    /**
+     * @brief Change the object's filename
+     *
+     * Set the object's filename
+     *
+     * @param i_name
+     *      New name, or null to simply get
+     *
+     * @return void
+     *
+    */
+    void FileName( const char * i_name );
+
+    // Instance variables
+    char*       iv_filePathName;    ///< Name of file being operated on
+    UtilMem     iv_contents;
+};
+
+
+/*****************************************************************************/
+// Get Filename
+/*****************************************************************************/
+inline const char * UtilFile::Name() const
+{
+    return iv_filePathName;
+}
+
+#endif //UTILFILE_H
diff --git a/src/include/usr/util/utilmem.H b/src/include/usr/util/utilmem.H
new file mode 100644
index 000000000..57d4bf047
--- /dev/null
+++ b/src/include/usr/util/utilmem.H
@@ -0,0 +1,242 @@
+//  IBM_PROLOG_BEGIN_TAG
+//  This is an automatically generated prolog.
+//
+//  $Source: src/include/usr/util/utilmem.H $
+//
+//  IBM CONFIDENTIAL
+//
+//  COPYRIGHT International Business Machines Corp. 2003-2012
+//
+//  p1
+//
+//  Object Code Only (OCO) source materials
+//  Licensed Internal Code Source Materials
+//  IBM HostBoot Licensed Internal Code
+//
+//  The source code for this program is not published or other-
+//  wise divested of its trade secrets, irrespective of what has
+//  been deposited with the U.S. Copyright Office.
+//
+//  Origin: 30
+//
+//  IBM_PROLOG_END
+#ifndef UTILMEM_H
+#define UTILMEM_H
+
+/**
+ * @file utilmem.H
+ *
+ * @brief Memory Stream manipulation
+ *
+ * Used for creating and manipulating memory streams
+ *
+ */
+
+/*****************************************************************************/
+// I n c l u d e s
+/*****************************************************************************/
+
+// Utility Includes
+#include <util/utilstream.H>
+
+/*****************************************************************************/
+// Forwards
+/*****************************************************************************/
+class UtilFile;
+
+//*****************************************************************************/
+// C o n s t a n t s
+/*****************************************************************************/
+/*****************************************************************************/
+// Memory Stream class
+/*****************************************************************************/
+/**
+ *  @brief     Utility Memory Stream class
+ *
+ *  Used for memory streams
+ *
+ */
+class UtilMem : public UtilStream
+{
+public:
+
+    /**
+     *  @brief Default constructor
+     *
+     *  Initializes internals of the memory stream object, setting autogrow
+     *  to true.
+     *
+     */
+    UtilMem();
+
+    /**
+     *  @brief Constructor with size parameter
+     *
+     *  Initializes internals of the memory stream object and allocates a
+     *  stream of the specified size.
+     *
+     */
+    UtilMem(uint32_t i_size);
+
+    /**
+     *  @brief Constructor with buffer pointer and size parameter
+     *
+     *  Initializes internals of the memory stream object.
+     *
+     */
+    UtilMem(void * i_buffer, uint32_t i_size);
+
+    /**
+     *  @brief Assignment operator
+     *
+     */
+    UtilMem & operator = ( const UtilMem & i_right );
+
+    /**
+     *  @brief UtilFile assignment
+     *
+     *  Easy way to transfer data between a file and a memory object
+     *
+     *  The file object is read from the current position up to the
+     *  size of the mem object.
+     *
+     *  @return UtilMem reference
+     *
+     *  @note Errors are reported by getLastError()
+     *
+     */
+    UtilMem & operator = ( UtilFile & i_right );
+
+    /**
+     *  @brief Default destructor
+     *
+     *
+     */
+    virtual ~UtilMem();
+
+    /**
+     *  @brief Reads data from current position of the stream
+     *
+     *  Reads data from the current postion of the stream for the
+     *  specified number of bytes.
+     *
+     */
+    uint32_t read(
+        void *        o_buffer, ///< Buffer data is read into
+        uint32_t      i_size    ///< Size in bytes of data to be read
+        );
+
+    /**
+     *  @brief Writes data to current position of the stream
+     *
+     *  Writes data to the current postion of the stream for the
+     *  specified number of bytes.
+     *
+     */
+    uint32_t write(
+        const void *i_buffer,   ///< Source buffer data is written from
+        uint32_t    i_size      ///< Size in bytes of data to be written
+        );
+
+    /**
+     *  @brief Seek to the specified position in the stream
+     *
+     *  Performs a seek based on the specified position and offset.
+     *
+     */
+    uint32_t seek(
+        int         i_pos,      ///< Seek offset in bytes
+        whence    i_whence      ///< Position to seek from
+        );
+
+    /**
+     *  @brief Return the current size of the stream
+     *
+     *  Returns the current size of the stream.
+     *
+     */
+    uint32_t size() const
+    {
+        return iv_size;
+    }
+
+    /**
+     *  @brief Change size
+     *
+     *  Change the size of the memory object to the requested
+     *  size.  The data is maintained.
+     *
+     */
+    void changeSize( uint32_t i_size );
+
+    /**
+     *  @brief Set autoGrow flag as specified
+     *
+     *  Sets the autoGrow flag as specified.
+     *
+     */
+    void autoGrow(bool i_flag);
+
+    /**
+     *  @brief Query the autoGrow flag
+     *
+     *  Queries the autoGrow flag.
+     *
+     */
+    bool autoGrow();
+
+    /**
+     *  @brief Base pointer access
+     *
+     *  Obtains a constant pointer to the data
+     *
+     */
+    const void * base() const
+    {
+        return iv_memStart;
+    }
+
+    /**
+     *  @brief Reset the the object
+     *
+     *  1. Clears the memory to the specified value
+     *  2. Sets the offest back to 0
+     *  3. Deletes any pending errors
+     */
+    void reset( int i_c = 0 );
+
+private:
+
+    uint8_t *   iv_memStart;
+    uint32_t    iv_offset;
+    uint32_t    iv_size;
+    bool        iv_autoGrow;
+    bool        iv_autoCleanup;
+
+};
+
+/*****************************************************************************/
+// I n l i n e s
+/*****************************************************************************/
+
+/*****************************************************************************/
+// Set the autoGrow flag
+/*****************************************************************************/
+inline void UtilMem::autoGrow(bool i_flag)
+{
+    if ( iv_autoCleanup )
+    {
+        // Can only autogrow if the memory is ours
+        iv_autoGrow = i_flag;
+    }
+}
+
+/*****************************************************************************/
+// Query the autoGrow flag
+/*****************************************************************************/
+inline bool UtilMem::autoGrow()
+{
+    return iv_autoGrow;
+}
+
+#endif //UTILMEM_H
diff --git a/src/include/usr/util/utilstream.H b/src/include/usr/util/utilstream.H
new file mode 100644
index 000000000..8aced71f9
--- /dev/null
+++ b/src/include/usr/util/utilstream.H
@@ -0,0 +1,305 @@
+//  IBM_PROLOG_BEGIN_TAG
+//  This is an automatically generated prolog.
+//
+//  $Source: src/include/usr/util/utilstream.H $
+//
+//  IBM CONFIDENTIAL
+//
+//  COPYRIGHT International Business Machines Corp. 2003-2012
+//
+//  p1
+//
+//  Object Code Only (OCO) source materials
+//  Licensed Internal Code Source Materials
+//  IBM HostBoot Licensed Internal Code
+//
+//  The source code for this program is not published or other-
+//  wise divested of its trade secrets, irrespective of what has
+//  been deposited with the U.S. Copyright Office.
+//
+//  Origin: 30
+//
+//  IBM_PROLOG_END
+
+#ifndef UTILSTREAM_H
+#define UTILSTREAM_H
+
+/**
+ * @file utilstream.H
+ *
+ * @brief       Stream manipulation
+ *
+ * Used for creating and manipulating streams
+ *
+ */
+
+/*****************************************************************************/
+// I n c l u d e s
+/*****************************************************************************/
+#include <stdint.h>
+#include <errl/errlentry.H>
+
+/*****************************************************************************/
+// User Types
+/*****************************************************************************/
+
+//*****************************************************************************/
+// C o n s t a n t s
+/*****************************************************************************/
+
+/*****************************************************************************/
+// Stream class
+/*****************************************************************************/
+/**
+ *  @brief  Stream Base class
+ *
+ *  Stream interface specification
+ *
+ */
+class UtilStream
+{
+  public:
+
+    enum whence
+    {
+        CURRENT = 0,
+        START = 1,
+        END = 2
+    };
+
+
+    /**
+     *  @brief Default constructor
+     *
+     *  Initializes internals of the stream object.
+     *
+     */
+    UtilStream();
+
+    /**
+     *  @brief Destructor
+     *
+     */
+    virtual ~UtilStream();
+
+    /**
+     *  @brief Reads data from current position of the stream
+     *
+     *  Reads data from the current postion of the stream for the
+     *  specified number of bytes.
+     *
+     *  @return # of bytes read or zero if none.
+     *
+     *  @note Errors are not reported by this interface, instead
+     *        the user must call getLastError.
+     *
+     */
+    virtual uint32_t read(
+        void *      o_buffer,   ///< Buffer data is read into
+        uint32_t    i_size      ///< Size in bytes of data to be read
+        ) = 0;
+
+    /**
+     *  @brief Writes data to current position of the stream
+     *
+     *  Writes data to the current postion of the stream for the
+     *  specified number of bytes.
+     *
+     *  @return # of bytes written or zero if none.
+     *
+     *  @note Errors are not reported by this interface, instead
+     *        the user must call getLastError.
+     *
+     */
+    virtual uint32_t write(
+        const void *i_buffer,   ///< Source buffer data is written from
+        uint32_t    i_size      ///< Size in bytes of data to be written
+        ) = 0;
+
+    /**
+     *  @brief Seek to the specified position in the stream
+     *
+     *  Performs a seek based on the specified position and offset.
+     *
+     *  @return Current file position after the interface completes.
+     *
+     *  @note Errors are not reported by this interface, instead
+     *        the user must call getLastError.
+     *
+     *  @example
+     *  // To Get the current file position
+     *
+     *  UtilFile    l_file;
+     *  ...
+     *  uint32_t l_curpos = l_file.seek( 0, l_file.CURRENT );
+     *
+     *  @endexample
+     *
+     */
+    virtual uint32_t seek(
+        int32_t     i_pos,      ///< Seek offset in bytes
+        whence      i_whence    ///< Position to seek from
+        ) = 0;
+
+    /**
+     *  @brief Return the current size of the stream
+     *
+     *  Returns the current size of the stream.
+     *
+     */
+    virtual uint32_t size() const = 0;
+
+    /**
+     *  @brief Return EOF status
+     *
+     *  Returns true if EOF has been reached, and false if it has not been
+     *  reached.
+     *
+     */
+    bool eof();
+
+    /**
+     *  @brief Get the last error received.
+     *
+     *  Returns the last error received and clears error status.
+     *
+     *  @note clearing the error status involves returning the last
+     *        error and setting eof to false.  In other words, it wipes
+     *        the slate clean.
+     *
+     */
+    errlHndl_t getLastError();
+
+    /**
+     *  @brief Set the last error received.
+     *
+     *  Replaces the last error with the user supplied parameter.
+     *
+     *  @note If an error exists, it will be deleted and replaced by this
+     *        call.  For this reason, the user should normally do one
+     *        of the following:
+     *        1. getLastError & append then setLastError, or
+     *        2. peekLastError & append, or if it's null, just setLastError
+     *
+     */
+    void setLastError( errlHndl_t i_error );
+
+    /**
+     *  @brief Peek last error
+     *
+     *  Returns the last error received but does NOT clear the error status.
+     *
+     *  @note
+     *      The returned handle should not be:
+     *      1. committed
+     *      2. deleted
+     *
+     *      under any circumstances since it belongs to the UtilStream
+     *      object.
+     *
+     */
+    errlHndl_t peekLastError() const;
+
+    /**
+     *  @brief General Insertion to cover all outstanding cases
+     *
+     *  Writes the data value to the stream
+     *
+     *  @return A reference to the stream
+     *
+     *  @note Errors are not reported by this interface, instead
+     *        the user must call getLastError.
+     *
+     */
+    template< class D >
+    UtilStream & operator<< ( const D & i_right )
+    {
+        write( &i_right, sizeof(D) );
+        return *this;
+    }
+
+    /**
+     *  @brief General Extraction to cover all outstanding cases
+     *
+     *  Reads the data value from the stream
+     *
+     *  @return A reference to the stream
+     *
+     *  @note Errors are not reported by this interface, instead
+     *        the user must call getLastError.
+     *
+     */
+    template< class D >
+    UtilStream & operator>> ( D & i_right )
+    {
+        read( &i_right, sizeof(D) );
+        return *this;
+    }
+
+protected:
+
+    /**
+     * @brief   Assignment operator
+     *
+     * Deletes any pending errors, and copies the eof file
+     * from the right hand operand.
+     *
+     * @return A stream reference
+     *
+    */
+    UtilStream & operator = ( const UtilStream & i_right );
+
+
+    bool                iv_eof;                 ///<Stream EOF
+    mutable errlHndl_t  iv_lastError;           ///<Last Error
+
+
+private:
+
+    // Disable assignment & copy-constructor until the meaning is defined
+    UtilStream( const UtilStream & i_right );
+
+
+};
+
+
+/*****************************************************************************/
+// I n l i n e s
+/*****************************************************************************/
+
+/*****************************************************************************/
+// Query End of File
+/*****************************************************************************/
+inline bool UtilStream::eof()
+{
+    return iv_eof;
+}
+
+
+/*****************************************************************************/
+// Get the last Error Log
+/*****************************************************************************/
+inline errlHndl_t UtilStream::getLastError()
+{
+    errlHndl_t l_lastError;
+
+    l_lastError = iv_lastError;
+
+    // Clear the error condition
+    iv_lastError = 0;
+    iv_eof = false;
+
+    return l_lastError;
+}
+
+
+/*****************************************************************************/
+// Peek last Error Log
+/*****************************************************************************/
+inline errlHndl_t UtilStream::peekLastError() const
+{
+    return iv_lastError;
+}
+
+#endif //UTILSTREAM_H
+