1.\" Copyright (c) 2005 Gleb Smirnoff <glebius@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd April 21, 2022 26.Dt UNR 9 27.Os 28.Sh NAME 29.Nm new_unrhdr , 30.Nm clean_unrhdr , 31.Nm clear_unrhdr , 32.Nm delete_unrhdr , 33.Nm alloc_unr , 34.Nm alloc_unr_specific , 35.Nm free_unr , 36.Nm create_iter_unr , 37.Nm next_iter_unr , 38.Nm free_iter_unr 39.Nd "kernel unit number allocator" 40.Sh SYNOPSIS 41.In sys/systm.h 42.Ft "struct unrhdr *" 43.Fn new_unrhdr "int low" "int high" "struct mtx *mutex" 44.Ft void 45.Fn clean_unrhdr "struct unrhdr *uh" 46.Ft void 47.Fn clean_unrhdrl "struct unrhdr *uh" 48.Ft void 49.Fn clear_unrhdr "struct unrhdr *uh" 50.Ft void 51.Fn delete_unrhdr "struct unrhdr *uh" 52.Ft int 53.Fn alloc_unr "struct unrhdr *uh" 54.Ft int 55.Fn alloc_unrl "struct unrhdr *uh" 56.Ft int 57.Fn alloc_unr_specific "struct unrhdr *uh" "u_int item" 58.Ft void 59.Fn free_unr "struct unrhdr *uh" "u_int item" 60.Ft void * 61.Fn create_iter_unr "struct unrhdr *uh" 62.Ft int 63.Fn next_iter_unr "void *handle" 64.Ft void 65.Fn free_iter_unr "void *handle" 66.Sh DESCRIPTION 67The kernel unit number allocator is a generic facility, which allows to allocate 68unit numbers within a specified range. 69.Bl -tag -width indent 70.It Fn new_unrhdr low high mutex 71Initialize a new unit number allocator entity. 72The 73.Fa low 74and 75.Fa high 76arguments 77specify minimum and maximum number of unit numbers. 78There is no cost associated with the range of unit numbers, so unless the resource 79really is finite, 80.Dv INT_MAX 81can be used. 82If 83.Fa mutex 84is not 85.Dv NULL , 86it is used for locking when allocating and freeing units. 87If the passed value is the token 88.Va UNR_NO_MTX , 89then no locking is applied internally. 90Otherwise, internal mutex is used. 91.It Fn clear_unrhdr uh 92Clear all units from the specified unit number allocator entity. 93This function resets the entity as if it were just initialized with 94.Fn new_unrhdr . 95.It Fn delete_unrhdr uh 96Delete specified unit number allocator entity. 97This function frees the memory associated with the entity, it does not free 98any units. 99To free all units use 100.Fn clear_unrhdr . 101.It Fn clean_unrhdr uh 102Freeing unit numbers might result in some internal memory becoming unused. 103There are 104.Nm unit 105allocator consumers that cannot tolerate taking 106.Xr malloc 9 107locks to free the memory, while having their unit mutex locked. 108For this reason, free of the unused memory after delete is postponed 109until the consumer can afford calling into the 110.Xr malloc 9 111subsystem. 112Call 113.Fn clean_unrhdr uh 114to do the cleanup. 115In particular, this needs to be done before freeing a unr, if 116a deletion of units could have been performed. 117.It Fn clean_unrhdrl 118Same as 119.Fn clean_unrhdr , 120but assumes that the unr mutex is already owned, if any. 121.It Fn alloc_unr uh 122Return a new unit number. 123The lowest free number is always allocated. 124This function does not allocate memory and never sleeps, however it may 125block on a mutex. 126If no free unit numbers are left, 127.Li \-1 128is returned. 129.It Fn alloc_unrl uh 130Same as 131.Fn alloc_unr 132except that mutex is assumed to be already locked and thus is not used. 133.It Fn alloc_unr_specific uh item 134Allocate a specific unit number. 135This function allocates memory and thus may sleep. 136The allocated unit number is returned on success. 137If the specified number is already allocated or out of the range, 138.Li \-1 139is returned. 140.It Fn free_unr uh item 141Free a previously allocated unit number. 142This function may require allocating memory, and thus it can sleep. 143There is no pre-locked variant. 144.El 145.Sh ITERATOR INTERFACE 146The 147.Nm unr 148facility provides an interface to iterate over all allocated units 149for the given 150.Dv unrhdr . 151Iterators are identified by an opaque handle. 152More than one iterators can operate simultaneously; the iterator position 153data is recorded only in the iterator handle. 154.Pp 155Consumers must ensure that the unit allocator is not modified between 156calls to the iterator functions. 157In particular, the internal allocator mutex cannot provide consistency, 158because it is acquired and dropped inside the 159.Fn next_iter_unr 160function. 161If the allocator was modified, it is safe to free the iterator with 162.Fn free_iter_unr 163method nevertheless. 164.Bl -tag -width indent 165.It Fn create_iter_unr uh 166Create an iterator. 167Return the handle that should be passed to other iterator functions. 168.It Fn next_iter_unr handle 169Return the value of the next unit. 170Units are returned in ascending order. 171A return value of 172.Li \-1 173indicates the end of iteration, in which 174case 175.Li \-1 176is returned for all future calls. 177.It Fn free_iter_unr handle 178Free the iterator, handle is no longer valid. 179.El 180.Sh CODE REFERENCES 181The above functions are implemented in 182.Pa sys/kern/subr_unit.c . 183.Sh HISTORY 184Kernel unit number allocator first appeared in 185.Fx 6.0 . 186.Sh AUTHORS 187.An -nosplit 188Kernel unit number allocator was written by 189.An Poul-Henning Kamp . 190This manpage was written by 191.An Gleb Smirnoff . 192