From 060d9d3e1282e3ccf4bbb3cc4ea94bed3ce69310 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 30 Apr 2020 18:04:26 +0200 Subject: docs: networking: convert strparser.txt to ReST - add SPDX header; - adjust title markup; - mark code blocks and literals as such; - mark tables as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/strparser.rst | 240 +++++++++++++++++++++++++++++++++ Documentation/networking/strparser.txt | 207 ---------------------------- 3 files changed, 241 insertions(+), 207 deletions(-) create mode 100644 Documentation/networking/strparser.rst delete mode 100644 Documentation/networking/strparser.txt (limited to 'Documentation/networking') diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index d19ddcbe66e5..e5a705024c6a 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -104,6 +104,7 @@ Contents: secid seg6-sysctl skfp + strparser .. only:: subproject and html diff --git a/Documentation/networking/strparser.rst b/Documentation/networking/strparser.rst new file mode 100644 index 000000000000..6cab1f74ae05 --- /dev/null +++ b/Documentation/networking/strparser.rst @@ -0,0 +1,240 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Stream Parser (strparser) +========================= + +Introduction +============ + +The stream parser (strparser) is a utility that parses messages of an +application layer protocol running over a data stream. 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. + +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 +========= + + :: + + strp_init(struct strparser *strp, struct sock *sk, + const struct strp_callbacks *cb) + + 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). + + :: + + void strp_pause(struct strparser *strp) + + Temporarily pause a stream parser. Message parsing is suspended + and no new messages are delivered to the upper layer. + + :: + + void strp_unpause(struct strparser *strp) + + Unpause a paused stream parser. + + :: + + void strp_stop(struct strparser *strp); + + strp_stop is called to completely stop stream parser operations. + This is called internally when the stream parser encounters an + error, and it is called from the upper layer to stop parsing + operations. + + :: + + void strp_done(struct strparser *strp); + + strp_done is called to release any resources held by the stream + 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); + + The upper layer calls strp_tcp_data_ready when data is ready on + the lower socket for strparser to process. This should be called + from a data_ready callback that is set on the socket. Note that + maximum messages size is the limit of the receive socket + buffer and message timeout is the receive timeout for the socket. + + :: + + void strp_check_rcv(struct strparser *strp); + + strp_check_rcv is called to check for new messages on the socket. + This is normally called at initialization of a stream parser + instance or after strp_unpause. + +Callbacks +========= + +There are six 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. + + The skb->cb in the input skb is a struct strp_msg. Only + the offset field is relevant in parse_msg and gives the offset + where the message starts in the skb. + + The return values of this function are: + + ========= =========================================================== + >0 indicates length of successfully parsed message + 0 indicates more data must be received to parse the message + -ESTRPIPE current message should not be processed by the + kernel, return control of the socket to userspace which + can proceed to read the messages itself + other < 0 Error in parsing, give control back to userspace + assuming that synchronization is lost and the stream + is unrecoverable (application expected to close TCP socket) + ========= =========================================================== + + 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. + + :: + + 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. + + :: + + void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb); + + 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. + + The skb->cb in the input skb is a struct strp_msg. This + struct contains two fields: offset and full_len. Offset is + where the message starts in the skb, and full_len is the + the length of the message. skb->len - offset may be greater + then full_len since strparser does not trim the skb. + + :: + + 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. + + :: + + 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. + +Statistics +========== + +Various counters are kept for each stream parser instance. These are in +the strp_stats structure. strp_aggr_stats is a convenience structure for +accumulating statistics for multiple stream parser instances. +save_strp_stats and aggregate_strp_stats are helper functions to save +and aggregate statistics. + +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. + +In receive callback mode, 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 +====== + +Tom Herbert (tom@quantonium.net) diff --git a/Documentation/networking/strparser.txt b/Documentation/networking/strparser.txt deleted file mode 100644 index a7d354ddda7b..000000000000 --- a/Documentation/networking/strparser.txt +++ /dev/null @@ -1,207 +0,0 @@ -Stream Parser (strparser) - -Introduction -============ - -The stream parser (strparser) is a utility that parses messages of an -application layer protocol running over a data stream. 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. - -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 -========= - -strp_init(struct strparser *strp, struct sock *sk, - const struct strp_callbacks *cb) - - 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). - -void strp_pause(struct strparser *strp) - - Temporarily pause a stream parser. Message parsing is suspended - and no new messages are delivered to the upper layer. - -void strp_unpause(struct strparser *strp) - - Unpause a paused stream parser. - -void strp_stop(struct strparser *strp); - - strp_stop is called to completely stop stream parser operations. - This is called internally when the stream parser encounters an - error, and it is called from the upper layer to stop parsing - operations. - -void strp_done(struct strparser *strp); - - strp_done is called to release any resources held by the stream - 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); - - The upper layer calls strp_tcp_data_ready when data is ready on - the lower socket for strparser to process. This should be called - from a data_ready callback that is set on the socket. Note that - maximum messages size is the limit of the receive socket - buffer and message timeout is the receive timeout for the socket. - -void strp_check_rcv(struct strparser *strp); - - strp_check_rcv is called to check for new messages on the socket. - This is normally called at initialization of a stream parser - instance or after strp_unpause. - -Callbacks -========= - -There are six 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. - - The skb->cb in the input skb is a struct strp_msg. Only - the offset field is relevant in parse_msg and gives the offset - where the message starts in the skb. - - The return values of this function are: - - >0 : indicates length of successfully parsed message - 0 : indicates more data must be received to parse the message - -ESTRPIPE : current message should not be processed by the - kernel, return control of the socket to userspace which - can proceed to read the messages itself - other < 0 : Error in parsing, give control back to userspace - assuming that synchronization is lost and the stream - is unrecoverable (application expected to close TCP socket) - - 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. - -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. - -void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb); - - 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. - - The skb->cb in the input skb is a struct strp_msg. This - struct contains two fields: offset and full_len. Offset is - where the message starts in the skb, and full_len is the - the length of the message. skb->len - offset may be greater - then full_len since strparser does not trim the skb. - -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. - -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. - -Statistics -========== - -Various counters are kept for each stream parser instance. These are in -the strp_stats structure. strp_aggr_stats is a convenience structure for -accumulating statistics for multiple stream parser instances. -save_strp_stats and aggregate_strp_stats are helper functions to save -and aggregate statistics. - -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. - -In receive callback mode, 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 -====== - -Tom Herbert (tom@quantonium.net) - -- cgit v1.2.3