/* **********************************************************
 * Copyright (c) 2012-2015 Google, Inc.  All rights reserved.
 * Copyright (c) 2008-2009 VMware, Inc.  All rights reserved.
 * **********************************************************/

/*
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * * Redistributions of source code must retain the above copyright notice,
 *   this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 *
 * * Neither the name of VMware, Inc. nor the names of its contributors may be
 *   used to endorse or promote products derived from this software without
 *   specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL VMWARE, INC. OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 */

/**
\page API_tutorial API Usage Tutorial

Below we provide a few short tutorials on using the DynamoRIO API to write
several clients.

- A client that tracks the average dynamic basic block size
demonstrating some simple instrumentation : \subpage API_tutorial_bbdynsize1 "average_bb_size".

- A client that steals a register from the application demonstrating
some simple state translation : \subpage API_tutorial_steal_reg1 "steal_reg".

- A client that adjusts prefetch instructions demonstrating some simple
app modifications : \subpage API_tutorial_prefetch1 "prefetch".

The following tutorial additionally shows how to create a new annotation to support a
client-specific feature.

- A new annotation for a hypothetical memory usage client. The annotation marks any
specified memory region as defined, even when the client analysis shows it is undefined :
\subpage API_tutorial_annotation1 "create_annotation"

**/


/**
\page API_tutorial_bbdynsize1 average_bb_size

In this tutorial we'll create a simple client that will compute the
average size of basic blocks executed (in instructions) weighted by
their execution frequency. We start with an empty DynamoRIO client.

\code
#include "dr_api.h"

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    /* empty */
}
\endcode

[ \ref API_tutorial "prev" | \subpage API_tutorial_bbdynsize2 "next" ]

\page API_tutorial_bbdynsize2 average_bb_size.p2
Now we register for events we'll need.  For our first pass we only
need to register for the bb event (to add our instrumentation) and the
exit event (to display the results).  We don't need to register for
trace events (as we will add our instrumentation to the constituent
bbs) and we can ignore the \p for_trace and \p translating arguments
to the basic block callback as our changes are deterministic and
idempotent so DynamoRIO default translation will work fine.

\code
#include "dr_api.h"

+ static void
+ event_exit(void);
+ static dr_emit_flags_t
+ event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
+                   bool for_trace, bool translating);

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
+     /* register events */
+     dr_register_exit_event(event_exit);
+     dr_register_bb_event(event_basic_block);
}

+ static void
+ event_exit(void)
+ {
+     /* empty */
+ }
+
+ static dr_emit_flags_t
+ event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
+                   bool for_trace, bool translating)
+ {
+     /* empty */
+     return DR_EMIT_DEFAULT;
+ }
\endcode

[ \ref API_tutorial_bbdynsize1 "prev" | \subpage API_tutorial_bbdynsize3 "next" ]

\page API_tutorial_bbdynsize3  average_bb_size.p3
Next we add code to track the size of blocks as we build them for our
as-built count.  This will give us the number of blocks built and
their average size.  Next we will add the dynamic execution counts.

\code
#include "dr_api.h"

+ #ifdef WINDOWS
+ # define DISPLAY_STRING(msg) dr_messagebox(msg)
+ #else
+ # define DISPLAY_STRING(msg) dr_printf("%s\n", msg)
+ #endif

+ typedef struct bb_counts {
+    uint64 blocks;
+    uint64 total_size;
+ } bb_counts;

+ static bb_counts counts_as_built;
+ void *as_built_lock;

static void
event_exit(void);
static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating);

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    /* register events */
    dr_register_exit_event(event_exit);
    dr_register_bb_event(event_basic_block);
+
+     /* initialize lock */
+     as_built_lock = dr_mutex_create();
}

static void
event_exit(void)
{
+     /* Display results - we must first snpritnf the string as on windows
+      * dr_printf(), dr_messagebox() and dr_fprintf() can't print floats. */
+     char msg[512];
+     int len;
+     len = snprintf(msg, sizeof(msg)/sizeof(msg[0]),
+                    "Number of basic blocks built : %"UINT64_FORMAT_CODE"\n"
+                    "     Average size            : %5.2lf instructions\n",
+                    counts_as_built.blocks,
+                    counts_as_built.total_size / (double)counts_as_built.blocks);
+     DR_ASSERT(len > 0);
+     msg[sizeof(msg)/sizeof(msg[0])-1] = '\0'; /* NUll terminate */
+     DISPLAY_STRING(msg);
+
+      /* free mutex */
+      dr_mutex_destroy(as_built_lock);
}

static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating)
{
+     uint num_instructions = 0;
+     instr_t *instr;
+
+     /* count the number of instructions in this block */
+     for (instr = instrlist_first(bb); instr != NULL; instr = instr_get_next(instr)) {
+         num_instructions++;
+     }
+
+     /* update the as-built counts */
+     dr_mutex_lock(as_built_lock);
+     counts_as_built.blocks++;
+     counts_as_built.total_size += num_instructions;
+     dr_mutex_unlock(as_built_lock);
    return DR_EMIT_DEFAULT;
}
\endcode

[ \ref API_tutorial_bbdynsize2 "prev" | \subpage API_tutorial_bbdynsize4 "next" ]

\page API_tutorial_bbdynsize4  average_bb_size.p4
Now we add instrumentation to gather the dynamic counts.  For the
first pass we'll use a clean call to increment the counters from each
block.  However this approach is very slow since for each basic block
execution a context switch out of the cache will occur.  We'll look at
other approaches next.

\code
#include "dr_api.h"

#ifdef WINDOWS
# define DISPLAY_STRING(msg) dr_messagebox(msg)
#else
# define DISPLAY_STRING(msg) dr_printf("%s\n", msg)
#endif

typedef struct bb_counts {
   uint64 blocks;
   uint64 total_size;
} bb_counts;

static bb_counts counts_as_built;
void *as_built_lock;

+ static bb_counts counts_dynamic;
+ void *count_lock;

static void
event_exit(void);
static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating);
+ static void
+ clean_call(uint instruction_count);

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    /* register events */
    dr_register_exit_event(event_exit);
    dr_register_bb_event(event_basic_block);

    /* initialize lock */
    as_built_lock = dr_mutex_create();
