xref: /netbsd/src/external/bsd/elftosb/dist/common/StExecutableImage.h

/*
 * File:  StExecutableImage.h
 *
 * Copyright (c) Freescale Semiconductor, Inc. All rights reserved.
 * See included license file for license details.
 */
#if !defined(_StExecutableImage_h_)
#define _StExecutableImage_h_

#include "stdafx.h"
#include <list>

/*!
 * \brief Used to build a representation of memory regions.
 *
 * An intermediate representation of the memory regions and segments loaded
 * from an executable file. Also used to find contiguous segments that are
 * specified separately in the source file.
 *
 * When regions are added, an attempt is made to coalesce contiguous regions.
 * In order for this to succeed, the touching regions must be of the same
 * type and have the same permissions. Regions are also kept sorted by their
 * address range as they are added.
 *
 * \todo Implement alignment support.
 */
class StExecutableImage
{
public:
          //! Possible types of memory regions.
          typedef enum {
                    TEXT_REGION,        //!< A region containing data or instructions.
                    FILL_REGION                   //!< Region to be initialized with zero bytes.
          } MemoryRegionType;

          //! Memory region flag constants.
          enum {
                    REGION_READ_FLAG = 1,         //!< Region is readable.
                    REGION_WRITE_FLAG = 2,        //!< Region is writable.
                    REGION_EXEC_FLAG = 4,         //!< Region may contain executable code.

                    REGION_RW_FLAG = REGION_READ_FLAG | REGION_WRITE_FLAG,      //!< Region is read-write.

                    //! Mask to access only permissions flags for a region.
                    REGION_PERM_FLAG_MASK = 0x7
          };

          /*!
           * Representation of a contiguous region of memory.
     *
     * \todo Add comparison operators so we can use the STL sort algorithm.
           */
          struct MemoryRegion
          {
                    MemoryRegionType m_type;      //!< Memory region type.
                    uint32_t m_address; //!< The 32-bit start address of this region.
                    uint32_t m_length;  //!< Number of bytes in this region.
                    uint8_t * m_data;   //!< Pointer to data. Will be NULL for FILL_REGION type.
                    unsigned m_flags;   //!< Flags for the region.

        //! \brief Calculates the address of the last byte occupied by this region.
        inline uint32_t endAddress() const { return m_address + m_length - 1; }

        //! \brief Equality operator.
        bool operator == (const MemoryRegion & other) const;
          };

          //! A list of #StExecutableImage::MemoryRegion objects.
          typedef std::list<MemoryRegion> MemoryRegionList;

    //! The iterator type used to access #StExecutableImage::MemoryRegion objects. This type
    //! is used by the methods #getRegionBegin() and #getRegionEnd().
          typedef MemoryRegionList::const_iterator const_iterator;

    //! The possible actions for regions matching an address filter range.
    typedef enum {
        ADDR_FILTER_NONE,       //!< Do nothing.
        ADDR_FILTER_ERROR,      //!< Raise an error exception.
        ADDR_FILTER_WARNING,    //!< Raise a warning exception.
        ADDR_FILTER_CROP        //!< Don't include the matching address range in the executable image.
    } AddressFilterAction;

    /*!
     * An address filter consists of a single address range and an action. If a
     * memory region overlaps the filter's range then the action will be performed.
     * The possible filter actions are defined by the #AddressFilterAction enumeration.
     */
    struct AddressFilter
    {
        AddressFilterAction m_action;   //!< Action to be performed when the filter is matched.
        uint32_t m_fromAddress; //!< Start address of the filter. Should be lower than or equal to #m_toAddress.
        uint32_t m_toAddress;   //!< End address of the filter. Should be higher than or equal to #m_fromAddress.
        unsigned m_priority;     //!< Priority for this filter. Zero is the lowest priority.

        //! \brief Constructor.
        AddressFilter(AddressFilterAction action, uint32_t from, uint32_t to, unsigned priority=0)
        :   m_action(action), m_fromAddress(from), m_toAddress(to), m_priority(priority)
        {
        }

        //! \brief Test routine.
        bool matchesMemoryRegion(const MemoryRegion & region) const;

        //! \brief Compares two address filter objects.
        int compare(const AddressFilter & other) const;

        //! \name Comparison operators
        //@{
        inline bool operator < (const AddressFilter & other) const { return compare(other) == -1; }
        inline bool operator > (const AddressFilter & other) const { return compare(other) == 1; }
        inline bool operator == (const AddressFilter & other) const { return compare(other) == 0; }
        inline bool operator <= (const AddressFilter & other) const { return compare(other) != 1; }
        inline bool operator >= (const AddressFilter & other) const { return compare(other) != -1; }
        //@}
    };

