3.6. Embedded C functions

General syntax:

function <name>:<type> ( <arg1>:<type>, ... ) %{ <C_stmts> %}

Embedded code is permitted in a function body. In that case, the script language body is replaced entirely by a piece of C code enclosed between %{ and %} markers. The enclosed code may do anything reasonable and safe as allowed by the parser.

There are a number of undocumented but complex safety constraints on concurrency, resource consumption and runtime limits that are applied to code written in the SystemTap language. These constraints are not applied to embedded C code, so use such code with caution as it is used verbatim. Be especially careful when dereferencing pointers. Use the kread() macro to dereference any pointers that could potentially be invalid or dangerous. If you are unsure, err on the side of caution and use kread(). The kread() macro is one of the safety mechanisms used in code generated by embedded C. It protects against pointer accesses that could crash the system.

For example, to access the pointer chain name = skb->dev->name in embedded C, use the following code.

struct net_device *dev;
char *name;
dev = kread(&(skb->dev));
name = kread(&(dev->name));

The memory locations reserved for input and output values are provided to a function using a macro named THIS . The following are examples.

function add_one (val) %{
THIS->__retvalue = THIS->val + 1;
}
function add_one_str (val) %{
strlcpy (THIS->__retvalue, THIS->val, MAXSTRINGLEN);
strlcat (THIS->__retvalue, "one", MAXSTRINGLEN);
}

The function argument and return value types must be inferred by the translator from the call sites in order for this method to work. You should examine C code generated for ordinary script language functions to write compatible embedded-C. Note that all SystemTap functions and probes run with interrupts disabled, thus you cannot call functions that might sleep from within embedded C.