+     count_lock = dr_mutex_create();
}

static void
event_exit(void)
{
    /* Display results - we must first snpritnf the string as on windows
     * dr_printf(), dr_messagebox() and dr_fprintf() can't print floats. */
    char msg[512];
    int len;
    len = snprintf(msg, sizeof(msg)/sizeof(msg[0]),
                   "Number of blocks built : %"UINT64_FORMAT_CODE"\n"
                   "     Average size      : %5.2lf instructions\n"
+                    "Number of blocks executed  : %"UINT64_FORMAT_CODE"\n"
+                    "     Average weighted size : %5.2lf instructions\n",
                   counts_as_built.blocks,
                   counts_as_built.total_size / (double)counts_as_built.blocks,
+                    counts_dynamic.blocks,
+                    counts_dynamic.total_size / (double)counts_dynamic.blocks);
    DR_ASSERT(len > 0);
    msg[sizeof(msg)/sizeof(msg[0])-1] = '\0';
    DISPLAY_STRING(msg);

    /* free mutex */
    dr_mutex_destroy(as_built_lock);
+     dr_mutex_destroy(count_lock);
}

+ static void
+ clean_call(uint instruction_count)
+ {
+     dr_mutex_lock(count_lock);
+     counts_dynamic.blocks++;
+     counts_dynamic.total_size += instruction_count;
+     dr_mutex_unlock(count_lock);
+ }

static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating)
{
    uint num_instructions = 0;
    instr_t *instr;

    /* count the number of instructions in this block */
    for (instr = instrlist_first(bb); instr != NULL; instr = instr_get_next(instr)) {
        num_instructions++;
    }

    /* update the as-built counts */
    dr_mutex_lock(as_built_lock);
    counts_as_built.blocks++;
    counts_as_built.total_size += num_instructions;
    dr_mutex_unlock(as_built_lock);

+     /* insert clean call */
+     dr_insert_clean_call(drcontext, bb, instrlist_first(bb), (void *)clean_call,
+                          false, 1, OPND_CREATE_INT32(num_instructions));
+
    return DR_EMIT_DEFAULT;
}
\endcode

[ \ref API_tutorial_bbdynsize3 "prev" | \subpage API_tutorial_bbdynsize5 "next" ]

\page API_tutorial_bbdynsize5  average_bb_size.p5
In this variation we use inlined atomic instructions to adjust the counters.  On
a single core box this form should be quite fast, but on a multi-core box the
cache line locking for atomic operations will slow things dramatically.  We'll
look at forms more suitable for multi-core further on.

\code
#include "dr_api.h"

#ifdef WINDOWS
# define DISPLAY_STRING(msg) dr_messagebox(msg)
#else
# define DISPLAY_STRING(msg) dr_printf("%s\n", msg)
#endif

typedef struct bb_counts {
   uint64 blocks;
   uint64 total_size;
} bb_counts;

static bb_counts counts_as_built;
void *as_built_lock;

static bb_counts counts_dynamic;

static void
event_exit(void);
static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating);

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    /* register events */
    dr_register_exit_event(event_exit);
    dr_register_bb_event(event_basic_block);

    /* initialize lock */
    as_built_lock = dr_mutex_create();
}

static void
event_exit(void)
{
    /* Display results - we must first snpritnf the string as on windows
     * dr_printf(), dr_messagebox() and dr_fprintf() can't print floats. */
    char msg[512];
    int len;
    len = snprintf(msg, sizeof(msg)/sizeof(msg[0]),
                   "Number of blocks built : %"UINT64_FORMAT_CODE"\n"
                   "     Average size      : %5.2lf instructions\n"
                   "Number of blocks executed  : %"UINT64_FORMAT_CODE"\n"
                   "     Average weighted size : %5.2lf instructions\n",
                   counts_as_built.blocks,
                   counts_as_built.total_size / (double)counts_as_built.blocks,
                   counts_dynamic.blocks,
                   counts_dynamic.total_size / (double)counts_dynamic.blocks);
    DR_ASSERT(len > 0);
    msg[sizeof(msg)/sizeof(msg[0])-1] = '\0';
    DISPLAY_STRING(msg);

    /* free mutex */
    dr_mutex_destroy(as_built_lock);
}

static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating)
{
    uint num_instructions = 0;
    instr_t *instr, *where = NULL;

    /* count the number of instructions in this block */
    for (instr = instrlist_first(bb); instr != NULL; instr = instr_get_next(instr)) {
        num_instructions++;
    }

    /* update the as-built counts */
    dr_mutex_lock(as_built_lock);
    counts_as_built.blocks++;
    counts_as_built.total_size += num_instructions;
    dr_mutex_unlock(as_built_lock);

+     /* increment counters */
+     where = instrlist_first(bb);
+     dr_save_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
+ #ifdef X86_32
+     /* Since the counters are 64-bit we must use an add + an addc to increment.
+      * The operations is still effectively atomic since we're only increasing
+      * the count. */
+     instrlist_meta_preinsert(bb, where,
+         LOCK(INSTR_CREATE_add(drcontext,
+                               OPND_CREATE_ABSMEM((byte *)&counts_dynamic.blocks, OPSZ_4),
+                               OPND_CREATE_INT8(1))));
+     instrlist_meta_preinsert(bb, where,
+         LOCK(INSTR_CREATE_adc(drcontext,
+                               OPND_CREATE_ABSMEM((byte *)&counts_dynamic.blocks + 4, OPSZ_4),
+                               OPND_CREATE_INT8(0))));
+
+     instrlist_meta_preinsert(bb, where,
+         LOCK(INSTR_CREATE_add(drcontext,
+                               OPND_CREATE_ABSMEM((byte *)&counts_dynamic.total_size, OPSZ_4),
+                               OPND_CREATE_INT_32OR8(num_instructions))));
+     instrlist_meta_preinsert(bb, where,
+         LOCK(INSTR_CREATE_adc(drcontext,
+                               OPND_CREATE_ABSMEM((byte *)&counts_dynamic.total_size + 4, OPSZ_4),
+                               OPND_CREATE_INT8(0))));
+ #else /* X86_64 */
+     instrlist_meta_preinsert(bb, where,
+         LOCK(INSTR_CREATE_inc(drcontext,
+                               OPND_CREATE_ABSMEM((byte *)&counts_dynamic.blocks, OPSZ_8))));
+     instrlist_meta_preinsert(bb, where,
+         LOCK(INSTR_CREATE_add(drcontext,
+                               OPND_CREATE_ABSMEM((byte *)&counts_dynamic.total_size, OPSZ_8),
+                               OPND_CREATE_INT_32OR8(num_instructions))));
+ #endif
+     dr_restore_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
+
    return DR_EMIT_DEFAULT;
}
\endcode

