/* ******************************************************************************
 * Copyright (c) 2010-2021 Google, 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 Google, 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 page_annotations Annotations

# Annotation Types

-# <b>Statement</b>: the annotation directly precedes the call site
  - the target app may specify a block of statements to execute only on a native run
-# <b>Expression</b>: the annotation appears at the beginning of the annotation function
  - the remainder of the annotation function only executes on a native run
  - the call site is not annotated

Every annotation function is defined as an expression, i.e., its body begins with the annotation tag.
If a particular call site is annotated,
that invocation becomes a statement, and the annotation function call is skipped in a native run.
When calling an annotation as an expression, the annotation function is invoked (i.e., not skipped) to avoid
control flow confusion in nested expressions (especially where annotation expressions are nested).
The annotation tag is placed inside the annotation function for the expression context because
(1) it is easy to find there, (2) it requires only one instrumentation per run, and (3) the function is being
invoked anyway.

# Annotation Samples from Debug Builds

## Unix x64 Expression

<b>C function definition</b>
```
  DR_DEFINE_ANNOTATION(char, dynamorio_annotate_running_on_dynamorio, (), return 0)
```

<b>C macro</b> for definition of `dynamorio_annotate_running_on_dynamorio()`:
```
#define LABEL_REFERENCE_LENGTH "0x11"
#define LABEL_REFERENCE_REGISTER "%rax"
#define ANNOTATION_FUNCTION_CLOBBER_LIST "%rax","%rcx","%rdx","%rsi","%rdi","%r8","%r9"
#define _CALL_TYPE
#define DR_ANNOTATION_ATTRIBUTES \
    __attribute__((noinline, visibility("hidden") _CALL_TYPE))
#define DR_DEFINE_ANNOTATION(return_type, annotation, parameters, body) \
    const char *annotation##_label = "dynamorio-annotation:"#annotation; \
    DR_ANNOTATION_ATTRIBUTES return_type annotation parameters \
    { \
        __label__ native_run, native_end_marker; \
        extern const char *annotation##_label; \
        __asm__ volatile goto (".byte 0xeb; .byte "LABEL_REFERENCE_LENGTH"; \
                               mov _GLOBAL_OFFSET_TABLE_,%"LABEL_REFERENCE_REGISTER"; \
                               bsr "#annotation"_label@GOT,%"LABEL_REFERENCE_REGISTER"; \
                               jmp %l0;" \
                               ::: ANNOTATION_FUNCTION_CLOBBER_LIST \
                               : native_run); \
        goto native_end_marker; \
        native_run: body; \
        native_end_marker: ; \
    }
```

<b>ASM</b> for `dynamorio_annotate_running_on_dynamorio()`:
```
  40213e:   55                      push   %rbp                       # function preamble
  40213f:   48 89 e5                mov    %rsp,%rbp
  402142:   eb 11                   jmp    402155                     # jump to native version
  402144:   48 8b 04 25 b8 0e 20    mov    0x200eb8,%rax              # GOT offset from (%rip + 4)
  40214b:   00
  40214c:   48 0f bd 04 25 b0 ff    bsr    0xffffffffffffffb0,%rax    # annotation name offset in GOT
  402153:   ff ff                                                     # `bsr` indicates function tag
  402155:   eb 02                   jmp    402159
  402157:   eb 07                   jmp    402160
  402159:   b8 00 00 00 00          mov    $0x0,%eax                  # native version
  40215e:   eb 00                   jmp    402160
  402160:   5d                      pop    %rbp
  402161:   c3                      retq
```

## Unix x64 Statement

<b>C code</b>
```
  TEST_ANNOTATION_SET_MODE(init->id, MODE_1,
  {
      printf("Mode 1 on %d\n", init->id); // native version
  });
```

<b>C macro</b> for `TEST_ANNOTATION_SET_MODE()`:
```
#define LABEL_REFERENCE_LENGTH "0x11"
#define LABEL_REFERENCE_REGISTER "%rax"
#define ANNOTATION_FUNCTION_CLOBBER_LIST "%rax","%rcx","%rdx","%rsi","%rdi","%r8","%r9"
#define DR_ANNOTATION_OR_NATIVE(annotation, native_version, ...) \
({ \
    __label__ native_run, native_end_marker; \
    extern const char *annotation##_label; \
    __asm__ volatile goto (".byte 0xeb; .byte "LABEL_REFERENCE_LENGTH"; \
                            mov _GLOBAL_OFFSET_TABLE_,%"LABEL_REFERENCE_REGISTER"; \
                            bsf "#annotation"_label@GOT,%"LABEL_REFERENCE_REGISTER"; \
                            jmp %l0;" \
                            ::: LABEL_REFERENCE_REGISTER \
                            : native_run); \
    annotation(__VA_ARGS__); \
    goto native_end_marker; \
    native_run: native_version; \
    native_end_marker: ; \
})
#define TEST_ANNOTATION_SET_MODE(context_id, mode, native_version) \
    DR_ANNOTATION_OR_NATIVE(test_annotation_set_mode, native_version, context_id, mode)
```

<b>ASM</b> for annotated call to `TEST_ANNOTATION_SET_MODE()`:
```
  401b60:   eb 11                   jmp    401b73 <main+0x7e6>      # jump over the annotation name reference
  401b62:   48 8b 04 25 9a 14 20    mov    0x20149a,%rax            # GOT offset from %eip
  401b69:   00
  401b6a:   48 0f bc 04 25 e0 ff    bsf    0xffffffffffffffe0,%rax  # offset of name reference within GOT (bsf indicates call site tag)
  401b71:   ff ff
  401b73:   eb 14                   jmp    401b89 <main+0x7fc>      # jump to the native version
  401b75:   8b 05 e5 15 20 00       mov    0x2015e5(%rip),%eax      # annotation args
  401b7b:   be 01 00 00 00          mov    $0x1,%esi
  401b80:   89 c7                   mov    %eax,%edi
  401b82:   e8 20 06 00 00          callq  4021a7                   # annotation call
  401b87:   eb 17                   jmp    401ba0
  401b89:   8b 05 d1 15 20 00       mov    0x2015d1(%rip),%eax      # native version
  401b8f:   89 c6                   mov    %eax,%esi
  401b91:   bf b2 25 40 00          mov    $0x4025b2,%edi
  401b96:   b8 00 00 00 00          mov    $0x0,%eax
  401b9b:   e8 f0 f5 ff ff          callq  401190 <printf@plt>
  401ba0:   c7 45 e8 00 00 00 00    movl   $0x0,-0x18(%rbp)         # app code...
```

## Unix x86 Expression

<b>C function definition</b>
```
  DR_DEFINE_ANNOTATION(char, dynamorio_annotate_running_on_dynamorio, (), return 0)
```

<b>C macro</b> for definition of `dynamorio_annotate_running_on_dynamorio()`:
```
#define LABEL_REFERENCE_LENGTH "0xc"
#define LABEL_REFERENCE_REGISTER "%eax"
#define ANNOTATION_FUNCTION_CLOBBER_LIST "%rax","%rcx","%rdx"
#define _CALL_TYPE , fastcall
#define DR_ANNOTATION_ATTRIBUTES \
    __attribute__((noinline, visibility("hidden") _CALL_TYPE))
#define DR_DEFINE_ANNOTATION(return_type, annotation, parameters, body) \
    const char *annotation##_label = "dynamorio-annotation:"#annotation; \
    DR_ANNOTATION_ATTRIBUTES return_type annotation parameters \
    { \
        __label__ native_run, native_end_marker; \
        extern const char *annotation##_label; \
        __asm__ volatile goto (".byte 0xeb; .byte "LABEL_REFERENCE_LENGTH"; \
                               mov _GLOBAL_OFFSET_TABLE_,%"LABEL_REFERENCE_REGISTER"; \
                               bsr "#annotation"_label@GOT,%"LABEL_REFERENCE_REGISTER"; \
                               jmp %l0;" \
                               ::: ANNOTATION_FUNCTION_CLOBBER_LIST \
                               : native_run); \
        goto native_end_marker; \
        native_run: body; \
        native_end_marker: ; \
    }
```

<b>ASM</b> for `dynamorio_annotate_running_on_dynamorio()`:
```
 8049b68:   55                      push   %ebp              # function preamble
 8049b69:   89 e5                   mov    %esp,%ebp
 8049b6b:   eb 0c                   jmp    8049b79           # jump to native version
 8049b6d:   a1 93 24 00 00          mov    0x2493,%eax       # GOT offset from (%rip + 4)
 8049b72:   0f bd 05 d8 ff ff ff    bsr    0xffffffd8,%eax   # annotation name offset in GOT
 8049b79:   eb 02                   jmp    8049b7d           # intermediate jump to native version
 8049b7b:   eb 07                   jmp    8049b84           # jump over native version
 8049b7d:   b8 00 00 00 00          mov    $0x0,%eax         # native version
 8049b82:   eb 00                   jmp    8049b84
 8049b84:   5d                      pop    %ebp
 8049b85:   c3                      ret
```

## Unix x86 Statement

<b>C code</b>
```
  TEST_ANNOTATION_SET_MODE(init->id, MODE_1,
  {
      printf("Mode 1 on %d\n", init->id); // native version
  });
```

<b>C macro</b> for `TEST_ANNOTATION_SET_MODE()`:
```
#define LABEL_REFERENCE_LENGTH "0xc"
#define LABEL_REFERENCE_REGISTER "%eax"
#define ANNOTATION_FUNCTION_CLOBBER_LIST "%rax","%rcx","%rdx"
#define DR_ANNOTATION_OR_NATIVE(annotation, native_version, ...) \
({ \
    __label__ native_run, native_end_marker; \
    extern const char *annotation##_label; \
    __asm__ volatile goto (".byte 0xeb; .byte "LABEL_REFERENCE_LENGTH"; \
                            mov _GLOBAL_OFFSET_TABLE_,%"LABEL_REFERENCE_REGISTER"; \
                            bsf "#annotation"_label@GOT,%"LABEL_REFERENCE_REGISTER"; \
                            jmp %l0;" \
                            ::: LABEL_REFERENCE_REGISTER \
                            : native_run); \
    annotation(__VA_ARGS__); \
    goto native_end_marker; \
    native_run: native_version; \
    native_end_marker: ; \
})
#define TEST_ANNOTATION_SET_MODE(context_id, mode, native_version) \
    DR_ANNOTATION_OR_NATIVE(test_annotation_set_mode, native_version, context_id, mode)
```

<b>ASM</b> for annotated call to `TEST_ANNOTATION_SET_MODE()`:
```
 8049610:   eb 0c                   jmp    804961e <main+0x6f1>  # jump over the annotation name reference
 8049612:   a1 ee 29 00 00          mov    0x29ee,%eax           # GOT offset from %eip
 8049617:   0f bc 05 f0 ff ff ff    bsf    0xfffffff0,%eax       # offset of name reference within GOT (bsf indicates call site tag)
 804961e:   eb 13                   jmp    8049633 <main+0x706>  # jump to the native version
 8049620:   a1 b8 c0 04 08          mov    0x804c0b8,%eax        # annotation args
 8049625:   ba 01 00 00 00          mov    $0x1,%edx
 804962a:   89 c1                   mov    %eax,%ecx
 804962c:   e8 92 05 00 00          call   8049bc3               # annotation call
 8049631:   eb 15                   jmp    8049648 <main+0x71b>  # jump over the native version
 8049633:   a1 b8 c0 04 08          mov    0x804c0b8,%eax        # native version
 8049638:   89 44 24 04             mov    %eax,0x4(%esp)
 804963c:   c7 04 24 9a 9f 04 08    movl   $0x8049f9a,(%esp)
 8049643:   e8 88 f6 ff ff          call   8048cd0 <printf@plt>
 8049648:   c7 45 e8 00 00 00 00    movl   $0x0,-0x18(%ebp)      # app code...
```

## Windows x64 Expression

<b>C function definition</b>
```
  DR_DEFINE_ANNOTATION(char, dynamorio_annotate_running_on_dynamorio, (), return 0)
```

<b>C macro</b> for definition of `dynamorio_annotate_running_on_dynamorio()`:
```
#define DR_DEFINE_ANNOTATION_LABELS(annotation) \
    const char *annotation##_expression_label = "dynamorio-annotation:expression:"#annotation; \
    const char *annotation##_statement_label = "dynamorio-annotation:statement:"#annotation;
#define DR_DEFINE_ANNOTATION(return_type, annotation, parameters, body) \
    DR_DEFINE_ANNOTATION_LABELS(annotation) \
    return_type __fastcall annotation parameters \
    { \
        DR_ANNOTATION_FUNCTION(annotation, body) \
    }
```

<b>C macro</b> for function tag of `dynamorio_annotate_running_on_dynamorio()`:
```
#define DR_ANNOTATION_FUNCTION(annotation, body) \
    if (GET_RETURN_PTR() == (void *) 0) { \
        extern const char *annotation##_expression_label; \
        __int2c(); \
        _m_prefetchw(annotation##_expression_label); \
        __debugbreak(); \
    } else { \
        body; \
    }
```

<b>ASM</b> for annotation in `dynamorio_annotate_running_on_dynamorio()`:
```
  0000000140001FF0: 48 8D 04 24        lea         rax,[# _AddressOfReturnAddress()
  0000000140001FF4: 48 85 C0           test        rax,rax
  0000000140001FF7: 75 0F              jne         0000000140002008   # jump to the native version
  0000000140001FF9: CD 2C              int         2Ch                # detection hint
  0000000140001FFB: 48 8B 05 FE BF 02  mov         rax,qword ptr [dynamorio_annotate_running_on_dynamorio_expression_label](rsp])
                    00
  0000000140002002: 0F 0D 08           prefetchw   [# (guarantee that the label variable gets used)
  0000000140002005: CC                 int         3                  # (discourage compiler reorderings)
  0000000140002006: EB 02              jmp         000000014000200A   # jump over the native version
  0000000140002008: 32 C0              xor         al,al              # native version (return 0)
  000000014000200A: F3 C3              rep ret
```

## Windows x64 Statement

<em>C code</em>
```
  TEST_ANNOTATION_SET_MODE(init->id, MODE_1,
  {
      printf("Mode 1 on %d\n", init->id); // native version
  });
```

<em>C macro</em> for `TEST_ANNOTATION_SET_MODE()`:
```
#define DR_ANNOTATION_OR_NATIVE(annotation, native_version, ...) \
do { \
    if ((unsigned __int64) GET_RETURN_PTR() > (0xfffffffffffffff1 - (2 * __LINE__))) { \
        extern const char *annotation##_statement_label; \
        __int2c(); \
        _m_prefetchw(annotation##_statement_label); \
        __debugbreak(); \
        annotation(__VA_ARGS__); \
    } else { \
        native_version; \
    } \
} while ((unsigned __int64) GET_RETURN_PTR() > (0xfffffffffffffff0 - (2 * __LINE__)))
#define TEST_ANNOTATION_SET_MODE(context_id, mode, native_version) \
    DR_ANNOTATION_OR_NATIVE(test_annotation_set_mode, native_version, context_id, mode)
```

<em>ASM</em> for annotated call to `TEST_ANNOTATION_SET_MODE()`:
```
  00000001400019B6: 48 8D 84 24 C8 00  lea         rax,[rsp+0C8h](rax])           # _AddressOfReturnAddress() (annotation head)
                    00 00
  00000001400019BE: 48 3D EF FD FF FF  cmp         rax,0FFFFFFFFFFFFFDEFh
  00000001400019C4: 76 1F              jbe         00000001400019E5         # jump to the native version (always taken)
  00000001400019C6: CD 2C              int         2Ch                      # detection hint
  00000001400019C8: 48 8B 05 41 C8 02  mov         rax,qword ptr [00
  00000001400019CF: 0F 0D 08           prefetchw   [rax](test_annotation_set_mode_statement_label])                       # (guarantee that the label variable gets used)
  00000001400019D2: CC                 int         3                           # (discourage compiler reorderings)
  00000001400019D3: BA 01 00 00 00     mov         edx,1                       # annotations args
  00000001400019D8: 8B 0D 82 E7 02 00  mov         ecx,dword ptr [# (arbitrary code may appear among the args)
  00000001400019DE: E8 8D 06 00 00     call        test_annotation_set_mode    # annotation call
  00000001400019E3: EB 12              jmp         00000001400019F7            # jump over the native version
  00000001400019E5: 8B 15 75 E7 02 00  mov         edx,dword ptr [140030160h](140030160h])  # native version--calls printf()
  00000001400019EB: 48 8D 0D 56 26 02  lea         rcx,[00
  00000001400019F2: E8 5D 0C 00 00     call        printf
  00000001400019F7: 48 8D 84 24 C8 00  lea         rax,[rsp+0C8h](??_C@_0O@NICOHPLL@Mode?51?5on?5?$CFd?6?$AA@])           # _AddressOfReturnAddress() (annotation tail)
                    00 00
  00000001400019FF: 48 3D EE FD FF FF  cmp         rax,0FFFFFFFFFFFFFDEEh
  0000000140001A05: 77 AF              ja          00000001400019B6         # loopback to annotation head (never taken)
  0000000140001A07: C7 44 24 50 00 00  mov         dword ptr [# app code...
                    00 00
```

## Windows x86 Expression

<em>C function definition</em>
```
  DR_DEFINE_ANNOTATION(char, dynamorio_annotate_running_on_dynamorio, (), return 0)
```

<em>C macro</em> for definition of `dynamorio_annotate_running_on_dynamorio()`:
```
#define DR_DEFINE_ANNOTATION(return_type, annotation, parameters, body) \
    DR_DEFINE_ANNOTATION_LABELS(annotation) \
    return_type __fastcall annotation parameters \
    { \
        DR_ANNOTATION_FUNCTION(annotation, body) \
    }
```

<em>C macro</em> for function tag of `dynamorio_annotate_running_on_dynamorio()`:
```
#define DR_ANNOTATION_FUNCTION_INSTANCE(unique_id, annotation, body) \
    __asm { \
        __asm _emit 0xeb \
        __asm _emit 0x06 \
        __asm mov eax, annotation##_label \
        __asm nop \
        __asm jmp PASTE(native_run, unique_id) \
    } \
    goto PASTE(native_end_marker, unique_id); \
    PASTE(native_run, unique_id): body; \
    PASTE(native_end_marker, unique_id): ;
#define DR_ANNOTATION_FUNCTION(annotation, body) \
    DR_ANNOTATION_FUNCTION_INSTANCE(__COUNTER__, annotation, body)
```

<em>ASM</em> for `dynamorio_annotate_running_on_dynamorio()`:
```
  00401990: 55                 push        ebp
  00401991: 8B EC              mov         ebp,esp
  00401993: EB 06              jmp         0040199B   # jump over annotation
  00401995: A1 00 B0 42 00     mov         eax,dword ptr [_dynamorio_annotate_running_on_dynamorio_label](rsp+50h],0)
  0040199A: 90                 nop
  0040199B: EB 02              jmp         0040199F   # jump to native version
  0040199D: EB 02              jmp         004019A1   # jump over native version
  0040199F: 32 C0              xor         al,al      # native version
  004019A1: 5D                 pop         ebp
  004019A2: C3                 ret
```

## Windows x86 Statement

<b>C code</b>
```
  TEST_ANNOTATION_SET_MODE(init->id, MODE_1,
  {
      printf("Mode 1 on %d\n", init->id); // native version
  });
```

<b>C macro</b> for `TEST_ANNOTATION_SET_MODE()`:
```
#define DR_ANNOTATION_OR_NATIVE(annotation, native_version, ...) \
    { \
        extern const char *annotation##_name; \
        __asm { \
            __asm _emit 0xeb \
            __asm _emit 0x06 \
            __asm mov eax, annotation##_name \
            __asm _emit 0x01 \
            __asm jmp PASTE(native_execution_, __LINE__) \
            __asm jmp PASTE(native_end_marker_, __LINE__) \
        } \
        annotation(__VA_ARGS__); \
        PASTE(native_execution_, __LINE__) : native_version; \
        PASTE(native_end_marker_, __LINE__): ; \
    }
#define TEST_ANNOTATION_SET_MODE(context_id, mode, native_version) \
    DR_ANNOTATION_OR_NATIVE(test_annotation_set_mode, native_version, context_id, mode)
```

<b>ASM</b> for annotated call to `TEST_ANNOTATION_SET_MODE()`:
```
  00401782: EB 06              jmp         0040178A
  00401784: A1 BC B0 42 00     mov         eax,dword ptr [00401789: 58                 pop         eax        # indicates call site tag (avoids EB 05, which is common in windows core libs)
  0040178A: EB 12              jmp         0040179E                              # jump to the native version
  0040178C: BA 01 00 00 00     mov         edx,1                                 # annotation args
  00401791: 8B 0D 70 C7 42 00  mov         ecx,dword ptr ds:[42C770h](_test_annotation_set_mode_label])
  00401797: E8 96 F8 FF FF     call        @ILT+45(@test_annotation_set_mode@8)  # annotation call
  0040179C: EB 14              jmp         004017B2                              # jump over the native version
  0040179E: 8B 0D 70 C7 42 00  mov         ecx,dword ptr ds:[# native version
  004017A4: 51                 push        ecx
  004017A5: 68 80 3F 42 00     push        offset ??_C@_0O@NICOHPLL@Mode?51?5on?5?$CFd?6?$AA@
  004017AA: E8 BB 09 00 00     call        _printf
  004017AF: 83 C4 08           add         esp,8
  004017B2: C7 45 FC 00 00 00  mov         dword ptr [ebp-4](42C770h]),0                   # app code...
            00
```

# Samples of Special Cases

## Nested annotations: Windows x64 (/Ox /GL)

<b>C code</b> for nested annotations
```
static __inline int
annotated_function()
{
    NOTE2(7, 8);
    return 9;
}

int main(void)
{
    NOTE1(1, 2, annotated_function());
}
```

<b>ASM</b> for nested annotations:
```
  000000014000F936: 48 8D 5C 24 28     lea         rbx,[# _AddressOfReturnAddress()
  000000014000F93B: 0F 1F 44 00 00     nop         dword ptr [rax+rax](rsp+28h])
  000000014000F940: 48 81 FB 6D FF FF  cmp         rbx,0FFFFFFFFFFFFFF6Dh     # NOTE1 head
                    FF
  000000014000F947: 76 44              jbe         000000014000F98D           # target is NOTE1 tail
  000000014000F949: CD 2C              int         2Ch                        # annotation hint
  000000014000F94B: 0F 0D 0D 9E A9 00  prefetchw   [# operand is ((char *) NOTE1 label)
                    00
  000000014000F952: CC                 int         3                          # (discourage compiler reorderings)
  000000014000F953: 48 81 FB 79 FF FF  cmp         rbx,0FFFFFFFFFFFFFF79h     # NOTE2 head
                    FF
  000000014000F95A: 76 17              jbe         000000014000F973           # target is NOTE2 tail
  000000014000F95C: CD 2C              int         2Ch                        # annotation hint
  000000014000F95E: 0F 0D 0D DB A9 00  prefetchw   [14001A340h](14001A2F0h])
                    00
  000000014000F965: CC                 int         3                          # (discourage compiler reorderings)
  000000014000F966: BA 08 00 00 00     mov         edx,8                      # NOTE2 args
  000000014000F96B: 8D 4A FF           lea         ecx,[000000014000F96E: E8 9D 00 00 00     call        note2
  000000014000F973: 48 81 FB 78 FF FF  cmp         rbx,0FFFFFFFFFFFFFF78h     # NOTE2 tail
                    FF
  000000014000F97A: 77 D7              ja          000000014000F953
  000000014000F97C: BA 02 00 00 00     mov         edx,2                      # NOTE1 args
  000000014000F981: 44 8D 42 07        lea         r8d,[rdx+7](rdx-1])
  000000014000F985: 8D 4A FF           lea         ecx,[000000014000F988: E8 B3 00 00 00     call        note1
  000000014000F98D: 48 81 FB 6C FF FF  cmp         rbx,0FFFFFFFFFFFFFF6Ch     # NOTE1 tail
                    FF
  000000014000F994: 77 AA              ja          000000014000F940
  000000014000F996: 33 C0              xor         eax,eax                    # app code...
```

## Nested annotations with shared label: Windows x64 (/Ox /GL)

<em>C code</em> for nested annotations with shared label
```
INLINE double Triangle::get_b()
{
    TEST_ANNOTATION_TWO_ARGS(__LINE__, (unsigned int) get_c(), {
        printf("Native two-args in Triangle::get_b()\n");
    });

    return lengths[1](rdx-1]);
}

INLINE double Triangle::get_c()
{
    TEST_ANNOTATION_TWO_ARGS(__LINE__, (unsigned int) get_a(), {
        printf("Native two-args in Triangle::get_c()\n");
    });
    TEST_ANNOTATION_THREE_ARGS(__LINE__, 0x77, 0x7890);

    return lengths[}
```

<em>ASM</em> for nested annotations with shared label
```
  00000001400011AD: 48 8D 7C 24 28     lea         rdi,[rsp+28h](2];)             # _AddressOfReturnAddress()
  00000001400011B2: 48 81 FF D9 FE FF  cmp         rdi,0FFFFFFFFFFFFFED9h
                    FF
  00000001400011B9: 76 79              jbe         0000000140001234          # outer annotation head
  00000001400011BB: CD 2C              int         2Ch                       # outer annotation hint
  00000001400011BD: 48 8B 05 84 FE 02  mov         rax,qword ptr [# shared!!
                    00
  00000001400011C4: 0F 0D 08           prefetchw   [rax](test_annotation_two_args_statement_label])                     # outer annotation label use
  00000001400011C7: CC                 int         3                         # (discourage compiler reorderings)
  00000001400011C8: 0F 1F 84 00 00 00  nop         dword ptr [# (compiler padded)
                    00 00
  00000001400011D0: 48 81 FF C7 FE FF  cmp         rdi,0FFFFFFFFFFFFFEC7h    # inner annotation head
                    FF
  00000001400011D7: 76 18              jbe         00000001400011F1
  00000001400011D9: CD 2C              int         2Ch                       # inner annotation hint
  00000001400011DB: 0F 0D 08           prefetchw   [rax](rax+rax])                     # inner annotation uses shared label
  00000001400011DE: CC                 int         3                         # (discourage compiler reorderings)
  00000001400011DF: F2 48 0F 2C 53 08  cvttsd2si   rdx,mmword ptr [# inner annotation args
  00000001400011E5: B9 95 00 00 00     mov         ecx,95h
  00000001400011EA: E8 A1 02 00 00     call        test_annotation_two_args  # inner annotation call
  00000001400011EF: EB 0C              jmp         00000001400011FD          # inner annotation jump over native version
  00000001400011F1: 48 8D 0D 50 B2 02  lea         rcx,[??_C@_0CG@OGPOCELO@Native?5two?9args?5in?5Triangle?3?3get@](rbx+8])
                    00                                                       # inner annotation native version
  00000001400011F8: E8 07 08 00 00     call        printf
  00000001400011FD: 48 81 FF C6 FE FF  cmp         rdi,0FFFFFFFFFFFFFEC6h
                    FF
  0000000140001204: 76 09              jbe         000000014000120F          # jump over inner annotation tail
  0000000140001206: 48 8B 05 3B FE 02  mov         rax,qword ptr [00                                                       # inner annotation tail
  000000014000120D: EB C1              jmp         00000001400011D0
  000000014000120F: BA 77 00 00 00     mov         edx,77h                   # inner three-arg expression args
  0000000140001214: 41 B8 90 78 00 00  mov         r8d,7890h
  000000014000121A: 8D 4A 1F           lea         ecx,[rdx+1Fh](test_annotation_two_args_statement_label])
  000000014000121D: E8 9E 02 00 00     call        test_annotation_three_args  # inner three-arg expression call
  0000000140001222: B9 8C 00 00 00     mov         ecx,8Ch                   # outer annotation args
  0000000140001227: F2 48 0F 2C 53 18  cvttsd2si   rdx,mmword ptr [000000014000122D: E8 5E 02 00 00     call        test_annotation_two_args  # outer annotation call
  0000000140001232: EB 0C              jmp         0000000140001240          # jump over native version
  0000000140001234: 48 8D 0D E5 B1 02  lea         rcx,[??_C@_0CG@NLJOANAO@Native?5two?9args?5in?5Triangle?3?3get@](rbx+18h])
                    00
  000000014000123B: E8 C4 07 00 00     call        printf
  0000000140001240: 48 81 FF D8 FE FF  cmp         rdi,0FFFFFFFFFFFFFED8h    # outer annotation tail
                    FF
  0000000140001247: 0F 87 65 FF FF FF  ja          00000001400011B2
```

# Detection Algorithms

## Unix

  - For each ubr with exact byte sequence "`EB XX`" (where "`XX`" is "`11`" on x64 and "`0c`" on x86)
    - `TRY_EXCEPT`:
      - Attempt to read the operands of the next 2 instructions as `(GOT + offset)`
        - The first instruction (referring to `GOT`) must be a `mov`
          - The only src operand must be base/disp
        - The second instruction (referring to `offset`) must be a `bsr` or `bsf`
          - The only src operand must be base/disp
      - If the `(GOT + offset)` can be dereferenced as `**(const char ***)`, and the string matches `"dynamorio-annotation:(.*)"`
        - The name of the annotation is the first regex group of the `(GOT + offset)` match
        - If the `offset` instruction was `bsr`, the code sequence is an expression (appearing at the top of an annotation function body)
        - If the `offset` instruction was `bsf`, the code sequence is a statement (appearing at an annotation site)
        - The current instruction will be a jump to the native version, and the following instruction will be the <b>instrumentation pc</b>
    - On `EXCEPT`: clean up resources and ignore any annotations found

## Windows x86

  - For each ubr with exact byte sequence "`EB 06`"
    - `TRY_EXCEPT`:
    - Attempt to read the operand of the next instruction as a memory reference
      - The instruction must be a `mov`
        - The only src operand must be base/disp
    - If the operand can be dereferenced as `*(const char **)`, and the resulting string matches `"dynamorio-annotation:(.*)"`
      - The name of the annotation is the first regex group of the match
      - Skip the next 1-byte instruction
        - If it is "`nop`" (`0x90`), the code sequence appears at the top of an annotation function body
        - If it is "`pop eax`" (`0x58`), the code sequence appears at an annotation site
      - The current instruction will be a jump to the native version, and the following instruction will be the <b>instrumentation pc</b>
    - On `EXCEPT`: clean up resources and ignore any annotations found

## Windows x64

  - For each cbr
    - If `(bb->checked_end == bb->cur_pc)`, execute a safe read of 1 byte; otherwise just read the byte
      - Return if the safe read is attempted and fails
    - Compare the byte to "`CD`" (interrupt)
      - *Note: the interrupt should never execute, but this needs to be verified for C# and VB apps*
      - `TRY_EXCEPT`:
      - Attempt to read the operand of the next instruction as a memory reference
        - The instruction may be a `mov` or a `prefetchw`
          - The only src operand must be rel addr
      - If the operand can be dereferenced as `*(const char **)`, and the resulting string matches `"dynamorio-annotation:(.**)"`
        - Match the first regex group (i.e., above) against a second regex `"(.**):(.*)"`
          - If the first group of the second regex matches "expression", the code sequence appears at the top of an annotation function body
          - If the first group of the second regex matches "statement", the code sequence appears at an annotation site
        - Skip arbitrary instructions past the next "`int 3`" (there should usually just be one intervening instruction)
          - Memo the current pc as the <b>instrumentation pc</b>
          - If the next 2 instructions are "`<cbr>; int 2c`", repeat "skip arbitrary instructions..."
      - On `EXCEPT`: clean up resources and ignore any annotations found

# Instrumentation Algorithms

## Expression

<em>Occurs at the top of an annotation function body</em>

  - For each annotation handler registered for this annotation (by name)
    - insert a clean call to the handler at the <b>instrumentation pc</b> (as identified by the Detection Algorithms above)
    - terminate the basic block

## Statement

<em>Occurs at an annotation site</em>

  - Skip translation of the annotation header
  - Resume translation at the <b>instrumentation pc</b> (as identified by the Detection Algorithms above)
    - Do not terminate the basic block at this point

Arbitrary code can appear within the annotation statement body, for example when the compiler inlines
a call that appears in the annotation argument list, like this:

```
DYNAMORIO_SOME_ANNOTATION(foo(), bar());
```

Such inlined code can be very complex, including other calls and unrolled loops.
To simplify the instrumentation, the annotation statement body is translated into the code cache
without annotation-specific introspection. Instead of attempting to insert a clean call in place
of the annotation function call (which occurs inside the annotation statement body), that call is
translated like any other. The clean calls for registered annotation handlers are only inserted
at the top of the annotation function body (see above).

 ****************************************************************************
 */
