From: Dave Martin <Dave.Martin@arm.com> To: Michael Kerrisk <mtk.manpages@gmail.com> Cc: Catalin Marinas <catalin.marinas@arm.com>, Will Deacon <will@kernel.org>, Vincenzo Frascino <vincenzo.frascino@arm.com>, linux-man@vger.kernel.org, linux-arch@vger.kernel.org, linux-arm-kernel@lists.infradead.org Subject: RFC: Adding arch-specific user ABI documentation in linux-man Date: Mon, 4 May 2020 16:32:35 +0100 [thread overview] Message-ID: <20200504153214.GH30377@arm.com> (raw) Hi all, I considering trying to plug some gaps in the arch-specific ABI documentation in the linux man-pages, specifically for arm64 (and possibly arm, where compat means we have some overlap). For arm64, there are now significant new extensions (Pointer authentication, SVE, MTE etc.) Currently there is some user-facing documentation mixed in with the kernel-facing documentation in the kernel tree, but this situation isn't ideal. Do you have an opinion on where in the man-pages documentation should be added, and how to structure it? Affected areas include: * exec interface * aux vector, hwcaps * arch-specific signals * signal frame * mmap/mprotect extensions * prctl calls * ptrace quirks and extensions * coredump contents Not everything has an obvious home in an existing page, and adding specifics for every architecture could make some existing manpages very unwieldy. I think for some arch features, we really need some "overview" pages too: just documenting the low-level details is of limited value without some guide as to how to use them together. Does the following sketch look reasonable? * man7/arm64.7: new page: overview of arm64-specific ABI extensions * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: overview of arm64 SVE ABI * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: arm64 ptrace extensions * man2/mmap.2: extend with arm64-specific flags (only two flags, so we add them to the existing man page rather than creating a new one). etc. Ideally, I'd like to adopt a pattern that other arches can follow. Thoughts? Cheers ---Dave
WARNING: multiple messages have this Message-ID (diff)
From: Dave Martin <Dave.Martin@arm.com> To: Michael Kerrisk <mtk.manpages@gmail.com> Cc: linux-arch@vger.kernel.org, linux-man@vger.kernel.org, Catalin Marinas <catalin.marinas@arm.com>, Vincenzo Frascino <vincenzo.frascino@arm.com>, Will Deacon <will@kernel.org>, linux-arm-kernel@lists.infradead.org Subject: RFC: Adding arch-specific user ABI documentation in linux-man Date: Mon, 4 May 2020 16:32:35 +0100 [thread overview] Message-ID: <20200504153214.GH30377@arm.com> (raw) Hi all, I considering trying to plug some gaps in the arch-specific ABI documentation in the linux man-pages, specifically for arm64 (and possibly arm, where compat means we have some overlap). For arm64, there are now significant new extensions (Pointer authentication, SVE, MTE etc.) Currently there is some user-facing documentation mixed in with the kernel-facing documentation in the kernel tree, but this situation isn't ideal. Do you have an opinion on where in the man-pages documentation should be added, and how to structure it? Affected areas include: * exec interface * aux vector, hwcaps * arch-specific signals * signal frame * mmap/mprotect extensions * prctl calls * ptrace quirks and extensions * coredump contents Not everything has an obvious home in an existing page, and adding specifics for every architecture could make some existing manpages very unwieldy. I think for some arch features, we really need some "overview" pages too: just documenting the low-level details is of limited value without some guide as to how to use them together. Does the following sketch look reasonable? * man7/arm64.7: new page: overview of arm64-specific ABI extensions * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: overview of arm64 SVE ABI * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: arm64 ptrace extensions * man2/mmap.2: extend with arm64-specific flags (only two flags, so we add them to the existing man page rather than creating a new one). etc. Ideally, I'd like to adopt a pattern that other arches can follow. Thoughts? Cheers ---Dave _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next reply other threads:[~2020-05-04 15:32 UTC|newest] Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-05-04 15:32 Dave Martin [this message] 2020-05-04 15:32 ` RFC: Adding arch-specific user ABI documentation in linux-man Dave Martin 2020-05-05 7:45 ` AW: " Walter Harms 2020-05-05 7:45 ` Walter Harms 2020-05-05 7:45 ` Walter Harms 2020-05-05 7:45 ` Walter Harms 2020-05-05 10:55 ` Dave Martin 2020-05-05 10:55 ` Dave Martin 2020-05-05 10:55 ` Dave Martin 2020-05-05 10:55 ` Dave Martin 2020-05-05 10:44 ` RFC: " Will Deacon 2020-05-05 10:44 ` Will Deacon 2020-05-05 11:05 ` Dave Martin 2020-05-05 11:05 ` Dave Martin 2020-05-05 11:05 ` Dave Martin 2020-05-05 12:14 ` Will Deacon 2020-05-05 12:14 ` Will Deacon 2020-05-05 12:14 ` Will Deacon 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-05 12:43 ` Russell King - ARM Linux admin 2020-05-05 12:43 ` Russell King - ARM Linux admin 2020-05-05 12:43 ` Russell King - ARM Linux admin 2020-05-05 13:06 ` Will Deacon 2020-05-05 13:06 ` Will Deacon 2020-05-05 13:16 ` Russell King - ARM Linux admin 2020-05-05 13:16 ` Russell King - ARM Linux admin 2020-05-05 13:16 ` Russell King - ARM Linux admin 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 2020-05-06 14:29 ` Dave Martin 2020-05-06 14:29 ` Dave Martin 2020-05-06 14:29 ` Dave Martin
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20200504153214.GH30377@arm.com \ --to=dave.martin@arm.com \ --cc=catalin.marinas@arm.com \ --cc=linux-arch@vger.kernel.org \ --cc=linux-arm-kernel@lists.infradead.org \ --cc=linux-man@vger.kernel.org \ --cc=mtk.manpages@gmail.com \ --cc=vincenzo.frascino@arm.com \ --cc=will@kernel.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.