Merge branch 'for-3.8' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup

00-INDEX

	- this file

blkio-controller.txt

	- Description for Block IO Controller, implementation and usage details.

cgroups.txt

	- Control Groups definition, implementation details, examples and API.

cgroup_event_listener.c

	- A user program for cgroup listener.

cpuacct.txt

	- CPU Accounting Controller; account CPU usage for groups of tasks.

cpusets.txt

	- Device Whitelist Controller; description, interface and security.

freezer-subsystem.txt

	- checkpointing; rationale to not use signals, interface.

hugetlb.txt

	- HugeTLB Controller implementation and usage details.

memcg_test.txt

	- Memory Resource Controller; implementation details.

memory.txt

	- Memory Resource Controller; design, accounting, interface, testing.

net_prio.txt

	- Network priority cgroups details and usages.

resource_counter.txt

	- Resource Counter API.

1.5 What does clone_children do ?

---------------------------------

If the clone_children flag is enabled (1) in a cgroup, then all

cgroups created beneath will call the post_clone callbacks for each

subsystem of the newly created cgroup. Usually when this callback is

implemented for a subsystem, it copies the values of the parent

subsystem, this is the case for the cpuset.

This flag only affects the cpuset controller. If the clone_children

flag is enabled (1) in a cgroup, a new cpuset cgroup will copy its

configuration from the parent during initialization.

1.6 How do I use cgroups ?

--------------------------

THIS_MODULE in its .c file.

Each subsystem may export the following methods. The only mandatory

methods are create/destroy. Any others that are null are presumed to

methods are css_alloc/free. Any others that are null are presumed to

be successful no-ops.

struct cgroup_subsys_state *create(struct cgroup *cgrp)

struct cgroup_subsys_state *css_alloc(struct cgroup *cgrp)

(cgroup_mutex held by caller)

Called to create a subsystem state object for a cgroup. The

Called to allocate a subsystem state object for a cgroup. The

subsystem should allocate its subsystem state object for the passed

cgroup, returning a pointer to the new object on success or a

negative error code. On success, the subsystem pointer should point to

ERR_PTR() value. On success, the subsystem pointer should point to

a structure of type cgroup_subsys_state (typically embedded in a

larger subsystem-specific object), which will be initialized by the

cgroup system. Note that this will be called at initialization to

it's the root of the hierarchy) and may be an appropriate place for

initialization code.

void destroy(struct cgroup *cgrp)

int css_online(struct cgroup *cgrp)

(cgroup_mutex held by caller)

The cgroup system is about to destroy the passed cgroup; the subsystem

should do any necessary cleanup and free its subsystem state

object. By the time this method is called, the cgroup has already been

unlinked from the file system and from the child list of its parent;

cgroup->parent is still valid. (Note - can also be called for a

newly-created cgroup if an error occurs after this subsystem's

create() method has been called for the new cgroup).

Called after @cgrp successfully completed all allocations and made

visible to cgroup_for_each_child/descendant_*() iterators. The

subsystem may choose to fail creation by returning -errno. This

callback can be used to implement reliable state sharing and

propagation along the hierarchy. See the comment on

cgroup_for_each_descendant_pre() for details.

int pre_destroy(struct cgroup *cgrp);

void css_offline(struct cgroup *cgrp);

Called before checking the reference count on each subsystem. This may

be useful for subsystems which have some extra references even if

there are not tasks in the cgroup. If pre_destroy() returns error code,

rmdir() will fail with it. From this behavior, pre_destroy() can be

called multiple times against a cgroup.

This is the counterpart of css_online() and called iff css_online()

has succeeded on @cgrp. This signifies the beginning of the end of

@cgrp. @cgrp is being removed and the subsystem should start dropping

all references it's holding on @cgrp. When all references are dropped,

cgroup removal will proceed to the next step - css_free(). After this

callback, @cgrp should be considered dead to the subsystem.

void css_free(struct cgroup *cgrp)

(cgroup_mutex held by caller)

The cgroup system is about to free @cgrp; the subsystem should free

its subsystem state object. By the time this method is called, @cgrp

is completely unused; @cgrp->parent is still valid. (Note - can also

be called for a newly-created cgroup if an error occurs after this

subsystem's create() method has been called for the new cgroup).

int can_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)

(cgroup_mutex held by caller)

Called during task exit.

void post_clone(struct cgroup *cgrp)

(cgroup_mutex held by caller)

Called during cgroup_create() to do any parameter

initialization which might be required before a task could attach.  For

example, in cpusets, no task may attach before 'cpus' and 'mems' are set

up.

void bind(struct cgroup *root)

(cgroup_mutex held by caller)

being frozen. This allows the bash example above and gdb to run as

expected.

