vm_map_find (9)

Leading comments

Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
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
   documenta...

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

NAME

vm_map_find - find a free region within a map, and optionally map a vm_object

SYNOPSIS

In sys/param.h In vm/vm.h In vm/vm_map.h Ft int Fo vm_map_find Fa vm_map_t map vm_object_t object vm_ooffset_t offset Fa vm_offset_t *addr vm_size_t length vm_offset_t max_addr Fa int find_space vm_prot_t prot vm_prot_t max int cow Fc

DESCRIPTION

The Fn vm_map_find function attempts to find a free region in the target Fa map , with the given Fa length. If a free region is found, Fn vm_map_find creates a mapping of Fa object via a call to vm_map_insert9.

The arguments Fa offset , Fa prot , Fa max , and Fa cow are passed unchanged to vm_map_insert9 when creating the mapping, if and only if a free region is found.

If Fa object is non- NULL the reference count on the object must be incremented by the caller before calling this function to account for the new entry.

If Fa max_addr is non-zero, it specifies an upper bound on the mapping. The mapping will only succeed if a free region can be found that resides entirely below Fa max_addr .

The Fa find_space argument specifies the strategy to use when searching for a free region of the requested length. For all values other than VMFS_NO_SPACE vm_map_findspace9 is called to locate a free region of the requested length with a starting address at or above Fa *addr . The following strategies are supported:

VMFS_NO_SPACE

The mapping will only succeed if there is a free region of the requested length at the given address Fa *addr .

VMFS_ANY_SPACE

The mapping will succeed as long as there is a free region.

VMFS_SUPER_SPACE

The mapping will succeed as long as there is a free region that begins on a superpage boundary. If Fa object is non- NULL and is already backed by superpages, then the mapping will require a free region that aligns relative to the existing superpages rather than one beginning on a superpage boundary.

VMFS_OPTIMAL_SPACE

The mapping will succeed as long as there is a free region. However, if Fa object is non- NULL and is already backed by superpages, this strategy will attempt to find a free region aligned relative to the existing superpages.

VMFS_ALIGNED_SPACE (Fa n )

The mapping will succeed as long as there is a free region that aligns on a 2^ Fa n boundary.

IMPLEMENTATION NOTES

This function acquires a lock on Fa map by calling vm_map_lock9, and holds it until the function returns.

The search for a free region is defined to be first-fit, from the address Fa addr onwards.

RETURN VALUES

The Fn vm_map_find function returns KERN_SUCCESS if the mapping was successfully created. If space could not be found or Fa find_space was VMFS_NO_SPACE and the given address, Fa addr , was already mapped, KERN_NO_SPACE will be returned. If the discovered range turned out to be bogus, KERN_INVALID_ADDRESS will be returned.

SEE ALSO

vm_map9, vm_map_findspace9, vm_map_insert9, vm_map_lock9

AUTHORS

This manual page was written by An Bruce M Simpson Aq bms@spc.org .