MTuner SDK

Overview

Instrumenting your application manually enables additional MTuner features allowing more precise profiling of your software. Using the Instrumentation API is very simple, all it takes is including a single header file and link against the shipped (or built, depending on the toolchain) library. Instrumentation API is defined entirely in a single header file and can be used either from a C or C++ program. For most applications, just linking against the library and following a few simple rules will be sufficient as MTuner SDK will override run time memory functions or hook directly to low level system calls. In case your software is using custom memory manager(s), it is possible to call to MTuner SDK functions directly and avoid automatic instrumentation. Below you can find the structure of MTuner SDK:

  • 3rd
    Third party source code is located in this directory. There is a portion of google gperftools source code that is used for hooking Windows heap functions, LZ4 compressor by Yann Colet and stdint.h replacement for earlier versions of MSVC compiler.

  • samples

    • Linker
      Linker folder contains an example of using the MTuner SDK. This sample shows how to make use of linker functionality to avoid having to manually call API functions. Usage of memory tags and memory markers is also demonstrated.
    • Manual
      Manual folder contains an example of using the MTuner SDK. This sample shows how to make use of manual instrumentation functionality for more control over the profiling process.

  • genie
    This directory contains the GENie script. GENie is a meta build system used to generate makefiles, project files and similar. Instructions for building MTuner SDK with GENie are inside the README.txt file, included in this directory as well.

  • inc
    rmem.h header file is located here. Entire API is declared here. MTuner.h header is provided for backwards compatibility purposes.

  • src
    Full source of MTuner SDK is located in this directory. Source code is provided so it can be compiled for any target platform targeted by your software. For more information please check the custom toolchains page.

Using the Instrumentation API

If your application needs finer control, for example if you are using custom memory manager(s), you can use the API functions directly. MTuner SDK needs to be initialized and cleaned up on exit, this is done by using rmemInit and rmemShutDown functions. It is best to call them at the very beginning/end of your main function.

Notifying MTuner SDK about memory operations is done through 5 functions. Each of them provides a way to record details about the operation.


/* Called for each alloc operation */  
void rmemAlloc(uint64_t _handle, void* _ptr, uint32_t _size, uint32_t _overhead);  
  
/* Called for each realloc operation */  
void rmemRealloc(uint64_t _handle, void* _ptr, uint32_t _size, uint32_t _overhead, void* _prevPtr);  
  
/* Called for each aligned alloc operation */  
void rmemAllocAligned(uint64_t _handle, void* _ptr, uint32_t _size, uint32_t _overhead, uint32_t _alignment);  
  
/* Called for each aligned realloc operation */  
void rmemReallocAligned(uint64_t _handle, void* _ptr, uint32_t _size, uint32_t _overhead, void* _prevPtr, uint32_t _aAlignment);  
  
/* Called for each free operation */  
void rmemFree(uint64_t _handle, void* _ptr);

Example of using Instrumentation API to capture a memory allocation:


void* myCustomAlloc( size_t _size )
{
    void* retPtr = /* custom allocation code */
    rmemAlloc(0, retPtr, _size, myAllocOverheadCalc(inSize));
    return retPtr;
}

MTuner tags

Memory tags have to be registered prior to their usage. Registration process is simple as MTuner SDK only needs to be aware of a tag name. There is only one root tag, all other tags have parent tags. Child tags are declared with a macro that takes a second argument - name of the parent tag. There is no limit on the depth of hierarchy of the tag tree. Please make sure the parent names are correct, they are case sensitive. Below you can see how to register a root tag and a child tag:


RMEM_REGISTER_TAG("Some root tag");
RMEM_REGISTER_TAG_CHILD("Some child tag", "Some root tag");

Memory tags are scope based. Assuming you are using C++, it is a matter of adding one line of code to declare a tag:


void SomeClass::SomeMethod
{
    RMEM_TAG("Second half")
    // Code goes here
}

For more information see the tag tree page.

MTuner markers

Memory markers are used to mark significant events in your application. A marker is a set of a time stamp, name and color. Once the capture file is loaded, the markers will be displayed under the memory timeline. For example, markers can be placed to mark start and end of data loading. Using markers makes filtering out of memory operations that happen between any two of them a trivial task. There are two macros that can be used to specify a marker.

Declaring a marker with predefined colors:


RMEM_MARKER("Marker name",MARKER_COLOR_DEFAULT);

Declaring a marker with custom colors, providing a RGB triplet:


RMEM_MARKER_RGB("Alloc",90,120,90);