Skip to content
  • Tom Herbert's avatar
    strparser: Stream parser for messages · 43a0c675
    Tom Herbert authored
    
    
    This patch introduces a utility for parsing application layer protocol
    messages in a TCP stream. This is a generalization of the mechanism
    implemented of Kernel Connection Multiplexor.
    
    The API includes a context structure, a set of callbacks, utility
    functions, and a data ready function.
    
    A stream parser instance is defined by a strparse structure that
    is bound to a TCP socket. The function to initialize the structure
    is:
    
    int strp_init(struct strparser *strp, struct sock *csk,
                  struct strp_callbacks *cb);
    
    csk is the TCP socket being bound to and cb are the parser callbacks.
    
    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:
    
    void strp_tcp_data_ready(struct strparser *strp);
    
    A parser is bound to a TCP socket by setting data_ready function to
    strp_tcp_data_ready so that all receive indications on the socket
    go through the parser. This is assumes that sk_user_data is set to
    the strparser structure.
    
    There are four callbacks.
     - parse_msg is called to parse the message (returns length or error).
     - rcv_msg is called when a complete message has been received
     - read_sock_done is called when data_ready function exits
     - abort_parser is called to abort the parser
    
    The input to parse_msg is an skbuff which contains next message under
    construction. The backend processing of parse_msg will parse the
    application layer protocol headers to determine the length of
    the message in the stream. The possible return values 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 is parsing, give control back to userspace
          assuming that synchronzation is lost and the stream
          is unrecoverable (application expected to close TCP socket)
    
    In the case of error return (< 0) strparse will stop the parser
    and report and error to userspace. The application must deal
    with the error. To handle the error the strparser is unbound
    from the TCP socket. If the error indicates that the stream
    TCP socket is at recoverable point (ESTRPIPE) then the application
    can read the TCP socket to process the stream. Once the application
    has dealt with the exceptions in the stream, it may again bind the
    socket to a strparser to continue data operations.
    
    Note that ENODATA may be returned to the application. In this case
    parse_msg returned -ESTRPIPE, however strparser was unable to maintain
    synchronization of the stream (i.e. some of the message in question
    was already read by the parser).
    
    strp_pause and strp_unpause are used to provide flow control. For
    instance, if rcv_msg is called but the upper layer can't immediately
    consume the message it can hold the message and pause strparser.
    
    Signed-off-by: default avatarTom Herbert <tom@herbertland.com>
    Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
    43a0c675