Heap Inspector NX Plugin
===============================================================================

1. Overview
2. Requirements
3. Runtime Integration
4. Heap Inspector Tool Setup
5. Troubleshooting
6. Known Issues
7. Change log

===============================================================================

1. Overview

Heap Inspector is a tool provided as-is with no warranty from Nintendo.
Please see the License.rtf for more information on the tool.

Nintendo is providing a plugin for this tool to allow for tracking memory
allocations, frees, and reallocations within an application. This functionality
will eventually be moved into the Nintendo NX CPU Profiler, with the Heap
Inspector tool standing in until such a time that the work has finished.

===============================================================================

2. Requirements

 * .NET 4.5 or later

===============================================================================

3. Runtime Integration

Note: This API can introduce serious overhead on memory allocations, frees, and
      reallocations. This is due in part to the API ensuring single memory
      operations occur at a time and in part to the PC communication that
      occurs to record each memory operation occurring.

Note: For more information on a function mentioned below, check its API
      reference page in the NX Addon documentation.

Integration Steps:
 1. Initialize the Nintendo NX CPU Profiler.
    a. Steps on this can be found in the Nintendo NX CPU Profiler readme.

 2. Register the application heaps.
    a. Call nn::profiler::RecordHeapRange for each heap in the application.
       For example:
          void* startAddr = nullptr;
          void* endAddr = reinterpret_cast<void*>(UINTPTR_MAX);
          nn::profiler::RecordHeapRange(startAddr, endAddr, "Example");
       Note that with the current implementation that only 6 heaps may be
       registered.

 3. Log allocations, frees, and reallocations.
    a. Find each place where memory is allocated, freed, or reallocated.
       Ideally, these should be in a central location. These functions can also
       be called before the profiler API is initialized. However, only memory
       operations after the profiler API initialization can be tracked.
    b. After each operation, place the corresponding Track operation.
       For example, after calling malloc, place:
          nn::profiler::TrackMalloc(memory, size);
    c. [optional] Before each operation, generate a tracking id.
       This enforces memory operation ordering when the data gets to the PC.
       The tracking id must then be also used in the argument list from
       step 3b. For example:
          auto id = nn::profiler::GenerateNextTrackingId();
          void* memory = malloc(size);
          nn::profiler::TrackMalloc(id, memory, size);

===============================================================================

4. Heap Inspector Tool Setup

Setup Steps:
 1. Create an HTCS reservation for '@NvMemoryProfiler'.
    a. In Target Manager, go to Tools->Edit HTCS reservations.
    b. Edit the text file to include the reservation for the SDEV's serial
       number with the port name '@NvMemoryProfiler' and a port number
       under 10000. For example:
          XAW02121004141, @NvMemoryProfiler, 6569
    c. Save and close the text file.
    d. Reset the SDEV.

 2. Set NX plugin options in Heap Inspector.
    a. Start Heap Inspector.
    b. Go to Tools->Options->NX.
    c. Set 'Path to addr2line.exe' to the addr2line executable that comes in
       NX Addon. In should be located in the Compilers folder. For example:
          F:\NintendoSDK\Compilers\NX\nx\aarch64\bin\aarch64-nintendo-nx-elf-addr2line.exe
    d. Similar to 2c, set 'Path to readelf.exe' to the readelf executable that
       comes in NX Addon. It should be located in the Compilers folder.
       For example:
          F:\NintendoSDK\Compilers\NX\nx\aarch64\bin\aarch64-nintendo-nx-elf-readelf.exe

 3. Create a connection profile.
    a. In Heap Inspector, go to Live/Recoding->Connect.
    b. In the Connect window, click the '...' button in the Connection group.
    c. Click the 'Add' button.
    d. Set the settings for the connection. The Name can be anything. The IP
       address should be 127.0.0.1. The Port should be the same as the one
       set in 1b. For example:
          Name: SDEV 4141
          IP address: 127.0.0.1
          Port: 6569

 4. Connect to the runtime.
    a. In the Connect window, select the connection profile created in Step 3.
    b. It is generally recommended to leave the Callstack mode set to 'Full'.
    c. Click the 'OK' button to connect.

Note: If Step 2 is skipped, callstacks will just be addresses and show the
      function as 'Unresolved symbol'.

===============================================================================

5. Troubleshooting

The following are common issues:

 1. HeapInspector cannot connect to the application.
    The necessary threads and communication layers are not started unless
    a heap has been recorded. Please ensure that Runtime Integration step 2
    has been followed.

===============================================================================

6. Known Issues

The following are known issues:

 1. Only 6 heap regions can be recorded. If more calls to RecordHeapRange are
    made, the data is ignored.

 2. The 'systemName' and 'alignment' arguments in the Track APIs are not used.

===============================================================================

6. Change log

2016-11-16:
 * API changes
 * Simplified how NSS files and their start addresses are found.

2016-09-20:
 * Initial version
