Merge branch 'akpm' (Andrew's patch-bomb)

	- info on locking under a preemptive kernel.

printk-formats.txt

	- how to get printk format specifiers right

prio_tree.txt

	- info on radix-priority-search-tree use for indexing vmas.

ramoops.txt

	- documentation of the ramoops oops/panic logging module.

rbtree.txt

What:	/proc/<pid>/oom_adj

When:	August 2012

Why:	/proc/<pid>/oom_adj allows userspace to influence the oom killer's

	badness heuristic used to determine which task to kill when the kernel

	is out of memory.

	The badness heuristic has since been rewritten since the introduction of

	this tunable such that its meaning is deprecated.  The value was

	implemented as a bitshift on a score generated by the badness()

	function that did not have any precise units of measure.  With the

	rewrite, the score is given as a proportion of available memory to the

	task allocating pages, so using a bitshift which grows the score

	exponentially is, thus, impossible to tune with fine granularity.

	A much more powerful interface, /proc/<pid>/oom_score_adj, was

	introduced with the oom killer rewrite that allows users to increase or

	decrease the badness score linearly.  This interface will replace

	/proc/<pid>/oom_adj.

	A warning will be emitted to the kernel log if an application uses this

	deprecated interface.  After it is printed once, future warnings will be

	suppressed until the kernel is rebooted.

uses of the memory controller. The memory controller can be used to

a. Isolate an application or a group of applications

   Memory hungry applications can be isolated and limited to a smaller

   Memory-hungry applications can be isolated and limited to a smaller

   amount of memory.

b. Create a cgroup with limited amount of memory, this can be used

b. Create a cgroup with a limited amount of memory; this can be used

   as a good alternative to booting with mem=XXXX.

c. Virtualization solutions can control the amount of memory they want

   to assign to a virtual machine instance.

d. A CD/DVD burner could control the amount of memory used by the

   rest of the system to ensure that burning does not fail due to lack

   of available memory.

e. There are several other use cases, find one or use the controller just

e. There are several other use cases; find one or use the controller just

   for fun (to learn and hack on the VM subsystem).

Current Status: linux-2.6.34-mmotm(development version of 2010/April)

 - oom-killer disable knob and oom-notifier

 - Root cgroup has no limit controls.

 Kernel memory support is work in progress, and the current version provides

 Kernel memory support is a work in progress, and the current version provides

 basically functionality. (See Section 2.7)

Brief summary of control files.

The accounting is done as follows: mem_cgroup_charge() is invoked to set up

the necessary data structures and check if the cgroup that is being charged

is over its limit. If it is then reclaim is invoked on the cgroup.

is over its limit. If it is, then reclaim is invoked on the cgroup.

More details can be found in the reclaim section of this document.

If everything goes well, a page meta-data-structure called page_cgroup is

updated. page_cgroup has its own LRU on cgroup.

inserted into inode (radix-tree). While it's mapped into the page tables of

processes, duplicate accounting is carefully avoided.

A RSS page is unaccounted when it's fully unmapped. A PageCache page is

An RSS page is unaccounted when it's fully unmapped. A PageCache page is

unaccounted when it's removed from radix-tree. Even if RSS pages are fully

unmapped (by kswapd), they may exist as SwapCache in the system until they

are really freed. Such SwapCaches also also accounted.

are really freed. Such SwapCaches are also accounted.

A swapped-in page is not accounted until it's mapped.

Note: The kernel does swapin-readahead and read multiple swaps at once.

Note: The kernel does swapin-readahead and reads multiple swaps at once.

This means swapped-in pages may contain pages for other tasks than a task

causing page fault. So, we avoid accounting at swap-in I/O.

Example: Assume a system with 4G of swap. A task which allocates 6G of memory

(by mistake) under 2G memory limitation will use all swap.

In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap.

By using memsw limit, you can avoid system OOM which can be caused by swap

By using the memsw limit, you can avoid system OOM which can be caused by swap

shortage.

* why 'memory+swap' rather than swap.

to move account from memory to swap...there is no change in usage of

memory+swap. In other words, when we want to limit the usage of swap without

affecting global LRU, memory+swap limit is better than just limiting swap from

OS point of view.

an OS point of view.

* What happens when a cgroup hits memory.memsw.limit_in_bytes

When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out

cgroup. (See 10. OOM Control below.)

The reclaim algorithm has not been modified for cgroups, except that

pages that are selected for reclaiming come from the per cgroup LRU

pages that are selected for reclaiming come from the per-cgroup LRU

list.

NOTE: Reclaim does not work for the root cgroup, since we cannot set any

# cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes

1216512

A successful write to this file does not guarantee a successful set of

A successful write to this file does not guarantee a successful setting of

this limit to the value written into the file. This can be due to a

number of factors, such as rounding up to page boundaries or the total

availability of memory on the system. The user is required to re-read

4.1 Troubleshooting

Sometimes a user might find that the application under a cgroup is

terminated by OOM killer. There are several causes for this:

terminated by the OOM killer. There are several causes for this:

1. The cgroup limit is too low (just too low to do anything useful)

2. The user is using anonymous memory and swap is turned off or too low

A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of

some of the pages cached in the cgroup (page cache pages).

To know what happens, disable OOM_Kill by 10. OOM Control(see below) and

To know what happens, disabling OOM_Kill as per "10. OOM Control" (below) and

seeing what happens will be helpful.

4.2 Task migration

  moved to parent (if use_hierarchy==1) or root (if use_hierarchy==0) and this

  cgroup will be empty.

  Typical use case of this interface is that calling this before rmdir().

  The typical use case for this interface is before calling rmdir().

  Because rmdir() moves all pages to parent, some out-of-use page caches can be

  moved to the parent. If you want to avoid that, force_empty will be useful.

For efficiency, as other kernel components, memory cgroup uses some optimization

to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the

method and doesn't show 'exact' value of memory(and swap) usage, it's an fuzz

method and doesn't show 'exact' value of memory (and swap) usage, it's a fuzz

value for efficient access. (Of course, when necessary, it's synchronized.)

If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP)

value in memory.stat(see 5.2).

useful for providing visibility into the numa locality information within

an memcg since the pages are allowed to be allocated from any physical

node.  One of the use cases is evaluating application performance by

combining this information with the application's cpu allocation.

combining this information with the application's CPU allocation.

We export "total", "file", "anon" and "unevictable" pages per-node for

each memcg.  The ouput format of memory.numa_stat is:

group is very high, they are pushed back as much as possible to make

sure that one control group does not starve the others of memory.

Please note that soft limits is a best effort feature, it comes with

Please note that soft limits is a best-effort feature; it comes with

no guarantees, but it does its best to make sure that when memory is

heavily contended for, memory is allocated based on the soft limit

hints/setup. Currently soft limit based reclaim is set up such that

8.1 Interface

This feature is disabled by default. It can be enabled(and disabled again) by

This feature is disabled by default. It can be enabledi (and disabled again) by

writing to memory.move_charge_at_immigrate of the destination cgroup.

If you want to enable it:

Note: Each bits of move_charge_at_immigrate has its own meaning about what type

      of charges should be moved. See 8.2 for details.

Note: Charges are moved only when you move mm->owner, IOW, a leader of a thread

      group.

Note: Charges are moved only when you move mm->owner, in other words,

      a leader of a thread group.

Note: If we cannot find enough space for the task in the destination cgroup, we

      try to make space by reclaiming memory. Task migration may fail if we

      cannot make enough space.

# echo 0 > memory.move_charge_at_immigrate

8.2 Type of charges which can be move

8.2 Type of charges which can be moved

Each bits of move_charge_at_immigrate has its own meaning about what type of

charges should be moved. But in any cases, it must be noted that an account of

a page or a swap can be moved only when it is charged to the task's current(old)

memory cgroup.

Each bit in move_charge_at_immigrate has its own meaning about what type of

charges should be moved. But in any case, it must be noted that an account of

a page or a swap can be moved only when it is charged to the task's current

(old) memory cgroup.

  bit | what type of charges would be moved ?

 -----+------------------------------------------------------------------------

9. Memory thresholds

Memory cgroup implements memory thresholds using cgroups notification

Memory cgroup implements memory thresholds using the cgroups notification

API (see cgroups.txt). It allows to register multiple memory and memsw

thresholds and gets notifications when it crosses.

To register a threshold application need:

To register a threshold, an application must:

- create an eventfd using eventfd(2);

- open memory.usage_in_bytes or memory.memsw.usage_in_bytes;

- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to

memory.oom_control file is for OOM notification and other controls.

Memory cgroup implements OOM notifier using cgroup notification

Memory cgroup implements OOM notifier using the cgroup notification

API (See cgroups.txt). It allows to register multiple OOM notification

delivery and gets notification when OOM happens.

To register a notifier, application need:

To register a notifier, an application must:

 - create an eventfd using eventfd(2)

 - open memory.oom_control file

 - write string like "<event_fd> <fd of memory.oom_control>" to

   cgroup.event_control

Application will be notified through eventfd when OOM happens.

OOM notification doesn't work for root cgroup.

The application will be notified through eventfd when OOM happens.

OOM notification doesn't work for the root cgroup.

You can disable OOM-killer by writing "1" to memory.oom_control file, as:

You can disable the OOM-killer by writing "1" to memory.oom_control file, as:

	#echo 1 > memory.oom_control

This operation is only allowed to the top cgroup of sub-hierarchy.

This operation is only allowed to the top cgroup of a sub-hierarchy.

If OOM-killer is disabled, tasks under cgroup will hang/sleep

in memory cgroup's OOM-waitqueue when they request accountable memory.

  2	Modifying System Parameters

  3	Per-Process Parameters

  3.1	/proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj - Adjust the oom-killer

  3.1	/proc/<pid>/oom_score_adj - Adjust the oom-killer

								score

  3.2	/proc/<pid>/oom_score - Display current oom-killer score

  3.3	/proc/<pid>/io - Display the IO accounting fields

CHAPTER 3: PER-PROCESS PARAMETERS

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

3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj- Adjust the oom-killer score

3.1 /proc/<pid>/oom_score_adj- Adjust the oom-killer score

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

These file can be used to adjust the badness heuristic used to select which

This file can be used to adjust the badness heuristic used to select which

process gets killed in out of memory conditions.

The badness heuristic assigns a value to each candidate task ranging from 0

equivalent to discounting 50% of the task's allowed memory from being considered

as scoring against the task.

For backwards compatibility with previous kernels, /proc/<pid>/oom_adj may also

be used to tune the badness score.  Its acceptable values range from -16

(OOM_ADJUST_MIN) to +15 (OOM_ADJUST_MAX) and a special value of -17

(OOM_DISABLE) to disable oom killing entirely for that task.  Its value is

scaled linearly with /proc/<pid>/oom_score_adj.

Writing to /proc/<pid>/oom_score_adj or /proc/<pid>/oom_adj will change the

other with its scaled value.

The value of /proc/<pid>/oom_score_adj may be reduced no lower than the last

value set by a CAP_SYS_RESOURCE process. To reduce the value any lower

requires CAP_SYS_RESOURCE.

NOTICE: /proc/<pid>/oom_adj is deprecated and will be removed, please see

Documentation/feature-removal-schedule.txt.

Caveat: when a parent task is selected, the oom killer will sacrifice any first

generation children with separate address spaces instead, if possible.  This

avoids servers and important system daemons from being killed and loses the

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

This file can be used to check the current score used by the oom-killer is for

any given <pid>. Use it together with /proc/<pid>/oom_adj to tune which

process should be killed in an out-of-memory situation.

any given <pid>.

3.3  /proc/<pid>/io - Display the IO accounting fields

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

There are several classic problems related to memory on Linux

systems.

	1) There are some motherboards that will not cache above

	   a certain quantity of memory.  If you have one of these

	   motherboards, your system will be SLOWER, not faster

	   as you add more memory.  Consider exchanging your 

           motherboard.

All of these problems can be addressed with the "mem=XXXM" boot option

(where XXX is the size of RAM to use in megabytes).  

It can also tell Linux to use less memory than is actually installed.

If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid

physical address space collisions.

See the documentation of your boot loader (LILO, grub, loadlin, etc.) about

how to pass options to the kernel.

There are other memory problems which Linux cannot deal with.  Random

corruption of memory is usually a sign of serious hardware trouble.

Try:

	* Reducing memory settings in the BIOS to the most conservative 

          timings.

	* Adding a cooling fan.

	* Not overclocking your CPU.

	* Having the memory tested in a memory tester or exchanged

	  with the vendor. Consider testing it with memtest86 yourself.

	* Exchanging your CPU, cache, or motherboard for one that works.