1    :  // Copyright 2013 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    :  // Implements the functions that a custom heap can use to provide necessary
  16    :  // metadata to the SyzyASan bookkeeping.
  17    :  #ifndef SYZYGY_AGENT_ASAN_NESTED_HEAP_H_
  18    :  #define SYZYGY_AGENT_ASAN_NESTED_HEAP_H_
  19    :  
  20  m :  extern "C" {
  21    :  
  22    :  // Poisons the given range of memory, marking it as inaccessible. This should
  23    :  // be done when a block of unused memory is allocated from the OS.
  24    :  // @pre address + size mod 8 == 0.
  25    :  // @param address The starting address.
  26    :  // @param size The size of the memory to poison.
  27  m :  void asan_PoisonMemoryRange(const void* address, size_t size);
  28    :  
  29    :  // Unpoisons the given range of memory, marking it as accessible. This should
  30    :  // be done after a block of memory has been returned to the OS.
  31    :  // @pre address mod 8 == 0 && size mod 8 == 0.
  32    :  // @param addr The starting address.
  33    :  // @param size The size of the memory to unpoison.
  34  m :  void asan_UnpoisonMemoryRange(const void* address, size_t size);
  35    :  
  36    :  // Given a desired user object size and alignment, returns the size of memory
  37    :  // required to wrap the object with ASAN headers and footers. Assumes the
  38    :  // ASAN-wrapped object will be placed with the same alignment.
  39    :  // @param user_object_size The user object size.
  40    :  // @param alignment The user object alignment.
  41  m :  size_t asan_GetAsanObjectSize(size_t user_object_size, size_t alignment);
  42    :  
  43    :  // Mark the given block as allocated. This will red-zone the header and
  44    :  // trailer, green zone the user data, and grab an allocation stack trace and
  45    :  // other metadata.
  46    :  // @param asan_pointer The ASan block to initialize.
  47    :  // @param user_object_size The user object size.
  48    :  // @param alignment The user object alignment.
  49  m :  void asan_InitializeObject(void* asan_pointer,
  50  m :                             size_t user_object_size,
  51  m :                             size_t alignment);
  52    :  
  53    :  // Given a pointer to an ASAN wrapped allocation, returns the location and
  54    :  // size of the user data contained within.
  55    :  // @param asan_pointer The pointer to the ASan block.
  56    :  // @param user_pointer Receives the user pointer.
  57    :  // @param size Receives the size of the user part of this block.
  58  m :  void asan_GetUserExtent(const void* asan_pointer,
  59  m :                          void** user_pointer,
  60  m :                          size_t* size);
  61    :  
  62    :  // Return the location and size of the ASAN block wrapping the given user
  63    :  // pointer.
  64    :  // @param user_pointer The user pointer for this ASan block.
  65    :  // @param asan_pointer Receives the ASan pointer.
  66    :  // @param size Receives the size of this ASan block.
  67  m :  void asan_GetAsanExtent(const void* user_pointer,
  68  m :                          void** asan_pointer,
  69  m :                          size_t* size);
  70    :  
  71    :  // Mark the given block as freed, but still residing in memory. This will
  72    :  // red-zone the user data and grab a free stack trace and other metadata.
  73    :  // After this call the object is effectively quarantined and access to it will
  74    :  // be caught as errors.
  75    :  // @param asan_pointer The pointer to the ASan block to quarantine.
  76  m :  void asan_QuarantineObject(void* asan_pointer);
  77    :  
  78    :  // Clean up the object's metadata. The object is dead entirely, clean up the
  79    :  // metadata. This makes sure that we can decrement stack trace ref-counts and
  80    :  // reap them. This leaves the memory red-zoned (inaccessible).
  81    :  // NOTE: If the memory has been returned to the OS then it must also be
  82    :  //       unpoisoned.
  83    :  // @param asan_pointer The pointer to the ASan block to destroy.
  84  m :  void asan_DestroyObject(void* asan_pointer);
  85    :  
  86    :  // Clones an object from one location to another. This mediates access to the
  87    :  // protected header and footer wrapping the user object, as the client code
  88    :  // may itself be instrumented. This will also copy the shadow memory: the new
  89    :  // object will preserve the alive or free status of the old object.
  90    :  // NOTES:
  91    :  // - The client must ensure there is sufficient room at the destination
  92    :  //   for the object to be cloned.
  93    :  // - If the source object is no longer needed it is up to the client to call
  94    :  //   QuarantineObject or DestroyObject.
  95    :  // - It is up to the client to ensure that the destination address meets any
  96    :  //   alignment requirements of the source object.
  97    :  // @param src_asan_pointer The pointer to the ASan source block.
  98    :  // @param dst_asan_pointer The pointer to the ASan destination block.
  99  m :  void asan_CloneObject(const void* src_asan_pointer,
 100  m :                        void* dst_asan_pointer);
 101    :  
 102  m :  }  // extern "C"
 103    :  
 104    :  #endif  // SYZYGY_AGENT_ASAN_NESTED_HEAP_H_