|
| 1 | +--- |
| 2 | +title: Implement NatVis custom intrinsic function |
| 3 | +description: Learn how to use the Natvis framework to implement a custom intrinsic function. |
| 4 | +ms.date: 01/09/2025 |
| 5 | +ms.topic: how-to |
| 6 | +f1_keywords: |
| 7 | + - natvis, intrinsic function |
| 8 | +dev_langs: |
| 9 | + - C++ |
| 10 | +author: mikejo5000 |
| 11 | +ms.author: mikejo |
| 12 | +manager: mijacobs |
| 13 | +ms.subservice: debug-diagnostics |
| 14 | +--- |
| 15 | + |
| 16 | +# Implement NatVis custom intrinsic function for C++ |
| 17 | + |
| 18 | +In this article, you learn about the guidelines for implementing a custom intrinsic function within a NatVis visualization. For more information about NatVis, see [Create custom views of C++ objects](../debugger/create-custom-views-of-native-objects.md). |
| 19 | + |
| 20 | +## Syntax |
| 21 | + |
| 22 | +A NatVis file may define an intrinsic function using the following syntax: |
| 23 | + |
| 24 | +```xml |
| 25 | +<Intrinsic Name="Func" Expression="arg + 1"> |
| 26 | + <Parameter Name="arg" Type="int" /> |
| 27 | +</Intrinsic> |
| 28 | +``` |
| 29 | + |
| 30 | +Once the definition exists, any debugger expression may call the function, like any other function. For example, using the preceding NatVis definition, the expression `Func(3)` evaluates to 4. |
| 31 | + |
| 32 | +An `<Intrinsic>` element may appear either on the file-level, or inside a `<Type>` element, before any other elements. Intrinsic functions defined within a `<Type>` define member functions of that type, while intrinsic functions defined outside a `<Type>` define global functions. For example: |
| 33 | + |
| 34 | +```xml |
| 35 | +<?xml version="1.0" encoding="utf-8"?> |
| 36 | +<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010"> |
| 37 | + <Type Name="std::vector<*>"> |
| 38 | + <Intrinsic Name="size" Expression="_Mypair._Myval2._Mylast - _Mypair._Myval2._Myfirst" /> |
| 39 | + <Intrinsic Name="capacity" Expression="_Mypair._Myval2._Myend - _Mypair._Myval2._Myfirst" /> |
| 40 | + </Type> |
| 41 | + <Intrinsic Name="LOWORD" Expression="arg & 0xFFFF"> |
| 42 | + <Parameter Name="arg" Type="unsigned int" /> |
| 43 | + </Intrinsic> |
| 44 | +</AutoVisualizer> |
| 45 | +``` |
| 46 | + |
| 47 | +In the preceding example, `size()` and `capacity()` are defined as member functions of the `std::vector` class, |
| 48 | +so whenever an expression evaluates `vector.size()`, it will actually evaluate |
| 49 | +`vector._Mypair._Myval2._Mylast - vector._Mypair._Myval2._Myfirst`, rather than perform a func-eval. |
| 50 | +Similarly, `LOWORD(0x12345678)` returns `0x5678`, also without func-eval. |
| 51 | + |
| 52 | +For another example, see the [Intrinsic expansion](../debugger/create-custom-views-of-native-objects.md#intrinsic-expansion). |
| 53 | + |
| 54 | +## Guidelines for using an intrinsic function |
| 55 | + |
| 56 | +Be aware of the following guidelines when using an intrinsic function: |
| 57 | + |
| 58 | +- Intrinsic functions may be overloaded, either with PDB-defined functions, or with each other. |
| 59 | + |
| 60 | +- When an intrinsic function conflicts with a PDB-defined function with the same name and argument list, the intrinsic function will win. You can't func-eval the PDB function if an equivalent intrinsic function exists. |
| 61 | + |
| 62 | +- You can't take the address of an intrinsic function; you can only call it. |
| 63 | + |
| 64 | +- Intrinsic member functions must belong to the default view of the respective type in order to be evaluated in an expression. For example, a type entry with an `IncludeView` constraint may not specify an intrinsic function. |
| 65 | + |
| 66 | +- Intrinsic functions may be called from any expression, including NatVis expressions. Intrinsic functions may also call each other. However, intrinsic functions that use recursion are currently not supported. For example: |
| 67 | + |
| 68 | + ```xml |
| 69 | + <!-- OK --> |
| 70 | + <Intrinsic Name="Func2" Expression="this->Func3(arg + 1)"> |
| 71 | + <Parameter Name="arg" Type="int" /> |
| 72 | + </Intrinsic> |
| 73 | + <Intrinsic Name="Func3" Expression="arg + 1"> |
| 74 | + <Parameter Name="arg" Type="int"/> |
| 75 | + </Intrinsic> |
| 76 | + |
| 77 | + <!-- Unsupported --> |
| 78 | + <Intrinsic Name="Func2" Expression="this->Func3(arg + 1)"> |
| 79 | + <Parameter Name="arg" Type="int" /> |
| 80 | + </Intrinsic> |
| 81 | + <Intrinsic Name="Func3" Expression="Func2(arg + 1)"> |
| 82 | + <Parameter Name="arg" Type="int"/> |
| 83 | + </Intrinsic> |
| 84 | + |
| 85 | + <!-- Also unsupported--> |
| 86 | + <Intrinsic Name="Fib" Expression="(n <= 1) ? 1 : Fib(n - 1) + Fib(n - 2)"> |
| 87 | + <Parameter Name="n" Type="int"/> |
| 88 | + </Intrinsic> |
| 89 | + ``` |
| 90 | + |
| 91 | +- By default, intrinsic functions are assumed to be side-effect free. That is, they can be called in contexts that disallow side effects, and the implementation expression isn't allowed to contain side effects. |
| 92 | + |
| 93 | + The definition can override this behavior by specifying the `SideEffect` attribute in the declaration. If the function is marked as having side effects, side effects in the implementation expression become permitted. However, invoking the function in contexts where side effects are prohibited is no longer permitted. |
| 94 | + |
| 95 | +- When the definitions of two intrinsic functions conflict with each other (same name, same signature), the last one wins (within the same file). |
| 96 | + |
| 97 | + Within different files, the instance in the file with higher priority wins (project is higher than user directory, which is higher than install directory). If a higher-priority definition contains an expression that does not parse, that definition is ignored, and the next-highest priority definition is used instead. |
| 98 | + |
| 99 | +## Guidelines to implement an Intrinsic function |
| 100 | + |
| 101 | +Intrinsic functions support two possible forms of implementation: |
| 102 | + |
| 103 | +- Expression-based |
| 104 | + |
| 105 | + The NatVis file defines an expression that evaluates to the return value of the function. The expression may use any arguments passed into it declared as `<Parameter>` elements. Functions defined within a class are also assumed to be "instance" functions, and may access the "this" pointer as well. |
| 106 | + |
| 107 | +- Extension-based |
| 108 | + |
| 109 | + The NatVis file provides instructions for invoking a debugger extension to actually evaluate the function. A debugger extension has full access to the Concord API, and has the ability to perform tasks that aren't possible within a NatVis expression. |
| 110 | + |
| 111 | +To provide an extension-based implementation, the `<Intrinsic>` element should omit the `Expression` attribute and, instead, provide `SourceId`, `LanguageId`, `Id`, and `ReturnType` attributes, as provided in the following example: |
| 112 | + |
| 113 | +```xml |
| 114 | +<Intrinsic Name="MyFunc" SourceId="a665fa54-6e7d-480e-a80b-1fc1202e9646" LanguageId="3a12d0b7-c26c-11d0-b442-00a0244a1dd2" Id="1000" ReturnType="double"> |
| 115 | + <Parameter Type="int" /> |
| 116 | + <Parameter Type="int" /> |
| 117 | + <Parameter Type="int" /> |
| 118 | +</Intrinsic> |
| 119 | +``` |
| 120 | + |
| 121 | +To implement the function, the debugger extension must implement the `IDkmIntrinsicFunctionEvaluator140` interface, using `LanguageId` and |
| 122 | +`SourceId` filters that match the corresponding values of the `<Intrinsic>` element in the NatVis file. When the function is called, the call translates into the component's `Execute()` method: |
| 123 | + |
| 124 | +```cpp |
| 125 | +STDMETHOD(Execute)( |
| 126 | + _In_ Evaluation::IL::DkmILExecuteIntrinsic* pExecuteIntrinsic, |
| 127 | + _In_ Evaluation::DkmILContext* pILContext, |
| 128 | + _In_ Evaluation::IL::DkmCompiledILInspectionQuery* pInspectionQuery, |
| 129 | + _In_ const DkmArray<Evaluation::IL::DkmILEvaluationResult*>& Arguments, |
| 130 | + _In_opt_ DkmReadOnlyCollection<Evaluation::DkmCompiledInspectionQuery*>* pSubroutines, |
| 131 | + _Out_ DkmArray<Evaluation::IL::DkmILEvaluationResult*>* pResults, |
| 132 | + _Out_ Evaluation::IL::DkmILFailureReason* pFailureReason |
| 133 | + ); |
| 134 | +``` |
| 135 | +
|
| 136 | +The component receives the bytes of each argument via the `Arguments` argument. If the function in question is a member function, |
| 137 | +the `this` pointer comes first, followed by the explicit arguments. The component should return the result by allocating |
| 138 | +a single-element array in `pResults`, storing the bytes of the return value. |
| 139 | +
|
| 140 | +Use the following guidelines to implement functions: |
| 141 | +
|
| 142 | +- It's illegal to "mix and match" the two implementation forms. That is, you can't include both an expression and a source ID. |
| 143 | +
|
| 144 | +- Specifying a return type for an expression-based implementation is allowed, but not required. If a return type is specified, the return type of the expression must exactly match it (no implicit casting allowed). If a return type isn't specified, the return type is inferred from the expression. Any extension-based implementation must state a return type in the NatVis file. |
| 145 | +
|
| 146 | +- Non-recursive calls to other intrinsic functions are allowed. Recursion isn't allowed. |
| 147 | +
|
| 148 | +- If the function has side effects, you must specify `SideEffect="true"` in the declaration. It's illegal for an expression-based |
| 149 | +implementation to have side effects in the expression without declaring the function to have side effects. Invoking an extension-based |
| 150 | +implementation to have side effects without declaring the function as having side effects is undefined behavior, and should be avoided. |
| 151 | +
|
| 152 | +- Varargs intrinsic functions are allowed. To declare a varargs function, specify `Varargs="true"` in the declaration. While it's legal for an expression-based implementation to declare a `vararg` function, currently, only extension-based implementations have a way to access the variable arguments. With an extension-based implementation, the `Execute()` function receives all the arguments that are actually passed in, not just the declared arguments. |
| 153 | +
|
| 154 | +- Intrinsic functions consuming a class/struct/union type as an argument type aren't supported. Returning a class/struct/union type is OK. (A pointer or reference to a class/struct/union type is OK as an argument type). |
| 155 | +
|
| 156 | +## Customize the icon for calls to intrinsic functions. |
| 157 | +
|
| 158 | +By default, when you call an intrinsic function, the expression is given the pink diamond icon in the **Watch** window associated with function calls. You can override this behavior by specifying the `Category` attribute using one of the following values: |
| 159 | +
|
| 160 | +- Method. Use the pink diamond icon, typically used with method calls (default). |
| 161 | +- Property. Use the black wrench icon, typically used with properties. |
| 162 | +- Data. Use the blue diamond icon, typically used with data. |
| 163 | +
|
| 164 | +By combining intrinsic functions with the `<Item>` element, it's possible to author a NatVis file where item expressions have the wrench property icon: |
| 165 | +
|
| 166 | +```xml |
| 167 | +<Type Name="MyClass"> |
| 168 | + <Intrinsic Name="GetValue" ReturnType="int" Expression="m_value" Category="Property" /> |
| 169 | + <Expand> |
| 170 | + <Item Name="Value">this->GetValue()</Item> |
| 171 | + </Expand> |
| 172 | +</Type> |
| 173 | +``` |
| 174 | + |
| 175 | +> [!NOTE] |
| 176 | +> Placing the icon choice on the function level, rather than the `<Item>` level, avoids issues where the icon customization is lost when the full name is evaluated. Because the full name includes a call to the function, it has the same icon customization as the `<Item>` itself. |
| 177 | +
|
0 commit comments