prio_tree: remove

	- 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

The prio_tree.c code indexes vmas using 3 different indexes:

	* heap_index  = vm_pgoff + vm_size_in_pages : end_vm_pgoff

	* radix_index = vm_pgoff : start_vm_pgoff

	* size_index = vm_size_in_pages

A regular radix-priority-search-tree indexes vmas using only heap_index and

radix_index. The conditions for indexing are:

	* ->heap_index >= ->left->heap_index &&

		->heap_index >= ->right->heap_index

	* if (->heap_index == ->left->heap_index)

		then ->radix_index < ->left->radix_index;

	* if (->heap_index == ->right->heap_index)

		then ->radix_index < ->right->radix_index;

	* nodes are hashed to left or right subtree using radix_index

	  similar to a pure binary radix tree.

A regular radix-priority-search-tree helps to store and query

intervals (vmas). However, a regular radix-priority-search-tree is only

suitable for storing vmas with different radix indices (vm_pgoff).

Therefore, the prio_tree.c extends the regular radix-priority-search-tree

to handle many vmas with the same vm_pgoff. Such vmas are handled in

2 different ways: 1) All vmas with the same radix _and_ heap indices are

linked using vm_set.list, 2) if there are many vmas with the same radix

index, but different heap indices and if the regular radix-priority-search

tree cannot index them all, we build an overflow-sub-tree that indexes such

vmas using heap and size indices instead of heap and radix indices. For

example, in the figure below some vmas with vm_pgoff = 0 (zero) are

indexed by regular radix-priority-search-tree whereas others are pushed

into an overflow-subtree. Note that all vmas in an overflow-sub-tree have

the same vm_pgoff (radix_index) and if necessary we build different

overflow-sub-trees to handle each possible radix_index. For example,

in figure we have 3 overflow-sub-trees corresponding to radix indices

0, 2, and 4.

In the final tree the first few (prio_tree_root->index_bits) levels

are indexed using heap and radix indices whereas the overflow-sub-trees below

those levels (i.e. levels prio_tree_root->index_bits + 1 and higher) are

indexed using heap and size indices. In overflow-sub-trees the size_index

is used for hashing the nodes to appropriate places.

Now, an example prio_tree:

  vmas are represented [radix_index, size_index, heap_index]

                 i.e., [start_vm_pgoff, vm_size_in_pages, end_vm_pgoff]

level  prio_tree_root->index_bits = 3

-----

												_

  0			 				[0,7,7]					 |

  							/     \					 |

				      ------------------       ------------			 |     Regular

  				     /					   \			 |  radix priority

  1		 		[1,6,7]					  [4,3,7]		 |   search tree

  				/     \					  /     \		 |

			 -------       -----			    ------       -----		 |  heap-and-radix

			/		    \			   /		      \		 |      indexed

  2		    [0,6,6]	 	   [2,5,7]		[5,2,7]		    [6,1,7]	 |

		    /     \		   /     \		/     \		    /     \	 |

  3		[0,5,5]	[1,5,6]		[2,4,6]	[3,4,7]	    [4,2,6] [5,1,6]	[6,0,6]	[7,0,7]	 |

		   /			   /		       /		   		_

                  /		          /		      /					_

  4	      [0,4,4]		      [2,3,5]		   [4,1,5]				 |

  		 /			 /		      /					 |

  5	     [0,3,3]		     [2,2,4]		  [4,0,4]				 |  Overflow-sub-trees

  		/			/							 |

  6	    [0,2,2]		    [2,1,3]							 |    heap-and-size

  	       /		       /							 |       indexed

  7	   [0,1,1]		   [2,0,2]							 |

  	      /											 |

  8	  [0,0,0]										 |

  												_

Note that we use prio_tree_root->index_bits to optimize the height

of the heap-and-radix indexed tree. Since prio_tree_root->index_bits is

set according to the maximum end_vm_pgoff mapped, we are sure that all

bits (in vm_pgoff) above prio_tree_root->index_bits are 0 (zero). Therefore,

we only use the first prio_tree_root->index_bits as radix_index.

Whenever index_bits is increased in prio_tree_expand, we shuffle the tree

to make sure that the first prio_tree_root->index_bits levels of the tree

is indexed properly using heap and radix indices.

We do not optimize the height of overflow-sub-trees using index_bits.

The reason is: there can be many such overflow-sub-trees and all of

them have to be suffled whenever the index_bits increases. This may involve

walking the whole prio_tree in prio_tree_insert->prio_tree_expand code

path which is not desirable. Hence, we do not optimize the height of the

heap-and-size indexed overflow-sub-trees using prio_tree->index_bits.

Instead the overflow sub-trees are indexed using full BITS_PER_LONG bits

of size_index. This may lead to skewed sub-trees because most of the

higher significant bits of the size_index are likely to be 0 (zero). In

the example above, all 3 overflow-sub-trees are skewed. This may marginally

affect the performance. However, processes rarely map many vmas with the

same start_vm_pgoff but different end_vm_pgoffs. Therefore, we normally

do not require overflow-sub-trees to index all vmas.

From the above discussion it is clear that the maximum height of

a prio_tree can be prio_tree_root->index_bits + BITS_PER_LONG.

However, in most of the common cases we do not need overflow-sub-trees,

