* [PATCH] mctp.7: Add man page for Linux MCTP support
@ 2021-10-14 7:05 Jeremy Kerr
2021-10-17 18:49 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 9+ messages in thread
From: Jeremy Kerr @ 2021-10-14 7:05 UTC (permalink / raw)
To: linux-man; +Cc: Alejandro Colomar, Michael Kerrisk
This change adds a brief description for the new Management Component
Transport Protocol (MCTP) support added to Linux as of bc49d8169.
This is a fairly regular sockets-API implementation, so we're just
describing the semantics of socket, bind, sendto and recvfrom for the
new protocol.
Signed-off-by: Jeremy Kerr <jk@codeconstruct.com.au>
---
man7/address_families.7 | 7 ++
man7/mctp.7 | 181 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 188 insertions(+)
create mode 100644 man7/mctp.7
diff --git a/man7/address_families.7 b/man7/address_families.7
index 3e535e66d..3c8299e69 100644
--- a/man7/address_families.7
+++ b/man7/address_families.7
@@ -405,6 +405,13 @@ XDP (express data path) interface (since Linux 4.18).
See
.I Documentation/networking/af_xdp.rst
in the Linux kernel source tree for details.
+.TP
+.B AF_MCTP
+.\" commit: bc49d8169aa72295104f1558830c568efb946315
+MCTP (Management Component Transport Protocol) interface (since Linux 5.15),
+as defined by the DMTF specification DSP0236.
+For further information, see
+.BR mctp (7).
.SH SEE ALSO
.BR socket (2),
.BR socket (7)
diff --git a/man7/mctp.7 b/man7/mctp.7
new file mode 100644
index 000000000..eb9b61cb9
--- /dev/null
+++ b/man7/mctp.7
@@ -0,0 +1,181 @@
+.\" Copyright (c) 2021 Jeremy Kerr <jk@codeconstruct.com.au>
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\" commit: bc49d8169aa72295104f1558830c568efb946315
+.TH MCTP 7 2021-10-14 "Linux" "Linux Programmer's Manual"
+.SH NAME
+mctp \- Management Component Transport Protocol
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.B #include <linux/mctp.h>
+.PP
+.B mctp_socket = socket(AF_MCTP, SOCK_DGRAM, 0);
+.fi
+.SH DESCRIPTION
+Linux implements the Management Component Transport Protocol (MCTP),
+specified by DMTF spec DSP0236, currently at version 1.
+This is a connectionless protocol, typically used between devices within a
+server system. Message reliability and ordering are not guaranteed, but
+message boundaries are preserved.
+.PP
+The API for MCTP messaging uses a standard sockets interface, using the
+.BR sendto (2)
+and
+.BR recvfrom (2)
+classes of system calls to transfer messages.
+Messages may be fragmented into packets before transmission, and reassembled at
+the remote endpoint.
+This fragmentation and reassembly is transparent to userspace.
+.PP
+.SS Address format
+MCTP addresses (also referred to as EIDs, or Endpoint Identifiers) are
+single-byte values, typed as
+.BR mctp_eid_t .
+Packets between a local and remote endpoint are identified by the source
+and destination EIDs, plus a three-bit tag value.
+.PP
+Addressing data is passed in socket system calls through
+.B struct sockaddr\_mctp
+defined as:
+.PP
+.in +4n
+.EX
+typedef uint8_t mctp_eid_t;
+
+struct mctp_addr {
+ mctp_eid_t s_addr;
+};
+
+struct sockaddr_mctp {
+ unsigned short int smctp_family; /* = AF_MCTP */
+ int smctp_network; /* local network identifier */
+ struct mctp_addr smctp_addr; /* EID */
+ uint8_t smctp_type; /* message type byte */
+ uint8_t smctp_tag; /* tag value, including TO flag */
+};
+.EE
+.in
+.SS Sending messages
+Messages can be transmitted using the
+.BR sendto (2)
+and
+.BR sendmsg (2)
+system calls, by providing a
+.B struct sockaddr_mctp
+describing the addressing parameters.
+.PP
+.in +4n
+.EX
+struct sockaddr_mctp addr;
+ssize_t len;
+char *buf;
+
+/* set message destination */
+addr.smctp_family = AF_MCTP;
+addr.smctp_network = 0;
+addr.smctp_addr.s_addr = 8; /* remote EID */
+addr.smctp_tag = MCTP_TAG_OWNER;
+addr.smctp_type = MCTP_TYPE_ECHO; /* fictional message type */
+
+buf = "hello, world!"
+
+len = sendto(sd, buf, 13, 0,
+ (struct sockaddr_mctp *)&addr, sizeof(addr));
+.EE
+.in
+.PP
+Here, the sender owns the message tag; so
+.B MCTP_TAG_OWNER
+is used as the tag data.
+The kernel will allocate a specific tag value for this message.
+If no tag is available,
+.B sendto
+will return an error, with errno set to
+.BR EBUSY .
+This allocated tag remains associated with the socket, so that any replies to
+the sent message will be received by the same socket.
+.PP
+Sending a MCTP message requires the
+.B CAP_NET_RAW
+capability.
+.SS Receiving messages
+Messages can be received using the
+.BR recvfrom (2)
+and
+.BR recvmsg (2)
+system calls.
+.PP
+.in +4n
+.EX
+struct sockaddr_mctp addr;
+socklen_t addrlen;
+char buf[13];
+
+addrlen = sizeof(addr);
+
+len = recvfrom(sd, buf, sizeof(buf), 0,
+ (struct sockaddr_mctp *)&addr, &addrlen);
+.EE
+.in
+.PP
+In order to receive an incoming message, the receiver will need to either have
+previously sent a message to the same endpoint, or performed a
+.BR bind (2)
+to receive all messages of a certain type:
+.PP
+.in +4n
+.EX
+struct sockaddr_mctp addr;
+
+addr.smctp_family = AF_MCTP;
+addr.smctp_network = MCTP_NET_ANY;
+addr.smctp_addr.s_addr = MCTP_ADDR_ANY;
+addr.smctp_type = MCTP_TYPE_ECHO; /* our fictional 'echo' type */
+
+int rc = bind(sd, (struct sockaddr *)&addr, sizeof(addr));
+.EE
+.in
+.PP
+This call requires the
+.B CAP_NET_BIND_SERVICE
+capability, and will result in the socket receiving all messages sent to
+locally-assigned EIDs, for the specified message type.
+.PP
+After a
+.B recvfrom
+or
+.B recvmsg
+returns a success condition, the provided address argument will be populated
+with the sender's network and EID, as well as the tag value used for the
+message.
+Any reply to this message should pass the same address and tag value (with the
+TO bit cleared) to indicate that is is directed to the same remote endpoint.
+.SH SEE ALSO
+.BR socket (7)
+.PP
+The kernel source file
+.IR Documentation/networking/mctp.rst .
+.PP
+The DSP0236 specification, at
+.UR https://www.dmtf.org/standards/pmci
+.UE .
--
2.30.2
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] mctp.7: Add man page for Linux MCTP support
2021-10-14 7:05 [PATCH] mctp.7: Add man page for Linux MCTP support Jeremy Kerr
@ 2021-10-17 18:49 ` Alejandro Colomar (man-pages)
2021-10-18 5:05 ` Jeremy Kerr
2021-10-18 7:46 ` Alejandro Colomar (man-pages)
0 siblings, 2 replies; 9+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-10-17 18:49 UTC (permalink / raw)
To: Jeremy Kerr; +Cc: Michael Kerrisk, linux-man
Hello Jeremy,
On 10/14/21 9:05 AM, Jeremy Kerr wrote:
> This change adds a brief description for the new Management Component
> Transport Protocol (MCTP) support added to Linux as of bc49d8169.
>
> This is a fairly regular sockets-API implementation, so we're just
> describing the semantics of socket, bind, sendto and recvfrom for the
> new protocol.
>
> Signed-off-by: Jeremy Kerr <jk@codeconstruct.com.au>
Thanks for the manual page!
Please, check some comments below.
Cheers,
Alex
> ---
> man7/address_families.7 | 7 ++
> man7/mctp.7 | 181 ++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 188 insertions(+)
> create mode 100644 man7/mctp.7
>
> diff --git a/man7/address_families.7 b/man7/address_families.7
> index 3e535e66d..3c8299e69 100644
> --- a/man7/address_families.7
> +++ b/man7/address_families.7
> @@ -405,6 +405,13 @@ XDP (express data path) interface (since Linux 4.18).
> See
> .I Documentation/networking/af_xdp.rst
> in the Linux kernel source tree for details.
> +.TP
> +.B AF_MCTP
> +.\" commit: bc49d8169aa72295104f1558830c568efb946315
> +MCTP (Management Component Transport Protocol) interface (since Linux 5.15),
> +as defined by the DMTF specification DSP0236.
> +For further information, see
> +.BR mctp (7).
> .SH SEE ALSO
> .BR socket (2),
> .BR socket (7)
> diff --git a/man7/mctp.7 b/man7/mctp.7
> new file mode 100644
> index 000000000..eb9b61cb9
> --- /dev/null
> +++ b/man7/mctp.7
> @@ -0,0 +1,181 @@
> +.\" Copyright (c) 2021 Jeremy Kerr <jk@codeconstruct.com.au>
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" This is free documentation; you can redistribute it and/or
> +.\" modify it under the terms of the GNU General Public License as
> +.\" published by the Free Software Foundation; either version 2 of
> +.\" the License, or (at your option) any later version.
> +.\"
> +.\" The GNU General Public License's references to "object code"
> +.\" and "executables" are to be interpreted as the output of any
> +.\" document formatting or typesetting system, including
> +.\" intermediate and printed output.
> +.\"
> +.\" This manual is distributed in the hope that it will be useful,
> +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +.\" GNU General Public License for more details.
> +.\"
> +.\" You should have received a copy of the GNU General Public
> +.\" License along with this manual; if not, see
> +.\" <http://www.gnu.org/licenses/>.
> +.\" %%%LICENSE_END
> +.\" commit: bc49d8169aa72295104f1558830c568efb946315
> +.TH MCTP 7 2021-10-14 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +mctp \- Management Component Transport Protocol
> +.SH SYNOPSIS
> +.nf
> +.B #include <sys/socket.h>
> +.B #include <linux/mctp.h>
> +.PP
> +.B mctp_socket = socket(AF_MCTP, SOCK_DGRAM, 0);
mctp_socket is a variable name. See socket.7 for an example.
It should be in italics.
> +.fi
> +.SH DESCRIPTION
> +Linux implements the Management Component Transport Protocol (MCTP),
> +specified by DMTF spec DSP0236, currently at version 1.
> +This is a connectionless protocol, typically used between devices within a
> +server system. Message reliability and ordering are not guaranteed, but
Please use semantic newlines. See man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be
started on new lines, and long sentences should be split
into lines at clause breaks (commas, semicolons, colons,
and so on). This convention, sometimes known as "seman‐
tic newlines", makes it easier to see the effect of
patches, which often operate at the level of individual
sentences or sentence clauses.
> +message boundaries are preserved.
> +.PP
> +The API for MCTP messaging uses a standard sockets interface, using the
> +.BR sendto (2)
> +and
> +.BR recvfrom (2)
> +classes of system calls to transfer messages.
> +Messages may be fragmented into packets before transmission, and reassembled at
> +the remote endpoint.
> +This fragmentation and reassembly is transparent to userspace.
> +.PP
> +.SS Address format
> +MCTP addresses (also referred to as EIDs, or Endpoint Identifiers) are
> +single-byte values, typed as
> +.BR mctp_eid_t .
> +Packets between a local and remote endpoint are identified by the source
> +and destination EIDs, plus a three-bit tag value.
> +.PP
> +Addressing data is passed in socket system calls through
> +.B struct sockaddr\_mctp
That escape is unnecessary. Did you see it in another page perhaps?
> +defined as:
> +.PP
> +.in +4n
> +.EX
> +typedef uint8_t mctp_eid_t;
> +
> +struct mctp_addr {
> + mctp_eid_t s_addr;
> +};
> +
> +struct sockaddr_mctp {
> + unsigned short int smctp_family; /* = AF_MCTP */
We only use 'int' in 'unsigned int', as the kernel does (or attempts to
do). checkpatch.pl warns about 'unsigned short int', IIRC.
So, 'unsigned short'.
> + int smctp_network; /* local network identifier */
> + struct mctp_addr smctp_addr; /* EID */
> + uint8_t smctp_type; /* message type byte */
> + uint8_t smctp_tag; /* tag value, including TO flag */
> +};
> +.EE
> +.in
> +.SS Sending messages
> +Messages can be transmitted using the
> +.BR sendto (2)
> +and
> +.BR sendmsg (2)
> +system calls, by providing a
> +.B struct sockaddr_mctp
No escape here. That's correct.
> +describing the addressing parameters.
> +.PP
> +.in +4n
> +.EX
> +struct sockaddr_mctp addr;
> +ssize_t len;
> +char *buf;
> +
> +/* set message destination */
> +addr.smctp_family = AF_MCTP;
> +addr.smctp_network = 0;
> +addr.smctp_addr.s_addr = 8; /* remote EID */
> +addr.smctp_tag = MCTP_TAG_OWNER;
> +addr.smctp_type = MCTP_TYPE_ECHO; /* fictional message type */
I don't like 'MCTP_TYPE_ECHO': It's not a flag defined by the kernel,
so it shouldn't have such a name (it resembles too much other kernel
identifiers, such as MCTP_TAG_OWNER). Better something like
MYPROGRAM_MCTP_TYPE_ECHO, to clearly show the reader that this one is
really arbitrary.
> +
> +buf = "hello, world!"
> +
> +len = sendto(sd, buf, 13, 0,
> + (struct sockaddr_mctp *)&addr, sizeof(addr));
This cast is incorrect. Since the parameter is not a 'void *', that
cast would give a compile error. It should be '(struct sockaddr *)'.
There are similar casts in this page which also should be fixed like
this one.
> +.EE
> +.in
> +.PP
> +Here, the sender owns the message tag; so
> +.B MCTP_TAG_OWNER
> +is used as the tag data.
> +The kernel will allocate a specific tag value for this message.
> +If no tag is available,
> +.B sendto
> +will return an error, with errno set to
> +.BR EBUSY .
> +This allocated tag remains associated with the socket, so that any replies to
> +the sent message will be received by the same socket.
> +.PP
> +Sending a MCTP message requires the
> +.B CAP_NET_RAW
> +capability.
> +.SS Receiving messages
> +Messages can be received using the
> +.BR recvfrom (2)
> +and
> +.BR recvmsg (2)
> +system calls.
> +.PP
> +.in +4n
> +.EX
> +struct sockaddr_mctp addr;
> +socklen_t addrlen;
> +char buf[13];
> +
> +addrlen = sizeof(addr);
> +
> +len = recvfrom(sd, buf, sizeof(buf), 0,
> + (struct sockaddr_mctp *)&addr, &addrlen);
> +.EE
> +.in
> +.PP
> +In order to receive an incoming message, the receiver will need to either have
> +previously sent a message to the same endpoint, or performed a
> +.BR bind (2)
> +to receive all messages of a certain type:
> +.PP
> +.in +4n
> +.EX
> +struct sockaddr_mctp addr;
> +
> +addr.smctp_family = AF_MCTP;
> +addr.smctp_network = MCTP_NET_ANY;
> +addr.smctp_addr.s_addr = MCTP_ADDR_ANY;
> +addr.smctp_type = MCTP_TYPE_ECHO; /* our fictional 'echo' type */
> +
> +int rc = bind(sd, (struct sockaddr *)&addr, sizeof(addr));
> +.EE
> +.in
> +.PP
> +This call requires the
> +.B CAP_NET_BIND_SERVICE
> +capability, and will result in the socket receiving all messages sent to
> +locally-assigned EIDs, for the specified message type.
> +.PP
> +After a
> +.B recvfrom
> +or
> +.B recvmsg
Use man syntax:
.BR recvfrom (3)
or
.BR recvmsg (3)
> +returns a success condition, the provided address argument will be populated
> +with the sender's network and EID, as well as the tag value used for the
> +message.
> +Any reply to this message should pass the same address and tag value (with the
> +TO bit cleared) to indicate that is is directed to the same remote endpoint.
> +.SH SEE ALSO
> +.BR socket (7)
> +.PP
> +The kernel source file
> +.IR Documentation/networking/mctp.rst .
> +.PP
> +The DSP0236 specification, at
> +.UR https://www.dmtf.org/standards/pmci
> +.UE .
>
Please, use break points for both URIs above. See the source code of
uri.7, which has plenty of examples.
See also "the Chicago Manual of Style"
<https://libguides.lorainccc.edu/c.php?g=29361&p=183502> for guidelines
on that.
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] mctp.7: Add man page for Linux MCTP support
2021-10-17 18:49 ` Alejandro Colomar (man-pages)
@ 2021-10-18 5:05 ` Jeremy Kerr
2021-10-18 5:57 ` G. Branden Robinson
2021-10-18 6:59 ` [PATCH] mctp.7: Add man page for Linux MCTP support Alejandro Colomar (man-pages)
2021-10-18 7:46 ` Alejandro Colomar (man-pages)
1 sibling, 2 replies; 9+ messages in thread
From: Jeremy Kerr @ 2021-10-18 5:05 UTC (permalink / raw)
To: Alejandro Colomar (man-pages); +Cc: Michael Kerrisk, linux-man
Hi Alex,
> Thanks for the manual page!
And thanks for the review! In general, I've updated to suit your
comments, just a couple of queries inline.
> > +.SH SYNOPSIS
> > +.nf
> > +.B #include <sys/socket.h>
> > +.B #include <linux/mctp.h>
> > +.PP
> > +.B mctp_socket = socket(AF_MCTP, SOCK_DGRAM, 0);
>
> mctp_socket is a variable name. See socket.7 for an example.
> It should be in italics.
This was based on udp.7; want me to send a patch for that too?
> > +Packets between a local and remote endpoint are identified by the
> > source
> > +and destination EIDs, plus a three-bit tag value.
> > +.PP
> > +Addressing data is passed in socket system calls through
> > +.B struct sockaddr\_mctp
>
> That escape is unnecessary. Did you see it in another page perhaps?
I thought I'd seen some odd line-breaks at the underscore, but can't
replicate that now. Will remove.
> > +typedef uint8_t mctp_eid_t;
> > +
> > +struct mctp_addr {
> > + mctp_eid_t s_addr;
> > +};
> > +
> > +struct sockaddr_mctp {
> > + unsigned short int smctp_family; /* = AF_MCTP */
>
> We only use 'int' in 'unsigned int', as the kernel does (or attempts
> to do). checkpatch.pl warns about 'unsigned short int', IIRC.
No, there are no warnings from checkpatch there; that's just copied from
the current kernel header.
However, I have just sent a separate patch to change that to
__kernel_sa_family_t. Should I use that here (keeping this an exact
match of the kernel header), or stick to the more familiar unsigned
short?
Cheers,
Jeremy
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] mctp.7: Add man page for Linux MCTP support
2021-10-18 5:05 ` Jeremy Kerr
@ 2021-10-18 5:57 ` G. Branden Robinson
2021-10-18 7:16 ` Alejandro Colomar (man-pages)
2021-10-18 6:59 ` [PATCH] mctp.7: Add man page for Linux MCTP support Alejandro Colomar (man-pages)
1 sibling, 1 reply; 9+ messages in thread
From: G. Branden Robinson @ 2021-10-18 5:57 UTC (permalink / raw)
To: Jeremy Kerr; +Cc: Alejandro Colomar (man-pages), Michael Kerrisk, linux-man
[-- Attachment #1: Type: text/plain, Size: 1664 bytes --]
Hi Jeremy,
At 2021-10-18T13:05:25+0800, Jeremy Kerr wrote:
> > > +Addressing data is passed in socket system calls through
> > > +.B struct sockaddr\_mctp
> >
> > That escape is unnecessary. Did you see it in another page perhaps?
>
> I thought I'd seen some odd line-breaks at the underscore, but can't
> replicate that now. Will remove.
My groff experiments don't reveal _ or \_ as being permissible
break points[1]. However, the structure tag _could_ break like this:
sock‐addr_mctp
In other words (if my UTF-8 gets mangled), after "sock".
To prevent that, you can prefix the word with the hyphenation control
escape sequence, "\%". This escape sequence is extremely portable; it
dates back to 1970s AT&T troff.
Further, if you wanted to prevent breaking between the "struct" keyword
and the structure tag, you could use a nonbreaking adjustable space
escape sequence, "\~". While this was a groff innovation (about 30
years ago), it's been adopted by Heirloom Doctools troff and mandoc(1),
so it's pretty portable to systems likely to install the Linux
man-pages.
So we might write
.B struct\~\%sockaddr_mctp
for instance in running text (that is, in sentences). (When filling is
off, as in code examples and the synopses of most pages documenting C
interfaces, neither of these escape sequences is necessary; unfilled
lines are neither automatically hyphenated nor adjusted.)
Just a typographical FYI. I know these issues sometimes frustrate
people.
Regards,
Branden
[1] I'm using groff's defaults. It's possible to change the groff
"hyphenation code" of any character, but few do so.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] mctp.7: Add man page for Linux MCTP support
2021-10-18 5:05 ` Jeremy Kerr
2021-10-18 5:57 ` G. Branden Robinson
@ 2021-10-18 6:59 ` Alejandro Colomar (man-pages)
1 sibling, 0 replies; 9+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-10-18 6:59 UTC (permalink / raw)
To: Jeremy Kerr
Cc: Michael Kerrisk, linux-man, Dwaipayan Ray, Joe Perches,
Andy Whitcroft, Lukas Bulwahn, linux-kernel
[CC += checkpatch.pl maintainers (see reason below)]
Hi Jeremy,
On 10/18/21 7:05 AM, Jeremy Kerr wrote:
> Hi Alex,
>
>> Thanks for the manual page!
>
> And thanks for the review! In general, I've updated to suit your
> comments, just a couple of queries inline.
>
>>> +.SH SYNOPSIS
>>> +.nf
>>> +.B #include <sys/socket.h>
>>> +.B #include <linux/mctp.h>
>>> +.PP
>>> +.B mctp_socket = socket(AF_MCTP, SOCK_DGRAM, 0);
>>
>> mctp_socket is a variable name. See socket.7 for an example.
>> It should be in italics.
>
> This was based on udp.7; want me to send a patch for that too?
Sure. Thanks!
>
>>> +Packets between a local and remote endpoint are identified by the
>>> source
>>> +and destination EIDs, plus a three-bit tag value.
>>> +.PP
>>> +Addressing data is passed in socket system calls through
>>> +.B struct sockaddr\_mctp
>>
>> That escape is unnecessary. Did you see it in another page perhaps?
>
> I thought I'd seen some odd line-breaks at the underscore, but can't
> replicate that now. Will remove.
>
>>> +typedef uint8_t mctp_eid_t;
>>> +
>>> +struct mctp_addr {
>>> + mctp_eid_t s_addr;
>>> +};
>>> +
>>> +struct sockaddr_mctp {
>>> + unsigned short int smctp_family; /* = AF_MCTP */
>>
>> We only use 'int' in 'unsigned int', as the kernel does (or attempts
>> to do). checkpatch.pl warns about 'unsigned short int', IIRC.
>
> No, there are no warnings from checkpatch there; that's just copied from
> the current kernel header.
Huh! That's weird; 'unsigned long int' does, so I expected the same
with 'short'. Maybe a bug in checkpatch?
WARNING:UNNECESSARY_INT: Prefer 'unsigned long' over 'unsigned long int'
as the int is unnecessary
#42: FILE: /home/user/src/alx/test/unsigned_short_int.c:42:
+ unsigned long int a;
total: 0 errors, 1 warnings, 0 checks, 65 lines checked
>
> However, I have just sent a separate patch to change that to
> __kernel_sa_family_t. Should I use that here (keeping this an exact
> match of the kernel header), or stick to the more familiar unsigned
> short?
I prefer 'unsigned short' for consistency with 'unsigned long'.
>
> Cheers,
>
>
> Jeremy
>
Cheers,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] mctp.7: Add man page for Linux MCTP support
2021-10-18 5:57 ` G. Branden Robinson
@ 2021-10-18 7:16 ` Alejandro Colomar (man-pages)
2021-10-18 7:53 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 9+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-10-18 7:16 UTC (permalink / raw)
To: G. Branden Robinson, Jeremy Kerr; +Cc: Michael Kerrisk, linux-man
Hi Branden,
On 10/18/21 7:57 AM, G. Branden Robinson wrote:
> Hi Jeremy,
>
> At 2021-10-18T13:05:25+0800, Jeremy Kerr wrote:
>>>> +Addressing data is passed in socket system calls through
>>>> +.B struct sockaddr\_mctp
>>>
>>> That escape is unnecessary. Did you see it in another page perhaps?
>>
>> I thought I'd seen some odd line-breaks at the underscore, but can't
>> replicate that now. Will remove.
>
> My groff experiments don't reveal _ or \_ as being permissible
> break points[1]. However, the structure tag _could_ break like this:
>
> sock‐addr_mctp
>
> In other words (if my UTF-8 gets mangled), after "sock".
>
> To prevent that, you can prefix the word with the hyphenation control
> escape sequence, "\%". This escape sequence is extremely portable; it
> dates back to 1970s AT&T troff.
Hmm, this is one of the few points we disagree, it seems :)
As I said previously, I think this uglyfies code too much, for something
that I think should be default (it is rarer to want break points at
highlighted words than not wanting them). But, to try to confirm my
thoughts, I'll accept using this in the man-pages and see what happens
(maybe some day, a winter day it shall be, you'll wake up and see a cold
commit reaping them all :p)
>
> Further, if you wanted to prevent breaking between the "struct" keyword
> and the structure tag, you could use a nonbreaking adjustable space
> escape sequence, "\~". While this was a groff innovation (about 30
> years ago), it's been adopted by Heirloom Doctools troff and mandoc(1),
> so it's pretty portable to systems likely to install the Linux
> man-pages.
Ah yes, I should have spotted that one :p
>
> So we might write
>
> .B struct\~\%sockaddr_mctp
Okay.
>
> for instance in running text (that is, in sentences). (When filling is
> off, as in code examples and the synopses of most pages documenting C
> interfaces, neither of these escape sequences is necessary; unfilled
> lines are neither automatically hyphenated nor adjusted.)
>
> Just a typographical FYI. I know these issues sometimes frustrate
> people.
>
> Regards, > Branden
Thanks!
Alex
>
> [1] I'm using groff's defaults. It's possible to change the groff
> "hyphenation code" of any character, but few do so.
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] mctp.7: Add man page for Linux MCTP support
2021-10-17 18:49 ` Alejandro Colomar (man-pages)
2021-10-18 5:05 ` Jeremy Kerr
@ 2021-10-18 7:46 ` Alejandro Colomar (man-pages)
1 sibling, 0 replies; 9+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-10-18 7:46 UTC (permalink / raw)
To: Jeremy Kerr; +Cc: Michael Kerrisk, linux-man, G. Branden Robinson
Hello Jeremy,
On 10/17/21 8:49 PM, Alejandro Colomar (man-pages) wrote:
>> +TO bit cleared) to indicate that is is directed to the same remote
>> endpoint.
>> +.SH SEE ALSO
>> +.BR socket (7)
>> +.PP
>> +The kernel source file
>> +.IR Documentation/networking/mctp.rst .
>> +.PP
>> +The DSP0236 specification, at
>> +.UR https://www.dmtf.org/standards/pmci
>> +.UE .
>>
>
> Please, use break points for both URIs above. See the source code of
> uri.7, which has plenty of examples.
>
> See also "the Chicago Manual of Style"
> <https://libguides.lorainccc.edu/c.php?g=29361&p=183502> for guidelines
> on that.
Please, don't read those. As Branden and I discussed in another thread
today, we prefer not following that style.
So instead of those sources, I'll just write it for you.
.IR Documentation/\:networking/\:mctp.rst .
.UR https://\:www.dmtf.org/\:standards/\:pmci
We could also break before dots, but since the names are short, I don't
think it's needed. It could be:
.IR Documentation/\:networking/\:mctp\:.rst .
.UR https://\:www\:.dmtf\:.org/\:standards/\:pmci
If you are curious about the discussion we had about this, it's here:
<https://lists.gnu.org/archive/html/groff/2021-10/msg00045.html>.
Thanks,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] mctp.7: Add man page for Linux MCTP support
2021-10-18 7:16 ` Alejandro Colomar (man-pages)
@ 2021-10-18 7:53 ` Alejandro Colomar (man-pages)
2021-11-22 1:09 ` Suppressing hyphenation (was: [PATCH] mctp.7: Add man page for Linux MCTP support) G. Branden Robinson
0 siblings, 1 reply; 9+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-10-18 7:53 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: Michael Kerrisk, linux-man, Jeremy Kerr
On 10/18/21 9:16 AM, Alejandro Colomar (man-pages) wrote:
>> So we might write
>>
>> .B struct\~\%sockaddr_mctp
>
> Okay.
Actually, wouldn't it be better to just write?:
.B \%struct\~sockaddr_mctp
This way \% applies to the whole (even if it was unnecessary for
'struct\~').
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 9+ messages in thread
* Suppressing hyphenation (was: [PATCH] mctp.7: Add man page for Linux MCTP support)
2021-10-18 7:53 ` Alejandro Colomar (man-pages)
@ 2021-11-22 1:09 ` G. Branden Robinson
0 siblings, 0 replies; 9+ messages in thread
From: G. Branden Robinson @ 2021-11-22 1:09 UTC (permalink / raw)
To: Alejandro Colomar (man-pages); +Cc: Michael Kerrisk, linux-man
[-- Attachment #1: Type: text/plain, Size: 5072 bytes --]
[Jeremy Kerr dropped from CC--I hope that's okay]
Hi Alex,
Getting back to this after a month...
At 2021-10-18T09:53:54+0200, Alejandro Colomar (man-pages) wrote:
> On 10/18/21 9:16 AM, Alejandro Colomar (man-pages) wrote:
> > > So we might write
> > >
> > > .B struct\~\%sockaddr_mctp
> >
> > Okay.
>
> Actually, wouldn't it be better to just write?:
>
> .B \%struct\~sockaddr_mctp
>
> This way \% applies to the whole (even if it was unnecessary for
> 'struct\~').
In fact it does not apply to the whole; '\~' still counts as a word
delimiter to groff even if it is not a permissible location for a
"break" (line break).
Before I bust out the long explanation, I'll try to present some short
advice for man page writers.
* If you wish to suppress hyphenation with the '\%' escape sequence,
place it at the _beginning_ of each such word. Except for special
character escape sequences like '\-', '\(ha', and '\[aq]', most groff
escape sequences act as word boundaries, so you may need to specify
'\%' before each word in a series, as in '\%typedef\~int\~\%strsize'.
Now for the deeper dive.
As strange as it may seem, this is consistent with the behavior of
hyphenation when it encounters most other escape sequences[1] (most of
which a portable man page should not attempt to use). The key factor to
consider in matters of hyphenation suppression is where the _word
boundaries_ are, not where white space appears.
By contrast, anything that formats a glyph for output generally _is_
part of a word. But only glyphs that not part of natural language words
(in English, [A-Za-z]) are eligible for adjacent hyphenation.
Here's the documentation of '\%' (and '\:') from the Info documentation
of the forthcoming groff 1.23.0 release.
[[
-- Escape: \%
-- Escape: \:
To tell GNU 'troff' how to hyphenate words as they occur in input,
use the '\%' escape, also known as the "hyphenation character".
Each instance within a word indicates to GNU 'troff' that the word
may be hyphenated at that point, while prefixing a word with this
escape prevents it from being otherwise hyphenated. This mechanism
affects only that occurrence of the word; to change the hyphenation
of a word for the remainder of input processing, use the 'hw'
request.
GNU 'troff' regards the escapes '\X' and '\Y' as starting a word;
that is, the '\%' escape in, say, '\X'...'\%foobar' or
'\Y'...'\%foobar' no longer prevents hyphenation of 'foobar' but
inserts a hyphenation point just prior to it; most likely this
isn't what you want. *Note Postprocessor Access::.
The '\:' escape inserts a non-printing break point; that is, the
word can break there, but the soft hyphen glyph (see below) is not
written to the output if it does. This escape is an input word
boundary, so the remainder of the word is subject to hyphenation as
normal.
You can use '\:' and '\%' in combination to control breaking of a
file name or URL or to permit hyphenation only after certain
explicit hyphens within a word.
The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce
was, in retrospect, inevitable once the contents of
\%/var/log/\:\%httpd/\:\%access_log on the family web
server came to light, revealing visitors from Hogwarts.
]]
Here's a short shell script to tell you where your installed
version of groff will hyphenate words: it forces hyphenation to occur at
every possible location.
$ cat ~/bin/hyphen
#!/bin/sh
for W
do
printf ".hy 4\n.ll 1u\n%s\n" "$W" | nroff -Wbreak | sed '/^$/d' \
| tr -d '\n'
echo
done
$ LC_ALL=C hyphen antidisestablishmentarianism 'struct\\~sockaddr'
an-tidis-es-tab-lish-men-tar-i-an-ism
struct\~sock-addr
$ LC_ALL=C hyphen sockaddr \\%sockaddr \\%sock\\%addr sock_addr sock^addr
sock-addr
sockaddr
sock-addr
sock_addr
sock^addr
(I set the locale so as to keep this email strictly "basic Latin", groff
will happily emit proper Unicode hyphens U+2010 to a supporting output
device.)
You can see from the above that we can't recklessly sprinkle '\%': apart
from looking ugly, '\%' at the beginning of a word suppresses only
_automatic_ hyphenation. If you specify it both at the beginning _and_
within a word, its other meaning of marking a hyphenation point is
still honored.
Regards,
Branden
[1] There are a few exceptions, like those which "don't produce an input
token" as the groff Texinfo manual puts it, a construction that is more
intelligible to the groff developer than the groff user. These
have to do with escape sequences that change the way glyphs are
rendered, such as changes to the font style or family, type size, or
stroke or fill colors. Most of these should never occur in portable man
pages and even '\f' is, in my view, better handled with man(7) font
style macros and the '\c' escape sequence if required for break
suppression.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2021-11-22 1:09 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-10-14 7:05 [PATCH] mctp.7: Add man page for Linux MCTP support Jeremy Kerr
2021-10-17 18:49 ` Alejandro Colomar (man-pages)
2021-10-18 5:05 ` Jeremy Kerr
2021-10-18 5:57 ` G. Branden Robinson
2021-10-18 7:16 ` Alejandro Colomar (man-pages)
2021-10-18 7:53 ` Alejandro Colomar (man-pages)
2021-11-22 1:09 ` Suppressing hyphenation (was: [PATCH] mctp.7: Add man page for Linux MCTP support) G. Branden Robinson
2021-10-18 6:59 ` [PATCH] mctp.7: Add man page for Linux MCTP support Alejandro Colomar (man-pages)
2021-10-18 7:46 ` Alejandro Colomar (man-pages)
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.