From mboxrd@z Thu Jan 1 00:00:00 1970 From: Russell King - ARM Linux admin Subject: Re: RFC: Adding arch-specific user ABI documentation in linux-man Date: Tue, 5 May 2020 14:16:19 +0100 Message-ID: <20200505131619.GG1551@shell.armlinux.org.uk> References: <20200504153214.GH30377@arm.com> <20200505104454.GC19710@willie-the-truck> <20200505124351.GF1551@shell.armlinux.org.uk> <20200505130629.GK19710@willie-the-truck> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Content-Disposition: inline In-Reply-To: <20200505130629.GK19710@willie-the-truck> Sender: linux-man-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org To: Will Deacon Cc: Dave Martin , linux-arch-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, Catalin Marinas , Michael Kerrisk , Vincenzo Frascino , linux-arm-kernel-IAPFreCvJWM7uuMidbF8XUB+6BGkLq7r@public.gmane.org List-Id: linux-arch.vger.kernel.org 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39456 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729019AbgEENQ3 (ORCPT ); Tue, 5 May 2020 09:16:29 -0400 Date: Tue, 5 May 2020 14:16:19 +0100 From: Russell King - ARM Linux admin Subject: Re: RFC: Adding arch-specific user ABI documentation in linux-man Message-ID: <20200505131619.GG1551@shell.armlinux.org.uk> References: <20200504153214.GH30377@arm.com> <20200505104454.GC19710@willie-the-truck> <20200505124351.GF1551@shell.armlinux.org.uk> <20200505130629.GK19710@willie-the-truck> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20200505130629.GK19710@willie-the-truck> Sender: linux-arch-owner@vger.kernel.org List-ID: To: Will Deacon Cc: Dave Martin , linux-arch@vger.kernel.org, linux-man@vger.kernel.org, Catalin Marinas , Michael Kerrisk , Vincenzo Frascino , linux-arm-kernel@lists.infradead.org Message-ID: <20200505131619.fD7WqxjILv71Vlz7cgMPJ1QYSr_rUP6dLtcWJaPnVck@z> 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.2 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED,USER_AGENT_SANE_1 autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 71A2BC47254 for ; Tue, 5 May 2020 13:16:37 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 2D9B220746 for ; Tue, 5 May 2020 13:16:37 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="I+W/Reba"; dkim=fail reason="signature verification failed" (2048-bit key) header.d=armlinux.org.uk header.i=@armlinux.org.uk header.b="1uVH8dV3" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 2D9B220746 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=armlinux.org.uk Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+infradead-linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:In-Reply-To:MIME-Version:References: Message-ID:Subject:To:From:Date:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=RW6ZQqXZTCMCCDoU4OSRFLWSFz+od1IhFJF3/hIRsD4=; b=I+W/RebadOAI4a qsVuqvls63Ri7lx7cI/S2d4FDeor9t9phsH2PWZjvx48wN1eXFv/sGZhcTnTngoP8dATmxA2GZ2Wn rDZ9AztyC7t4JUEbK3b8vmJIQW38zB7i//e7JnONwEBucsOSob+ikEmBRzlIvFgBft9vZYzf8Jv9l StoLEcZjwTUKsH/WGfFFcj5BD7xkQVYA1ugljXLtk0xkqCJ42LiHMMxrA4Xl+AGkth13uvs77GsU/ CjW4vYTMsykgp0AXqhIMOqpuTPu2EtjuAQ7A3HxXczqpeVNT0KN+19pgCURGe+Fkh9gJhmWZwsfge dVwfXO6ewS1RO4469OTQ==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.92.3 #3 (Red Hat Linux)) id 1jVxR6-0000ZL-43; Tue, 05 May 2020 13:16:36 +0000 Received: from pandora.armlinux.org.uk ([2001:4d48:ad52:3201:214:fdff:fe10:1be6]) by bombadil.infradead.org with esmtps (Exim 4.92.3 #3 (Red Hat Linux)) id 1jVxR3-0000XN-63 for linux-arm-kernel@lists.infradead.org; Tue, 05 May 2020 13:16:34 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=armlinux.org.uk; s=pandora-2019; h=Sender:In-Reply-To: Content-Transfer-Encoding:Content-Type:MIME-Version:References:Message-ID: Subject:Cc:To:From:Date:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=MB282HLZkeyYhgLoz3UzvjWBjtseuypJMoQRy7x6wmU=; b=1uVH8dV30INpdk9iqTu+UxJiJ ApkVzBDRp1hvwrn1MEk70bp0j+d5oqaTrdBJ62gec4/5fN7BzLR5xD6gCdG+lZO1FWDB5r7X3Rof6 veb6S7/h86xM6xQEpIGOYHVW8Bl0S8VjUHKY9chFQ7mnjAx7CWTlWjeR+Qxl9OLnUYKI9iwA2Dqgf kn1gYq1vQIK1VufPto2p/wbwVobs88Z39Msi8Vinde2ujrHbb47O/5eQDGwEitDNqXOhR5M0ZMrWg eqpUIgwt4+wWF6Wd3xld/RFuWc1LY0W8VW3ik4aKyW7XyOCsR9sc/317qMD3vC5EVxoJce7n34mKW 8YSpJA3OA==; Received: from shell.armlinux.org.uk ([2002:4e20:1eda:1:5054:ff:fe00:4ec]:54034) by pandora.armlinux.org.uk with esmtpsa (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jVxQr-0002Yl-H2; Tue, 05 May 2020 14:16:21 +0100 Received: from linux by shell.armlinux.org.uk with local (Exim 4.92) (envelope-from ) id 1jVxQp-0007BJ-Ro; Tue, 05 May 2020 14:16:19 +0100 Date: Tue, 5 May 2020 14:16:19 +0100 From: Russell King - ARM Linux admin To: Will Deacon Subject: Re: RFC: Adding arch-specific user ABI documentation in linux-man Message-ID: <20200505131619.GG1551@shell.armlinux.org.uk> References: <20200504153214.GH30377@arm.com> <20200505104454.GC19710@willie-the-truck> <20200505124351.GF1551@shell.armlinux.org.uk> <20200505130629.GK19710@willie-the-truck> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20200505130629.GK19710@willie-the-truck> User-Agent: Mutt/1.10.1 (2018-07-13) X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20200505_061633_229601_91C9E066 X-CRM114-Status: GOOD ( 18.07 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: linux-arch@vger.kernel.org, linux-man@vger.kernel.org, Catalin Marinas , Michael Kerrisk , Vincenzo Frascino , Dave Martin , linux-arm-kernel@lists.infradead.org Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+infradead-linux-arm-kernel=archiver.kernel.org@lists.infradead.org T24gVHVlLCBNYXkgMDUsIDIwMjAgYXQgMDI6MDY6MzBQTSArMDEwMCwgV2lsbCBEZWFjb24gd3Jv dGU6Cj4gT24gVHVlLCBNYXkgMDUsIDIwMjAgYXQgMDE6NDM6NTFQTSArMDEwMCwgUnVzc2VsbCBL aW5nIC0gQVJNIExpbnV4IGFkbWluIHdyb3RlOgo+ID4gT24gVHVlLCBNYXkgMDUsIDIwMjAgYXQg MTE6NDQ6NTVBTSArMDEwMCwgV2lsbCBEZWFjb24gd3JvdGU6Cj4gPiA+IE1pY2hhZWwgaGFzIGJl ZW4gbmFnZ2luZyBtZSBvbiBhbmQgb2ZmIGFib3V0IHRoYXQgZm9yLCB3aGF0LCAxMCB5ZWFycyBu b3c/Cj4gPiA+IEkgd291bGQgdGhlcmVmb3JlIGJlIHZlcnkgbXVjaCBpbiBmYXZvdXIgb2YgaGF2 aW5nIG91ciBwdHJhY2UgZXh0ZW5zaW9ucwo+ID4gPiBkb2N1bWVudGVkIQo+ID4gPiAKPiA+ID4g V2UgY291bGQgZXZlbiBwdXQgdGhpcyBzdHVmZiB1bmRlciBEb2N1bWVudGF0aW9uL2FybTY0L21h bi8gaWYgaXQncyBkZWVtZWQKPiA+ID4gdG9vIENQVS1zcGVjaWZpYyBmb3IgdGhlIG1hbi1wYWdl cyBwcm9qZWN0LCBidXQgbXkgcHJlZmVyZW5jZSB3b3VsZCBzdGlsbAo+ID4gPiBiZSBmb3IgaXQg dG8gYmUgaG9zdGVkIHRoZXJlIGFsb25nc2lkZSBhbGwgdGhlIG90aGVyIG1hbiBwYWdlcy4KPiA+ IAo+ID4gU3R1ZmZpbmcgcmFuZG9tIHRoaW5ncyBpbnRvIHRoZSBrZXJuZWwgdHJlZSBpcyBwYWlu ZnVsIGZvciBzb21lIHBlb3BsZS4KPiA+IAo+ID4gRm9yIGV4YW1wbGUsIGlmIHlvdSBjcm9zcy1i dWlsZCB5b3VyIGtlcm5lbCwgdGhlbiB0aGUgc3R1ZmYgaW4gdGhlCj4gPiB0b29scy8gc3ViZGly ZWN0b3J5IGlzIHRvdGFsbHkgdXNlbGVzcyAoSSB0aGluayBldmVyeXRoaW5nIGV4Y2VwdAo+ID4g cGVyZikgYmVjYXVzZSB5b3UgY2FuJ3QgYnVpbGQgaXQuCj4gPiAKPiA+IExldCdzIHN0b3AgbWFr aW5nIHRoZSBtaXN0YWtlIG9mIGNvbnN0YW50bHkgc2hvdmluZyBzdHVmZiBpbnRvIHRoZQo+ID4g a2VybmVsIHNvdXJjZSB0cmVlLgo+IAo+IEZvciB1c2Vyc3BhY2UgdG9vbHMsIEknbSBpbmNsaW5l ZCB0byBhZ3JlZSwgYnV0IHRoaXMgaXMganVzdCBkb2N1bWVudGF0aW9uCj4gc28gaXQgc2hvdWxk bid0IGNhdXNlIGFueSBpc3N1ZXMgd2l0aCBjcm9zcyBidWlsZGluZy4gQnV0IHRvIGJlIGNsZWFy OiBJJ2QKPiBzdGlsbCBwcmVmZXIgaXQgdG8gYmUgcGFydCBvZiB0aGUgbWFuLXBhZ2VzIHByb2pl Y3QsIGFuZCB3b3VsZCBvbmx5IGNvbnNpZGVyCj4gaXQgZm9yIGluY2x1c2lvbiBpbiB0aGUga2Vy bmVsIHRyZWUgaWYgaXQgd2FzIHJlamVjdGVkIGZvciBiZWluZyB0b28KPiBDUFUtc3BlY2lmaWMu CgpJIGRvbid0IHRoaW5rIHRoYXQgc2hvdWxkIGJlIGEgY29uY2VybjsgdGhlIG1hbi1wYWdlcyBw cm9qZWN0IGFscmVhZHkKY29udGFpbnMgZG9jdW1lbnRhdGlvbiB0aGF0IGlzIHNwZWNpZmljIHRv IGtlcm5lbCB2ZXJzaW9ucywgaW5jbHVkaW5nCmRvY3VtZW50YXRpb24gZm9yIGludGVyZmFjZXMg dGhhdCBhcmUgYXJjaGl0ZWN0dXJlIHNwZWNpZmljIChzdWNoIGFzCnByY3RsIGlzIGEgYmlnIG9u ZSwgcHRyYWNlIHRvIGEgbGVzc2VyIGV4dGVudC4pICBzeXNjYWxsKDIpIGNvbnRhaW5zCmEgd2hv bGUgYnVuY2ggb2YgYXJjaGl0ZWN0dXJlIHN0dWZmIGFib3V0IHRoZSBjYWxsaW5nIGNvbnZlbnRp b24gZm9yCnN5c2NhbGxzLgoKSW50ZXJlc3RpbmdseSwgSSBub3RpY2UgdGhhdCBzeXNjYWxsKDIp IGlzIHdyb25nIGZvciBhcm0vT0FCSS4gSSBhbQpub3Qgc3VycHJpc2VkLCBiZWNhdXNlIHRoYXQg ZG9jdW1lbnRhdGlvbiBuZXZlciBjYW1lIG15IHdheSwgYW5kIEkgYW0KdGhlIGF1dGhvciBvZiB0 aGUga2VybmVsJ3MgT0FCSSBzeXNjYWxsIGludGVyZmFjZS4KCkl0IGNsYWltczoKCiAgICAgICBh cmNoL0FCSSAgICAgIGFyZzEgIGFyZzIgIGFyZzMgIGFyZzQgIGFyZzUgIGFyZzYgIGFyZzcgIE5v dGVzCiAgICAgICDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDi lIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDi lIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDi lIDilIDilIDilIDilIDilIDilIDilIDilIAKICAgICAgIGFybS9PQUJJICAgICAgYTEgICAgYTIg ICAgYTMgICAgYTQgICAgdjEgICAgdjIgICAgdjMKCndoZXJlYXMsIGF0IHRoZSB0aW1lIEkgaW52 ZW50ZWQgaXQsIEkgZGVjaWRlZCB0aGF0IGl0IHNoYWxsIHBhc3MKYXJndW1lbnRzIGluIHIwIHRv IHI2LiAgVGhhdCdzIHIwIHRvIHI2LiAgTm90IHRoZSBBUENTIHJlZ2lzdGVyCm5hbWVzIHRoYXQg dGhpcyBkb2N1bWVudCBjbGFpbXMuICBOb3QgZXZlcnl0aGluZyBpbiBPQUJJIGlzIEFQQ1MsCmFz IGlsbHVzdHJhdGVkIGhlcmUgLSBBUENTIHBhc3NlcyB0aGUgZmlyc3QgZm91ciBhcmd1bWVudHMg aW4gYTEKdG8gYTQsIGFuZCB0aGVuIHRoZSByZXN0IG9uIHRoZSBzdGFjay4gIFRoZSBPQUJJIHN5 c2NhbGwgaW50ZXJmYWNlCmRvZXNuJ3QgZG8gdGhhdC4KCkkgZ3Vlc3MgdGhhdCdzIHdoYXQgaGFw cGVucyB3aGVuIHNvbWVvbmUgZWxzZSB3cml0ZXMgaW50ZXJmYWNlCmRvY3VtZW50YXRpb24gYW5k IGRvZXNuJ3QgYm90aGVyIHRvIGdldCBpdCByZXZpZXdlZCBieSB0aG9zZSB3aG8KY3JlYXRlZCB0 aGUgaW50ZXJmYWNlIGluIHRoZSBmaXJzdCBwbGFjZS4KCi0tIApSTUsncyBQYXRjaCBzeXN0ZW06 IGh0dHBzOi8vd3d3LmFybWxpbnV4Lm9yZy51ay9kZXZlbG9wZXIvcGF0Y2hlcy8KRlRUQyBicm9h ZGJhbmQgZm9yIDAuOG1pbGUgbGluZSBpbiBzdWJ1cmJpYTogc3luYyBhdCAxMC4yTWJwcyBkb3du IDU4N2ticHMgdXAKCl9fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X19fCmxpbnV4LWFybS1rZXJuZWwgbWFpbGluZyBsaXN0CmxpbnV4LWFybS1rZXJuZWxAbGlzdHMu aW5mcmFkZWFkLm9yZwpodHRwOi8vbGlzdHMuaW5mcmFkZWFkLm9yZy9tYWlsbWFuL2xpc3RpbmZv L2xpbnV4LWFybS1rZXJuZWwK