so the tree height in the common cases will be prio_tree_root->index_bits.

It is fair to mention here that the prio_tree_root->index_bits

is increased on demand, however, the index_bits is not decreased when

vmas are removed from the prio_tree. That's tricky to do. Hence, it's

left as a home work problem.

#ifndef _LINUX_PRIO_TREE_H

#define _LINUX_PRIO_TREE_H

/*

 * K&R 2nd ed. A8.3 somewhat obliquely hints that initial sequences of struct

 * fields with identical types should end up at the same location. We'll use

 * this until we can scrap struct raw_prio_tree_node.

 *

 * Note: all this could be done more elegantly by using unnamed union/struct

 * fields. However, gcc 2.95.3 and apparently also gcc 3.0.4 don't support this

 * language extension.

 */

struct raw_prio_tree_node {

	struct prio_tree_node	*left;

	struct prio_tree_node	*right;

	struct prio_tree_node	*parent;

};

struct prio_tree_node {

	struct prio_tree_node	*left;

	struct prio_tree_node	*right;

	struct prio_tree_node	*parent;

	unsigned long		start;

	unsigned long		last;	/* last location _in_ interval */

};

struct prio_tree_root {

	struct prio_tree_node	*prio_tree_node;

	unsigned short 		index_bits;

	unsigned short		raw;

		/*

		 * 0: nodes are of type struct prio_tree_node

		 * 1: nodes are of type raw_prio_tree_node

		 */

};

struct prio_tree_iter {

	struct prio_tree_node	*cur;

	unsigned long		mask;

	unsigned long		value;

	int			size_level;

	struct prio_tree_root	*root;

	pgoff_t			r_index;

	pgoff_t			h_index;

};

static inline void prio_tree_iter_init(struct prio_tree_iter *iter,

		struct prio_tree_root *root, pgoff_t r_index, pgoff_t h_index)

{

	iter->root = root;

	iter->r_index = r_index;

	iter->h_index = h_index;

	iter->cur = NULL;

}

#define __INIT_PRIO_TREE_ROOT(ptr, _raw)	\

do {					\

	(ptr)->prio_tree_node = NULL;	\

	(ptr)->index_bits = 1;		\

	(ptr)->raw = (_raw);		\

} while (0)

#define INIT_PRIO_TREE_ROOT(ptr)	__INIT_PRIO_TREE_ROOT(ptr, 0)

#define INIT_RAW_PRIO_TREE_ROOT(ptr)	__INIT_PRIO_TREE_ROOT(ptr, 1)

#define INIT_PRIO_TREE_NODE(ptr)				\

do {								\

	(ptr)->left = (ptr)->right = (ptr)->parent = (ptr);	\

} while (0)

#define INIT_PRIO_TREE_ITER(ptr)	\

do {					\

	(ptr)->cur = NULL;		\

	(ptr)->mask = 0UL;		\

	(ptr)->value = 0UL;		\

	(ptr)->size_level = 0;		\

} while (0)

#define prio_tree_entry(ptr, type, member) \

       ((type *)((char *)(ptr)-(unsigned long)(&((type *)0)->member)))

static inline int prio_tree_empty(const struct prio_tree_root *root)

{

	return root->prio_tree_node == NULL;

}

static inline int prio_tree_root(const struct prio_tree_node *node)

{

	return node->parent == node;

}

static inline int prio_tree_left_empty(const struct prio_tree_node *node)

{

	return node->left == node;

}

static inline int prio_tree_right_empty(const struct prio_tree_node *node)

{

	return node->right == node;

}

struct prio_tree_node *prio_tree_replace(struct prio_tree_root *root,

                struct prio_tree_node *old, struct prio_tree_node *node);

struct prio_tree_node *prio_tree_insert(struct prio_tree_root *root,

                struct prio_tree_node *node);

void prio_tree_remove(struct prio_tree_root *root, struct prio_tree_node *node);

struct prio_tree_node *prio_tree_next(struct prio_tree_iter *iter);

#define raw_prio_tree_replace(root, old, node) \

	prio_tree_replace(root, (struct prio_tree_node *) (old), \

	    (struct prio_tree_node *) (node))

#define raw_prio_tree_insert(root, node) \

	prio_tree_insert(root, (struct prio_tree_node *) (node))

#define raw_prio_tree_remove(root, node) \

	prio_tree_remove(root, (struct prio_tree_node *) (node))

#endif /* _LINUX_PRIO_TREE_H */

extern void fork_init(unsigned long);

extern void mca_init(void);

extern void sbus_init(void);

extern void prio_tree_init(void);

extern void radix_tree_init(void);

#ifndef CONFIG_DEBUG_RODATA

static inline void mark_rodata_ro(void) { }

	/* init some links before init_ISA_irqs() */

	early_irq_init();

	init_IRQ();

	prio_tree_init();

	init_timers();

	hrtimers_init();

	softirq_init();

	  A benchmark measuring the performance of the rbtree library.

	  Also includes rbtree invariant checks.

config PRIO_TREE_TEST

	tristate "Prio tree test"

	depends on m && DEBUG_KERNEL

	help

	  A benchmark measuring the performance of the prio tree library

config INTERVAL_TREE_TEST

	tristate "Interval tree test"

	depends on m && DEBUG_KERNEL