* RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-04 15:32 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-04 15:32 UTC (permalink / raw) To: Michael Kerrisk Cc: Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel 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 ^ permalink raw reply [flat|nested] 38+ messages in thread
* RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-04 15:32 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-04 15:32 UTC (permalink / raw) To: Michael Kerrisk Cc: linux-arch, linux-man, Catalin Marinas, Vincenzo Frascino, Will Deacon, linux-arm-kernel 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 ^ permalink raw reply [flat|nested] 38+ messages in thread
* AW: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 7:45 ` Walter Harms 0 siblings, 0 replies; 38+ messages in thread From: Walter Harms @ 2020-05-05 7:45 UTC (permalink / raw) To: Dave Martin, Michael Kerrisk Cc: Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel Hi Dave, you are pointing to an (IMHO) interesting question. How to document different CPUs ? Given that an operating system should hide the different CPU's using CPU specific features should be used sparsely at best. the easy part are adds-on like flags for prctrl etc. simply add it to the page. Other things should go to a cpu specific pages (can of worms). The problem will be to keep that small but informative. I have no idea about the level of detail (and i have worked with a range of CPUs) that could be interesting for a programmer. An of cause every other CPU now needs also a page. jm2c wh ________________________________________ Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von Dave Martin <Dave.Martin@arm.com> Gesendet: Montag, 4. Mai 2020 17:32:35 An: Michael Kerrisk Cc: Catalin Marinas; Will Deacon; Vincenzo Frascino; linux-man@vger.kernel.org; linux-arch@vger.kernel.org; linux-arm-kernel@lists.infradead.org Betreff: RFC: Adding arch-specific user ABI documentation in linux-man 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 ^ permalink raw reply [flat|nested] 38+ messages in thread
* AW: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 7:45 ` Walter Harms 0 siblings, 0 replies; 38+ messages in thread From: Walter Harms @ 2020-05-05 7:45 UTC (permalink / raw) To: Dave Martin, Michael Kerrisk Cc: linux-arch, linux-man, Catalin Marinas, Vincenzo Frascino, Will Deacon, linux-arm-kernel Hi Dave, you are pointing to an (IMHO) interesting question. How to document different CPUs ? Given that an operating system should hide the different CPU's using CPU specific features should be used sparsely at best. the easy part are adds-on like flags for prctrl etc. simply add it to the page. Other things should go to a cpu specific pages (can of worms). The problem will be to keep that small but informative. I have no idea about the level of detail (and i have worked with a range of CPUs) that could be interesting for a programmer. An of cause every other CPU now needs also a page. jm2c wh ________________________________________ Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von Dave Martin <Dave.Martin@arm.com> Gesendet: Montag, 4. Mai 2020 17:32:35 An: Michael Kerrisk Cc: Catalin Marinas; Will Deacon; Vincenzo Frascino; linux-man@vger.kernel.org; linux-arch@vger.kernel.org; linux-arm-kernel@lists.infradead.org Betreff: RFC: Adding arch-specific user ABI documentation in linux-man 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 ^ permalink raw reply [flat|nested] 38+ messages in thread
* AW: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 7:45 ` Walter Harms 0 siblings, 0 replies; 38+ messages in thread From: Walter Harms @ 2020-05-05 7:45 UTC (permalink / raw) To: Dave Martin, Michael Kerrisk Cc: Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel Hi Dave, you are pointing to an (IMHO) interesting question. How to document different CPUs ? Given that an operating system should hide the different CPU's using CPU specific features should be used sparsely at best. the easy part are adds-on like flags for prctrl etc. simply add it to the page. Other things should go to a cpu specific pages (can of worms). The problem will be to keep that small but informative. I have no idea about the level of detail (and i have worked with a range of CPUs) that could be interesting for a programmer. An of cause every other CPU now needs also a page. jm2c wh ________________________________________ Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von Dave Martin <Dave.Martin@arm.com> Gesendet: Montag, 4. Mai 2020 17:32:35 An: Michael Kerrisk Cc: Catalin Marinas; Will Deacon; Vincenzo Frascino; linux-man@vger.kernel.org; linux-arch@vger.kernel.org; linux-arm-kernel@lists.infradead.org Betreff: RFC: Adding arch-specific user ABI documentation in linux-man 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 ^ permalink raw reply [flat|nested] 38+ messages in thread
* AW: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 7:45 ` Walter Harms 0 siblings, 0 replies; 38+ messages in thread From: Walter Harms @ 2020-05-05 7:45 UTC (permalink / raw) To: Dave Martin, Michael Kerrisk Cc: Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man-u79uwXL29TY76Z2rM5mHXA, linux-arch-u79uwXL29TY76Z2rM5mHXA, linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r Hi Dave, you are pointing to an (IMHO) interesting question. How to document different CPUs ? Given that an operating system should hide the different CPU's using CPU specific features should be used sparsely at best. the easy part are adds-on like flags for prctrl etc. simply add it to the page. Other things should go to a cpu specific pages (can of worms). The problem will be to keep that small but informative. I have no idea about the level of detail (and i have worked with a range of CPUs) that could be interesting for a programmer. An of cause every other CPU now needs also a page. jm2c wh ________________________________________ Von: linux-man-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org <linux-man-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org> im Auftrag von Dave Martin <Dave.Martin-5wv7dgnIgG8@public.gmane.org> Gesendet: Montag, 4. Mai 2020 17:32:35 An: Michael Kerrisk Cc: Catalin Marinas; Will Deacon; Vincenzo Frascino; linux-man-u79uwXL29TasMV2rI37PzA@public.gmane.orgorg; linux-arch-u79uwXL29TY76Z2rM5mHXA@public.gmane.org; linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r@public.gmane.org Betreff: RFC: Adding arch-specific user ABI documentation in linux-man 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 ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 10:55 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-05 10:55 UTC (permalink / raw) To: Walter Harms Cc: Michael Kerrisk, Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel On Tue, May 05, 2020 at 07:45:32AM +0000, Walter Harms wrote: > Hi Dave, > you are pointing to an (IMHO) interesting question. > How to document different CPUs ? > Given that an operating system should hide the different CPU's using > CPU specific features should be used sparsely at best. Agreed! But there are real situations where cpu specifics can't be avoided, and having documentation will help people to use those features correctly. > the easy part are adds-on like flags for prctrl etc. simply add it to the page. For prctl, that makes sense (it's a jumble of arch specifics already). But would it be considered a problem if the ptrace page, say, becomes 80% arch-specific stuff? That page is cumbersome enough already... > Other things should go to a cpu specific pages (can of worms). The problem will > be to keep that small but informative. I have no idea about the level of detail > (and i have worked with a range of CPUs) that could be interesting for a programmer. > An of cause every other CPU now needs also a page. Fair enough. Cheers ---Dave ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 10:55 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-05 10:55 UTC (permalink / raw) To: Walter Harms Cc: linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, Will Deacon, linux-arm-kernel On Tue, May 05, 2020 at 07:45:32AM +0000, Walter Harms wrote: > Hi Dave, > you are pointing to an (IMHO) interesting question. > How to document different CPUs ? > Given that an operating system should hide the different CPU's using > CPU specific features should be used sparsely at best. Agreed! But there are real situations where cpu specifics can't be avoided, and having documentation will help people to use those features correctly. > the easy part are adds-on like flags for prctrl etc. simply add it to the page. For prctl, that makes sense (it's a jumble of arch specifics already). But would it be considered a problem if the ptrace page, say, becomes 80% arch-specific stuff? That page is cumbersome enough already... > Other things should go to a cpu specific pages (can of worms). The problem will > be to keep that small but informative. I have no idea about the level of detail > (and i have worked with a range of CPUs) that could be interesting for a programmer. > An of cause every other CPU now needs also a page. Fair enough. Cheers ---Dave _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 10:55 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-05 10:55 UTC (permalink / raw) To: Walter Harms Cc: Michael Kerrisk, Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel On Tue, May 05, 2020 at 07:45:32AM +0000, Walter Harms wrote: > Hi Dave, > you are pointing to an (IMHO) interesting question. > How to document different CPUs ? > Given that an operating system should hide the different CPU's using > CPU specific features should be used sparsely at best. Agreed! But there are real situations where cpu specifics can't be avoided, and having documentation will help people to use those features correctly. > the easy part are adds-on like flags for prctrl etc. simply add it to the page. For prctl, that makes sense (it's a jumble of arch specifics already). But would it be considered a problem if the ptrace page, say, becomes 80% arch-specific stuff? That page is cumbersome enough already... > Other things should go to a cpu specific pages (can of worms). The problem will > be to keep that small but informative. I have no idea about the level of detail > (and i have worked with a range of CPUs) that could be interesting for a programmer. > An of cause every other CPU now needs also a page. Fair enough. Cheers ---Dave ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 10:55 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-05 10:55 UTC (permalink / raw) To: Walter Harms Cc: Michael Kerrisk, Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man-u79uwXL29TY76Z2rM5mHXA, linux-arch-u79uwXL29TY76Z2rM5mHXA, linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r On Tue, May 05, 2020 at 07:45:32AM +0000, Walter Harms wrote: > Hi Dave, > you are pointing to an (IMHO) interesting question. > How to document different CPUs ? > Given that an operating system should hide the different CPU's using > CPU specific features should be used sparsely at best. Agreed! But there are real situations where cpu specifics can't be avoided, and having documentation will help people to use those features correctly. > the easy part are adds-on like flags for prctrl etc. simply add it to the page. For prctl, that makes sense (it's a jumble of arch specifics already). But would it be considered a problem if the ptrace page, say, becomes 80% arch-specific stuff? That page is cumbersome enough already... > Other things should go to a cpu specific pages (can of worms). The problem will > be to keep that small but informative. I have no idea about the level of detail > (and i have worked with a range of CPUs) that could be interesting for a programmer. > An of cause every other CPU now needs also a page. Fair enough. Cheers ---Dave ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man 2020-05-04 15:32 ` Dave Martin @ 2020-05-05 10:44 ` Will Deacon -1 siblings, 0 replies; 38+ messages in thread From: Will Deacon @ 2020-05-05 10:44 UTC (permalink / raw) To: Dave Martin Cc: Michael Kerrisk, Catalin Marinas, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel Hi Dave, On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > 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 Michael has been nagging me on and off about that for, what, 10 years now? I would therefore be very much in favour of having our ptrace extensions documented! We could even put this stuff under Documentation/arm64/man/ if it's deemed too CPU-specific for the man-pages project, but my preference would still be for it to be hosted there alongside all the other man pages. Will ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 10:44 ` Will Deacon 0 siblings, 0 replies; 38+ messages in thread From: Will Deacon @ 2020-05-05 10:44 UTC (permalink / raw) To: Dave Martin Cc: linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, linux-arm-kernel Hi Dave, On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > 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 Michael has been nagging me on and off about that for, what, 10 years now? I would therefore be very much in favour of having our ptrace extensions documented! We could even put this stuff under Documentation/arm64/man/ if it's deemed too CPU-specific for the man-pages project, but my preference would still be for it to be hosted there alongside all the other man pages. Will _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man 2020-05-05 10:44 ` Will Deacon (?) @ 2020-05-05 11:05 ` Dave Martin -1 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-05 11:05 UTC (permalink / raw) To: Will Deacon Cc: Michael Kerrisk, Catalin Marinas, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > Hi Dave, > > On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > > 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 > > Michael has been nagging me on and off about that for, what, 10 years now? > I would therefore be very much in favour of having our ptrace extensions > documented! > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > too CPU-specific for the man-pages project, but my preference would still > be for it to be hosted there alongside all the other man pages. Heh, perhaps we could build that into the kernel and mount it somewhere. Seriously though, I guess I can start off with straightforward small things for which the documentation has an obvious home (like prctls[*]) and then move on to the bigger stuff like ptrace. If people start shouting about a page getting too big or messy I can try to split it up. Make sense? Cheers ---Dave [*] "straightforward" was a joke, obviously ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 11:05 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-05 11:05 UTC (permalink / raw) To: Will Deacon Cc: linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, linux-arm-kernel On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > Hi Dave, > > On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > > 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 > > Michael has been nagging me on and off about that for, what, 10 years now? > I would therefore be very much in favour of having our ptrace extensions > documented! > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > too CPU-specific for the man-pages project, but my preference would still > be for it to be hosted there alongside all the other man pages. Heh, perhaps we could build that into the kernel and mount it somewhere. Seriously though, I guess I can start off with straightforward small things for which the documentation has an obvious home (like prctls[*]) and then move on to the bigger stuff like ptrace. If people start shouting about a page getting too big or messy I can try to split it up. Make sense? Cheers ---Dave [*] "straightforward" was a joke, obviously _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 11:05 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-05 11:05 UTC (permalink / raw) To: Will Deacon Cc: Michael Kerrisk, Catalin Marinas, Vincenzo Frascino, linux-man-u79uwXL29TY76Z2rM5mHXA, linux-arch-u79uwXL29TY76Z2rM5mHXA, linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > Hi Dave, > > On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > > 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 > > Michael has been nagging me on and off about that for, what, 10 years now? > I would therefore be very much in favour of having our ptrace extensions > documented! > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > too CPU-specific for the man-pages project, but my preference would still > be for it to be hosted there alongside all the other man pages. Heh, perhaps we could build that into the kernel and mount it somewhere. Seriously though, I guess I can start off with straightforward small things for which the documentation has an obvious home (like prctls[*]) and then move on to the bigger stuff like ptrace. If people start shouting about a page getting too big or messy I can try to split it up. Make sense? Cheers ---Dave [*] "straightforward" was a joke, obviously ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 12:14 ` Will Deacon 0 siblings, 0 replies; 38+ messages in thread From: Will Deacon @ 2020-05-05 12:14 UTC (permalink / raw) To: Dave Martin Cc: Michael Kerrisk, Catalin Marinas, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel On Tue, May 05, 2020 at 12:05:19PM +0100, Dave Martin wrote: > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > Hi Dave, > > > > On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > > > 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 > > > > Michael has been nagging me on and off about that for, what, 10 years now? > > I would therefore be very much in favour of having our ptrace extensions > > documented! > > > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > > too CPU-specific for the man-pages project, but my preference would still > > be for it to be hosted there alongside all the other man pages. > > Heh, perhaps we could build that into the kernel and mount it somewhere. Argh, don't joke too loudly about things like that! > Seriously though, > > I guess I can start off with straightforward small things for which the > documentation has an obvious home (like prctls[*]) and then move on to > the bigger stuff like ptrace. > > If people start shouting about a page getting too big or messy I can try > to split it up. > > Make sense? Sure, works for me. Will ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 12:14 ` Will Deacon 0 siblings, 0 replies; 38+ messages in thread From: Will Deacon @ 2020-05-05 12:14 UTC (permalink / raw) To: Dave Martin Cc: linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, linux-arm-kernel On Tue, May 05, 2020 at 12:05:19PM +0100, Dave Martin wrote: > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > Hi Dave, > > > > On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > > > 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 > > > > Michael has been nagging me on and off about that for, what, 10 years now? > > I would therefore be very much in favour of having our ptrace extensions > > documented! > > > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > > too CPU-specific for the man-pages project, but my preference would still > > be for it to be hosted there alongside all the other man pages. > > Heh, perhaps we could build that into the kernel and mount it somewhere. Argh, don't joke too loudly about things like that! > Seriously though, > > I guess I can start off with straightforward small things for which the > documentation has an obvious home (like prctls[*]) and then move on to > the bigger stuff like ptrace. > > If people start shouting about a page getting too big or messy I can try > to split it up. > > Make sense? Sure, works for me. Will _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 12:14 ` Will Deacon 0 siblings, 0 replies; 38+ messages in thread From: Will Deacon @ 2020-05-05 12:14 UTC (permalink / raw) To: Dave Martin Cc: Michael Kerrisk, Catalin Marinas, Vincenzo Frascino, linux-man-u79uwXL29TY76Z2rM5mHXA, linux-arch-u79uwXL29TY76Z2rM5mHXA, linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r On Tue, May 05, 2020 at 12:05:19PM +0100, Dave Martin wrote: > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > Hi Dave, > > > > On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > > > 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 > > > > Michael has been nagging me on and off about that for, what, 10 years now? > > I would therefore be very much in favour of having our ptrace extensions > > documented! > > > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > > too CPU-specific for the man-pages project, but my preference would still > > be for it to be hosted there alongside all the other man pages. > > Heh, perhaps we could build that into the kernel and mount it somewhere. Argh, don't joke too loudly about things like that! > Seriously though, > > I guess I can start off with straightforward small things for which the > documentation has an obvious home (like prctls[*]) and then move on to > the bigger stuff like ptrace. > > If people start shouting about a page getting too big or messy I can try > to split it up. > > Make sense? Sure, works for me. Will ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man 2020-05-05 11:05 ` Dave Martin @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) -1 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Dave Martin, Will Deacon Cc: mtk.manpages, Catalin Marinas, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel > If people start shouting about a page getting too big or messy I can try > to split it up. > > Make sense? Yes. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Dave Martin, Will Deacon Cc: linux-arch, linux-man, Catalin Marinas, mtk.manpages, Vincenzo Frascino, linux-arm-kernel > If people start shouting about a page getting too big or messy I can try > to split it up. > > Make sense? Yes. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man 2020-05-05 10:44 ` Will Deacon (?) @ 2020-05-05 12:43 ` Russell King - ARM Linux admin -1 siblings, 0 replies; 38+ messages in thread From: Russell King - ARM Linux admin @ 2020-05-05 12:43 UTC (permalink / raw) To: Will Deacon Cc: Dave Martin, linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, linux-arm-kernel On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > Michael has been nagging me on and off about that for, what, 10 years now? > I would therefore be very much in favour of having our ptrace extensions > documented! > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > too CPU-specific for the man-pages project, but my preference would still > be for it to be hosted there alongside all the other man pages. Stuffing random things into the kernel tree is painful for some people. For example, if you cross-build your kernel, then the stuff in the tools/ subdirectory is totally useless (I think everything except perf) because you can't build it. Let's stop making the mistake of constantly shoving stuff into the kernel source tree. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 12:43 ` Russell King - ARM Linux admin 0 siblings, 0 replies; 38+ messages in thread From: Russell King - ARM Linux admin @ 2020-05-05 12:43 UTC (permalink / raw) To: Will Deacon Cc: linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, Dave Martin, linux-arm-kernel On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > Michael has been nagging me on and off about that for, what, 10 years now? > I would therefore be very much in favour of having our ptrace extensions > documented! > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > too CPU-specific for the man-pages project, but my preference would still > be for it to be hosted there alongside all the other man pages. Stuffing random things into the kernel tree is painful for some people. For example, if you cross-build your kernel, then the stuff in the tools/ subdirectory is totally useless (I think everything except perf) because you can't build it. Let's stop making the mistake of constantly shoving stuff into the kernel source tree. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 12:43 ` Russell King - ARM Linux admin 0 siblings, 0 replies; 38+ messages in thread From: Russell King - ARM Linux admin @ 2020-05-05 12:43 UTC (permalink / raw) To: Will Deacon Cc: Dave Martin, linux-arch-u79uwXL29TY76Z2rM5mHXA, linux-man-u79uwXL29TY76Z2rM5mHXA, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > Michael has been nagging me on and off about that for, what, 10 years now? > I would therefore be very much in favour of having our ptrace extensions > documented! > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > too CPU-specific for the man-pages project, but my preference would still > be for it to be hosted there alongside all the other man pages. Stuffing random things into the kernel tree is painful for some people. For example, if you cross-build your kernel, then the stuff in the tools/ subdirectory is totally useless (I think everything except perf) because you can't build it. Let's stop making the mistake of constantly shoving stuff into the kernel source tree. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man 2020-05-05 12:43 ` Russell King - ARM Linux admin @ 2020-05-05 13:06 ` Will Deacon -1 siblings, 0 replies; 38+ messages in thread From: Will Deacon @ 2020-05-05 13:06 UTC (permalink / raw) To: Russell King - ARM Linux admin Cc: Dave Martin, linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, linux-arm-kernel On Tue, May 05, 2020 at 01:43:51PM +0100, Russell King - ARM Linux admin wrote: > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > Michael has been nagging me on and off about that for, what, 10 years now? > > I would therefore be very much in favour of having our ptrace extensions > > documented! > > > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > > too CPU-specific for the man-pages project, but my preference would still > > be for it to be hosted there alongside all the other man pages. > > Stuffing random things into the kernel tree is painful for some people. > > For example, if you cross-build your kernel, then the stuff in the > tools/ subdirectory is totally useless (I think everything except > perf) because you can't build it. > > Let's stop making the mistake of constantly shoving stuff into the > kernel source tree. For userspace tools, I'm inclined to agree, but this is just documentation so it shouldn't cause any issues with cross building. But to be clear: I'd still prefer it to be part of the man-pages project, and would only consider it for inclusion in the kernel tree if it was rejected for being too CPU-specific. Will ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 13:06 ` Will Deacon 0 siblings, 0 replies; 38+ messages in thread From: Will Deacon @ 2020-05-05 13:06 UTC (permalink / raw) To: Russell King - ARM Linux admin Cc: linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, Dave Martin, linux-arm-kernel On Tue, May 05, 2020 at 01:43:51PM +0100, Russell King - ARM Linux admin wrote: > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > Michael has been nagging me on and off about that for, what, 10 years now? > > I would therefore be very much in favour of having our ptrace extensions > > documented! > > > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > > too CPU-specific for the man-pages project, but my preference would still > > be for it to be hosted there alongside all the other man pages. > > Stuffing random things into the kernel tree is painful for some people. > > For example, if you cross-build your kernel, then the stuff in the > tools/ subdirectory is totally useless (I think everything except > perf) because you can't build it. > > Let's stop making the mistake of constantly shoving stuff into the > kernel source tree. For userspace tools, I'm inclined to agree, but this is just documentation so it shouldn't cause any issues with cross building. But to be clear: I'd still prefer it to be part of the man-pages project, and would only consider it for inclusion in the kernel tree if it was rejected for being too CPU-specific. Will _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man 2020-05-05 13:06 ` Will Deacon (?) @ 2020-05-05 13:16 ` Russell King - ARM Linux admin -1 siblings, 0 replies; 38+ messages in thread From: Russell King - ARM Linux admin @ 2020-05-05 13:16 UTC (permalink / raw) To: Will Deacon Cc: Dave Martin, linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, linux-arm-kernel On Tue, May 05, 2020 at 02:06:30PM +0100, Will Deacon wrote: > On Tue, May 05, 2020 at 01:43:51PM +0100, Russell King - ARM Linux admin wrote: > > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > > Michael has been nagging me on and off about that for, what, 10 years now? > > > I would therefore be very much in favour of having our ptrace extensions > > > documented! > > > > > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > > > too CPU-specific for the man-pages project, but my preference would still > > > be for it to be hosted there alongside all the other man pages. > > > > Stuffing random things into the kernel tree is painful for some people. > > > > For example, if you cross-build your kernel, then the stuff in the > > tools/ subdirectory is totally useless (I think everything except > > perf) because you can't build it. > > > > Let's stop making the mistake of constantly shoving stuff into the > > kernel source tree. > > For userspace tools, I'm inclined to agree, but this is just documentation > so it shouldn't cause any issues with cross building. But to be clear: I'd > still prefer it to be part of the man-pages project, and would only consider > it for inclusion in the kernel tree if it was rejected for being too > CPU-specific. I don't think that should be a concern; the man-pages project already contains documentation that is specific to kernel versions, including documentation for interfaces that are architecture specific (such as prctl is a big one, ptrace to a lesser extent.) syscall(2) contains a whole bunch of architecture stuff about the calling convention for syscalls. Interestingly, I notice that syscall(2) is wrong for arm/OABI. I am not surprised, because that documentation never came my way, and I am the author of the kernel's OABI syscall interface. It claims: arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 Notes ────────────────────────────────────────────────────────────── arm/OABI a1 a2 a3 a4 v1 v2 v3 whereas, at the time I invented it, I decided that it shall pass arguments in r0 to r6. That's r0 to r6. Not the APCS register names that this document claims. Not everything in OABI is APCS, as illustrated here - APCS passes the first four arguments in a1 to a4, and then the rest on the stack. The OABI syscall interface doesn't do that. I guess that's what happens when someone else writes interface documentation and doesn't bother to get it reviewed by those who created the interface in the first place. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 13:16 ` Russell King - ARM Linux admin 0 siblings, 0 replies; 38+ messages in thread From: Russell King - ARM Linux admin @ 2020-05-05 13:16 UTC (permalink / raw) To: Will Deacon Cc: linux-arch, linux-man, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, Dave Martin, linux-arm-kernel On Tue, May 05, 2020 at 02:06:30PM +0100, Will Deacon wrote: > On Tue, May 05, 2020 at 01:43:51PM +0100, Russell King - ARM Linux admin wrote: > > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > > Michael has been nagging me on and off about that for, what, 10 years now? > > > I would therefore be very much in favour of having our ptrace extensions > > > documented! > > > > > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > > > too CPU-specific for the man-pages project, but my preference would still > > > be for it to be hosted there alongside all the other man pages. > > > > Stuffing random things into the kernel tree is painful for some people. > > > > For example, if you cross-build your kernel, then the stuff in the > > tools/ subdirectory is totally useless (I think everything except > > perf) because you can't build it. > > > > Let's stop making the mistake of constantly shoving stuff into the > > kernel source tree. > > For userspace tools, I'm inclined to agree, but this is just documentation > so it shouldn't cause any issues with cross building. But to be clear: I'd > still prefer it to be part of the man-pages project, and would only consider > it for inclusion in the kernel tree if it was rejected for being too > CPU-specific. I don't think that should be a concern; the man-pages project already contains documentation that is specific to kernel versions, including documentation for interfaces that are architecture specific (such as prctl is a big one, ptrace to a lesser extent.) syscall(2) contains a whole bunch of architecture stuff about the calling convention for syscalls. Interestingly, I notice that syscall(2) is wrong for arm/OABI. I am not surprised, because that documentation never came my way, and I am the author of the kernel's OABI syscall interface. It claims: arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 Notes ────────────────────────────────────────────────────────────── arm/OABI a1 a2 a3 a4 v1 v2 v3 whereas, at the time I invented it, I decided that it shall pass arguments in r0 to r6. That's r0 to r6. Not the APCS register names that this document claims. Not everything in OABI is APCS, as illustrated here - APCS passes the first four arguments in a1 to a4, and then the rest on the stack. The OABI syscall interface doesn't do that. I guess that's what happens when someone else writes interface documentation and doesn't bother to get it reviewed by those who created the interface in the first place. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-05 13:16 ` Russell King - ARM Linux admin 0 siblings, 0 replies; 38+ messages in thread From: Russell King - ARM Linux admin @ 2020-05-05 13:16 UTC (permalink / raw) To: Will Deacon Cc: Dave Martin, linux-arch-u79uwXL29TY76Z2rM5mHXA, linux-man-u79uwXL29TY76Z2rM5mHXA, Catalin Marinas, Michael Kerrisk, Vincenzo Frascino, linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r On Tue, May 05, 2020 at 02:06:30PM +0100, Will Deacon wrote: > On Tue, May 05, 2020 at 01:43:51PM +0100, Russell King - ARM Linux admin wrote: > > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > > Michael has been nagging me on and off about that for, what, 10 years now? > > > I would therefore be very much in favour of having our ptrace extensions > > > documented! > > > > > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > > > too CPU-specific for the man-pages project, but my preference would still > > > be for it to be hosted there alongside all the other man pages. > > > > Stuffing random things into the kernel tree is painful for some people. > > > > For example, if you cross-build your kernel, then the stuff in the > > tools/ subdirectory is totally useless (I think everything except > > perf) because you can't build it. > > > > Let's stop making the mistake of constantly shoving stuff into the > > kernel source tree. > > For userspace tools, I'm inclined to agree, but this is just documentation > so it shouldn't cause any issues with cross building. But to be clear: I'd > still prefer it to be part of the man-pages project, and would only consider > it for inclusion in the kernel tree if it was rejected for being too > CPU-specific. I don't think that should be a concern; the man-pages project already contains documentation that is specific to kernel versions, including documentation for interfaces that are architecture specific (such as prctl is a big one, ptrace to a lesser extent.) syscall(2) contains a whole bunch of architecture stuff about the calling convention for syscalls. Interestingly, I notice that syscall(2) is wrong for arm/OABI. I am not surprised, because that documentation never came my way, and I am the author of the kernel's OABI syscall interface. It claims: arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 Notes ────────────────────────────────────────────────────────────── arm/OABI a1 a2 a3 a4 v1 v2 v3 whereas, at the time I invented it, I decided that it shall pass arguments in r0 to r6. That's r0 to r6. Not the APCS register names that this document claims. Not everything in OABI is APCS, as illustrated here - APCS passes the first four arguments in a1 to a4, and then the rest on the stack. The OABI syscall interface doesn't do that. I guess that's what happens when someone else writes interface documentation and doesn't bother to get it reviewed by those who created the interface in the first place. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man 2020-05-05 12:43 ` Russell King - ARM Linux admin @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) -1 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Russell King - ARM Linux admin, Will Deacon Cc: mtk.manpages, Dave Martin, linux-arch, linux-man, Catalin Marinas, Vincenzo Frascino, linux-arm-kernel On 5/5/20 2:43 PM, Russell King - ARM Linux admin wrote: > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: >> Michael has been nagging me on and off about that for, what, 10 years now? >> I would therefore be very much in favour of having our ptrace extensions >> documented! >> >> We could even put this stuff under Documentation/arm64/man/ if it's deemed >> too CPU-specific for the man-pages project, but my preference would still >> be for it to be hosted there alongside all the other man pages. > > Stuffing random things into the kernel tree is painful for some people. Yes, and too often not easily noticeable for user-space programmers. > > For example, if you cross-build your kernel, then the stuff in the > tools/ subdirectory is totally useless (I think everything except > perf) because you can't build it. > > Let's stop making the mistake of constantly shoving stuff into the > kernel source tree. Agrred. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Russell King - ARM Linux admin, Will Deacon Cc: linux-arch, linux-man, Catalin Marinas, mtk.manpages, Vincenzo Frascino, Dave Martin, linux-arm-kernel On 5/5/20 2:43 PM, Russell King - ARM Linux admin wrote: > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: >> Michael has been nagging me on and off about that for, what, 10 years now? >> I would therefore be very much in favour of having our ptrace extensions >> documented! >> >> We could even put this stuff under Documentation/arm64/man/ if it's deemed >> too CPU-specific for the man-pages project, but my preference would still >> be for it to be hosted there alongside all the other man pages. > > Stuffing random things into the kernel tree is painful for some people. Yes, and too often not easily noticeable for user-space programmers. > > For example, if you cross-build your kernel, then the stuff in the > tools/ subdirectory is totally useless (I think everything except > perf) because you can't build it. > > Let's stop making the mistake of constantly shoving stuff into the > kernel source tree. Agrred. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man 2020-05-05 10:44 ` Will Deacon @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) -1 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Will Deacon, Dave Martin Cc: mtk.manpages, Catalin Marinas, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel >> * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: >> arm64 ptrace extensions > > Michael has been nagging me on and off about that for, what, 10 years now? Perhaps not that long, but a while now ;-). > I would therefore be very much in favour of having our ptrace extensions > documented! > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > too CPU-specific for the man-pages project, but my preference would still > be for it to be hosted there alongside all the other man pages. Agreed; manual pages is I think a better place. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Will Deacon, Dave Martin Cc: linux-arch, linux-man, Catalin Marinas, mtk.manpages, Vincenzo Frascino, linux-arm-kernel >> * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: >> arm64 ptrace extensions > > Michael has been nagging me on and off about that for, what, 10 years now? Perhaps not that long, but a while now ;-). > I would therefore be very much in favour of having our ptrace extensions > documented! > > We could even put this stuff under Documentation/arm64/man/ if it's deemed > too CPU-specific for the man-pages project, but my preference would still > be for it to be hosted there alongside all the other man pages. Agreed; manual pages is I think a better place. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Dave Martin Cc: mtk.manpages, Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel Hello Dave, et al. On 5/4/20 5:32 PM, Dave Martin wrote: > 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). Sounds good to me. > 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 Not sure what the details are here, so I have no opinion yet. But probably, as additions to execve(2). > * aux vector, hwcaps ==> getauxval(3) > * arch-specific signals > * signal frame Not sure what the details are here, so I have no opinion yet. > * mmap/mprotect extensions See below. > * prctl calls As additions in prctl(2) would be fine, I think. > * ptrace quirks and extensions See below. > * coredump contents Not sure what the details are here, so I have no opinion yet. Possibly as additions to core(5). > Not everything has an obvious home in an existing page, Yes. > and adding > specifics for every architecture could make some existing manpages very > unwieldy. Still, I think it's worth adding details, especially for widely used architectures. > 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 I'm a little unclear on what would land in here, but sounds reasonable in principle. > * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: > overview of arm64 SVE ABI Sounds reasonable to me. > * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: > arm64 ptrace extensions I think maybe better is: ptrace-arm64.2 I'm agnostic about whether there should be a new page, or whether these should be added to ptrace(2). But, we could start with the idea of a new page. > * 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). Sounds good to me > etc. > > > Ideally, I'd like to adopt a pattern that other arches can follow. Well, if they do follow. Arch-specific documentation is woefully thin at the moment. I'm not going to worry too much about the right pattern (don't let perfect get in the way of good, yadda, yadda), until I get so much arch-specific documentation that some refactoring may be required. (I'm not going to hold my breath waiting for that to happen ;-).) Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Dave Martin Cc: linux-arch, linux-man, Catalin Marinas, mtk.manpages, Vincenzo Frascino, Will Deacon, linux-arm-kernel Hello Dave, et al. On 5/4/20 5:32 PM, Dave Martin wrote: > 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). Sounds good to me. > 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 Not sure what the details are here, so I have no opinion yet. But probably, as additions to execve(2). > * aux vector, hwcaps ==> getauxval(3) > * arch-specific signals > * signal frame Not sure what the details are here, so I have no opinion yet. > * mmap/mprotect extensions See below. > * prctl calls As additions in prctl(2) would be fine, I think. > * ptrace quirks and extensions See below. > * coredump contents Not sure what the details are here, so I have no opinion yet. Possibly as additions to core(5). > Not everything has an obvious home in an existing page, Yes. > and adding > specifics for every architecture could make some existing manpages very > unwieldy. Still, I think it's worth adding details, especially for widely used architectures. > 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 I'm a little unclear on what would land in here, but sounds reasonable in principle. > * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: > overview of arm64 SVE ABI Sounds reasonable to me. > * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: > arm64 ptrace extensions I think maybe better is: ptrace-arm64.2 I'm agnostic about whether there should be a new page, or whether these should be added to ptrace(2). But, we could start with the idea of a new page. > * 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). Sounds good to me > etc. > > > Ideally, I'd like to adopt a pattern that other arches can follow. Well, if they do follow. Arch-specific documentation is woefully thin at the moment. I'm not going to worry too much about the right pattern (don't let perfect get in the way of good, yadda, yadda), until I get so much arch-specific documentation that some refactoring may be required. (I'm not going to hold my breath waiting for that to happen ;-).) Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 10:47 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 38+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-06 10:47 UTC (permalink / raw) To: Dave Martin Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man-u79uwXL29TY76Z2rM5mHXA, linux-arch-u79uwXL29TY76Z2rM5mHXA, linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r Hello Dave, et al. On 5/4/20 5:32 PM, Dave Martin wrote: > 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). Sounds good to me. > 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 Not sure what the details are here, so I have no opinion yet. But probably, as additions to execve(2). > * aux vector, hwcaps ==> getauxval(3) > * arch-specific signals > * signal frame Not sure what the details are here, so I have no opinion yet. > * mmap/mprotect extensions See below. > * prctl calls As additions in prctl(2) would be fine, I think. > * ptrace quirks and extensions See below. > * coredump contents Not sure what the details are here, so I have no opinion yet. Possibly as additions to core(5). > Not everything has an obvious home in an existing page, Yes. > and adding > specifics for every architecture could make some existing manpages very > unwieldy. Still, I think it's worth adding details, especially for widely used architectures. > 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 I'm a little unclear on what would land in here, but sounds reasonable in principle. > * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: > overview of arm64 SVE ABI Sounds reasonable to me. > * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: > arm64 ptrace extensions I think maybe better is: ptrace-arm64.2 I'm agnostic about whether there should be a new page, or whether these should be added to ptrace(2). But, we could start with the idea of a new page. > * 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). Sounds good to me > etc. > > > Ideally, I'd like to adopt a pattern that other arches can follow. Well, if they do follow. Arch-specific documentation is woefully thin at the moment. I'm not going to worry too much about the right pattern (don't let perfect get in the way of good, yadda, yadda), until I get so much arch-specific documentation that some refactoring may be required. (I'm not going to hold my breath waiting for that to happen ;-).) Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 14:29 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-06 14:29 UTC (permalink / raw) To: Michael Kerrisk (man-pages) Cc: Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man, linux-arch, linux-arm-kernel On Wed, May 06, 2020 at 12:47:17PM +0200, Michael Kerrisk (man-pages) wrote: > Hello Dave, et al. > > On 5/4/20 5:32 PM, Dave Martin wrote: > > 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). > > Sounds good to me. > > > 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 > > Not sure what the details are here, so I have no opinion yet. > But probably, as additions to execve(2). Having looked at that page again, probably yes. This would include things like how arch-specific registers get reset, and how various thread properties are reset/inherited. Possibly, much of this would be documented by cross-referencing other pages. > > > * aux vector, hwcaps > > ==> getauxval(3) Ah, yes. I keep forgetting that because it's provided by libc. There are a few things missing, but we can add them in there. > > * arch-specific signals > > * signal frame > > Not sure what the details are here, so I have no opinion yet. Stuff like architecture-specific si_codes and how they are used. Signal handlers that poke about in the signal frame need to know how it is structured, and for arm64 this is now quite complex. I want to document some example code for parsing it somewhere, and I feel that will be too much noise for signal(7). I guess I can try to write something and than we can figure out where to put it. > > > * mmap/mprotect extensions > > See below. > > > * prctl calls > > As additions in prctl(2) would be fine, I think. > > > * ptrace quirks and extensions > > See below. > > > * coredump contents > > Not sure what the details are here, so I have no opinion yet. > Possibly as additions to core(5). Things like arch-specific regsets. Some of that can probabably live in the ptrace page, with cross-references from core(5). > > Not everything has an obvious home in an existing page, > > Yes. > > > and adding > > specifics for every architecture could make some existing manpages very > > unwieldy. > > Still, I think it's worth adding details, especially for widely > used architectures. Agreed. If there's a lot of explanation required for somethings which feels out of scope for the core page, then I might still be tempted to push some of that out into a more arch-specific page and cross-reference it. We can play that by ear, though. > > 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 > > I'm a little unclear on what would land in here, but sounds > reasonable in principle. I probably won't attempt to add such a page until I find a use for it. I mainly intended this as an overview of what areas are impacted by the architecture and which other pages to go look at. > > * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: > > overview of arm64 SVE ABI > > Sounds reasonable to me. > > > * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: > > arm64 ptrace extensions > > I think maybe better is: ptrace-arm64.2 Agreed. That's probably easier to for people to place in their mental map. > > I'm agnostic about whether there should be a new page, or whether > these should be added to ptrace(2). But, we could start with the > idea of a new page. > > > * 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). > > Sounds good to me > > > etc. > > > > > > Ideally, I'd like to adopt a pattern that other arches can follow. > > Well, if they do follow. Arch-specific documentation is woefully > thin at the moment. I'm not going to worry too much about the right > pattern (don't let perfect get in the way of good, yadda, yadda), > until I get so much arch-specific documentation that some refactoring > may be required. (I'm not going to hold my breath waiting for that > to happen ;-).) Sure. I don't want to do something obviously broken, but it sounds like you're reasonably happy with my approach. In any case I'll start with the simple stuff. Where it's easy to do so, I may try to trawl up some undocumented non- ARM stuff, but I'm not the expert there... Cheers ---Dave ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 14:29 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-06 14:29 UTC (permalink / raw) To: Michael Kerrisk (man-pages) Cc: linux-arch, linux-man, Catalin Marinas, Vincenzo Frascino, Will Deacon, linux-arm-kernel On Wed, May 06, 2020 at 12:47:17PM +0200, Michael Kerrisk (man-pages) wrote: > Hello Dave, et al. > > On 5/4/20 5:32 PM, Dave Martin wrote: > > 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). > > Sounds good to me. > > > 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 > > Not sure what the details are here, so I have no opinion yet. > But probably, as additions to execve(2). Having looked at that page again, probably yes. This would include things like how arch-specific registers get reset, and how various thread properties are reset/inherited. Possibly, much of this would be documented by cross-referencing other pages. > > > * aux vector, hwcaps > > ==> getauxval(3) Ah, yes. I keep forgetting that because it's provided by libc. There are a few things missing, but we can add them in there. > > * arch-specific signals > > * signal frame > > Not sure what the details are here, so I have no opinion yet. Stuff like architecture-specific si_codes and how they are used. Signal handlers that poke about in the signal frame need to know how it is structured, and for arm64 this is now quite complex. I want to document some example code for parsing it somewhere, and I feel that will be too much noise for signal(7). I guess I can try to write something and than we can figure out where to put it. > > > * mmap/mprotect extensions > > See below. > > > * prctl calls > > As additions in prctl(2) would be fine, I think. > > > * ptrace quirks and extensions > > See below. > > > * coredump contents > > Not sure what the details are here, so I have no opinion yet. > Possibly as additions to core(5). Things like arch-specific regsets. Some of that can probabably live in the ptrace page, with cross-references from core(5). > > Not everything has an obvious home in an existing page, > > Yes. > > > and adding > > specifics for every architecture could make some existing manpages very > > unwieldy. > > Still, I think it's worth adding details, especially for widely > used architectures. Agreed. If there's a lot of explanation required for somethings which feels out of scope for the core page, then I might still be tempted to push some of that out into a more arch-specific page and cross-reference it. We can play that by ear, though. > > 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 > > I'm a little unclear on what would land in here, but sounds > reasonable in principle. I probably won't attempt to add such a page until I find a use for it. I mainly intended this as an overview of what areas are impacted by the architecture and which other pages to go look at. > > * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: > > overview of arm64 SVE ABI > > Sounds reasonable to me. > > > * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: > > arm64 ptrace extensions > > I think maybe better is: ptrace-arm64.2 Agreed. That's probably easier to for people to place in their mental map. > > I'm agnostic about whether there should be a new page, or whether > these should be added to ptrace(2). But, we could start with the > idea of a new page. > > > * 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). > > Sounds good to me > > > etc. > > > > > > Ideally, I'd like to adopt a pattern that other arches can follow. > > Well, if they do follow. Arch-specific documentation is woefully > thin at the moment. I'm not going to worry too much about the right > pattern (don't let perfect get in the way of good, yadda, yadda), > until I get so much arch-specific documentation that some refactoring > may be required. (I'm not going to hold my breath waiting for that > to happen ;-).) Sure. I don't want to do something obviously broken, but it sounds like you're reasonably happy with my approach. In any case I'll start with the simple stuff. Where it's easy to do so, I may try to trawl up some undocumented non- ARM stuff, but I'm not the expert there... Cheers ---Dave _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: RFC: Adding arch-specific user ABI documentation in linux-man @ 2020-05-06 14:29 ` Dave Martin 0 siblings, 0 replies; 38+ messages in thread From: Dave Martin @ 2020-05-06 14:29 UTC (permalink / raw) To: Michael Kerrisk (man-pages) Cc: Catalin Marinas, Will Deacon, Vincenzo Frascino, linux-man-u79uwXL29TY76Z2rM5mHXA, linux-arch-u79uwXL29TY76Z2rM5mHXA, linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r On Wed, May 06, 2020 at 12:47:17PM +0200, Michael Kerrisk (man-pages) wrote: > Hello Dave, et al. > > On 5/4/20 5:32 PM, Dave Martin wrote: > > 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). > > Sounds good to me. > > > 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 > > Not sure what the details are here, so I have no opinion yet. > But probably, as additions to execve(2). Having looked at that page again, probably yes. This would include things like how arch-specific registers get reset, and how various thread properties are reset/inherited. Possibly, much of this would be documented by cross-referencing other pages. > > > * aux vector, hwcaps > > ==> getauxval(3) Ah, yes. I keep forgetting that because it's provided by libc. There are a few things missing, but we can add them in there. > > * arch-specific signals > > * signal frame > > Not sure what the details are here, so I have no opinion yet. Stuff like architecture-specific si_codes and how they are used. Signal handlers that poke about in the signal frame need to know how it is structured, and for arm64 this is now quite complex. I want to document some example code for parsing it somewhere, and I feel that will be too much noise for signal(7). I guess I can try to write something and than we can figure out where to put it. > > > * mmap/mprotect extensions > > See below. > > > * prctl calls > > As additions in prctl(2) would be fine, I think. > > > * ptrace quirks and extensions > > See below. > > > * coredump contents > > Not sure what the details are here, so I have no opinion yet. > Possibly as additions to core(5). Things like arch-specific regsets. Some of that can probabably live in the ptrace page, with cross-references from core(5). > > Not everything has an obvious home in an existing page, > > Yes. > > > and adding > > specifics for every architecture could make some existing manpages very > > unwieldy. > > Still, I think it's worth adding details, especially for widely > used architectures. Agreed. If there's a lot of explanation required for somethings which feels out of scope for the core page, then I might still be tempted to push some of that out into a more arch-specific page and cross-reference it. We can play that by ear, though. > > 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 > > I'm a little unclear on what would land in here, but sounds > reasonable in principle. I probably won't attempt to add such a page until I find a use for it. I mainly intended this as an overview of what areas are impacted by the architecture and which other pages to go look at. > > * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: > > overview of arm64 SVE ABI > > Sounds reasonable to me. > > > * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: > > arm64 ptrace extensions > > I think maybe better is: ptrace-arm64.2 Agreed. That's probably easier to for people to place in their mental map. > > I'm agnostic about whether there should be a new page, or whether > these should be added to ptrace(2). But, we could start with the > idea of a new page. > > > * 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). > > Sounds good to me > > > etc. > > > > > > Ideally, I'd like to adopt a pattern that other arches can follow. > > Well, if they do follow. Arch-specific documentation is woefully > thin at the moment. I'm not going to worry too much about the right > pattern (don't let perfect get in the way of good, yadda, yadda), > until I get so much arch-specific documentation that some refactoring > may be required. (I'm not going to hold my breath waiting for that > to happen ;-).) Sure. I don't want to do something obviously broken, but it sounds like you're reasonably happy with my approach. In any case I'll start with the simple stuff. Where it's easy to do so, I may try to trawl up some undocumented non- ARM stuff, but I'm not the expert there... Cheers ---Dave ^ permalink raw reply [flat|nested] 38+ messages in thread
end of thread, other threads:[~2020-05-06 14:29 UTC | newest] Thread overview: 38+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-05-04 15:32 RFC: Adding arch-specific user ABI documentation in linux-man Dave Martin 2020-05-04 15:32 ` 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
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.