From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757062AbXE3OF0 (ORCPT ); Wed, 30 May 2007 10:05:26 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1756042AbXE3ODP (ORCPT ); Wed, 30 May 2007 10:03:15 -0400 Received: from smtp.polymtl.ca ([132.207.4.11]:46564 "EHLO smtp.polymtl.ca" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756043AbXE3ODL (ORCPT ); Wed, 30 May 2007 10:03:11 -0400 Message-Id: <20070530140229.082726276@polymtl.ca> References: <20070530140025.917261793@polymtl.ca> User-Agent: quilt/0.46-1 Date: Wed, 30 May 2007 10:00:32 -0400 From: Mathieu Desnoyers To: akpm@linux-foundation.org, linux-kernel@vger.kernel.org Cc: Mathieu Desnoyers Subject: [patch 7/9] Conditional Calls - Documentation Content-Disposition: inline; filename=conditional-calls-documentation.patch X-Poly-FromMTA: (dijkstra.casi.polymtl.ca [132.207.72.10]) at Wed, 30 May 2007 14:02:29 +0000 Sender: linux-kernel-owner@vger.kernel.org X-Mailing-List: linux-kernel@vger.kernel.org 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