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.Nd "kernel unit number allocator" 39.Sh SYNOPSIS 40.In sys/systm.h 41.Ft "struct unrhdr *" 42.Fn new_unrhdr "int low" "int high" "struct mtx *mutex" 43.Ft void 44.Fn clean_unrhdr "struct unrhdr *uh" 45.Ft void 46.Fn clean_unrhdrl "struct unrhdr *uh" 47.Ft void 48.Fn clear_unrhdr "struct unrhdr *uh" 49.Ft void 50.Fn delete_unrhdr "struct unrhdr *uh" 51.Ft int 52.Fn alloc_unr "struct unrhdr *uh" 53.Ft int 54.Fn alloc_unrl "struct unrhdr *uh" 55.Ft int 56.Fn alloc_unr_specific "struct unrhdr *uh" "u_int item" 57.Ft void 58.Fn free_unr "struct unrhdr *uh" "u_int item" 59.Sh DESCRIPTION 60The kernel unit number allocator is a generic facility, which allows to allocate 61unit numbers within a specified range. 62.Bl -tag -width indent 63.It Fn new_unrhdr low high mutex 64Initialize a new unit number allocator entity. 65The 66.Fa low 67and 68.Fa high 69arguments 70specify minimum and maximum number of unit numbers. 71There is no cost associated with the range of unit numbers, so unless the resource 72really is finite, 73.Dv INT_MAX 74can be used. 75If 76.Fa mutex 77is not 78.Dv NULL , 79it is used for locking when allocating and freeing units. 80If the passed value is the token 81.Va UNR_NO_MTX , 82then no locking is applied internally. 83Otherwise, internal mutex is used. 84.It Fn clear_unrhdr uh 85Clear all units from the specified unit number allocator entity. 86This function resets the entity as if it were just initialized with 87.Fn new_unrhdr . 88.It Fn delete_unrhdr uh 89Delete specified unit number allocator entity. 90This function frees the memory associated with the entity, it does not free 91any units. 92To free all units use 93.Fn clear_unrhdr . 94.It Fn clean_unrhdr uh 95Freeing unit numbers might result in some internal memory becoming unused. 96There are 97.Nm unit 98allocator consumers that cannot tolerate taking 99.Xr malloc 9 100locks to free the memory, while having their unit mutex locked. 101For this reason, free of the unused memory after delete is postponed 102until the consumer can afford calling into the 103.Xr malloc 9 104subsystem. 105Call 106.Fn clean_unrhdr uh 107to do the cleanup. 108In particular, this needs to be done before freeing a unr, if 109a deletion of units could have been performed. 110.It Fn clean_unrhdrl 111Same as 112.Fn clean_unrhdr , 113but assumes that the unr mutex is already owned, if any. 114.It Fn alloc_unr uh 115Return a new unit number. 116The lowest free number is always allocated. 117This function does not allocate memory and never sleeps, however it may 118block on a mutex. 119If no free unit numbers are left, 120.Li \-1 121is returned. 122.It Fn alloc_unrl uh 123Same as 124.Fn alloc_unr 125except that mutex is assumed to be already locked and thus is not used. 126.It Fn alloc_unr_specific uh item 127Allocate a specific unit number. 128This function allocates memory and thus may sleep. 129The allocated unit number is returned on success. 130If the specified number is already allocated or out of the range, 131.Li \-1 132is returned. 133.It Fn free_unr uh item 134Free a previously allocated unit number. 135This function may require allocating memory, and thus it can sleep. 136There is no pre-locked variant. 137.El 138.Sh CODE REFERENCES 139The above functions are implemented in 140.Pa sys/kern/subr_unit.c . 141.Sh HISTORY 142Kernel unit number allocator first appeared in 143.Fx 6.0 . 144.Sh AUTHORS 145.An -nosplit 146Kernel unit number allocator was written by 147.An Poul-Henning Kamp . 148This manpage was written by 149.An Gleb Smirnoff . 150