The freezer subsystem in the container filesystem defines a file named

freezer.state. Writing "FROZEN" to the state file will freeze all tasks in the

cgroup. Subsequently writing "THAWED" will unfreeze the tasks in the cgroup.

Reading will return the current state.

The cgroup freezer is hierarchical. Freezing a cgroup freezes all

tasks beloning to the cgroup and all its descendant cgroups. Each

cgroup has its own state (self-state) and the state inherited from the

parent (parent-state). Iff both states are THAWED, the cgroup is

THAWED.

Note freezer.state doesn't exist in root cgroup, which means root cgroup

is non-freezable.

The following cgroupfs files are created by cgroup freezer.

* freezer.state: Read-write.

  When read, returns the effective state of the cgroup - "THAWED",

  "FREEZING" or "FROZEN". This is the combined self and parent-states.

  If any is freezing, the cgroup is freezing (FREEZING or FROZEN).

  FREEZING cgroup transitions into FROZEN state when all tasks

  belonging to the cgroup and its descendants become frozen. Note that

  a cgroup reverts to FREEZING from FROZEN after a new task is added

  to the cgroup or one of its descendant cgroups until the new task is

  frozen.

  When written, sets the self-state of the cgroup. Two values are

  allowed - "FROZEN" and "THAWED". If FROZEN is written, the cgroup,

  if not already freezing, enters FREEZING state along with all its

  descendant cgroups.

  If THAWED is written, the self-state of the cgroup is changed to

  THAWED.  Note that the effective state may not change to THAWED if

  the parent-state is still freezing. If a cgroup's effective state

  becomes THAWED, all its descendants which are freezing because of

  the cgroup also leave the freezing state.

* freezer.self_freezing: Read only.

  Shows the self-state. 0 if the self-state is THAWED; otherwise, 1.

  This value is 1 iff the last write to freezer.state was "FROZEN".

* freezer.parent_freezing: Read only.

  Shows the parent-state.  0 if none of the cgroup's ancestors is

  frozen; otherwise, 1.

The root cgroup is non-freezable and the above interface files don't

exist.

* Examples of usage :

This is the basic mechanism which should do the right thing for user space task

in a simple scenario.

It's important to note that freezing can be incomplete. In that case we return

EBUSY. This means that some tasks in the cgroup are busy doing something that

prevents us from completely freezing the cgroup at this time. After EBUSY,

the cgroup will remain partially frozen -- reflected by freezer.state reporting

"FREEZING" when read. The state will remain "FREEZING" until one of these

things happens:

	1) Userspace cancels the freezing operation by writing "THAWED" to

		the freezer.state file

	2) Userspace retries the freezing operation by writing "FROZEN" to

		the freezer.state file (writing "FREEZING" is not legal

		and returns EINVAL)

	3) The tasks that blocked the cgroup from entering the "FROZEN"

		state disappear from the cgroup's set of tasks.

traffic to be steered to hardware/driver based traffic classes. These mappings

can then be managed by administrators or other networking protocols such as

DCBX.

A new net_prio cgroup inherits the parent's configuration.

};

/**

 * blkcg_pre_destroy - cgroup pre_destroy callback

 * blkcg_css_offline - cgroup css_offline callback

 * @cgroup: cgroup of interest

 *

 * This function is called when @cgroup is about to go away and responsible

 *

 * This is the blkcg counterpart of ioc_release_fn().

 */

static int blkcg_pre_destroy(struct cgroup *cgroup)

static void blkcg_css_offline(struct cgroup *cgroup)

{

	struct blkcg *blkcg = cgroup_to_blkcg(cgroup);

	}

	spin_unlock_irq(&blkcg->lock);

	return 0;

}

static void blkcg_destroy(struct cgroup *cgroup)

static void blkcg_css_free(struct cgroup *cgroup)

{

	struct blkcg *blkcg = cgroup_to_blkcg(cgroup);

		kfree(blkcg);

}

static struct cgroup_subsys_state *blkcg_create(struct cgroup *cgroup)

static struct cgroup_subsys_state *blkcg_css_alloc(struct cgroup *cgroup)

{

	static atomic64_t id_seq = ATOMIC64_INIT(0);

	struct blkcg *blkcg;

struct cgroup_subsys blkio_subsys = {

	.name = "blkio",

	.create = blkcg_create,

	.css_alloc = blkcg_css_alloc,

	.css_offline = blkcg_css_offline,

	.css_free = blkcg_css_free,

	.can_attach = blkcg_can_attach,

	.pre_destroy = blkcg_pre_destroy,

	.destroy = blkcg_destroy,

	.subsys_id = blkio_subsys_id,

	.base_cftypes = blkcg_files,

	.module = THIS_MODULE,