[ \ref API_tutorial_bbdynsize4 "prev" | \subpage API_tutorial_bbdynsize6 "next" ]

\page API_tutorial_bbdynsize6  average_bb_size.p6
Next up we add an optimization to only save and restore the flags if we can't find a spot
within the block where the flags are dead.

\code
#include "dr_api.h"

#ifdef WINDOWS
# define DISPLAY_STRING(msg) dr_messagebox(msg)
#else
# define DISPLAY_STRING(msg) dr_printf("%s\n", msg)
#endif

+ #define TESTALL(mask, var) (((mask) & (var)) == (mask))
+ #define TESTANY(mask, var) (((mask) & (var)) != 0)

typedef struct bb_counts {
   uint64 blocks;
   uint64 total_size;
} bb_counts;


static bb_counts counts_as_built;
void *as_built_lock;

static bb_counts counts_dynamic;

+ /* Protected by the as_built_lock */
+ static uint64 bbs_eflags_saved;


static void
event_exit(void);
static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating);

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    /* register events */
    dr_register_exit_event(event_exit);
    dr_register_bb_event(event_basic_block);

    /* initialize lock */
    as_built_lock = dr_mutex_create();
}

static void
event_exit(void)
{
    /* Display results - we must first snpritnf the string as on windows
     * dr_printf(), dr_messagebox() and dr_fprintf() can't print floats. */
    char msg[512];
    int len;
    len = snprintf(msg, sizeof(msg)/sizeof(msg[0]),
                   "Number of blocks built  : %"UINT64_FORMAT_CODE"\n"
                   "     Average size       : %5.2lf instructions\n"
+                    "     Num saved eflags : %"UINT64_FORMAT_CODE"\n"
                   "Number of blocks executed  : %"UINT64_FORMAT_CODE"\n"
                   "     Average weighted size : %5.2lf instructions\n",
                   counts_as_built.blocks,
                   counts_as_built.total_size / (double)counts_as_built.blocks,
+                    bbs_eflags_saved,
                   counts_dynamic.blocks,
                   counts_dynamic.total_size / (double)counts_dynamic.blocks);
    DR_ASSERT(len > 0);
    msg[sizeof(msg)/sizeof(msg[0])-1] = '\0';
    DISPLAY_STRING(msg);

    /* free mutex */
    dr_mutex_destroy(as_built_lock);
}

static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating)
{
    uint num_instructions = 0;
    instr_t *instr, *where = NULL;
+     bool eflags_saved = true;

    /* count the number of instructions in this block */
    for (instr = instrlist_first(bb); instr != NULL; instr = instr_get_next(instr)) {
+         /* Since it doesn't matter where we insert, look for a place
+          * where the eflags are dead. */
+         uint flags = instr_get_arith_flags(instr, DR_QUERY_DEFAULT);
+         if (TESTALL(EFLAGS_WRITE_6, flags) && !TESTANY(EFLAGS_READ_6, flags)) {
+             where = instr;
+             eflags_saved = false;
+         }
        num_instructions++;
    }

    /* update the as-built counts */
    dr_mutex_lock(as_built_lock);
    counts_as_built.blocks++;
    counts_as_built.total_size += num_instructions;
+     if (eflags_saved)
+         bbs_eflags_saved++;
    dr_mutex_unlock(as_built_lock);

    /* increment counters */
+     if (eflags_saved) {
+         where = instrlist_first(bb);
        dr_save_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
+     }
#ifdef X86_32
    /* Since the counters are 64-bit we must use an add an addc to increment.
     * The operations is still effectively atomic since we're only increasing
     * the count. */
    instrlist_meta_preinsert(bb, where,
        LOCK(INSTR_CREATE_add(drcontext,
                              OPND_CREATE_ABSMEM((byte *)&counts_dynamic.blocks, OPSZ_4),
                              OPND_CREATE_INT8(1))));
    instrlist_meta_preinsert(bb, where,
        LOCK(INSTR_CREATE_adc(drcontext,
                              OPND_CREATE_ABSMEM((byte *)&counts_dynamic.blocks + 4, OPSZ_4),
                              OPND_CREATE_INT8(0))));

    instrlist_meta_preinsert(bb, where,
        LOCK(INSTR_CREATE_add(drcontext,
                              OPND_CREATE_ABSMEM((byte *)&counts_dynamic.total_size, OPSZ_4),
                              OPND_CREATE_INT_32OR8(num_instructions))));
    instrlist_meta_preinsert(bb, where,
        LOCK(INSTR_CREATE_adc(drcontext,
                              OPND_CREATE_ABSMEM((byte *)&counts_dynamic.total_size + 4, OPSZ_4),
                              OPND_CREATE_INT8(0))));
#else /* X86_64 */
    instrlist_meta_preinsert(bb, where,
        LOCK(INSTR_CREATE_inc(drcontext,
                              OPND_CREATE_ABSMEM((byte *)&counts_dynamic.blocks, OPSZ_8))));
    instrlist_meta_preinsert(bb, where,
        LOCK(INSTR_CREATE_add(drcontext,
                              OPND_CREATE_ABSMEM((byte *)&counts_dynamic.total_size, OPSZ_8),
                              OPND_CREATE_INT_32OR8(num_instructions))));
#endif
+     if (eflags_saved) {
        dr_restore_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
+     }

    return DR_EMIT_DEFAULT;
}
\endcode

[ \ref API_tutorial_bbdynsize5 "prev" | \subpage API_tutorial_bbdynsize7 "next" ]

