git: 6162cf885c00 - main - malloc(9): Document/complete aligned variants

[Kyle Evans]

The branch main has been updated by kevans:

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

commit 6162cf885c00a0893a0961415f1829942343dcc1
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-02 20:36:14 +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.
    
    Reviewed by:    imp, kib, allanjude (manpages)
    Differential Revision:  https://reviews.freebsd.org/D31004
---
 share/man/man9/malloc.9 | 25 ++++++++++++++++++++++++-
 sys/sys/malloc.h        |  2 ++
 2 files changed, 26 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/sys/malloc.h b/sys/sys/malloc.h
index b8c2788edd44..3d88460a751e 100644
--- a/sys/sys/malloc.h
+++ b/sys/sys/malloc.h
@@ -265,6 +265,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);