vm_map_entry_resize_free (9)

Leading comments

Copyright (c) 2004 Mark W. Krentel <krentel@dreamscape.com>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
 ...

(The comments found at the beginning of the groff file "man9/vm_map_entry_resize_free.9freebsd".)

NAME

vm_map_entry_resize_free - vm map free space algorithm

SYNOPSIS

In sys/param.h In vm/vm.h In vm/vm_map.h Ft void Fn vm_map_entry_resize_free vm_map_t map vm_map_entry_t entry

DESCRIPTION

This manual page describes the Vt vm_map_entry fields used in the VM map free space algorithm, how to maintain consistency of these variables, and the Fn vm_map_entry_resize_free function.

VM map entries are organized as both a doubly-linked list ( prev and next pointers) and as a binary search tree ( left and right pointers). The search tree is organized as a Sleator and Tarjan splay tree, also known as a ``self-adjusting tree''

struct vm_map_entry {
        struct vm_map_entry *prev;
        struct vm_map_entry *next;
        struct vm_map_entry *left;
        struct vm_map_entry *right;
        vm_offset_t start;
        vm_offset_t end;
        vm_offset_t avail_ssize;
        vm_size_t adj_free;
        vm_size_t max_free;
        ...
};

The free space algorithm adds two fields to Vt struct vm_map_entry : adj_free and max_free The adj_free field is the amount of free address space adjacent to and immediately following (higher address) the map entry. This field is unused in the map header. Note that adj_free depends on the linked list, not the splay tree and that adj_free can be computed as:

entry->adj_free = (entry->next == &map->header ?
    map->max_offset : entry->next->start) - entry->end;

The max_free field is the maximum amount of contiguous free space in the entry's subtree. Note that max_free depends on the splay tree, not the linked list and that max_free is computed by taking the maximum of its own adj_free and the max_free of its left and right subtrees. Again, max_free is unused in the map header.

These fields allow for an Fn O log n implementation of Fn vm_map_findspace . Using max_free we can immediately test for a sufficiently large free region in an entire subtree. This makes it possible to find a first-fit free region of a given size in one pass down the tree, so Fn O log n amortized using splay trees.

When a free region changes size, we must update adj_free and max_free in the preceding map entry and propagate max_free up the tree. This is handled in Fn vm_map_entry_link and Fn vm_map_entry_unlink for the cases of inserting and deleting an entry. Note that Fn vm_map_entry_link updates both the new entry and the previous entry, and that Fn vm_map_entry_unlink updates the previous entry. Also note that max_free is not actually propagated up the tree. Instead, that entry is first splayed to the root and then the change is made there. This is a common technique in splay trees and is also how map entries are linked and unlinked into the tree.

The Fn vm_map_entry_resize_free function updates the free space variables in the given Fa entry and propagates those values up the tree. This function should be called whenever a map entry is resized in-place, that is, by modifying its start or end values. Note that if you change end then you should resize that entry, but if you change start then you should resize the previous entry. The map must be locked before calling this function, and again, propagating max_free is performed by splaying that entry to the root.

EXAMPLES

Consider adding a map entry with Fn vm_map_insert .

ret = vm_map_insert(map, object, offset, start, end, prot,
    max_prot, cow);

In this case, no further action is required to maintain consistency of the free space variables. The Fn vm_map_insert function calls Fn vm_map_entry_link which updates both the new entry and the previous entry. The same would be true for Fn vm_map_delete and for calling Fn vm_map_entry_link or Fn vm_map_entry_unlink directly.

Now consider resizing an entry in-place without a call to Fn vm_map_entry_link or Fn vm_map_entry_unlink .

entry->start = new_start;
if (entry->prev != &map->header)
        vm_map_entry_resize_free(map, entry->prev);

In this case, resetting start changes the amount of free space following the previous entry, so we use Fn vm_map_entry_resize_free to update the previous entry.

Finally, suppose we change an entry's end address.

entry->end = new_end;
vm_map_entry_resize_free(map, entry);

Here, we call Fn vm_map_entry_resize_free on the entry itself.

SEE ALSO

vm_map9, vm_map_findspace9

Daniel D. Sleator Robert E. Tarjan Self-Adjusting Binary Search Trees JACM vol. 32(3) pp. 652-686 July 1985

HISTORY

Splay trees were added to the VM map in Fx 5.0 , and the Fn O log n tree-based free space algorithm was added in Fx 5.3 .

AUTHORS

The tree-based free space algorithm and this manual page were written by An Mark W. Krentel Aq krentel@dreamscape.com .