1Stream Parser 2------------- 3 4The stream parser (strparser) is a utility that parses messages of an 5application layer protocol running over a TCP connection. The stream 6parser works in conjunction with an upper layer in the kernel to provide 7kernel support for application layer messages. For instance, Kernel 8Connection Multiplexor (KCM) uses the Stream Parser to parse messages 9using a BPF program. 10 11Interface 12--------- 13 14The API includes a context structure, a set of callbacks, utility 15functions, and a data_ready function. The callbacks include 16a parse_msg function that is called to perform parsing (e.g. 17BPF parsing in case of KCM), and a rcv_msg function that is called 18when a full message has been completed. 19 20A stream parser can be instantiated for a TCP connection. This is done 21by: 22 23strp_init(struct strparser *strp, struct sock *csk, 24 struct strp_callbacks *cb) 25 26strp is a struct of type strparser that is allocated by the upper layer. 27csk is the TCP socket associated with the stream parser. Callbacks are 28called by the stream parser. 29 30Callbacks 31--------- 32 33There are four callbacks: 34 35int (*parse_msg)(struct strparser *strp, struct sk_buff *skb); 36 37 parse_msg is called to determine the length of the next message 38 in the stream. The upper layer must implement this function. It 39 should parse the sk_buff as containing the headers for the 40 next application layer messages in the stream. 41 42 The skb->cb in the input skb is a struct strp_rx_msg. Only 43 the offset field is relevant in parse_msg and gives the offset 44 where the message starts in the skb. 45 46 The return values of this function are: 47 48 >0 : indicates length of successfully parsed message 49 0 : indicates more data must be received to parse the message 50 -ESTRPIPE : current message should not be processed by the 51 kernel, return control of the socket to userspace which 52 can proceed to read the messages itself 53 other < 0 : Error is parsing, give control back to userspace 54 assuming that synchronization is lost and the stream 55 is unrecoverable (application expected to close TCP socket) 56 57 In the case that an error is returned (return value is less than 58 zero) the stream parser will set the error on TCP socket and wake 59 it up. If parse_msg returned -ESTRPIPE and the stream parser had 60 previously read some bytes for the current message, then the error 61 set on the attached socket is ENODATA since the stream is 62 unrecoverable in that case. 63 64void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb); 65 66 rcv_msg is called when a full message has been received and 67 is queued. The callee must consume the sk_buff; it can 68 call strp_pause to prevent any further messages from being 69 received in rcv_msg (see strp_pause below). This callback 70 must be set. 71 72 The skb->cb in the input skb is a struct strp_rx_msg. This 73 struct contains two fields: offset and full_len. Offset is 74 where the message starts in the skb, and full_len is the 75 the length of the message. skb->len - offset may be greater 76 then full_len since strparser does not trim the skb. 77 78int (*read_sock_done)(struct strparser *strp, int err); 79 80 read_sock_done is called when the stream parser is done reading 81 the TCP socket. The stream parser may read multiple messages 82 in a loop and this function allows cleanup to occur when existing 83 the loop. If the callback is not set (NULL in strp_init) a 84 default function is used. 85 86void (*abort_parser)(struct strparser *strp, int err); 87 88 This function is called when stream parser encounters an error 89 in parsing. The default function stops the stream parser for the 90 TCP socket and sets the error in the socket. The default function 91 can be changed by setting the callback to non-NULL in strp_init. 92 93Functions 94--------- 95 96The upper layer calls strp_tcp_data_ready when data is ready on the lower 97socket for strparser to process. This should be called from a data_ready 98callback that is set on the socket. 99 100strp_stop is called to completely stop stream parser operations. This 101is called internally when the stream parser encounters an error, and 102it is called from the upper layer when unattaching a TCP socket. 103 104strp_done is called to unattach the stream parser from the TCP socket. 105This must be called after the stream processor has be stopped. 106 107strp_check_rcv is called to check for new messages on the socket. This 108is normally called at initialization of the a stream parser instance 109of after strp_unpause. 110 111Statistics 112---------- 113 114Various counters are kept for each stream parser for a TCP socket. 115These are in the strp_stats structure. strp_aggr_stats is a convenience 116structure for accumulating statistics for multiple stream parser 117instances. save_strp_stats and aggregate_strp_stats are helper functions 118to save and aggregate statistics. 119 120Message assembly limits 121----------------------- 122 123The stream parser provide mechanisms to limit the resources consumed by 124message assembly. 125 126A timer is set when assembly starts for a new message. The message 127timeout is taken from rcvtime for the associated TCP socket. If the 128timer fires before assembly completes the stream parser is aborted 129and the ETIMEDOUT error is set on the TCP socket. 130 131Message length is limited to the receive buffer size of the associated 132TCP socket. If the length returned by parse_msg is greater than 133the socket buffer size then the stream parser is aborted with 134EMSGSIZE error set on the TCP socket. Note that this makes the 135maximum size of receive skbuffs for a socket with a stream parser 136to be 2*sk_rcvbuf of the TCP socket. 137