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 <mchehab+huawei@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Mauro Carvalho Chehab
David S. Miller
parent
fe3dfe418c
commit
060d9d3e12
|
|
@ -104,6 +104,7 @@ Contents:
|
|||
secid
|
||||
seg6-sysctl
|
||||
skfp
|
||||
strparser
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,8 @@
|
|||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
=========================
|
||||
Stream Parser (strparser)
|
||||
=========================
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
|
@ -34,8 +38,10 @@ that is called when a full message has been completed.
|
|||
Functions
|
||||
=========
|
||||
|
||||
strp_init(struct strparser *strp, struct sock *sk,
|
||||
const struct strp_callbacks *cb)
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -43,31 +49,41 @@ strp_init(struct strparser *strp, struct sock *sk,
|
|||
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)
|
||||
::
|
||||
|
||||
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)
|
||||
::
|
||||
|
||||
void strp_unpause(struct strparser *strp)
|
||||
|
||||
Unpause a paused stream parser.
|
||||
|
||||
void strp_stop(struct strparser *strp);
|
||||
::
|
||||
|
||||
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);
|
||||
::
|
||||
|
||||
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)
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -75,7 +91,9 @@ int strp_process(struct strparser *strp, struct sk_buff *orig_skb,
|
|||
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);
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -83,7 +101,9 @@ void strp_data_ready(struct strparser *strp);
|
|||
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);
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -94,7 +114,9 @@ Callbacks
|
|||
|
||||
There are six callbacks:
|
||||
|
||||
int (*parse_msg)(struct strparser *strp, struct sk_buff *skb);
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -107,14 +129,16 @@ int (*parse_msg)(struct strparser *strp, struct sk_buff *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)
|
||||
========= ===========================================================
|
||||
>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
|
||||
|
|
@ -123,7 +147,9 @@ int (*parse_msg)(struct strparser *strp, struct sk_buff *skb);
|
|||
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)
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -131,14 +157,18 @@ void (*lock)(struct strparser *strp)
|
|||
function is to lock_sock for the associated socket. In general
|
||||
mode the callback must be set appropriately.
|
||||
|
||||
void (*unlock)(struct strparser *strp)
|
||||
::
|
||||
|
||||
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);
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -152,7 +182,9 @@ void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb);
|
|||
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);
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -160,7 +192,9 @@ int (*read_sock_done)(struct strparser *strp, int err);
|
|||
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);
|
||||
::
|
||||
|
||||
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
|
||||
|
|
@ -204,4 +238,3 @@ Author
|
|||
======
|
||||
|
||||
Tom Herbert (tom@quantonium.net)
|
||||
|
||||
Loading…
Reference in New Issue