    //! List of #StExecutableImage::AddressFilter objects.
    typedef std::list<AddressFilter> AddressFilterList;

    //! The exception class raised for the #ADDR_FILTER_ERROR and #ADDR_FILTER_WARNING
    //! filter actions.
    class address_filter_exception
    {
    public:
        //! \brief Constructor.
        //!
        //! A local copy of \a matchingFilter is made, in case the image and/or filter
        //! are on the stack and would be disposed of when the exception is raised.
        address_filter_exception(bool isError, std::string & imageName, const AddressFilter & matchingFilter)
        : m_isError(isError), m_imageName(imageName), m_filter(matchingFilter)
        {
        }

        //! \brief Returns true if the exception is an error. Otherwise the exception
        //!     is for a warning.
        inline bool isError() const { return m_isError; }

        //! \brief
        inline std::string getImageName() const { return m_imageName; }

        //! \brief
        inline const AddressFilter & getMatchingFilter() const { return m_filter; }

    protected:
        bool m_isError;
        std::string m_imageName;
        AddressFilter m_filter;
    };

public:
          //! \brief Constructor.
          StExecutableImage(int inAlignment=256);

          //! \brief Copy constructor.
          StExecutableImage(const StExecutableImage & inOther);

          //! \brief Destructor.
          virtual ~StExecutableImage();

          //! \name Image name
          //! Methods for getting and setting the image name.
          //@{
          //! \brief Sets the image's name to \a inName.
          virtual void setName(const std::string & inName);

          //! \brief Returns a copy of the image's name.
          virtual std::string getName() const;
          //@}

          //! \name Regions
          //! Methods to add and access memory regions.
          //@{
          //! \brief Add a region to be filled with zeroes.
          virtual void addFillRegion(uint32_t inAddress, unsigned inLength);

          //! \brief Add a region containing data to be loaded.
          virtual void addTextRegion(uint32_t inAddress, const uint8_t * inData, unsigned inLength);

          //! \brief Returns the total number of regions.
          //!
          //! Note that this count may not be the same as the number of calls to
          //! addFillRegion() and addTextRegion() due to region coalescing.
          inline unsigned getRegionCount() const { return static_cast<unsigned>(m_image.size()); }

          //! \brief Returns a reference to the region specified by \a inIndex.
          const MemoryRegion & getRegionAtIndex(unsigned inIndex) const;

    //! \brief Return an iterator to the first region.
          inline const_iterator getRegionBegin() const { return m_image.begin(); }

    //! \brief Return an iterator to the next-after-last region.
          inline const_iterator getRegionEnd() const { return m_image.end(); }
          //@}

          //! \name Entry point
          //@{
          //! \brief Sets the entry point address.
          inline void setEntryPoint(uint32_t inEntryAddress) { m_entry = inEntryAddress; m_hasEntry = true; }

          //! \brief Returns true if an entry point has been set.
          inline bool hasEntryPoint() const { return m_hasEntry; }

          //! \brief Returns the entry point address.
          inline uint32_t getEntryPoint() const { return hasEntryPoint() ? m_entry : 0; }
          //@}

    //! \name Address filter
    //@{
    //! \brief Add a new address filter.
    virtual void addAddressFilter(const AddressFilter & filter);

    //! \brief Add multiple address filters at once.
    //!
    //! The template argument \a _T must be an iterator or const iterator that
    //! dereferences to an StExecutableImage::AddressFilter reference. All filters
    //! from \a from to \a to will be added to the address filter list.
    template<typename _T> void addAddressFilters(_T from, _T to)
    {
        _T it = from;
        for (; it != to; ++it)
        {
            addAddressFilter(*it);
        }
    }

    //! \brief Remove all active filters.
    virtual void clearAddressFilters();

    //! \brief Process all active filters and perform associated actions.
    virtual void applyAddressFilters();
    //@}

protected:
          std::string m_name; //!< The name of the image (can be a file name, for instance).
          int m_alignment;    //!< The required address alignment for each memory region.
          bool m_hasEntry;    //!< True if an entry point has been set.
          uint32_t m_entry;   //!< Entry point address.
          MemoryRegionList m_image;     //!< The memory regions.
    AddressFilterList m_filters;    //!< List of active address filters.

    //! \brief Deletes the portion \a region that overlaps \a filter.
    void cropRegionToFilter(MemoryRegion & region, const AddressFilter & filter);

          //! \brief Inserts the region in sorted order or merges with one already in the image.
          void insertOrMergeRegion(MemoryRegion & inRegion);

          //! \brief Merges two memory regions into one.
          void mergeRegions(MemoryRegion & inOldRegion, MemoryRegion & inNewRegion);
};

#endif // _StExecutableImage_h_