Documentation/networking/mctp.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==============================================
   4 Management Component Transport Protocol (MCTP)
   5 ==============================================
   6
   7 net/mctp/ contains protocol support for MCTP, as defined by DMTF standard
   8 DSP0236. Physical interface drivers ("bindings" in the specification) are
   9 provided in drivers/net/mctp/.
  10
  11 The core code provides a socket-based interface to send and receive MCTP
  12 messages, through an AF_MCTP, SOCK_DGRAM socket.
  13
  14 Structure: interfaces & networks
  15 ================================
  16
  17 The kernel models the local MCTP topology through two items: interfaces and
  18 networks.
  19
  20 An interface (or "link") is an instance of an MCTP physical transport binding
  21 (as defined by DSP0236, section 3.2.47), likely connected to a specific hardware
  22 device. This is represented as a ``struct netdevice``.
  23
  24 A network defines a unique address space for MCTP endpoints by endpoint-ID
  25 (described by DSP0236, section 3.2.31). A network has a user-visible identifier
  26 to allow references from userspace. Route definitions are specific to one
  27 network.
  28
  29 Interfaces are associated with one network. A network may be associated with one
  30 or more interfaces.
  31
  32 If multiple networks are present, each may contain endpoint IDs (EIDs) that are
  33 also present on other networks.
  34
  35 Sockets API
  36 ===========
  37
  38 Protocol definitions
  39 --------------------
  40
  41 MCTP uses ``AF_MCTP`` / ``PF_MCTP`` for the address- and protocol- families.
  42 Since MCTP is message-based, only ``SOCK_DGRAM`` sockets are supported.
  43
  44 .. code-block:: C
  45
  46     int sd = socket(AF_MCTP, SOCK_DGRAM, 0);
  47
  48 The only (current) value for the ``protocol`` argument is 0.
  49
  50 As with all socket address families, source and destination addresses are
  51 specified with a ``sockaddr`` type, with a single-byte endpoint address:
  52
  53 .. code-block:: C
  54
  55     typedef __u8                mctp_eid_t;
  56
  57     struct mctp_addr {
  58             mctp_eid_t          s_addr;
  59     };
  60
  61     struct sockaddr_mctp {
  62             unsigned short int  smctp_family;
  63             int                 smctp_network;
  64             struct mctp_addr    smctp_addr;
  65             __u8                smctp_type;
  66             __u8                smctp_tag;
  67     };
  68
  69     #define MCTP_NET_ANY        0x0
  70     #define MCTP_ADDR_ANY       0xff
  71
  72
  73 Syscall behaviour
  74 -----------------
  75
  76 The following sections describe the MCTP-specific behaviours of the standard
  77 socket system calls. These behaviours have been chosen to map closely to the
  78 existing sockets APIs.
  79
  80 ``bind()`` : set local socket address
  81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  82
  83 Sockets that receive incoming request packets will bind to a local address,
  84 using the ``bind()`` syscall.
  85
  86 .. code-block:: C
  87
  88     struct sockaddr_mctp addr;
  89
  90     addr.smctp_family = AF_MCTP;
  91     addr.smctp_network = MCTP_NET_ANY;
  92     addr.smctp_addr.s_addr = MCTP_ADDR_ANY;
  93     addr.smctp_type = MCTP_TYPE_PLDM;
  94     addr.smctp_tag = MCTP_TAG_OWNER;
  95
  96     int rc = bind(sd, (struct sockaddr *)&addr, sizeof(addr));
  97
  98 This establishes the local address of the socket. Incoming MCTP messages that
  99 match the network, address, and message type will be received by this socket.
 100 The reference to 'incoming' is important here; a bound socket will only receive
 101 messages with the TO bit set, to indicate an incoming request message, rather
 102 than a response.
 103
 104 The ``smctp_tag`` value will configure the tags accepted from the remote side of
 105 this socket. Given the above, the only valid value is ``MCTP_TAG_OWNER``, which
 106 will result in remotely "owned" tags being routed to this socket. Since
 107 ``MCTP_TAG_OWNER`` is set, the 3 least-significant bits of ``smctp_tag`` are not
 108 used; callers must set them to zero.
 109
 110 A ``smctp_network`` value of ``MCTP_NET_ANY`` will configure the socket to
 111 receive incoming packets from any locally-connected network. A specific network
 112 value will cause the socket to only receive incoming messages from that network.
 113
 114 The ``smctp_addr`` field specifies a local address to bind to. A value of
 115 ``MCTP_ADDR_ANY`` configures the socket to receive messages addressed to any
 116 local destination EID.
 117
 118 The ``smctp_type`` field specifies which message types to receive. Only the
 119 lower 7 bits of the type is matched on incoming messages (ie., the
 120 most-significant IC bit is not part of the match). This results in the socket
 121 receiving packets with and without a message integrity check footer.
 122
 123 ``sendto()``, ``sendmsg()``, ``send()`` : transmit an MCTP message
 124 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 125
 126 An MCTP message is transmitted using one of the ``sendto()``, ``sendmsg()`` or
 127 ``send()`` syscalls. Using ``sendto()`` as the primary example:
 128
 129 .. code-block:: C
 130
 131     struct sockaddr_mctp addr;
 132     char buf[14];
 133     ssize_t len;
 134
 135     /* set message destination */
 136     addr.smctp_family = AF_MCTP;
 137     addr.smctp_network = 0;
 138     addr.smctp_addr.s_addr = 8;
 139     addr.smctp_tag = MCTP_TAG_OWNER;
 140     addr.smctp_type = MCTP_TYPE_ECHO;
 141
 142     /* arbitrary message to send, with message-type header */
 143     buf[0] = MCTP_TYPE_ECHO;
 144     memcpy(buf + 1, "hello, world!", sizeof(buf) - 1);
 145
 146     len = sendto(sd, buf, sizeof(buf), 0,
 147                     (struct sockaddr_mctp *)&addr, sizeof(addr));
 148
 149 The network and address fields of ``addr`` define the remote address to send to.
 150 If ``smctp_tag`` has the ``MCTP_TAG_OWNER``, the kernel will ignore any bits set
 151 in ``MCTP_TAG_VALUE``, and generate a tag value suitable for the destination
 152 EID. If ``MCTP_TAG_OWNER`` is not set, the message will be sent with the tag
 153 value as specified. If a tag value cannot be allocated, the system call will
 154 report an errno of ``EAGAIN``.
 155
 156 The application must provide the message type byte as the first byte of the
 157 message buffer passed to ``sendto()``. If a message integrity check is to be
 158 included in the transmitted message, it must also be provided in the message
 159 buffer, and the most-significant bit of the message type byte must be 1.
 160
 161 The ``sendmsg()`` system call allows a more compact argument interface, and the
 162 message buffer to be specified as a scatter-gather list. At present no ancillary
 163 message types (used for the ``msg_control`` data passed to ``sendmsg()``) are
 164 defined.
 165
 166 Transmitting a message on an unconnected socket with ``MCTP_TAG_OWNER``
 167 specified will cause an allocation of a tag, if no valid tag is already
 168 allocated for that destination. The (destination-eid,tag) tuple acts as an
 169 implicit local socket address, to allow the socket to receive responses to this
 170 outgoing message. If any previous allocation has been performed (to for a
 171 different remote EID), that allocation is lost.
 172
 173 Sockets will only receive responses to requests they have sent (with TO=1) and
 174 may only respond (with TO=0) to requests they have received.
 175
 176 ``recvfrom()``, ``recvmsg()``, ``recv()`` : receive an MCTP message
 177 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 178
 179 An MCTP message can be received by an application using one of the
 180 ``recvfrom()``, ``recvmsg()``, or ``recv()`` system calls. Using ``recvfrom()``
 181 as the primary example:
 182
 183 .. code-block:: C
 184
 185     struct sockaddr_mctp addr;
 186     socklen_t addrlen;
 187     char buf[14];
 188     ssize_t len;
 189
 190     addrlen = sizeof(addr);
 191
 192     len = recvfrom(sd, buf, sizeof(buf), 0,
 193                     (struct sockaddr_mctp *)&addr, &addrlen);
 194
 195     /* We can expect addr to describe an MCTP address */
 196     assert(addrlen >= sizeof(buf));
 197     assert(addr.smctp_family == AF_MCTP);
 198
 199     printf("received %zd bytes from remote EID %d\n", rc, addr.smctp_addr);
 200
 201 The address argument to ``recvfrom`` and ``recvmsg`` is populated with the
 202 remote address of the incoming message, including tag value (this will be needed
 203 in order to reply to the message).
 204
 205 The first byte of the message buffer will contain the message type byte. If an
 206 integrity check follows the message, it will be included in the received buffer.
 207
 208 The ``recv()`` system call behaves in a similar way, but does not provide a
 209 remote address to the application. Therefore, these are only useful if the
 210 remote address is already known, or the message does not require a reply.
 211
 212 Like the send calls, sockets will only receive responses to requests they have
 213 sent (TO=1) and may only respond (TO=0) to requests they have received.