mirrors/linux
0
0 Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-10-26 10:57:38 +08:00
Code Activity

docs: networking: strparser: remove general mode

Browse Source 
Now that the general mode of strp has been removed from the code,
update the documentation.

Signed-off-by: Sabrina Dubroca <sd@queasysnail.net>
Link: https://patch.msgid.link/0a31a783d4c9c38594da338c49bf085fe6336c92.1790702233.git.sd@queasysnail.net
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Sabrina Dubroca authored and Jakub Kicinski committed 2026-10-05 16:02:02 -07:00
1 parent 02fd0a2111
commit 5f193cdabf
1 file changed
+36 -84
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/networking/strparser.rst
+36 -84
View File
@@ -8,32 +8,24 @@ Introduction
============
The stream parser (strparser) is a utility that parses messages of an
application layer protocol running over a data stream. The stream
application layer protocol running over a TCP connection. The stream
parser works in conjunction with an upper layer in the kernel to provide
kernel support for application layer messages. For instance, Kernel
Connection Multiplexor (KCM) uses the Stream Parser to parse messages
using a BPF program.
The strparser works in one of two modes: receive callback or general
mode.
In receive callback mode, the strparser is called from the data_ready
callback of a TCP socket. Messages are parsed and delivered as they are
received on the socket.
In general mode, a sequence of skbs are fed to strparser from an
outside source. Message are parsed and delivered as the sequence is
processed. This modes allows strparser to be applied to arbitrary
streams of data.
The strparser is called from the data_ready callback of a TCP
socket. Messages are parsed and delivered as they are received on the
socket.
Interface
=========
The API includes a context structure, a set of callbacks, utility
functions, and a data_ready function for receive callback mode. The
callbacks include a parse_msg function that is called to perform
parsing (e.g. BPF parsing in case of KCM), and a rcv_msg function
that is called when a full message has been completed.
functions, and a data_ready function. The callbacks include a
parse_msg function that is called to perform parsing (e.g. BPF parsing
in case of KCM), and a rcv_msg function that is called when a full
message has been completed.
Functions
=========
@@ -45,9 +37,8 @@ Functions
Called to initialize a stream parser. strp is a struct of type
strparser that is allocated by the upper layer. sk is the TCP
socket associated with the stream parser for use with receive
callback mode; in general mode this is set to NULL. Callbacks
are called by the stream parser (the callbacks are listed below).
socket associated with the stream parser. Callbacks are called by
the stream parser (the callbacks are listed below).
::
@@ -79,18 +70,6 @@ Functions
parser instance. This must be called after the stream processor
has been stopped.
::
int strp_process(struct strparser *strp, struct sk_buff *orig_skb,
unsigned int orig_offset, size_t orig_len,
size_t max_msg_size, long timeo)
strp_process is called in general mode for a stream parser to
parse an sk_buff. The number of bytes processed or a negative
error number is returned. Note that strp_process does not
consume the sk_buff. max_msg_size is maximum size the stream
parser will parse. timeo is timeout for completing a message.
::
void strp_data_ready(struct strparser *strp);
@@ -112,16 +91,15 @@ Functions
Callbacks
=========
There are seven callbacks:
There are four callbacks:
::
int (*parse_msg)(struct strparser *strp, struct sk_buff *skb);
parse_msg is called to determine the length of the next message
in the stream. The upper layer must implement this function. It
should parse the sk_buff as containing the headers for the
next application layer message in the stream.
parse_msg is called to determine the length of the next message in
the stream. It should parse the sk_buff as containing the headers
for the next application layer message in the stream.
The strparser metadata in the input skb can be accessed with
strp_msg(skb). Only the offset field is relevant in parse_msg and
@@ -141,30 +119,13 @@ There are seven callbacks:
========= ===========================================================
In the case that an error is returned (return value is less than
zero) and the parser is in receive callback mode, then it will set
the error on TCP socket and wake it up. If parse_msg returned
-ESTRPIPE and the stream parser had previously read some bytes for
the current message, then the error set on the attached socket is
ENODATA since the stream is unrecoverable in that case.
zero), it will set the error on TCP socket and wake it up. If
parse_msg returned -ESTRPIPE and the stream parser had previously
read some bytes for the current message, then the error set on the
attached socket is ENODATA since the stream is unrecoverable in
that case.
::
void (*lock)(struct strparser *strp)
The lock callback is called to lock the strp structure when
the strparser is performing an asynchronous operation (such as
processing a timeout). In receive callback mode the default
function is to lock_sock for the associated socket. In general
mode the callback must be set appropriately.
::
void (*unlock)(struct strparser *strp)
The unlock callback is called to release the lock obtained
by the lock callback. In receive callback mode the default
function is release_sock for the associated socket. In general
mode the callback must be set appropriately.
This callback must be set.
::
@@ -173,8 +134,7 @@ There are seven callbacks:
rcv_msg is called when a full message has been received and
is queued. The callee must consume the sk_buff; it can
call strp_pause to prevent any further messages from being
received in rcv_msg (see strp_pause above). This callback
must be set.
received in rcv_msg (see strp_pause above).
The strparser metadata in the input skb can be accessed with
strp_msg(skb). This struct contains two fields: offset and full_len.
@@ -182,6 +142,8 @@ There are seven callbacks:
the length of the message. skb->len - offset may be greater than
full_len since strparser does not trim the skb.
This callback must be set.
::
int (*read_sock)(struct strparser *strp, read_descriptor_t *desc,
@@ -189,25 +151,20 @@ There are seven callbacks:
The read_sock callback is used by strparser instead of
sock->ops->read_sock, if provided.
This callback is optional.
::
int (*read_sock_done)(struct strparser *strp, int err);
read_sock_done is called when the stream parser is done reading
the TCP socket in receive callback mode. The stream parser may
read multiple messages in a loop and this function allows cleanup
to occur when exiting the loop. If the callback is not set (NULL
in strp_init) a default function is used.
the TCP socket. The stream parser may read multiple messages in a
loop and this function allows cleanup to occur when exiting the
loop. If the callback is not set (NULL in strp_init) a default
function is used.
::
void (*abort_parser)(struct strparser *strp, int err);
This function is called when stream parser encounters an error
in parsing. The default function stops the stream parser and
sets the error in the socket if the parser is in receive callback
mode. The default function can be changed by setting the callback
to non-NULL in strp_init.
This callback is optional.
Statistics
==========
@@ -224,23 +181,18 @@ Message assembly limits
The stream parser provide mechanisms to limit the resources consumed by
message assembly.
A timer is set when assembly starts for a new message. In receive
callback mode the message timeout is taken from rcvtime for the
associated TCP socket. In general mode, the timeout is passed as an
argument in strp_process. If the timer fires before assembly completes
the stream parser is aborted and the ETIMEDOUT error is set on the TCP
socket if in receive callback mode.
A timer is set when assembly starts for a new message. The message
timeout is taken from rcvtime for the associated TCP socket. If the
timer fires before assembly completes the stream parser is aborted and
the ETIMEDOUT error is set on the TCP socket.
In receive callback mode, message length is limited to the receive
Message length is limited to the receive
buffer size of the associated TCP socket. If the length returned by
parse_msg is greater than the socket buffer size then the stream parser
is aborted with EMSGSIZE error set on the TCP socket. Note that this
makes the maximum size of receive skbuffs for a socket with a stream
parser to be 2*sk_rcvbuf of the TCP socket.
In general mode the message length limit is passed in as an argument
to strp_process.
Author
======