docs: networking: convert strparser.txt to ReST

   secid

   seg6-sysctl

   skfp

   strparser

.. only::  subproject and html

.. SPDX-License-Identifier: GPL-2.0

=========================

Stream Parser (strparser)

=========================

Introduction

============

Functions

=========

     ::

	strp_init(struct strparser *strp, struct sock *sk,

		const struct strp_callbacks *cb)

     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.

     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)

    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

    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.

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

    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

    =========    ===========================================================

    >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

    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 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

    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

    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

    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

     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

======

Tom Herbert (tom@quantonium.net)