git: e70e1b132ee8 - stable/13 - malloc(9): Document/complete aligned variants

[Kyle Evans]

The branch stable/13 has been updated by kevans:

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

commit e70e1b132ee88611b2ea8e849811c73ee600cea9
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-26 17:28:38 +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 b8c6e504e0c0..71375e90951f 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 July 2, 2021
 .Dt MALLOC 9
 .Os
 .Sh NAME
@@ -58,6 +58,13 @@
 .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
+.Ft void *
 .Fn malloc_exec "size_t size" "struct malloc_type *type" "int flags"
 .Fn MALLOC_DECLARE type
 .In sys/param.h
@@ -69,6 +76,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 malloc_domainset_exec "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
 .Ft void *
 .Fn mallocarray_domainset "size_t nmemb" "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
@@ -88,6 +103,14 @@ See
 .Xr domainset 9
 for some example policies.
 .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
 Both
 .Fn malloc_exec
 and
diff --git a/sys/kern/kern_malloc.c b/sys/kern/kern_malloc.c
index 48383358e3ad..364828e6a1e6 100644
--- a/sys/kern/kern_malloc.c
+++ b/sys/kern/kern_malloc.c
@@ -763,6 +763,13 @@ malloc_domainset_exec(size_t size, struct malloc_type *mtp, struct domainset *ds
 	return (malloc_large(&size, mtp, ds, flags DEBUG_REDZONE_ARG));
 }
 
+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 8982e534fc22..93ec81c252ff 100644
--- a/sys/sys/malloc.h
+++ b/sys/sys/malloc.h
@@ -264,6 +264,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);