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.\" $FreeBSD$ 26.\" 27.Dd April 21, 2022 28.Dt UNR 9 29.Os 30.Sh NAME 31.Nm new_unrhdr , 32.Nm clean_unrhdr , 33.Nm clear_unrhdr , 34.Nm delete_unrhdr , 35.Nm alloc_unr , 36.Nm alloc_unr_specific , 37.Nm free_unr , 38.Nm create_iter_unr , 39.Nm next_iter_unr , 40.Nm free_iter_unr 41.Nd "kernel unit number allocator" 42.Sh SYNOPSIS 43.In sys/systm.h 44.Ft "struct unrhdr *" 45.Fn new_unrhdr "int low" "int high" "struct mtx *mutex" 46.Ft void 47.Fn clean_unrhdr "struct unrhdr *uh" 48.Ft void 49.Fn clean_unrhdrl "struct unrhdr *uh" 50.Ft void 51.Fn clear_unrhdr "struct unrhdr *uh" 52.Ft void 53.Fn delete_unrhdr "struct unrhdr *uh" 54.Ft int 55.Fn alloc_unr "struct unrhdr *uh" 56.Ft int 57.Fn alloc_unrl "struct unrhdr *uh" 58.Ft int 59.Fn alloc_unr_specific "struct unrhdr *uh" "u_int item" 60.Ft void 61.Fn free_unr "struct unrhdr *uh" "u_int item" 62.Ft void * 63.Fn create_iter_unr "struct unrhdr *uh" 64.Ft int 65.Fn next_iter_unr "void *handle" 66.Ft void 67.Fn free_iter_unr "void *handle" 68.Sh DESCRIPTION 69The kernel unit number allocator is a generic facility, which allows to allocate 70unit numbers within a specified range. 71.Bl -tag -width indent 72.It Fn new_unrhdr low high mutex 73Initialize a new unit number allocator entity. 74The 75.Fa low 76and 77.Fa high 78arguments 79specify minimum and maximum number of unit numbers. 80There is no cost associated with the range of unit numbers, so unless the resource 81really is finite, 82.Dv INT_MAX 83can be used. 84If 85.Fa mutex 86is not 87.Dv NULL , 88it is used for locking when allocating and freeing units. 89If the passed value is the token 90.Va UNR_NO_MTX , 91then no locking is applied internally. 92Otherwise, internal mutex is used. 93.It Fn clear_unrhdr uh 94Clear all units from the specified unit number allocator entity. 95This function resets the entity as if it were just initialized with 96.Fn new_unrhdr . 97.It Fn delete_unrhdr uh 98Delete specified unit number allocator entity. 99This function frees the memory associated with the entity, it does not free 100any units. 101To free all units use 102.Fn clear_unrhdr . 103.It Fn clean_unrhdr uh 104Freeing unit numbers might result in some internal memory becoming unused. 105There are 106.Nm unit 107allocator consumers that cannot tolerate taking 108.Xr malloc 9 109locks to free the memory, while having their unit mutex locked. 110For this reason, free of the unused memory after delete is postponed 111until the consumer can afford calling into the 112.Xr malloc 9 113subsystem. 114Call 115.Fn clean_unrhdr uh 116to do the cleanup. 117In particular, this needs to be done before freeing a unr, if 118a deletion of units could have been performed. 119.It Fn clean_unrhdrl 120Same as 121.Fn clean_unrhdr , 122but assumes that the unr mutex is already owned, if any. 123.It Fn alloc_unr uh 124Return a new unit number. 125The lowest free number is always allocated. 126This function does not allocate memory and never sleeps, however it may 127block on a mutex. 128If no free unit numbers are left, 129.Li \-1 130is returned. 131.It Fn alloc_unrl uh 132Same as 133.Fn alloc_unr 134except that mutex is assumed to be already locked and thus is not used. 135.It Fn alloc_unr_specific uh item 136Allocate a specific unit number. 137This function allocates memory and thus may sleep. 138The allocated unit number is returned on success. 139If the specified number is already allocated or out of the range, 140.Li \-1 141is returned. 142.It Fn free_unr uh item 143Free a previously allocated unit number. 144This function may require allocating memory, and thus it can sleep. 145There is no pre-locked variant. 146.El 147.Sh ITERATOR INTERFACE 148The 149.Nm unr 150facility provides an interface to iterate over all allocated units 151for the given 152.Dv unrhdr . 153Iterators are identified by an opaque handle. 154More than one iterators can operate simultaneously; the iterator position 155data is recorded only in the iterator handle. 156.Pp 157Consumers must ensure that the unit allocator is not modified between 158calls to the iterator functions. 159In particular, the internal allocator mutex cannot provide consistency, 160because it is acquired and dropped inside the 161.Fn next_iter_unr 162function. 163If the allocator was modified, it is safe to free the iterator with 164.Fn free_iter_unr 165method nevertheless. 166.Bl -tag -width indent 167.It Fn create_iter_unr uh 168Create an iterator. 169Return the handle that should be passed to other iterator functions. 170.It Fn next_iter_unr handle 171Return the value of the next unit. 172Units are returned in ascending order. 173A return value of 174.Li \-1 175indicates the end of iteration, in which 176case 177.Li \-1 178is returned for all future calls. 179.It Fn free_iter_unr handle 180Free the iterator, handle is no longer valid. 181.El 182.Sh CODE REFERENCES 183The above functions are implemented in 184.Pa sys/kern/subr_unit.c . 185.Sh HISTORY 186Kernel unit number allocator first appeared in 187.Fx 6.0 . 188.Sh AUTHORS 189.An -nosplit 190Kernel unit number allocator was written by 191.An Poul-Henning Kamp . 192This manpage was written by 193.An Gleb Smirnoff . 194