From nobody Sat Mar 26 01:11:45 2022 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id AA86C1A3CF62; Sat, 26 Mar 2022 01:11:46 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4KQLX16Kd6z3tk6; Sat, 26 Mar 2022 01:11:45 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1648257106; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=DKh5OPNoQwI+W4L3+cfA6tnOwZ6NUUHHqTnjyHIhFSY=; b=t6ce7HlcJ7h9fMRbdB3xZXocl2jLAs3gFZom36HeLC3Eerg2z9/x7fP+Pl1DO80Wy2L6Hh tzY3VOA1kA30PYCaXcfLM2x99g9erDoIN0mWQZnArU1csNth7WQzwFcfyeGruOe8q4msqu LKhCoXdeAEVyDEYbVITSqNp3giHQTm1DqsYfkGswsvEq+CsAOXZ24ibmjEzqXr1r0+VPoN LPCr6jkqRTllV0Gta9q0wO4VS/Ih2hxLHPLk6YXCFmYXZtX8OxJOD9D+GXdgAQvZG6FAGo i7wW7qhyRIXmq41CnOyX4PmKczgsFzU8Lwg77woLEqUq/s+GLkE3P+8B8eBi6w== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 5A3141779D; Sat, 26 Mar 2022 01:11:45 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 22Q1Bjw6063702; Sat, 26 Mar 2022 01:11:45 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 22Q1BjW5063701; Sat, 26 Mar 2022 01:11:45 GMT (envelope-from git) Date: Sat, 26 Mar 2022 01:11:45 GMT Message-Id: <202203260111.22Q1BjW5063701@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Eric van Gyzen Subject: git: a65bee6705ac - main - stack(9): dynamic allocation is not necessary List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: vangyzen X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: a65bee6705ac73bb334ee052bcf1e85bcc9efceb Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1648257106; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=DKh5OPNoQwI+W4L3+cfA6tnOwZ6NUUHHqTnjyHIhFSY=; b=Q0ZqCVYX4yQFYbfxtoQUXullU6Ss4gtOomiRxlpTo7Q0X69kQ+D5oKsDiZ8pIiMSqZn3We OPgTRE6KQwL7c5/iK8KoQNEd5R1rjAE6BATpxVsP1pSKZMEXbu6+gx34tu9ytLSRKxET1V VPgPkkENW2NFL0xU8VL6878GUHwa3EvMlk1GWTygfe/bTT6mPKLBwbmmsEA6AcV5tIwQoY 6yfUlFlu+rciniDaDQOW11vreKiIzVg8n9uXc13F46YUK5CSqPZisZ5KLZ3abs7IcdaP0W 1G4pkOLFwfF2bUakKTxZe3wEV/3Tdm62HOchsJzRuqjEyGcD0bzRaVGXhCkwDQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1648257106; a=rsa-sha256; cv=none; b=ANRTRY06cMdz2vq9pnVYHaNcH2XELf2amgW810mqQbhw8lj5QPFv4a0R5CKVfWwTUQ/xes LhTNK/3nb8gHjwADVoFl8TH8Yo9thBeoMVaz0d4K3Ms/I9LIQaF9y0qjNmUJkRj+UycBYt Dcy2Dhb5PcT081QBUHxP4eQ1TxxC0BWP/7uPU2J9Rev/P2bu1wsvERw/XVKMLk7JUSPvOc Gof27hV2DK3ptdcMElScbxifLGAsDznWgNlCoeciHSNMyMmlG8m2x/9dCbsKetNaR8Gwio F1UWZxYRTlIkPiD+IzNmG2VZ4cIxoACvKWOQh2PaUzEnKltKJSCy5HEO8EWZvA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by vangyzen: URL: https://cgit.FreeBSD.org/src/commit/?id=a65bee6705ac73bb334ee052bcf1e85bcc9efceb commit a65bee6705ac73bb334ee052bcf1e85bcc9efceb Author: Eric van Gyzen AuthorDate: 2022-03-07 01:12:28 +0000 Commit: Eric van Gyzen CommitDate: 2022-03-26 01:10:38 +0000 stack(9): dynamic allocation is not necessary The man page said dynamic allocation was required, but struct stack can be allocated in any way, including on the stack. Make this clear, and explain how to initialize the struct. While I'm here, stack_save does not require any lock. Reviewed by: markj, Pau Amma MFC after: 1 week Sponsored by: Dell EMC Isilon Differential Revision: https://reviews.freebsd.org/D34461 --- share/man/man9/stack.9 | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/share/man/man9/stack.9 b/share/man/man9/stack.9 index 6ac24ffe9500..9ac64ff333a8 100644 --- a/share/man/man9/stack.9 +++ b/share/man/man9/stack.9 @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 31, 2020 +.Dd March 6, 2022 .Dt STACK 9 .Os .Sh NAME @@ -48,7 +48,7 @@ In the kernel configuration file: .Ft int .Fn stack_put "struct stack *st" "vm_offset_t pc" .Ft void -.Fn stack_copy "const struct stack *src" "struct stack dst" +.Fn stack_copy "const struct stack *src" "struct stack *dst" .Ft void .Fn stack_zero "struct stack *st" .Ft void @@ -60,9 +60,9 @@ In the kernel configuration file: .Ft void .Fn stack_print_short_ddb "const struct stack *st" .Ft void -.Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st" +.Fn stack_sbuf_print "struct sbuf *sb" "const struct stack *st" .Ft void -.Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st" +.Fn stack_sbuf_print_ddb "struct sbuf *sb" "const struct stack *st" .Ft void .Fn stack_save "struct stack *st" .Ft int @@ -81,21 +81,26 @@ must be compiled into the kernel. .Pp Each stack trace is described by a .Vt "struct stack" . -Before a trace may be created or otherwise manipulated, storage for the trace -must be allocated with +It can be declared in the usual ways, including on the stack, and optionally +initialized with +.Fn stack_zero , +though this is not necessary before saving a trace. +It can also be dynamically allocated with .Fn stack_create . The .Ar flags argument is passed to .Xr malloc 9 . -Memory associated with a trace is freed by calling +This dynamic allocation must be freed with .Fn stack_destroy . .Pp A trace of the current thread's kernel call stack may be captured using .Fn stack_save . .Fn stack_save_td can be used to capture the kernel stack of a caller-specified thread. -Callers of these functions must own the thread lock of the specified thread, +Callers of +.Fn stack_save_td +must own the thread lock of the specified thread, and the thread's stack must not be swapped out. .Fn stack_save_td can capture the kernel stack of a running thread, though note that this is