\page API_tutorial_bbdynsize7  average_bb_size.p7
We now have a pretty fast implementation, probably about as fast as we can get
on a single core machine.  However, on multi-core systems the cache
line locking for the atomic operations becomes a bottle neck.  To get around that
we can use thread-private counts and aggregate them.  With thread-private counts
no locked instructions are needed, however the extra indirection does has its
own cost of extra added instructions to spill a register and get the tls pointer
so on single core this will be slower.

\code
#include "dr_api.h"
+ #include <stddef.h>

#ifdef WINDOWS
# define DISPLAY_STRING(msg) dr_messagebox(msg)
#else
# define DISPLAY_STRING(msg) dr_printf("%s\n", msg)
#endif

#define TESTALL(mask, var) (((mask) & (var)) == (mask))
#define TESTANY(mask, var) (((mask) & (var)) != 0)

typedef struct bb_counts {
   uint64 blocks;
   uint64 total_size;
} bb_counts;

static bb_counts counts_as_built;
void *as_built_lock;

static bb_counts counts_dynamic;
+ void *count_lock;

/* Protected by the as_built_lock */
static uint64 bbs_eflags_saved;


static void
event_exit(void);
static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating);
+ static void
+ event_thread_init(void *drcontext);
+ static void
+ event_thread_exit(void *drcontext);

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    /* register events */
    dr_register_exit_event(event_exit);
    dr_register_bb_event(event_basic_block);
+     dr_register_thread_init_event(event_thread_init);
+     dr_register_thread_exit_event(event_thread_exit);

    /* initialize lock */
    as_built_lock = dr_mutex_create();
+     count_lock = dr_mutex_create();
}

static void
event_exit(void)
{
    /* Display results - we must first snpritnf the string as on windows
     * dr_printf(), dr_messagebox() and dr_fprintf() can't print floats. */
    char msg[512];
    int len;
    len = snprintf(msg, sizeof(msg)/sizeof(msg[0]),
                   "Number of blocks built  : %"UINT64_FORMAT_CODE"\n"
                   "     Average size       : %5.2lf instructions\n"
                   "     Num saved eflags : %"UINT64_FORMAT_CODE"\n"
                   "Number of blocks executed  : %"UINT64_FORMAT_CODE"\n"
                   "     Average weighted size : %5.2lf instructions\n",
                   counts_as_built.blocks,
                   counts_as_built.total_size / (double)counts_as_built.blocks,
                   bbs_eflags_saved,
                   counts_dynamic.blocks,
                   counts_dynamic.total_size / (double)counts_dynamic.blocks);
    DR_ASSERT(len > 0);
    msg[sizeof(msg)/sizeof(msg[0])-1] = '\0';
    DISPLAY_STRING(msg);

    /* free mutex */
    dr_mutex_destroy(as_built_lock);
+     dr_mutex_destroy(count_lock);
}

+ static void
+ event_thread_init(void *drcontext)
+ {
+     /* create an instance of our data structure for this thread */
+     bb_counts *counts = (bb_counts *)dr_thread_alloc(drcontext, sizeof(bb_counts));
+     /* store it in the slot provided in the drcontext */
+     dr_set_tls_field(drcontext, counts);
+     memset(counts, 0, sizeof(bb_counts));
+ }
+
+ static void
+ event_thread_exit(void *drcontext)
+ {
+     bb_counts *counts = (bb_counts *) dr_get_tls_field(drcontext);
+     /* NOTE - if we so choose we could report per-thread sizes here. */
+     dr_mutex_lock(count_lock);
+     counts_dynamic.blocks += counts->blocks;
+     counts_dynamic.total_size += counts->total_size;
+     dr_mutex_unlock(count_lock);
+     dr_thread_free(drcontext, counts, sizeof(bb_counts));
+ }

static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating)
{
    uint num_instructions = 0;
    instr_t *instr, *where = NULL;
    bool eflags_saved = true;
+     bb_counts *counts = (bb_counts *) dr_get_tls_field(drcontext);

    /* count the number of instructions in this block */
    for (instr = instrlist_first(bb); instr != NULL; instr = instr_get_next(instr)) {
        /* Since it doesn't matter where we insert, look for a place
         * where the eflags are dead. */
        uint flags = instr_get_arith_flags(instr, DR_QUERY_DEFAULT);
        if (TESTALL(EFLAGS_WRITE_6, flags) && !TESTANY(EFLAGS_READ_6, flags)) {
            where = instr;
            eflags_saved = false;
        }
        num_instructions++;
    }

    /* update the as-built counts */
    dr_mutex_lock(as_built_lock);
    counts_as_built.blocks++;
    counts_as_built.total_size += num_instructions;
    if (eflags_saved)
        bbs_eflags_saved++;
    dr_mutex_unlock(as_built_lock);

    /* increment counters */
    if (eflags_saved) {
        where = instrlist_first(bb);
        dr_save_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
    }
+     /* Spill a register to get a pointer to our TLS structure. */
+     dr_save_reg(drcontext, bb, where, DR_REG_XDI, SPILL_SLOT_2);
+     dr_insert_read_tls_field(drcontext, bb, where, DR_REG_XDI);
#ifdef X86_32
    /* Since the counters are 64-bit we must use an add an addc to increment.
     * The operations is still effectively atomic since we're only increasing
     * the count. */
    instrlist_meta_preinsert(bb, where,
!         INSTR_CREATE_add(drcontext,
!                          OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, blocks)),
                         OPND_CREATE_INT8(1)));
    instrlist_meta_preinsert(bb, where,
!         INSTR_CREATE_adc(drcontext,
!                          OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, blocks)+4),
                         OPND_CREATE_INT8(0)));

    instrlist_meta_preinsert(bb, where,
!         INSTR_CREATE_add(drcontext,
!                          OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, total_size)),
                         OPND_CREATE_INT_32OR8(num_instructions)));
    instrlist_meta_preinsert(bb, where,
!         INSTR_CREATE_adc(drcontext,
!                          OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, total_size)+4),
                         OPND_CREATE_INT8(0)));
