man/man7/mctp.7: Document Linux MCTP support

This change adds a brief description for the new Management Component
Transport Protocol (MCTP) support added to Linux as of
linux.git bc49d8169aa7 (2021-07-29; "mctp: Add MCTP base").

This is a fairly regular sockets-API implementation, so we're just
describing the semantics of socket(2), bind(2), sendto(2), and
recvfrom(2) for the new protocol.

Signed-off-by: Jeremy Kerr <jk@codeconstruct.com.au>
Message-ID: <20250417-mctp-v3-1-07fff4d26f73@codeconstruct.com.au>
[alx: minor tweaks]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man7/address_families.7 b/man/man7/address_families.7
index 3c2400820627035d2fced0d9e49d61aa01e2d3f3..4e29e0bfb88447c64d53d44c3fae27ccc435e241 100644 (file)
--- a/man/man7/address_families.7
+++ b/man/man7/address_families.7
@@ -387,6 +387,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/man/man7/mctp.7 b/man/man7/mctp.7
new file mode 100644 (file)
index 0000000..47aea9b
--- /dev/null
+++ b/man/man7/mctp.7
@@ -0,0 +1,183 @@
+.\" Copyright 2021,2025, Jeremy Kerr <jk@codeconstruct.com.au>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH mctp 7 (date) "Linux man-pages (unreleased)"
+.SH NAME
+mctp \- Management Component Transport Protocol
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/mctp.h>" \
+"  /* MCTP address type and protocol constants */"
+.B #include <sys/socket.h>
+.P
+.IB 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.
+.P
+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 user space.
+.SS Address format
+MCTP addresses
+(also referred to as EIDs, or Endpoint Identifiers)
+are single-byte values,
+typed as
+.IR mctp_eid_t .
+Packets between a local and remote endpoint
+are identified by
+the source and destination EIDs,
+plus a three-bit tag value.
+.P
+Addressing data is passed in socket system calls through a
+.I sockaddr_mctp
+structure,
+defined as:
+.P
+.in +4n
+.EX
+typedef uint8_t        mctp_eid_t;
+\&
+struct mctp_addr {
+    mctp_eid_t         s_addr;
+};
+\&
+struct sockaddr_mctp {
+    unsigned short     smctp_family;  /* = AF_MCTP */
+    uint16_t           __smctp_pad0;
+    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 & owner */
+    uint8_t            __smctp_pad1;
+};
+.EE
+.in
+.SS Sending messages
+Messages can be transmitted using the
+.BR sendto (2)
+and
+.BR sendmsg (2)
+system calls,
+by providing a
+.I sockaddr_mctp
+structure
+describing the addressing parameters.
+.P
+.in +4n
+.EX
+ssize_t               n;
+const char            *buf;
+struct sockaddr_mctp  addr;
+\&
+/* unused fields must be zero */
+memset(&addr, 0, sizeof(addr));
+\&
+/* 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 = MYPROGRAM_MCTP_TYPE_ECHO; /* example type */
+\&
+buf = "hello, world!"
+\&
+n = sendto(sd, buf, 13, 0,
+           (struct sockaddr *) &addr, sizeof(addr));
+.EE
+.in
+.P
+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,
+.BR sendto (2)
+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.
+.P
+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.
+.P
+.in +4n
+.EX
+char                  buf[13];
+socklen_t             addrlen;
+struct sockaddr_mctp  addr;
+\&
+addrlen = sizeof(addr);
+\&
+n = recvfrom(sd, buf, sizeof(buf), 0,
+             (struct sockaddr *) &addr, &addrlen);
+.EE
+.in
+.P
+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:
+.P
+.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 = MYPROGRAM_MCTP_TYPE_ECHO; /* our 'echo' type */
+\&
+int rc = bind(sd, (struct sockaddr *) &addr, sizeof(addr));
+.EE
+.in
+.P
+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.
+.P
+After a
+.BR recvfrom (2)
+or
+.BR recvmsg (2)
+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)
+.P
+.I linux.git/Documentation/networking/mctp.rst
+.P
+.UR https://www.dmtf.org/\:standards/\:pmci
+The DSP0236 specification
+.UE .