1    :  // Copyright 2011 Google Inc. All Rights Reserved.
   2    :  //
   3    :  // Licensed under the Apache License, Version 2.0 (the "License");
   4    :  // you may not use this file except in compliance with the License.
   5    :  // You may obtain a copy of the License at
   6    :  //
   7    :  //     http://www.apache.org/licenses/LICENSE-2.0
   8    :  //
   9    :  // Unless required by applicable law or agreed to in writing, software
  10    :  // distributed under the License is distributed on an "AS IS" BASIS,
  11    :  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    :  // See the License for the specific language governing permissions and
  13    :  // limitations under the License.
  14    :  //
  15    :  // Declares utility functions for generating a combined source range map for
  16    :  // an ImageLayout.
  17    :  
  18    :  #ifndef SYZYGY_PE_IMAGE_SOURCE_MAP_H_
  19    :  #define SYZYGY_PE_IMAGE_SOURCE_MAP_H_
  20    :  
  21    :  #include <windows.h>  // NOLINT
  22    :  #include <dbghelp.h>
  23    :  
  24    :  #include "syzygy/pe/image_layout.h"
  25    :  
  26  m :  namespace pe {
  27    :  
  28    :  // An ImageSourceMap is a mapping from bytes in a modifed image to bytes in the
  29    :  // original image from which it was created.
  30  m :  typedef core::AddressRange<core::RelativeAddress, size_t> RelativeAddressRange;
  31  m :  typedef core::AddressRangeMap<RelativeAddressRange,
  32  m :                                RelativeAddressRange> ImageSourceMap;
  33    :  
  34    :  // This is used for representing an invalid address in a source range map that
  35    :  // is converted to an OMAP. Since the OMAP format only implicitly encodes
  36    :  // lengths we have to encode unmapped ranges by mapping to invalid addresses.
  37    :  // We do this for completeness, making the OMAP vector more useful as a
  38    :  // debugging tool, although it is not strictly necessary.
  39  m :  extern const ULONG kInvalidOmapRvaTo;
  40    :  
  41    :  // Given an ImageLayout representing an image that has been derived from exactly
  42    :  // one non-transformed image, returns the combined ImageSourceMap for all of the
  43    :  // data in the image.
  44    :  //
  45    :  // @param image_layout the ImageLayout whose source information to extract.
  46    :  // @param image_source_map the AddressRangeMap mapping relative addresses in the
  47    :  //     new image to relative addresses in the source image.
  48  m :  void BuildImageSourceMap(const ImageLayout& image_layout,
  49  m :                           ImageSourceMap* new_to_old);
  50    :  
  51    :  // Given an ImageSourceMap, converts it to an equivalent OMAP vector. The OMAP
  52    :  // vector is constructed such that source addresses with no equivalent address
  53    :  // in the destination address space are mapped to an invalid address that is
  54    :  // greater than or equal to kInvalidOmapRvaTo.
  55    :  //
  56    :  // Mappings whose destination range is shorter than its source range are broken
  57    :  // into multiple OMAP entries, each mapping a portion of the larger source
  58    :  // range. This ensures that any address in the source range will be mapped to
  59    :  // some address in the destination range, and not any address outside of it.
  60    :  //
  61    :  // This transformation is not lossless, with the OMAP inherently encoding less
  62    :  // information about the image than does the ImageSourceMap.
  63    :  //
  64    :  // @param range the range which the OMAP vector should cover.
  65    :  // @param source_map the source map to be translated to an OMAP vector.
  66    :  // @param omaps the OMAP vector be populated.
  67  m :  void BuildOmapVectorFromImageSourceMap(const RelativeAddressRange& range,
  68  m :                                         const ImageSourceMap& source_map,
  69  m :                                         std::vector<OMAP>* omaps);
  70    :  
  71  m :  }  // namespace pe
  72    :  
  73    :  #endif  // SYZYGY_PE_IMAGE_SOURCE_MAP_H_