#else /* X86_64 */
    instrlist_meta_preinsert(bb, where,
!        INSTR_CREATE_inc(drcontext,
!                         OPND_CREATE_MEM64(DR_REG_XDI, offsetof(bb_counts, blocks))));
    instrlist_meta_preinsert(bb, where,
!        INSTR_CREATE_add(drcontext,
!                         OPND_CREATE_MEM64(DR_REG_XDI, offsetof(bb_counts, total_size)),
                        OPND_CREATE_INT_32OR8(num_instructions)));
#endif
+     /* Restore spilled register. */
+     dr_restore_reg(drcontext, bb, where, DR_REG_XDI, SPILL_SLOT_2);
    if (eflags_saved) {
        dr_restore_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
    }

    return DR_EMIT_DEFAULT;
}
\endcode

[ \ref API_tutorial_bbdynsize6 "prev" | \subpage API_tutorial_bbdynsize8 "next" ]

\page API_tutorial_bbdynsize8  average_bb_size.p8
Our final optimization is to note that if we're running with thread-private caches
(i.e. with the -thread_private option to DynamoRIO) we can use absolute addressing
on the per-thread counters instead of indirecting via TLS which should greatly speed
things up.  The downside to -thread_private is that on applications with many threads
memory use can get quite high, potentially enough to impact performance of the system.

\code
#include "dr_api.h"
#include <stddef.h>

#ifdef WINDOWS
# define DISPLAY_STRING(msg) dr_messagebox(msg)
#else
# define DISPLAY_STRING(msg) dr_printf("%s\n", msg)
#endif

#define TESTALL(mask, var) (((mask) & (var)) == (mask))
#define TESTANY(mask, var) (((mask) & (var)) != 0)

typedef struct bb_counts {
   uint64 blocks;
   uint64 total_size;
} bb_counts;

static bb_counts counts_as_built;
void *as_built_lock;

static bb_counts counts_dynamic;
void *count_lock;

/* Protected by the as_built_lock */
static uint64 bbs_eflags_saved;


static void
event_exit(void);
static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating);
static void
event_thread_init(void *drcontext);
static void
event_thread_exit(void *drcontext);

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    /* register events */
    dr_register_exit_event(event_exit);
    dr_register_bb_event(event_basic_block);
    dr_register_thread_init_event(event_thread_init);
    dr_register_thread_exit_event(event_thread_exit);

    /* initialize lock */
    as_built_lock = dr_mutex_create();
    count_lock = dr_mutex_create();
}

static void
event_exit(void)
{
    /* Display results - we must first snpritnf the string as on windows
     * dr_printf(), dr_messagebox() and dr_fprintf() can't print floats. */
    char msg[512];
    int len;
    len = snprintf(msg, sizeof(msg)/sizeof(msg[0]),
                   "Number of blocks built  : %"UINT64_FORMAT_CODE"\n"
                   "     Average size       : %5.2lf instructions\n"
                   "     Num saved eflags : %"UINT64_FORMAT_CODE"\n"
                   "Number of blocks executed  : %"UINT64_FORMAT_CODE"\n"
                   "     Average weighted size : %5.2lf instructions\n",
                   counts_as_built.blocks,
                   counts_as_built.total_size / (double)counts_as_built.blocks,
                   bbs_eflags_saved,
                   counts_dynamic.blocks,
                   counts_dynamic.total_size / (double)counts_dynamic.blocks);
    DR_ASSERT(len > 0);
    msg[sizeof(msg)/sizeof(msg[0])-1] = '\0';
    DISPLAY_STRING(msg);

    /* free mutex */
    dr_mutex_destroy(as_built_lock);
    dr_mutex_destroy(count_lock);
}

static void
event_thread_init(void *drcontext)
{
    /* create an instance of our data structure for this thread */
    bb_counts *counts = (bb_counts *)dr_thread_alloc(drcontext, sizeof(bb_counts));
    /* store it in the slot provided in the drcontext */
    dr_set_tls_field(drcontext, counts);
    memset(counts, 0, sizeof(bb_counts));
}

static void
event_thread_exit(void *drcontext)
{
    bb_counts *counts = (bb_counts *) dr_get_tls_field(drcontext);
    /* NOTE - if we so choose we could report per-thread sizes here. */
    dr_mutex_lock(count_lock);
    counts_dynamic.blocks += counts->blocks;
    counts_dynamic.total_size += counts->total_size;
    dr_mutex_unlock(count_lock);
    dr_thread_free(drcontext, counts, sizeof(bb_counts));
}

static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating)
{
    uint num_instructions = 0;
    instr_t *instr, *where = NULL;
    bool eflags_saved = true;
    bb_counts *counts = (bb_counts *) dr_get_tls_field(drcontext);

    /* count the number of instructions in this block */
    for (instr = instrlist_first(bb); instr != NULL; instr = instr_get_next(instr)) {
        /* Since it doesn't matter where we insert, look for a place
         * where the eflags are dead. */
        uint flags = instr_get_arith_flags(instr, DR_QUERY_DEFAULT);
        if (TESTALL(EFLAGS_WRITE_6, flags) && !TESTANY(EFLAGS_READ_6, flags)) {
            where = instr;
            eflags_saved = false;
        }
        num_instructions++;
    }

    /* update the as-built counts */
    dr_mutex_lock(as_built_lock);
    counts_as_built.blocks++;
    counts_as_built.total_size += num_instructions;
    if (eflags_saved)
        bbs_eflags_saved++;
    dr_mutex_unlock(as_built_lock);

    /* increment counters */
    if (eflags_saved) {
        where = instrlist_first(bb);
        dr_save_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
    }
+     /* If all thread-private caches we can use direct addressing. */
+     if (!dr_using_all_private_caches()) {
        /* Spill a register to get a pointer to our TLS structure. */
        dr_save_reg(drcontext, bb, where, DR_REG_XDI, SPILL_SLOT_2);
        dr_insert_read_tls_field(drcontext, bb, where, DR_REG_XDI);
+     }
#ifdef X86_32
    /* Since the counters are 64-bit we must use an add an addc to increment.
     * The operations is still effectively atomic since we're only increasing
     * the count. */
    instrlist_meta_preinsert(bb, where,
        INSTR_CREATE_add(drcontext,
!                          dr_using_all_private_caches() ?
!                            OPND_CREATE_ABSMEM((byte *)&counts->blocks, OPSZ_4) :
!                            OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, blocks)),
                         OPND_CREATE_INT8(1)));
    instrlist_meta_preinsert(bb, where,
        INSTR_CREATE_adc(drcontext,
!                          dr_using_all_private_caches() ?
!                            OPND_CREATE_ABSMEM((byte *)&counts->blocks +4, OPSZ_4) :
!                            OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, blocks)+4),
                         OPND_CREATE_INT8(0)));

    instrlist_meta_preinsert(bb, where,
        INSTR_CREATE_add(drcontext,
!                          dr_using_all_private_caches() ?
!                            OPND_CREATE_ABSMEM((byte *)&counts->total_size, OPSZ_4) :
!                            OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, total_size)),
                         OPND_CREATE_INT_32OR8(num_instructions)));
    instrlist_meta_preinsert(bb, where,
        INSTR_CREATE_adc(drcontext,
!                          dr_using_all_private_caches() ?
!                            OPND_CREATE_ABSMEM((byte *)&counts->total_size +4, OPSZ_4) :
!                            OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, total_size)+4),
                         OPND_CREATE_INT8(0)));
