291 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=============================4Kernel Connection Multiplexor5=============================6 7Kernel Connection Multiplexor (KCM) is a mechanism that provides a message based8interface over TCP for generic application protocols. With KCM an application9can efficiently send and receive application protocol messages over TCP using10datagram sockets.11 12KCM implements an NxM multiplexor in the kernel as diagrammed below::13 14 +------------+ +------------+ +------------+ +------------+15 | KCM socket | | KCM socket | | KCM socket | | KCM socket |16 +------------+ +------------+ +------------+ +------------+17 | | | |18 +-----------+ | | +----------+19 | | | |20 +----------------------------------+21 | Multiplexor |22 +----------------------------------+23 | | | | |24 +---------+ | | | ------------+25 | | | | |26 +----------+ +----------+ +----------+ +----------+ +----------+27 | Psock | | Psock | | Psock | | Psock | | Psock |28 +----------+ +----------+ +----------+ +----------+ +----------+29 | | | | |30 +----------+ +----------+ +----------+ +----------+ +----------+31 | TCP sock | | TCP sock | | TCP sock | | TCP sock | | TCP sock |32 +----------+ +----------+ +----------+ +----------+ +----------+33 34KCM sockets35===========36 37The KCM sockets provide the user interface to the multiplexor. All the KCM sockets38bound to a multiplexor are considered to have equivalent function, and I/O39operations in different sockets may be done in parallel without the need for40synchronization between threads in userspace.41 42Multiplexor43===========44 45The multiplexor provides the message steering. In the transmit path, messages46written on a KCM socket are sent atomically on an appropriate TCP socket.47Similarly, in the receive path, messages are constructed on each TCP socket48(Psock) and complete messages are steered to a KCM socket.49 50TCP sockets & Psocks51====================52 53TCP sockets may be bound to a KCM multiplexor. A Psock structure is allocated54for each bound TCP socket, this structure holds the state for constructing55messages on receive as well as other connection specific information for KCM.56 57Connected mode semantics58========================59 60Each multiplexor assumes that all attached TCP connections are to the same61destination and can use the different connections for load balancing when62transmitting. The normal send and recv calls (include sendmmsg and recvmmsg)63can be used to send and receive messages from the KCM socket.64 65Socket types66============67 68KCM supports SOCK_DGRAM and SOCK_SEQPACKET socket types.69 70Message delineation71-------------------72 73Messages are sent over a TCP stream with some application protocol message74format that typically includes a header which frames the messages. The length75of a received message can be deduced from the application protocol header76(often just a simple length field).77 78A TCP stream must be parsed to determine message boundaries. Berkeley Packet79Filter (BPF) is used for this. When attaching a TCP socket to a multiplexor a80BPF program must be specified. The program is called at the start of receiving81a new message and is given an skbuff that contains the bytes received so far.82It parses the message header and returns the length of the message. Given this83information, KCM will construct the message of the stated length and deliver it84to a KCM socket.85 86TCP socket management87---------------------88 89When a TCP socket is attached to a KCM multiplexor data ready (POLLIN) and90write space available (POLLOUT) events are handled by the multiplexor. If there91is a state change (disconnection) or other error on a TCP socket, an error is92posted on the TCP socket so that a POLLERR event happens and KCM discontinues93using the socket. When the application gets the error notification for a94TCP socket, it should unattach the socket from KCM and then handle the error95condition (the typical response is to close the socket and create a new96connection if necessary).97 98KCM limits the maximum receive message size to be the size of the receive99socket buffer on the attached TCP socket (the socket buffer size can be set by100SO_RCVBUF). If the length of a new message reported by the BPF program is101greater than this limit a corresponding error (EMSGSIZE) is posted on the TCP102socket. The BPF program may also enforce a maximum messages size and report an103error when it is exceeded.104 105A timeout may be set for assembling messages on a receive socket. The timeout106value is taken from the receive timeout of the attached TCP socket (this is set107by SO_RCVTIMEO). If the timer expires before assembly is complete an error108(ETIMEDOUT) is posted on the socket.109 110User interface111==============112 113Creating a multiplexor114----------------------115 116A new multiplexor and initial KCM socket is created by a socket call::117 118 socket(AF_KCM, type, protocol)119 120- type is either SOCK_DGRAM or SOCK_SEQPACKET121- protocol is KCMPROTO_CONNECTED122 123Cloning KCM sockets124-------------------125 126After the first KCM socket is created using the socket call as described127above, additional sockets for the multiplexor can be created by cloning128a KCM socket. This is accomplished by an ioctl on a KCM socket::129 130 /* From linux/kcm.h */131 struct kcm_clone {132 int fd;133 };134 135 struct kcm_clone info;136 137 memset(&info, 0, sizeof(info));138 139 err = ioctl(kcmfd, SIOCKCMCLONE, &info);140 141 if (!err)142 newkcmfd = info.fd;143 144Attach transport sockets145------------------------146 147Attaching of transport sockets to a multiplexor is performed by calling an148ioctl on a KCM socket for the multiplexor. e.g.::149 150 /* From linux/kcm.h */151 struct kcm_attach {152 int fd;153 int bpf_fd;154 };155 156 struct kcm_attach info;157 158 memset(&info, 0, sizeof(info));159 160 info.fd = tcpfd;161 info.bpf_fd = bpf_prog_fd;162 163 ioctl(kcmfd, SIOCKCMATTACH, &info);164 165The kcm_attach structure contains:166 167 - fd: file descriptor for TCP socket being attached168 - bpf_prog_fd: file descriptor for compiled BPF program downloaded169 170Unattach transport sockets171--------------------------172 173Unattaching a transport socket from a multiplexor is straightforward. An174"unattach" ioctl is done with the kcm_unattach structure as the argument::175 176 /* From linux/kcm.h */177 struct kcm_unattach {178 int fd;179 };180 181 struct kcm_unattach info;182 183 memset(&info, 0, sizeof(info));184 185 info.fd = cfd;186 187 ioctl(fd, SIOCKCMUNATTACH, &info);188 189Disabling receive on KCM socket190-------------------------------191 192A setsockopt is used to disable or enable receiving on a KCM socket.193When receive is disabled, any pending messages in the socket's194receive buffer are moved to other sockets. This feature is useful195if an application thread knows that it will be doing a lot of196work on a request and won't be able to service new messages for a197while. Example use::198 199 int val = 1;200 201 setsockopt(kcmfd, SOL_KCM, KCM_RECV_DISABLE, &val, sizeof(val))202 203BFP programs for message delineation204------------------------------------205 206BPF programs can be compiled using the BPF LLVM backend. For example,207the BPF program for parsing Thrift is::208 209 #include "bpf.h" /* for __sk_buff */210 #include "bpf_helpers.h" /* for load_word intrinsic */211 212 SEC("socket_kcm")213 int bpf_prog1(struct __sk_buff *skb)214 {215 return load_word(skb, 0) + 4;216 }217 218 char _license[] SEC("license") = "GPL";219 220Use in applications221===================222 223KCM accelerates application layer protocols. Specifically, it allows224applications to use a message based interface for sending and receiving225messages. The kernel provides necessary assurances that messages are sent226and received atomically. This relieves much of the burden applications have227in mapping a message based protocol onto the TCP stream. KCM also make228application layer messages a unit of work in the kernel for the purposes of229steering and scheduling, which in turn allows a simpler networking model in230multithreaded applications.231 232Configurations233--------------234 235In an Nx1 configuration, KCM logically provides multiple socket handles236to the same TCP connection. This allows parallelism between in I/O237operations on the TCP socket (for instance copyin and copyout of data is238parallelized). In an application, a KCM socket can be opened for each239processing thread and inserted into the epoll (similar to how SO_REUSEPORT240is used to allow multiple listener sockets on the same port).241 242In a MxN configuration, multiple connections are established to the243same destination. These are used for simple load balancing.244 245Message batching246----------------247 248The primary purpose of KCM is load balancing between KCM sockets and hence249threads in a nominal use case. Perfect load balancing, that is steering250each received message to a different KCM socket or steering each sent251message to a different TCP socket, can negatively impact performance252since this doesn't allow for affinities to be established. Balancing253based on groups, or batches of messages, can be beneficial for performance.254 255On transmit, there are three ways an application can batch (pipeline)256messages on a KCM socket.257 258 1) Send multiple messages in a single sendmmsg.259 2) Send a group of messages each with a sendmsg call, where all messages260 except the last have MSG_BATCH in the flags of sendmsg call.261 3) Create "super message" composed of multiple messages and send this262 with a single sendmsg.263 264On receive, the KCM module attempts to queue messages received on the265same KCM socket during each TCP ready callback. The targeted KCM socket266changes at each receive ready callback on the KCM socket. The application267does not need to configure this.268 269Error handling270--------------271 272An application should include a thread to monitor errors raised on273the TCP connection. Normally, this will be done by placing each274TCP socket attached to a KCM multiplexor in epoll set for POLLERR275event. If an error occurs on an attached TCP socket, KCM sets an EPIPE276on the socket thus waking up the application thread. When the application277sees the error (which may just be a disconnect) it should unattach the278socket from KCM and then close it. It is assumed that once an error is279posted on the TCP socket the data stream is unrecoverable (i.e. an error280may have occurred in the middle of receiving a message).281 282TCP connection monitoring283-------------------------284 285In KCM there is no means to correlate a message to the TCP socket that286was used to send or receive the message (except in the case there is287only one attached TCP socket). However, the application does retain288an open file descriptor to the socket so it will be able to get statistics289from the socket which can be used in detecting issues (such as high290retransmissions on the socket).291