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.
47class FileRegionMemAccessor : public TrcMemAccessorBase
48{
49public:
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 uint8_t trcID, const uint32_t reqBytes, uint8_t *byteBuffer) { return 0; };
60
61    const ocsd_vaddr_t regionStartAddress() const { return m_startAddress; };
62
63private:
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 */
76class TrcMemAccessorFile : public TrcMemAccessorBase
77{
78public:
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 uint8_t trcID, const uint32_t reqBytes, uint8_t *byteBuffer);
81
82protected:
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
115public:
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
219private:
220    static std::map<std::string, TrcMemAccessorFile *> s_FileAccessorMap;   /**< map of file accessors in use. */
221
222private:
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 */
235