#else /* X86_64 */
    instrlist_meta_preinsert(bb, where,
       INSTR_CREATE_inc(drcontext,
!                          dr_using_all_private_caches() ?
!                            OPND_CREATE_ABSMEM((byte *)&counts->blocks, OPSZ_8) :
!                            OPND_CREATE_MEM64(DR_REG_XDI, offsetof(bb_counts, blocks))));
    instrlist_meta_preinsert(bb, where,
       INSTR_CREATE_add(drcontext,
!                          dr_using_all_private_caches() ?
!                            OPND_CREATE_ABSMEM((byte *)&counts->total_size, OPSZ_8) :
!                            OPND_CREATE_MEM64(DR_REG_XDI, offsetof(bb_counts, total_size)),
                        OPND_CREATE_INT_32OR8(num_instructions)));
#endif
+     if (!dr_using_all_private_caches()) {
        /* Restore spilled register. */
        dr_restore_reg(drcontext, bb, where, DR_REG_XDI, SPILL_SLOT_2);
+     }
    if (eflags_saved) {
        dr_restore_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
    }

    return DR_EMIT_DEFAULT;
}
\endcode


[ \ref API_tutorial_bbdynsize7 "prev" | \subpage API_tutorial_bbdynsize9 "next" ]

\page API_tutorial_bbdynsize9  average_bb_size.p9
The final multi-core optimized version.  If we are single core then the LOCK version
is probably faster unless we are running with -thread_private in which case it's probably
close to equivalent.

\code
#include "dr_api.h"
#include <stddef.h>

#ifdef WINDOWS
# define DISPLAY_STRING(msg) dr_messagebox(msg)
#else
# define DISPLAY_STRING(msg) dr_printf("%s\n", msg)
#endif

#define TESTALL(mask, var) (((mask) & (var)) == (mask))
#define TESTANY(mask, var) (((mask) & (var)) != 0)

typedef struct bb_counts {
   uint64 blocks;
   uint64 total_size;
} bb_counts;

static bb_counts counts_as_built;
void *as_built_lock;

static bb_counts counts_dynamic;
void *count_lock;

/* Protected by the as_built_lock */
static uint64 bbs_eflags_saved;


static void
event_exit(void);
static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating);
static void
event_thread_init(void *drcontext);
static void
event_thread_exit(void *drcontext);

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    /* register events */
    dr_register_exit_event(event_exit);
    dr_register_bb_event(event_basic_block);
    dr_register_thread_init_event(event_thread_init);
    dr_register_thread_exit_event(event_thread_exit);

    /* initialize lock */
    as_built_lock = dr_mutex_create();
    count_lock = dr_mutex_create();
}

static void
event_exit(void)
{
    /* Display results - we must first snpritnf the string as on windows
     * dr_printf(), dr_messagebox() and dr_fprintf() can't print floats. */
    char msg[512];
    int len;
    len = snprintf(msg, sizeof(msg)/sizeof(msg[0]),
                   "Number of blocks built  : %"UINT64_FORMAT_CODE"\n"
                   "     Average size       : %5.2lf instructions\n"
                   "     Num saved eflags : %"UINT64_FORMAT_CODE"\n"
                   "Number of blocks executed  : %"UINT64_FORMAT_CODE"\n"
                   "     Average weighted size : %5.2lf instructions\n",
                   counts_as_built.blocks,
                   counts_as_built.total_size / (double)counts_as_built.blocks,
                   bbs_eflags_saved,
                   counts_dynamic.blocks,
                   counts_dynamic.total_size / (double)counts_dynamic.blocks);
    DR_ASSERT(len > 0);
    msg[sizeof(msg)/sizeof(msg[0])-1] = '\0';
    DISPLAY_STRING(msg);

    /* free mutex */
    dr_mutex_destroy(as_built_lock);
    dr_mutex_destroy(count_lock);
}

static void
event_thread_init(void *drcontext)
{
    /* create an instance of our data structure for this thread */
    bb_counts *counts = (bb_counts *)dr_thread_alloc(drcontext, sizeof(bb_counts));
    /* store it in the slot provided in the drcontext */
    dr_set_tls_field(drcontext, counts);
    memset(counts, 0, sizeof(bb_counts));
}

static void
event_thread_exit(void *drcontext)
{
    bb_counts *counts = (bb_counts *) dr_get_tls_field(drcontext);
    /* NOTE - if we so choose we could report per-thread sizes here. */
    dr_mutex_lock(count_lock);
    counts_dynamic.blocks += counts->blocks;
    counts_dynamic.total_size += counts->total_size;
    dr_mutex_unlock(count_lock);
    dr_thread_free(drcontext, counts, sizeof(bb_counts));
}

