Documentation/networking/strparser.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 Stream Parser (strparser)
10 The stream parser (strparser) is a utility that parses messages of an
11 application layer protocol running over a data stream. The stream
13 kernel support for application layer messages. For instance, Kernel
14 Connection Multiplexor (KCM) uses the Stream Parser to parse messages
18 mode.
20 In receive callback mode, the strparser is called from the data_ready
24 In general mode, a sequence of skbs are fed to strparser from an
33 functions, and a data_ready function for receive callback mode. The
46      Called to initialize a stream parser. strp is a struct of type
48      socket associated with the stream parser for use with receive
49      callback mode; in general mode this is set to NULL. Callbacks
50      are called by the stream parser (the callbacks are listed below).
56      Temporarily pause a stream parser. Message parsing is suspended
63      Unpause a paused stream parser.
69      strp_stop is called to completely stop stream parser operations.
70      This is called internally when the stream parser encounters an
78      strp_done is called to release any resources held by the stream
79      parser instance. This must be called after the stream processor
88     strp_process is called in general mode for a stream parser to
91     consume the sk_buff. max_msg_size is maximum size the stream
109     This is normally called at initialization of a stream parser
122     in the stream. The upper layer must implement this function. It
124     next application layer message in the stream.
126     The skb->cb in the input skb is a struct strp_msg. Only
135     -ESTRPIPE    current message should not be processed by the
139 		 assuming that synchronization is lost and the stream
144     zero) and the parser is in receive callback mode, then it will set
146     -ESTRPIPE and the stream parser had previously read some bytes for
148     ENODATA since the stream is unrecoverable in that case.
156     processing a timeout). In receive callback mode the default
158     mode the callback must be set appropriately.
165     by the lock callback. In receive callback mode the default
167     mode the callback must be set appropriately.
179     The skb->cb in the input skb is a struct strp_msg. This
182     the length of the message. skb->len - offset may be greater
189      read_sock_done is called when the stream parser is done reading
190      the TCP socket in receive callback mode. The stream parser may
199      This function is called when stream parser encounters an error
200      in parsing. The default function stops the stream parser and
202      mode. The default function can be changed by setting the callback
203      to non-NULL in strp_init.
208 Various counters are kept for each stream parser instance. These are in
210 accumulating statistics for multiple stream parser instances.
217 The stream parser provide mechanisms to limit the resources consumed by
221 callback mode the message timeout is taken from rcvtime for the
222 associated TCP socket. In general mode, the timeout is passed as an
224 the stream parser is aborted and the ETIMEDOUT error is set on the TCP
225 socket if in receive callback mode.
227 In receive callback mode, message length is limited to the receive
229 parse_msg is greater than the socket buffer size then the stream parser
231 makes the maximum size of receive skbuffs for a socket with a stream
234 In general mode the message length limit is passed in as an argument