From owner-freebsd-arch@freebsd.org Tue Oct 9 22:18:27 2018 Return-Path: Delivered-To: freebsd-arch@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 505F310BF883 for ; Tue, 9 Oct 2018 22:18:27 +0000 (UTC) (envelope-from brooks@spindle.one-eyed-alien.net) Received: from spindle.one-eyed-alien.net (spindle.one-eyed-alien.net [199.48.129.229]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id F25B9814E8 for ; Tue, 9 Oct 2018 22:18:26 +0000 (UTC) (envelope-from brooks@spindle.one-eyed-alien.net) Received: by spindle.one-eyed-alien.net (Postfix, from userid 3001) id 087463C475F; Tue, 9 Oct 2018 22:18:26 +0000 (UTC) Date: Tue, 9 Oct 2018 22:18:26 +0000 From: Brooks Davis To: freebsd-arch@freebsd.org Subject: style change for syscalls.master Message-ID: <20181009221826.GA75401@spindle.one-eyed-alien.net> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="IS0zKkzwUGydFO0o" Content-Disposition: inline User-Agent: Mutt/1.9.4 (2018-02-28) X-BeenThere: freebsd-arch@freebsd.org X-Mailman-Version: 2.1.27 Precedence: list List-Id: Discussion related to FreeBSD architecture List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 09 Oct 2018 22:18:27 -0000 --IS0zKkzwUGydFO0o Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable I have a patch (https://reviews.freebsd.org/D17488) that removes the need for backslash line continuations in syscalls.master files with the aim of making the files more readable. Based on the functionality in that patch, I'd like to propose changing the style of the file to something better suited the long lines introduced by long type/variable names and SAL annotations. I'd also like it to be easier to diff between the main syscalls.master and the freebsd32 version. Longer term, I hope to be able to generate freebsd32 files from the default syscalls.master which will be aided by reducing diffs and making room for more annotations. To those ends, I propose a reformat along the lines of the examples below: Old format: 1 AUE_EXIT STD { void sys_exit(int rval); } exit \ sys_exit_args void =2E.. 5 AUE_OPEN_RWTC STD { int open( \ _In_z_ char *path, \ int flags, \ int mode); } New format: 1 AUE_EXIT STD { void sys_exit( int rval ); } exit sys_exit_args void =2E.. 5 AUE_OPEN_RWTC STD {=20 int open(=20 _In_z_ char *path, =20 int flags, =20 int mode =20 ); =20 } For an example of where this makes diffs easier, consider preadv: Old format: 289 AUE_PREADV STD { ssize_t preadv(int fd, \ _In_reads_(iovcnt) \ struct iovec *iovp, \ u_int iovcnt, off_t offset); } New format: 289 AUE_PREADV STD { ssize_t preadv( int fd, _In_reads_(iovcnt) struct iovec *iovp, u_int iovcnt, off_t offset ); } New format (freebsd32): 289 AUE_PREADV STD { ssize_t freebsd32_preadv( int fd, _In_reads_(iovcnt) struct iovec32 *iovp, u_int iovcnt, uint32_t offset1, uint32_t offset2 ); } Some comments on this: - One-variable-per-line allows for annotations and is struct-like which is appropriate since this is more about declaring uap structs then about function declarations. - I chose the top level indent keep things readable without adding a blank between each syscall block. I'd be happy to drop things back one tab if we'd rather have blanks between each declaration. - If one really cared about vertical space, one could combine the ");", "}", and alternative names, but I didn't find that very aesthetic. I'd like to know if this would break any out-of-tree parsers. If so, we can easily keep backslashes, but I'd rather clear those out if we're going to complicate svn blame for every line in the file. Parsers written in more sensible languages than the in-tree sh+sed+awk monster seem likely to be easy to fix and I hope that a more stylized format will be easier to handle with dumb parsers, but I'd like to hear if this change would cause issues. -- Brooks P.S. I'd plan to make this change after the 12.0 branch, but would like to reach concensus sooner as I'm working on yet-another-syscall vector in my work tree and I'd like to use this there. --IS0zKkzwUGydFO0o Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQEcBAEBAgAGBQJbvSkwAAoJEKzQXbSebgfA5dwIAIaOn+RGmwrlyNgiPHvF6AW9 0YjF0fgtIxKHzkH37F2iPJl62dxudK2dshsmCFmg5rP9bA5H+/9ovgrqWrzhvbAb iRgMDVztuzNu0Yq3UUorD7qeRUAg1eTsNxHCVfei/DncYDgK+Ln3zn+AN+g+jkY1 i90kpmtTeGnHSTmwbD58DjHwOQTJz5jgmSqEHw2ShMxuae0VHEGuVwsX0sg6/XfE yQO0eFg+UohJdC7QIe9JoYB0MBjcfCx9nC++CmUUcNUmBs3zXxQNjku8QGI7OJ3i 1BGDxP7WM4KqRE0xINfvt7dP1oNLq2Ry1USB5KIt0MFlYSEWM15AMOcRZZkNAMc= =2kf+ -----END PGP SIGNATURE----- --IS0zKkzwUGydFO0o--