static dr_emit_flags_t
event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
                  bool for_trace, bool translating)
{
    uint num_instructions = 0;
    instr_t *instr, *where = NULL;
    bool eflags_saved = true;
    bb_counts *counts = (bb_counts *) dr_get_tls_field(drcontext);

    /* count the number of instructions in this block */
    for (instr = instrlist_first(bb); instr != NULL; instr = instr_get_next(instr)) {
        /* Since it doesn't matter where we insert, look for a place
         * where the eflags are dead. */
        uint flags = instr_get_arith_flags(instr, DR_QUERY_DEFAULT);
        if (TESTALL(EFLAGS_WRITE_6, flags) && !TESTANY(EFLAGS_READ_6, flags)) {
            where = instr;
            eflags_saved = false;
        }
        num_instructions++;
    }

    /* update the as-built counts */
    dr_mutex_lock(as_built_lock);
    counts_as_built.blocks++;
    counts_as_built.total_size += num_instructions;
    if (eflags_saved)
        bbs_eflags_saved++;
    dr_mutex_unlock(as_built_lock);

    /* increment counters */
    if (eflags_saved) {
        where = instrlist_first(bb);
        dr_save_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
    }
    /* If all thread-private caches we can use direct addressing. */
    if (!dr_using_all_private_caches()) {
        /* Spill a register to get a pointer to our TLS structure. */
        dr_save_reg(drcontext, bb, where, DR_REG_XDI, SPILL_SLOT_2);
        dr_insert_read_tls_field(drcontext, bb, where, DR_REG_XDI);
    }
#ifdef X86_32
    /* Since the counters are 64-bit we must use an add an addc to increment.
     * The operations is still effectively atomic since we're only increasing
     * the count. */
    instrlist_meta_preinsert(bb, where,
        INSTR_CREATE_add(drcontext,
                         dr_using_all_private_caches() ?
                           OPND_CREATE_ABSMEM((byte *)&counts->blocks, OPSZ_4) :
                           OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, blocks)),
                         OPND_CREATE_INT8(1)));
    instrlist_meta_preinsert(bb, where,
        INSTR_CREATE_adc(drcontext,
                         dr_using_all_private_caches() ?
                           OPND_CREATE_ABSMEM((byte *)&counts->blocks +4, OPSZ_4) :
                           OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, blocks)+4),
                         OPND_CREATE_INT8(0)));

    instrlist_meta_preinsert(bb, where,
        INSTR_CREATE_add(drcontext,
                         dr_using_all_private_caches() ?
                           OPND_CREATE_ABSMEM((byte *)&counts->total_size, OPSZ_4) :
                           OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, total_size)),
                         OPND_CREATE_INT_32OR8(num_instructions)));
    instrlist_meta_preinsert(bb, where,
        INSTR_CREATE_adc(drcontext,
                         dr_using_all_private_caches() ?
                           OPND_CREATE_ABSMEM((byte *)&counts->total_size +4, OPSZ_4) :
                           OPND_CREATE_MEM32(DR_REG_XDI, offsetof(bb_counts, total_size)+4),
                         OPND_CREATE_INT8(0)));
#else /* X86_64 */
    instrlist_meta_preinsert(bb, where,
       INSTR_CREATE_inc(drcontext,
                         dr_using_all_private_caches() ?
                           OPND_CREATE_ABSMEM((byte *)&counts->blocks, OPSZ_8) :
                           OPND_CREATE_MEM64(DR_REG_XDI, offsetof(bb_counts, blocks))));
    instrlist_meta_preinsert(bb, where,
       INSTR_CREATE_add(drcontext,
                         dr_using_all_private_caches() ?
                           OPND_CREATE_ABSMEM((byte *)&counts->total_size, OPSZ_8) :
                           OPND_CREATE_MEM64(DR_REG_XDI, offsetof(bb_counts, total_size)),
                        OPND_CREATE_INT_32OR8(num_instructions)));
#endif
    if (!dr_using_all_private_caches()) {
        /* Restore spilled register. */
        dr_restore_reg(drcontext, bb, where, DR_REG_XDI, SPILL_SLOT_2);
    }
    if (eflags_saved) {
        dr_restore_arith_flags(drcontext, bb, where, SPILL_SLOT_1);
    }

    return DR_EMIT_DEFAULT;
}
\endcode

[ \ref API_tutorial_bbdynsize8 "prev" | \ref API_tutorial "back" ]

**/

/**
\page API_tutorial_annotation1 create_annotation

In this tutorial we'll create a new annotation MEMCLIENT_MARK_MEM_DEFINED_IF_ADDRESSABLE()
for use in a hypothetical client named MemClient that detects use of uninitialized
variables. Since an annotation definition has several detailed requirements, it will be
easiest to start with a copy of a DynamoRIO annotation and transform it into the new
annotation. The first step is to copy the DynamoRIO souce file
<b>core/lib/dr_annotations.h</b>:

\code
#ifndef _DYNAMORIO_ANNOTATIONS_H_
#define _DYNAMORIO_ANNOTATIONS_H_ 1

#include "dr_annotations_asm.h"

/* To simplify project configuration, this pragma excludes the file from GCC warnings. */
#ifdef __GNUC__
# pragma GCC system_header
#endif

#define DYNAMORIO_ANNOTATE_RUNNING_ON_DYNAMORIO() \
    dynamorio_annotate_running_on_dynamorio()

