[patch 08/38] CKRM e18: Documentation
From: Gerrit Huizenga
Date: Thu Jun 23 2005 - 02:23:34 EST
This patch adds all current documentation on CKRM.
Signed-Off-By: Hubertus Franke <frankeh@xxxxxxxxxx>
Signed-Off-By: Chandra Seetharaman <sekharan@xxxxxxxxxx>
Signed-Off-By: Shailabh Nagar <nagar@xxxxxxxxxx>
Signed-Off-By: Vivek Kashyap <vivk@xxxxxxxxxx>
Signed-Off-By: Gerrit Huizenga <gh@xxxxxxxxxx>
TODO | 16 +++++++++
ckrm_basics | 66 +++++++++++++++++++++++++++++++++++++++
core_usage | 72 +++++++++++++++++++++++++++++++++++++++++++
crbce | 33 +++++++++++++++++++
installation | 70 ++++++++++++++++++++++++++++++++++++++++++
rbce_basics | 67 ++++++++++++++++++++++++++++++++++++++++
rbce_usage | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
7 files changed, 422 insertions(+)
Index: linux-2.6.12-ckrm1/Documentation/ckrm/ckrm_basics
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.12-ckrm1/Documentation/ckrm/ckrm_basics 2005-06-20 13:08:35.000000000 -0700
@@ -0,0 +1,66 @@
+CKRM Basics
+-------------
+A brief review of CKRM concepts and terminology will help make installation
+and testing easier. For more details, please visit http://ckrm.sf.net.
+
+Currently there are two class types, taskclass and socketclass for grouping,
+regulating and monitoring tasks and sockets respectively.
+
+To avoid repeating instructions for each classtype, this document assumes a
+task to be the kernel object being grouped. By and large, one can replace task
+with socket and taskclass with socketclass.
+
+RCFS depicts a CKRM class as a directory. Hierarchy of classes can be
+created in which children of a class share resources allotted to
+the parent. Tasks can be classified to any class which is at any level.
+There is no correlation between parent-child relationship of tasks and
+the parent-child relationship of classes they belong to.
+
+Without a Classification Engine, class is inherited by a task. A privileged
+user can reassigned a task to a class as described below, after which all
+the child tasks under that task will be assigned to that class, unless the
+user reassigns any of them.
+
+A Classification Engine, if one exists, will be used by CKRM to
+classify a task to a class. The Rule based classification engine uses some
+of the attributes of the task to classify a task. When a CE is present
+class is not inherited by a task.
+
+Characteristics of a class can be accessed/changed through the following magic
+files under the directory representing the class:
+
+shares: allows to change the shares of different resources managed by the
+ class
+stats: allows to see the statistics associated with each resources managed
+ by the class
+target: allows to assign a task to a class. If a CE is present, assigning
+ a task to a class through this interface will prevent CE from
+ reassigning the task to any class during reclassification.
+members: allows to see which tasks has been assigned to a class
+config: allow to view and modify configuration information of different
+ resources in a class.
+
+Resource allocations for a class is controlled by the parameters:
+
+guarantee: specifies how much of a resource is guranteed to a class. A
+ special value DONT_CARE(-2) mean that there is no specific
+ guarantee of a resource is specified, this class may not get
+ any resource if the system is runing short of resources
+limit: specifies the maximum amount of resource that is allowed to be
+ allocated by a class. A special value DONT_CARE(-2) mean that
+ there is no specific limit is specified, this class can get all
+ the resources available.
+total_guarantee: total guarantee that is allowed among the children of this
+ class. In other words, the sum of "guarantee"s of all children
+ of this class cannot exit this number.
+max_limit: Maximum "limit" allowed for any of this class's children. In
+ other words, "limit" of any children of this class cannot exceed
+ this value.
+
+None of this parameters are absolute or have any units associated with
+them. These are just numbers(that are relative to its parents') that are
+used to calculate the absolute number of resource available for a specific
+class.
+
+Note: The root class has an absolute number of resource units associated with it.
+
Index: linux-2.6.12-ckrm1/Documentation/ckrm/core_usage
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.12-ckrm1/Documentation/ckrm/core_usage 2005-06-20 13:08:35.000000000 -0700
@@ -0,0 +1,72 @@
+Usage of CKRM without a classification engine
+-----------------------------------------------
+
+1. Create a class
+
+ # mkdir /rcfs/taskclass/c1
+ creates a taskclass named c1 , while
+ # mkdir /rcfs/socket_class/s1
+ creates a socketclass named s1
+
+The newly created class directory is automatically populated by magic files
+shares, stats, members, target and config.
+
+2. View default shares
+
+ # cat /rcfs/taskclass/c1/shares
+
+ "guarantee=-2,limit=-2,total_guarantee=100,max_limit=100" is the default
+ value set for resources that have controllers registered with CKRM.
+
+3. change shares of a <class>
+
+ One or more of the following fields can/must be specified
+ res=<res_name> #mandatory
+ guarantee=<number>
+ limit=<number>
+ total_guarantee=<number>
+ max_limit=<number>
+ e.g.
+ # echo "res=numtasks,limit=20" > /rcfs/taskclass/c1
+
+ If any of these parameters are not specified, the current value will be
+ retained.
+
+4. Reclassify a task (listening socket)
+
+ write the pid of the process to the destination class' target file
+ # echo 1004 > /rcfs/taskclass/c1/target
+
+ write the "<ipaddress>\<port>" string to the destination class' target file
+ # echo "0.0.0.0\32770" > /rcfs/taskclass/c1/target
+
+5. Get a list of tasks (sockets) assigned to a taskclass (socketclass)
+
+ # cat /rcfs/taskclass/c1/members
+ lists pids of tasks belonging to c1
+
+ # cat /rcfs/socket_class/s1/members
+ lists the ipaddress\port of all listening sockets in s1
+
+6. Get the statictics of different resources of a class
+
+ # cat /rcfs/tasksclass/c1/stats
+ shows c1's statistics for each resource with a registered resource
+ controller.
+
+ # cat /rcfs/socket_class/s1/stats
+ show's s1's stats for the listenaq controller.
+
+7. View the configuration values of the resources associated with a class
+
+ # cat /rcfs/taskclass/c1/config
+ shows per-controller config values for c1.
+
+8. Change the configuration values of resources associated with a class
+ Configuration values are different for different resources. the comman
+ field "res=<resname>" must always be specified.
+
+ # echo "res=numtasks,parameter=value" > /rcfs/taskclass/c1/config
+ to change (without any effect), the value associated with <parameter>.
+
+
Index: linux-2.6.12-ckrm1/Documentation/ckrm/crbce
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.12-ckrm1/Documentation/ckrm/crbce 2005-06-20 13:08:35.000000000 -0700
@@ -0,0 +1,33 @@
+CRBCE
+----------
+
+crbce is a superset of rbce. In addition to providing automatic
+classification, the crbce module
+- monitors per-process delay data that is collected by the delay
+accounting patch
+- collects data on significant kernel events where reclassification
+could occur e.g. fork/exec/setuid/setgid etc., and
+- uses relayfs to supply both these datapoints to userspace
+
+To illustrate the utility of the data gathered by crbce, we provide a
+userspace daemon called crbcedmn that prints the header info received
+from the records sent by the crbce module.
+
+0. Ensure that a CKRM-enabled kernel with following options configured
+ has been compiled. At a minimum, core, rcfs, at least one classtype,
+ delay-accounting patch and relayfs. For testing, it is recommended
+ all classtypes and resource controllers be compiled as modules.
+
+1. Ensure that the Makefile's BUILD_CRBCE=1 and KDIR points to the
+ kernel of step 1 and call make.
+ This also builds the userspace daemon, crbcedmn.
+
+2..9 Same as rbce installation and testing instructions,
+ except replacing rbce.ko with crbce.ko
+
+10. Read the pseudo daemon help file
+ # ./crbcedmn -h
+
+11. Run the crbcedmn to display all records being processed
+ # ./crbcedmn
+
Index: linux-2.6.12-ckrm1/Documentation/ckrm/installation
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.12-ckrm1/Documentation/ckrm/installation 2005-06-20 13:08:35.000000000 -0700
@@ -0,0 +1,70 @@
+Kernel installation
+------------------------------
+
+<kernver> = version of mainline Linux kernel
+<ckrmver> = version of CKRM
+
+Note: It is expected that CKRM versions will change fairly rapidly. Hence once
+a CKRM version has been released for some <kernver>, it will only be made
+available for future <kernver>'s until the next CKRM version is released.
+
+1. Patch
+
+ Apply ckrm/kernel/<kernver>/ckrm-<ckrmversion>.patch to a mainline kernel
+ tree with version <kernver>.
+
+ If CRBCE will be used, additionally apply the following patches, in order:
+ delayacctg-<ckrmversion>.patch
+ relayfs-<ckrmversion>.patch
+
+
+2. Configure
+
+Select appropriate configuration options:
+
+a. for taskclasses
+
+ General Setup-->Class Based Kernel Resource Management
+
+ [*] Class Based Kernel Resource Management
+ <M> Resource Class File System (User API)
+ [*] Class Manager for Task Groups
+ <M> Number of Tasks Resource Manager
+
+b. To test socket_classes and multiple accept queue controller
+
+ General Setup-->Class Based Kernel Resource Management
+ [*] Class Based Kernel Resource Management
+ <M> Resource Class File System (User API)
+ [*] Class Manager for socket groups
+ <M> Multiple Accept Queues Resource Manager
+
+ Device Drivers-->Networking Support-->Networking options-->
+ [*] Network packet filtering (replaces ipchains)
+ [*] IP: TCP Multiple accept queues support
+
+c. To test CRBCE later (requires 2a.)
+
+ File Systems-->Pseudo filesystems-->
+ <M> Relayfs filesystem support
+ (enable all sub fields)
+
+ General Setup-->
+ [*] Enable delay accounting
+
+
+3. Build, boot into kernel
+
+4. Enable rcfs
+
+ # insmod <patchedtree>/fs/rcfs/rcfs.ko
+ # mount -t rcfs rcfs /rcfs
+
+ This will create the directories /rcfs/taskclass and
+ /rcfs/socketclass which are the "roots" of subtrees for creating
+ taskclasses and socketclasses respectively.
+
+5. Load numtasks and listenaq controllers
+
+ # insmod <patchedtree>/kernel/ckrm/ckrm_tasks.ko
+ # insmod <patchedtree>/kernel/ckrm/ckrm_listenaq.ko
Index: linux-2.6.12-ckrm1/Documentation/ckrm/rbce_basics
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.12-ckrm1/Documentation/ckrm/rbce_basics 2005-06-20 13:08:35.000000000 -0700
@@ -0,0 +1,67 @@
+Rule-based Classification Engine (RBCE)
+-------------------------------------------
+
+The ckrm/rbce directory contains the sources for two classification engines
+called rbce and crbce. Both are optional, built as kernel modules and share much
+of their codebase. Only one classification engine (CE) can be loaded at a time
+in CKRM.
+
+
+With RBCE, user can specify rules for how tasks are classified to a
+class. Rules are specified by one or more attribute-value pairs and
+an associated class. The tasks that match all the attr-value pairs
+will get classified to the class attached with the rule.
+
+The file rbce_info under /rcfs/ce directory details the functionality
+of different files available under the directory and also details
+about attributes that can are used to define rules.
+
+order: When multiple rules are defined the rules are executed
+ according to the order of a rule. Order can be specified
+ while defining a rule. If order is not specified, the
+ highest order will be assigned to the rule(i.e, the new
+ rule will be executed after all the previously defined
+ evaluate false). So, order of rules is important as that
+ will decide, which class a task will get assigned to. For
+ example, if we have the two following rules: r1:
+ uid=1004,order=10,class=/rcfs/taskclass/c1 r2:
+ uid=1004,cmd=grep,order=20,class=/rcfs/taskclass/c2 then,
+ the task "grep" executed by user 1004 will always be
+ assigned to class /rcfs/taskclass/c1, as rule r1 will be
+ executed before r2 and the task successfully matched the
+ rule's attr-value pairs. Rule r2 will never be consulted
+ for the command. Note: The order in which the rules are
+ displayed(by ls) has no correlation with the order of the
+ rule.
+
+dependency: Rules can be defined to be depend on another rule. i.e a
+ rule can be dependent on one rule and has its own
+ additional attr-value pairs. the dependent rule will
+ evaluate true only if all the attr-value pairs of both
+ rules are satisfied. ex: r1: gid=502,class=/rcfs/taskclass
+ r2: depend=r1,cmd=grep,class=rcfstaskclass/c1 r2 is a
+ dependent rule that depends on r1, a task will be assigned
+ to /rcfs/taskclass/c1 if its gid is 502 and the executable
+ command name is "grep". If a task's gid is 502 but the
+ command name is _not_ "grep" then it will be assigned to
+ /rcfs/taskclass
+
+ Note: The order of dependent rule must be _lesser_ than the
+ rule it depends on, so that it is evaluated _before the
+ base rule is evaluated. Otherwise the base rule will
+ evaluate true and the task will be assigned to the class of
+ that rule without the dependent rule ever getting
+ evaluated. In the example above, order of r2 must be lesser
+ than order of r1.
+
+app_tag: a task can be attached with a tag(ascii string), that becomes
+ an attribute of that task and rules can be defined with the
+ tag value.
+
+state: states are at two levels in RBCE. The entire RBCE can be
+ enabled or disabled which writing 1 or 0 to the file
+ rbce_state under /rcfs/ce. Disabling RBCE, would mean that
+ the rules defined in RBCE will not be utilized for
+ classifying a task to a class. A specific rule can be
+ enabled/disabled by changing the state of that rule. Once
+ it is disabled, the rule will not be evaluated.
Index: linux-2.6.12-ckrm1/Documentation/ckrm/rbce_usage
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.12-ckrm1/Documentation/ckrm/rbce_usage 2005-06-20 13:08:35.000000000 -0700
@@ -0,0 +1,98 @@
+Usage of CKRM with RBCE
+--------------------------
+
+0. Ensure that a CKRM-enabled kernel with following options configured
+ has been compiled. At a minimum, core, rcfs and at least one
+ classtype. For testing, it is recommended all classtypes and
+ resource controllers be compiled as modules.
+
+1. Change ckrm/rbce/Makefile's KDIR to point to this compiled kernel's source
+ tree and call make
+
+2. Load rbce module.
+ # insmod ckrm/rbce/rbce.ko
+ Note that /rcfs has to be mounted before this.
+ Note: this command should populate the directory /rcfs/ce with files
+ rbce_reclassify, rbce_tag, rbce_info, rbce_state and a directory
+ rules.
+
+ Note2: If these are not created automatically, just create them by
+ using the commands touch and mkdir.(bug that needs to be fixed)
+
+3. Defining a rule
+ Rules are defined by creating(by writing) to a file under the
+ /rcfs/ce/rules directory by concatinating multiple attribute value
+ pairs.
+
+ Note that the classes must be defined before defining rules that
+ uses the classes. eg: the command # echo
+ "uid=1004,class=/rcfs/taskclass/c1" > /rcfs/ce/rules/r1 will define
+ a rule r1 that classifies all tasks belong to user id 1004 to class
+ /rcfs/taskclass/c1
+
+4. Viewing a rule
+ read the corresponding file.
+ to read rule r1, issue the command:
+ # cat /rcfs/ce/rules/r1
+
+5. Changing a rule
+
+ Changing a rule is done the same way as defining a rule, the new
+ rule will include the old set of attr-value pairs slapped with new
+ attr-value pairs. eg: if the current r2 is
+ uid=1004,depend=r1,class=/rcfs/taskclass/c1
+ (r1 as defined in step 3)
+
+ the command:
+ # echo gid=502 > /rcfs/ce/rules/r1
+ will change the rule to
+ r1: uid=1004,gid=502,depend=r1,class=/rcfs/taskclass/c1
+
+ the command:
+ # echo uid=1005 > /rcfs/ce/rules/r1
+ will change the rule to
+ r1: uid=1005,class=/rcfs/taskclass/c1
+
+ the command:
+ # echo class=/rcfs/taskclass/c2 > /rcfs/ce/rules/r1
+ will change the rule to
+ r1: uid=1004,depend=r1,class=/rcfs/taskclass/c2
+
+ the command:
+ # echo depend=r4 > /rcfs/ce/rules/r1
+ will change the rule to
+ r1: uid=1004,depend=r4,class=/rcfs/taskclass/c2
+
+ the command:
+ # echo +depend=r4 > /rcfs/ce/rules/r1
+ will change the rule to
+ r1: uid=1004,depend=r1,depend=r4,class=/rcfs/taskclass/c2
+
+ the command:
+ # echo -depend=r1 > /rcfs/ce/rules/r1
+ will change the rule to
+ r1: uid=1004,class=/rcfs/taskclass/c2
+
+6. Checking the state of RBCE
+ State(enabled/disabled) of RBCE can be checked by reading the file
+ /rcfs/ce/rbce_state, it will show 1(enabled) or 0(disabled).
+ By default, RBCE is enabled(1).
+ ex: # cat /rcfs/ce/rbce_state
+
+7. Changing the state of RBCE
+ State of RBCE can be changed by writing 1(enable) or 0(disable).
+ ex: # echo 1 > cat /rcfs/ce/rbce_state
+
+8. Checking the state of a rule
+ State of a rule is displayed in the rule. Rule can be viewed by
+ reading the rule file. ex: # cat /rcfs/ce/rules/r1
+
+9. Changing the state of a rule
+
+ State of a rule can be changed by writing "state=1"(enable) or
+ "state=0"(disable) to the corresponding rule file. By defeault, the
+ rule is enabled when defined. ex: to disable an existing rule r1,
+ issue the command
+ # echo "state=0" > /rcfs/ce/rules/r1
+
+
Index: linux-2.6.12-ckrm1/Documentation/ckrm/TODO
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.12-ckrm1/Documentation/ckrm/TODO 2005-06-20 13:08:35.000000000 -0700
@@ -0,0 +1,16 @@
+Current tasks in queue
+
+- Use __bitfield for enums
+- Add listenaq controller
+- Add RBCE/CRBCE
+- Add memory controller
+- Add I/O controller
+- Add forkrate control to numtasks controller
+- remove target file and move functionality to members file
+- init_task is not classified under any class
+- use netlink instead of relayfs for crbce
+- convert refcount usages to kref_t
+- add kerneldoc format headers to user consumable functions/macros
+- convert ckrm_init() to use standard initcalls
+- verify that the LGPL/GPL header/symbol usage is correct
+-
--
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/