contrib/opencsd/decoder/include/mem_acc/trc_mem_acc_file.h

   1 /*
   2  * \file       trc_mem_acc_file.h
   3  * \brief      OpenCSD :  Access binary target memory file
   4  *
   5  * \copyright  Copyright (c) 2015, ARM Limited. All Rights Reserved.
   6  */
   7
   8 /*
   9  * Redistribution and use in source and binary forms, with or without modification,
  10  * are permitted provided that the following conditions are met:
  11  *
  12  * 1. Redistributions of source code must retain the above copyright notice,
  13  * this list of conditions and the following disclaimer.
  14  *
  15  * 2. Redistributions in binary form must reproduce the above copyright notice,
  16  * this list of conditions and the following disclaimer in the documentation
  17  * and/or other materials provided with the distribution.
  18  *
  19  * 3. Neither the name of the copyright holder nor the names of its contributors
  20  * may be used to endorse or promote products derived from this software without
  21  * specific prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND
  24  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  25  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  26  * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  27  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  28  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  30  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  32  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 #ifndef ARM_TRC_MEM_ACC_FILE_H_INCLUDED
  36 #define ARM_TRC_MEM_ACC_FILE_H_INCLUDED
  37
  38 #include <map>
  39 #include <string>
  40 #include <fstream>
  41 #include <list>
  42
  43 #include "opencsd/ocsd_if_types.h"
  44 #include "mem_acc/trc_mem_acc_base.h"
  45
  46 // an add-on region to a file - allows setting of a region at a none-zero offset for a file.
  47 class FileRegionMemAccessor : public TrcMemAccessorBase
  48 {
  49 public:
  50     FileRegionMemAccessor() : TrcMemAccessorBase(MEMACC_FILE) {};
  51     virtual ~FileRegionMemAccessor() {};
  52
  53     void setOffset(const size_t offset) { m_file_offset = offset; };
  54     const size_t getOffset() const { return m_file_offset; };
  55
  56     bool operator<(const FileRegionMemAccessor& rhs) { return this->m_startAddress < rhs.m_startAddress; };
  57
  58     // not going to use these objects to read bytes - defer to the file class for that.
  59     virtual const uint32_t readBytes(const ocsd_vaddr_t s_address, const ocsd_mem_space_acc_t memSpace, const uint32_t reqBytes, uint8_t *byteBuffer) { return 0; };
  60
  61     const ocsd_vaddr_t regionStartAddress() const { return m_startAddress; };
  62
  63 private:
  64     size_t m_file_offset;
  65 };
  66
  67 /*!
  68  * @class TrcMemAccessorFile
  69  * @brief Memory accessor for a binary file.
  70  *
  71  * Memory accessor based on a binary file snapshot of some memory.
  72  *
  73  * Static creation code to allow reference counted accessor usable for
  74  * multiple access maps attached to multiple source trees for the same system.
  75  */
  76 class TrcMemAccessorFile : public TrcMemAccessorBase
  77 {
  78 public:
  79     /** read bytes override - reads from file */
  80     virtual const uint32_t readBytes(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t memSpace, const uint32_t reqBytes, uint8_t *byteBuffer);
  81
  82 protected:
  83     TrcMemAccessorFile();   /**< protected default constructor */
  84     virtual ~ TrcMemAccessorFile(); /**< protected default destructor */
  85
  86     /** increment reference counter */
  87     void IncRefCount() { m_ref_count++; };
  88
  89     /** decrement reference counter */
  90     void DecRefCount() { m_ref_count--; };
  91
  92     /** get current reference count */
  93     const int getRefCount() const { return  m_ref_count; };
  94
  95     /*!
  96      * Initialise accessor with file name and path, and start address.
  97      * File opened and length calculated to determine end address for the range.
  98      *
  99      * @param &pathToFile : Binary file path and name
 100      * @param startAddr : system memory address associated with start of binary datain file.
 101      *
 102      * @return bool  : true if set up successfully, false if file could not be opened.
 103      */
 104     ocsd_err_t initAccessor(const std::string &pathToFile, ocsd_vaddr_t startAddr, size_t offset, size_t size);
 105
 106     /** get the file path */
 107     const std::string &getFilePath() const { return m_file_path; };
 108
 109     /** get an offset region if extant for the address */
 110     FileRegionMemAccessor *getRegionForAddress(const ocsd_vaddr_t startAddr) const;
 111
 112     /* validate ranges */
 113     virtual const bool validateRange();
 114
 115 public:
 116
 117     /*!
 118      * File may contain multiple none-overlapping ranges in a single file.
 119      *
 120      * @param startAddr : Address for beginning of byte data.
 121      * @param size   : size of range in bytes.
 122      * @param offset : offset into file for that data.
 123      *
 124      * @return bool  : true if set successfully.
 125      */
 126     bool AddOffsetRange(const ocsd_vaddr_t startAddr, const size_t size, const size_t offset);
 127
 128     /*!
 129      * Override in case we have multiple regions in the file.
 130      *
 131      * @param s_address : Address to test.
 132      *
 133      * @return const bool  : true if the address is in range.
 134      */
 135     virtual const bool addrInRange(const ocsd_vaddr_t s_address) const;
 136
 137     /*!
 138      * test if an address is the start of range for this accessor
 139      *
 140      * @param s_address : Address to test.
 141      *
 142      * @return const bool  : true if the address is start of range.
 143      */
 144     virtual const bool addrStartOfRange(const ocsd_vaddr_t s_address) const;
 145
 146     /*!
 147      * Test number of bytes available from the start address, up to the number of requested bytes.
 148      * Tests if all the requested bytes are available from the supplied start address.
 149      * Returns the number available up to full requested amount.
 150      *
 151      * @param s_address : Start address within the range.
 152      * @param reqBytes : Number of bytes needed from the start address.
 153      *
 154      * @return const uint32_t  : Bytes available, up to reqBytes. 0 is s_address not in range.
 155      */
 156     virtual const uint32_t bytesInRange(const ocsd_vaddr_t s_address, const uint32_t reqBytes) const;
 157
 158     /*!
 159      * test is supplied range accessor overlaps this range.
 160      *
 161      * @param *p_test_acc : Accessor to test for overlap.
 162      *
 163      * @return bool  : true if overlap, false if not.
 164      */
 165     virtual const bool overLapRange(const TrcMemAccessorBase *p_test_acc) const;
 166
 167     /*! Override to handle ranges and offset accessors plus add in file name. */
 168     virtual void getMemAccString(std::string &accStr) const;
 169
 170
 171     /*!
 172      * Create a file accessor based on the supplied path and address.
 173      * Keeps a list of file accessors created.
 174      *
 175      * File will be checked to ensure valid accessor can be created.
 176      *
 177      * If an accessor using the supplied file is currently in use then a reference to that
 178      * accessor will be returned and the accessor reference counter updated.
 179      *
 180      * @param &pathToFile : Path to binary file
 181      * @param startAddr : Start address of data represented by file.
 182      *
 183      * @return TrcMemAccessorFile * : pointer to accessor if successful, 0 if it could not be created.
 184      */
 185     static ocsd_err_t createFileAccessor(TrcMemAccessorFile **p_acc, const std::string &pathToFile, ocsd_vaddr_t startAddr, size_t offset = 0, size_t size = 0);
 186
 187     /*!
 188      * Destroy supplied accessor.
 189      *
 190      * Reference counter decremented and checked and accessor destroyed if no longer in use.
 191      *
 192      * @param *p_accessor : File Accessor to destroy.
 193      */
 194     static void destroyFileAccessor(TrcMemAccessorFile *p_accessor);
 195
 196     /*!
 197      * Test if any accessor is currently using the supplied file path
 198      *
 199      * @param &pathToFile : Path to test.
 200      *
 201      * @return bool : true if an accessor exists with this file path.
 202      */
 203     static const bool isExistingFileAccessor(const std::string &pathToFile);
 204
 205     /*!
 206      * Get the accessor using the supplied file path
 207      * Use after createFileAccessor if additional memory ranges need
 208      * adding to an exiting file accessor.
 209      *
 210      * @param &pathToFile : Path to test.
 211      *
 212      * @return TrcMemAccessorFile * : none 0 if an accessor exists with this file path.
 213      */
 214     static TrcMemAccessorFile * getExistingFileAccessor(const std::string &pathToFile);
 215
 216
 217
 218
 219 private:
 220     static std::map<std::string, TrcMemAccessorFile *> s_FileAccessorMap;   /**< map of file accessors in use. */
 221
 222 private:
 223     std::ifstream m_mem_file;   /**< input binary file stream */
 224     ocsd_vaddr_t m_file_size;  /**< size of the file */
 225     int m_ref_count;            /**< accessor reference count */
 226     std::string m_file_path;    /**< path to input file */
 227     std::list<FileRegionMemAccessor *> m_access_regions;    /**< additional regions in the file at non-zero offsets */
 228     bool m_base_range_set;      /**< true when offset 0 set */
 229     bool m_has_access_regions;  /**< true if single file contains multiple regions */
 230 };
 231
 232 #endif // ARM_TRC_MEM_ACC_FILE_H_INCLUDED
 233
 234 /* End of File trc_mem_acc_file.h */