Debian Codegraph @

upstream/debian-unstable/man7/mctp.7

raw
1 .\" Copyright 2021-2025, Jeremy Kerr <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH mctp 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 mctp \- Management Component Transport Protocol
9 .SH SYNOPSIS
10 .nf
11 .BR "#include <linux/mctp.h>" \
12 " /* MCTP address type and protocol constants */"
13 .B #include <sys/socket.h>
14 .P
15 .IB mctp_socket " = socket(AF_MCTP, SOCK_DGRAM, 0);"
16 .fi
17 .SH DESCRIPTION
18 Linux implements the Management Component Transport Protocol (MCTP),
19 specified by DMTF spec DSP0236,
20 currently at version 1.
21 This is a connectionless protocol,
22 typically used between devices within a server system.
23 Message reliability and ordering are not guaranteed,
24 but message boundaries are preserved.
25 .P
26 The API for MCTP messaging uses a standard sockets interface,
27 using the
28 .BR sendto (2)
29 and
30 .BR recvfrom (2)
31 classes of system calls to transfer messages.
32 Messages may be fragmented into packets before transmission,
33 and reassembled at the remote endpoint.
34 This fragmentation and reassembly is transparent to user space.
35 .SS Address format
36 MCTP addresses
37 (also referred to as EIDs, or Endpoint Identifiers)
38 are single-byte values,
39 typed as
40 .IR mctp_eid_t .
41 Packets between a local and remote endpoint
42 are identified by
43 the source and destination EIDs,
44 plus a three-bit tag value.
45 .P
46 Addressing data is passed in socket system calls through a
47 .I sockaddr_mctp
48 structure,
49 defined as:
50 .P
51 .in +4n
52 .EX
53 typedef uint8_t mctp_eid_t;
54 \&
55 struct mctp_addr {
56 mctp_eid_t s_addr;
57 };
58 \&
59 struct sockaddr_mctp {
60 unsigned short smctp_family; /* = AF_MCTP */
61 uint16_t __smctp_pad0;
62 int smctp_network; /* local network identifier */
63 struct mctp_addr smctp_addr; /* EID */
64 uint8_t smctp_type; /* message type byte */
65 uint8_t smctp_tag; /* tag value & owner */
66 uint8_t __smctp_pad1;
67 };
68 .EE
69 .in
70 .SS Sending messages
71 Messages can be transmitted using the
72 .BR sendto (2)
73 and
74 .BR sendmsg (2)
75 system calls,
76 by providing a
77 .I sockaddr_mctp
78 structure
79 describing the addressing parameters.
80 .P
81 .in +4n
82 .EX
83 ssize_t n;
84 const char *buf;
85 struct sockaddr_mctp addr;
86 \&
87 /* unused fields must be zero */
88 memset(&addr, 0, sizeof(addr));
89 \&
90 /* set message destination */
91 addr.smctp_family = AF_MCTP;
92 addr.smctp_network = 0;
93 addr.smctp_addr.s_addr = 8; /* remote EID */
94 addr.smctp_tag = MCTP_TAG_OWNER;
95 addr.smctp_type = MYPROGRAM_MCTP_TYPE_ECHO; /* example type */
96 \&
97 buf = "hello, world!"
98 \&
99 n = sendto(sd, buf, 13, 0,
100 (struct sockaddr *) &addr, sizeof(addr));
101 .EE
102 .in
103 .P
104 Here, the sender owns the message tag;
105 so
106 .B MCTP_TAG_OWNER
107 is used as the tag data.
108 The kernel will allocate a specific tag value for this message.
109 If no tag is available,
110 .BR sendto (2)
111 will return an error,
112 with errno set to
113 .BR EBUSY .
114 This allocated tag remains associated with the socket,
115 so that any replies to the sent message will be received by the same socket.
116 .P
117 Sending a MCTP message requires the
118 .B CAP_NET_RAW
119 capability.
120 .SS Receiving messages
121 Messages can be received using the
122 .BR recvfrom (2)
123 and
124 .BR recvmsg (2)
125 system calls.
126 .P
127 .in +4n
128 .EX
129 char buf[13];
130 socklen_t addrlen;
131 struct sockaddr_mctp addr;
132 \&
133 addrlen = sizeof(addr);
134 \&
135 n = recvfrom(sd, buf, sizeof(buf), 0,
136 (struct sockaddr *) &addr, &addrlen);
137 .EE
138 .in
139 .P
140 In order to receive an incoming message,
141 the receiver will need to
142 either have previously sent a message to the same endpoint,
143 or performed a
144 .BR bind (2)
145 to receive all messages of a certain type:
146 .P
147 .in +4n
148 .EX
149 struct sockaddr_mctp addr;
150 \&
151 addr.smctp_family = AF_MCTP;
152 addr.smctp_network = MCTP_NET_ANY;
153 addr.smctp_addr.s_addr = MCTP_ADDR_ANY;
154 addr.smctp_type = MYPROGRAM_MCTP_TYPE_ECHO; /* our 'echo' type */
155 \&
156 int rc = bind(sd, (struct sockaddr *) &addr, sizeof(addr));
157 .EE
158 .in
159 .P
160 This call requires the
161 .B CAP_NET_BIND_SERVICE
162 capability,
163 and will result in
164 the socket receiving all messages sent to locally-assigned EIDs,
165 for the specified message type.
166 .P
167 After a
168 .BR recvfrom (2)
169 or
170 .BR recvmsg (2)
171 returns a success condition,
172 the provided address argument
173 will be populated with the sender's network and EID,
174 as well as the tag value used for the message.
175 Any reply to this message should pass the same address and tag value
176 (with the TO bit cleared)
177 to indicate that is is directed to the same remote endpoint.
178 .SH SEE ALSO
179 .BR socket (7)
180 .P
181 .I linux.git/Documentation/networking/mctp.rst
182 .P
183 .UR https:\://www.dmtf.org/\:standards/\:pmci
184 The DSP0236 specification
185 .UE .