#define DYNAMORIO_ANNOTATE_LOG(format, ...) \
    DR_ANNOTATION(dynamorio_annotate_log, format, ##__VA_ARGS__)

#ifdef __cplusplus
extern "C" {
#endif

DR_DECLARE_ANNOTATION(char, dynamorio_annotate_running_on_dynamorio, (void));

DR_DECLARE_ANNOTATION(unsigned int, dynamorio_annotate_log, (const char *format, ...));

#ifdef __cplusplus
}
#endif

#endif
\endcode

[ \ref API_tutorial "prev" | \subpage API_tutorial_annotation2 "next" ]

\page API_tutorial_annotation2 create_annotation.p2

Next, modify elements of the annotation macro and declaration according to its new
purpose:

1. Change the name;
2. Change the return type to void;
3. Replace the formal parameter list.

\code
+#ifndef _MEMCLIENT_ANNOTATIONS_H_
+#define _MEMCLIENT_ANNOTATIONS_H_ 1

#include "dr_annotations_asm.h"

/* To simplify project configuration, this pragma excludes the file from GCC warnings. */
#ifdef __GNUC__
# pragma GCC system_header
#endif

+#define MEMCLIENT_MARK_MEM_DEFINED_IF_ADDRESSABLE(start, size) \
+    DR_ANNOTATION(memclient_mark_mem_defined_if_addressable, start, size)

#ifdef __cplusplus
extern "C" {
#endif

+DR_DECLARE_ANNOTATION(void, memclient_mark_mem_defined_if_addressable,
+                      (void *p, size_t size));

#ifdef __cplusplus
}
#endif

#endif
\endcode

Note that one of the original annotations has been deleted. This completes the header for
the new annotation, and now the source must be similarly copied and modified.

[ \ref API_tutorial_annotation1 "prev" | \subpage API_tutorial_annotation3 "next" ]

\page API_tutorial_annotation3 create_annotation.p3

To create the annotation source file, first copy <b>core/lib/dr_annotations.c</b>:

\code
#include "dr_annotations.h"

DR_DEFINE_ANNOTATION(char, dynamorio_annotate_running_on_dynamorio, (void), return 0)

DR_DEFINE_ANNOTATION(unsigned int, dynamorio_annotate_log, (const char *format, ...),
                     return 0)
\endcode

Note that the last argument to the macro specifies the body of the annotation function,
which in the case of these annotations must contain a return statement because the
annotations are non-void.

[ \ref API_tutorial_annotation2 "prev" | \subpage API_tutorial_annotation4 "next" ]

\page API_tutorial_annotation4 create_annotation.p4

Next, modify elements of the annotation definition to match the header:

\code
#include "dr_annotations.h"

+DR_DEFINE_ANNOTATION(void, memclient_mark_mem_defined_if_addressable,
+                     (void *p, size_t size), )
\endcode

The last argument to the macro is now empty, since the annotation is now void and no
longer requires (or allows) a return statement.

[ \ref API_tutorial_annotation3 "prev" | \subpage API_tutorial_annotation5 "next" ]

\page API_tutorial_annotation5 create_annotation.p5

Target applications will now be able to mark any region of memory as defined by simply
invoking the macro MEMCLIENT_MARK_MEM_DEFINED_IF_ADDRESSABLE(). To implement the
corresponding functionality in memclient, the client developer creates a handler
function having the same signature as the annotation function and registers it for the
annotation using dr_annotation_register_call(). For example:

\code
#include "dr_api.h"

void handle_mark_mem_defined_if_addressable(void *p, size_t size)
{
    size_t *skip_size = dr_global_alloc(sizeof(size_t));
    hashtable_add_replace(skip_init_check_table, p, skip_size);
}

DR_EXPORT void
dr_client_main(client_id_t id, int argc, const char *argv[])
{
    dr_annotation_register_call("memclient_mark_mem_defined_if_addressable",
                                handle_mark_mem_defined_if_addressable, false, 2);
}
\endcode

After registering the handler, all instances of the new annotation will be transformed
into a clean call to handle_mark_mem_defined_if_addressable(), where the arguments to
the annotation macro become arguments to the clean call.

[ \ref API_tutorial_annotation4 "prev" | \subpage API_tutorial_annotation6 "next" ]

\page API_tutorial_annotation6 create_annotation.p6

Since the annotation declarations and definitions are only referenced by target programs
(not by MemClient itself), no additions to the MemClient build are required. However, to
simplify integration of the new annotation into target programs, the MemClient
developer may wish to provide a cmake package that defines a function for configuring
annotations. DynamoRIO provides a similar function use_DynamoRIO_annotations() for its
default annotations, so it will be easiest to start with a copy of that function from
DynamoRIOConfig.cmake (which is located in the DynamoRIO source tree in
make/DynamoRIOConfig.cmake.in):

\verbatim
# For configuring target applications that use default DynamoRIO annotations
function (use_DynamoRIO_annotations target target_srcs)
  set(dr_annotation_dir "${DynamoRIO_cwd}/../include/annotations")
  set(dr_annotation_srcs "${dr_annotation_dir}/dr_annotations.c")
  configure_DynamoRIO_annotation_sources("${dr_annotation_srcs}")
  set(${target_srcs} ${${target_srcs}} ${dr_annotation_srcs} PARENT_SCOPE)
endfunction (use_DynamoRIO_annotations target target_srcs)
\endverbatim

[ \ref API_tutorial_annotation5 "prev" | \subpage API_tutorial_annotation7 "next" ]

\page API_tutorial_annotation7 create_annotation.p7

Next modify elements of the cmake function for usage with the MemClient annotations:

1. Replace DynamoRIO with the client name, e.g. MemClient;
2. Change the variable prefix from dr_ to a suitable prefix, e.g. memclient_;
3. Specify the client's annotation source file(s).

\verbatim
+# For configuring target applications that use MemClient annotations
+function (use_MemClient_annotations target target_srcs)
+  set(memclient_annotation_dir "${MemClient_cwd}/../include/annotations")
+  set(memclient_annotation_srcs "${memclient_annotation_dir}/memclient_annotations.c")
+  configure_DynamoRIO_annotation_sources("${memclient_annotation_srcs}")
+  set(${target_srcs} ${${target_srcs}} ${memclient_annotation_srcs} PARENT_SCOPE)
+endfunction (use_MemClient_annotations target target_srcs)
\endverbatim

Note that the cmake variable memclient_annotation_dir has been set to the same direcotry
as the default DynamoRIO annotation directory, but this is not required--the client
developer may choose to put the new annotations in any directory within the build output
area.

In more general terms, this cmake function takes the following steps:

1. Copies the MemClient annotation header and source file to the build output area;
2. Assigns the required compiler flags;
3. Adds the source file to the project source list.

Target applications that are not built with cmake will need to take these same 3 steps in
a comparable way.

[ \ref API_tutorial_annotation6 "prev" | \ref API_tutorial "back" ]
**/


/**
\page API_tutorial_steal_reg1 steal_reg
<b>coming soon</b>

[ \ref API_tutorial "back" ]
**/


/**
\page API_tutorial_prefetch1 prefetch
<b>coming soon</b>

[ \ref API_tutorial "back" ]
**/
