git: b3e2d70a7f30 - stable/12 - malloc(9): Document/complete aligned variants

[Kyle Evans]

The branch stable/12 has been updated by kevans:

URL: https://cgit.FreeBSD.org/src/commit/?id=b3e2d70a7f301d21f38e38983677989dc88a6c3f

commit b3e2d70a7f301d21f38e38983677989dc88a6c3f
Author:     Adam Fenn <adam at fenn.io>
AuthorDate: 2021-08-02 20:33:31 +0000
Commit:     Kyle Evans <kevans at FreeBSD.org>
CommitDate: 2021-08-27 01:10:58 +0000

    malloc(9): Document/complete aligned variants
    
    Comments on a pending kvmclock driver suggested adding a
    malloc_aligned() to complement malloc_domainset_aligned(); add it now,
    and document both.
    
    (cherry picked from commit 6162cf885c00a0893a0961415f1829942343dcc1)
    (cherry picked from commit 04cc0c393c317b6d5e28c8dc80cd1b5ea071f28f)
---
 share/man/man9/malloc.9 | 25 ++++++++++++++++++++++++-
 sys/kern/kern_malloc.c  |  7 +++++++
 sys/sys/malloc.h        |  2 ++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9
index bdfdaca6bba9..a42183bb476c 100644
--- a/share/man/man9/malloc.9
+++ b/share/man/man9/malloc.9
@@ -29,7 +29,7 @@
 .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
 .\" $FreeBSD$
 .\"
-.Dd March 6, 2021
+.Dd August 26, 2021
 .Dt MALLOC 9
 .Os
 .Sh NAME
@@ -55,6 +55,13 @@
 .Fn reallocf "void *addr" "size_t size" "struct malloc_type *type" "int flags"
 .Ft size_t
 .Fn malloc_usable_size "const void *addr"
+.Ft void *
+.Fo malloc_aligned
+.Fa "size_t size"
+.Fa "size_t align"
+.Fa "struct malloc_type *type"
+.Fa "int flags"
+.Fc
 .Fn MALLOC_DECLARE type
 .In sys/param.h
 .In sys/malloc.h
@@ -65,6 +72,14 @@
 .Ft void *
 .Fn malloc_domainset "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
 .Ft void *
+.Fo malloc_domainset_aligned
+.Fa "size_t size"
+.Fa "size_t align"
+.Fa "struct malloc_type *type"
+.Fa "struct domainset *ds"
+.Fa "int flags"
+.Fc
+.Ft void *
 .Fn mallocarray_domainset "size_t nmemb" "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
 .Ft void
 .Fn free_domain "void *addr" "struct malloc_type *type"
@@ -87,6 +102,14 @@ Memory allocated with this function should be returned with
 .Fn free_domain .
 .Pp
 The
+.Fn malloc_aligned
+and
+.Fn malloc_domainset_aligned
+variants return allocations aligned as specified by
+.Fa align ,
+which must be non-zero, a power of two, and less than or equal to the page size.
+.Pp
+The
 .Fn mallocarray
 function allocates uninitialized memory in kernel address space for an
 array of
diff --git a/sys/kern/kern_malloc.c b/sys/kern/kern_malloc.c
index 41eef1d6a4ac..f16163d396e2 100644
--- a/sys/kern/kern_malloc.c
+++ b/sys/kern/kern_malloc.c
@@ -658,6 +658,13 @@ malloc_domainset(size_t size, struct malloc_type *mtp, struct domainset *ds,
 	return (ret);
 }
 
+void *
+malloc_aligned(size_t size, size_t align, struct malloc_type *type, int flags)
+{
+	return (malloc_domainset_aligned(size, align, type, DOMAINSET_RR(),
+	    flags));
+}
+
 void *
 malloc_domainset_aligned(size_t size, size_t align,
     struct malloc_type *mtp, struct domainset *ds, int flags)
diff --git a/sys/sys/malloc.h b/sys/sys/malloc.h
index bf7ec5c8e9c6..4459176ca9d3 100644
--- a/sys/sys/malloc.h
+++ b/sys/sys/malloc.h
@@ -252,6 +252,8 @@ void	*realloc(void *addr, size_t size, struct malloc_type *type, int flags)
 	    __result_use_check __alloc_size(2);
 void	*reallocf(void *addr, size_t size, struct malloc_type *type, int flags)
 	    __result_use_check __alloc_size(2);
+void	*malloc_aligned(size_t size, size_t align, struct malloc_type *type,
+	    int flags) __malloc_like __result_use_check __alloc_size(1);
 void	*malloc_domainset_aligned(size_t size, size_t align,
 	    struct malloc_type *mtp, struct domainset *ds, int flags)
 	    __malloc_like __result_use_check __alloc_size(1);