Signed-off-by: Mathieu Desnoyers --- Documentation/condcall.txt | 60 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) Index: linux-2.6-lttng/Documentation/condcall.txt =================================================================== --- /dev/null 1970-01-01 00:00:00.000000000 +0000 +++ linux-2.6-lttng/Documentation/condcall.txt 2007-05-17 01:55:05.000000000 -0400 @@ -0,0 +1,60 @@ + Using the Conditional Calls + + Mathieu Desnoyers + + +This document introduces Conditional Calls and their use. + +* Purpose of conditional calls + +A conditional call is used to compile into the kernel a function call that is +disabled at compile-time. Then, at runtime, it can be enabled dynamically. As +explained below, the opposite can also be done. + + +* Usage + +In order to use the macro cond_call, you should include linux/condcall.h. + +#include + +Add, in your code : + +ret = cond_call(examplecondcall, myfunc(a, b)); + +Where : +- examplecondcall is the conditional call identifier +- myfunc(a, b) is a call to myfunc with valid parameters. +- "ret" is, optionally, the variable in which the return value of myfunc() must + be put. If the conditional call is disabled, ret will be set to 0 casted to + the type of the return value of myfunc(). + +Use cond_call_arm("examplecondcall") to activate the conditional call. + +Use cond_call_disarm("examplecondcall") to deactivate the conditional call. + +Use cond_call_query("examplecondcall") to query the conditional call state. + +The cond_call mechanism supports inserting multiple instances of the same +cond_call. Conditional calls can be put in inline functions, inlined static +functions, and unrolled loops. + + +* Optimization for a given architecture + +One can implement optimized conditional calls for a given architecture by +replacing asm-$ARCH/condcall.h. + +The CF_* flags can be used to control the type of conditional call. See the +include/linux/condcall.h header for the list of flags. They can be specified as +the first parameter of the _cond_call() macro, as in the following example, +which declares a cond_call enabled statically (which can be disabled/reenabled +dynamically) + +ret = _cond_call(CF_DEFAULT | CF_STATIC_ENABLE, examplecondcall, myfunc(a, b)); + +Another example of flag usage is to declare a cond_call that always uses the +generic version of the cond_calls. It can be useful to use this when cond_calls +are placed in kernel code presenting particular reentrancy challenges. + +ret = _cond_call(CF_DEFAULT & ~CF_OPTIMIZED, examplecondcall, myfunc(a, b)); -- Mathieu Desnoyers Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F BA06 3F25 A8FE 3BAE 9A68 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/