Use of $Super$$ and $Sub$$ to patch symbol definitions

An existing symbol cannot be modified if, for example, it is located in an external library or in ROM code. In such cases, you can use the $Super$$ and $Sub$$ patterns to patch an existing symbol.

To patch the definition of the function foo(), then $Sub$$foo and the original definition of foo() must be a global or weak definition:

$Super$$foo

Identifies the original unpatched function foo(). Use this pattern to call the original function directly.

$Sub$$foo

Identifies the new function that is called instead of the original function foo(). Use this pattern to add processing before or after the original function.

The $Sub$$ and $Super$$ linker mechanism can operate only on symbol definitions and references that are visible to the tool. For example, the compiler can replace a call to printf("Hello\n") with puts("Hello") in a C program. Only the reference to the symbol puts is visible to the linker, so defining $Sub$$printf does not redirect this call.

The $Sub$$ and $Super$$ mechanism interacts with C++ as follows:

• The $Sub$$ and $Super$$ mechanism works with functions and function templates.
• A $Sub$$ function cannot be defined for a function template specialization without defining it for the corresponding primary template.
• The $Sub$$ and $Super$$ mechanism works with member functions of classes and class templates, but requires the overriding function to be declared in the class definition.
• Using the $Sub$$ and $Super$$ mechanism with virtual member functions is unsupported.
• The demangler does not recognize names with $Sub$$ or $Super$$ prefixes, and does not affect the debug illusion. It is a library that converts C++ decorated symbols such as _Z3fooIiEvT_c into human-readable ones such as void foo<int>(int, char). The demangler does not work correctly with, for example, $Sub$$_Z3fooIiEvT_c, in which case the demangler retains the symbol unaltered.

Example

The following example shows how to use $Super$$ and $Sub$$ to insert a call to the function ExtraFunc() before the call to the legacy function foo().

extern void ExtraFunc(void);
extern void $Super$$foo(void);

/* this function is called instead of the original foo() */
void $Sub$$foo(void)
{
  ExtraFunc();    /* does some extra setup work */
  $Super$$foo();  /* calls the original foo() function */
                  /* To avoid calling the original foo() function
                   * omit the $Super$$foo(); function call.
                   */
}