From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 996C2FA3742 for ; Wed, 26 Oct 2022 07:51:31 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233101AbiJZHv2 (ORCPT ); Wed, 26 Oct 2022 03:51:28 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39998 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232931AbiJZHvX (ORCPT ); Wed, 26 Oct 2022 03:51:23 -0400 Received: from mail-pj1-x102f.google.com (mail-pj1-x102f.google.com [IPv6:2607:f8b0:4864:20::102f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5AF83900F9 for ; Wed, 26 Oct 2022 00:51:17 -0700 (PDT) Received: by mail-pj1-x102f.google.com with SMTP id m6-20020a17090a5a4600b00212f8dffec9so1455571pji.0 for ; Wed, 26 Oct 2022 00:51:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sipanda-io.20210112.gappssmtp.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=Huud0eKt78gVwpD9WtoxgjZuklRbGsl/PXu3/W9jWhQ=; b=DitWF3M64pK51kRetnMZCLvNLu7hnNJQX753KmD3ataCeRolncIVx/v7xIAMA/1K9j zYQmmZS84fj/pxg8nhWq7RQG6Eeo41SDomW3XY2m4vMbLc3Ul1tgF/fqn1Tgh1LBc0o/ 1bLTqrTCPcI3e/UM6byULmvDYxEz9gyTljVg9ZVOdzjmbf0xkbhclkwjX5whZh9C2f5e yZWqmquphblYVepuKglpNN1yD6o6IHGihsnE5vaEhZqZUaUG916JLR/SLMgNJqBtridp /tbsamr1fatI6J55CdK1X5SIsQXHJq6M1Sm6p+WQgCsdUGhe/6rVT1UGbOD/YDufoCl4 cpEg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Huud0eKt78gVwpD9WtoxgjZuklRbGsl/PXu3/W9jWhQ=; b=ixpnKn6Z/Yh7JdhsquhlTQZqSkBaMILRj3yHtaeA4nBl6lslMd8OPllLh0ezWtPEK5 7l/MVSp8MsqssW/JIlgp0175DHDFx38DEKCXHcX/6LZcZ/dePp0jEoIMPJSvC0/kuOcw ftTbWNHDCmoWafcEKs9tGbB60dpLEqDod6WzwIfVAK2Nha+BvWYn0kLVBv2/inz5gdQ5 thNtHK8EJGkMETx8R44wkbgYFqAOXknY2m9KZiRk11R6/vwGyViBdEdp99IxL9629qS6 B3SL0IXaEtk9QKWl4E2cM18yV1wI1WdxBiGb8vVyllmyFUjJ80Ctj3lsRY9rDyXTQyPQ 9jZQ== X-Gm-Message-State: ACrzQf2GtCbRqPmGZ5vkWRGOpgHekF4JD4Hrs+8lyJH7TT2+EMiRuVip Z/ruRdW8ok0Ox7E+hb8gikvZl36HldiR2w== X-Google-Smtp-Source: AMsMyM6ndqK292DnEUMDZiyiaWULi95sCPKphIsfxYXm3adXXgp5fuqNnW78ucnMnHQDdsJ3mCMH0A== X-Received: by 2002:a17:90a:cb96:b0:213:1dc2:b1de with SMTP id a22-20020a17090acb9600b002131dc2b1demr2739301pju.21.1666770673631; Wed, 26 Oct 2022 00:51:13 -0700 (PDT) Received: from linkdev2.localdomain ([49.37.37.214]) by smtp.gmail.com with ESMTPSA id w20-20020a170902ca1400b001714e7608fdsm2310913pld.256.2022.10.26.00.51.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 26 Oct 2022 00:51:12 -0700 (PDT) From: Pratyush Kumar Khan To: netdev@vger.kernel.org, bpf@vger.kernel.org Cc: tom@sipanda.io, abuduri@ventanamicro.com, chethan@sipanda.io, Pratyush Kumar Khan Subject: [RFC PATCH 2/4] docs: networking: add doc entry for kParser Date: Wed, 26 Oct 2022 13:20:52 +0530 Message-Id: <20221026075054.119069-3-pratyush@sipanda.io> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221026075054.119069-1-pratyush@sipanda.io> References: <20221026075054.119069-1-pratyush@sipanda.io> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org Adding new docs entry for new linux networking kernel module named kParser Signed-off-by: Pratyush Kumar Khan --- Documentation/networking/kParser.rst | 302 +++ .../networking/parse_graph_example.svg | 2039 +++++++++++++++++ 2 files changed, 2341 insertions(+) create mode 100644 Documentation/networking/kParser.rst create mode 100644 Documentation/networking/parse_graph_example.svg diff --git a/Documentation/networking/kParser.rst b/Documentation/networking/kParser.rst new file mode 100644 index 000000000000..ab4315d0ca8a --- /dev/null +++ b/Documentation/networking/kParser.rst @@ -0,0 +1,302 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +kParser (the Kernel Parser) +========================== + + +Introduction +============ + +kParser is a fully programmable, fully functional, highly performant +protocol parser in the Linux kernel. A parser is programmed through +the "ip parser" CLI, and common netlink interfaces are used to +instantiate a parser in the kernel. A parser is defined by a parse +graph which is implemented by kparser as a set of parse node definitions +and protocol tables that describe the linkages between the nodes. +Per its program, a kparser instance will report metadata about the +packet and various protocols layers of the packet. Metadata is any +information about the packet including header offsets and value of +fields of interest to the programmer; the later is analogous to the +flow information extracted by flow dissector (the primary difference +being that kParser can extract arbitrary protocol fields and report on +fields in multiple layers of encapsulation). + +The iproute2 CLI for the kParser works in tandem with the KMOD kParser +to configure any number of parser instances. If kParser KMOD is not +statically compiled with Linux kernel, it needs to be additionally +enabled, compiled and loaded to use the iproute2 CLI for kParser. +Please note that the kParser CLI is scriptable meaning the parser +configuration in the kernel can by dynamically updated without need to +recompile any code or reload kernel module. + +kParser objects and namespaces +============================== + +Building blocks of kParser are various objects from different +namespaces/object types. For example, parser, node, table etc. are all +different types of objects, also known as namespaces. All the namespaces +are described in the next section. + +Each object is identified by a maximum 128 bytes long '\0' terminated +(128 bytes including the '\0' character) human readable ASCII name +(only character '/' is not allowed in the name, and names can not start +with '-'). Alternatively an unsigned 16 bit ID or both ID and name can +be used to identify objects. +NOTE: During CLI create operations of these objects, it is must to +specify either the name or ID. Both can also be specified.Whichever is +not specified during create will be auto generated by the KMOD kParser +and CLI will convey the identifiers to user for later use. User should +save these identifiers. +NOTE: During CLI create operations, unique name or ID must always be +specified. Those name/ID can later be used to identify the associated +object in further CLI operations. + +Various objects are: + * parser: + A parser represents a parse tree. It defines the user + metadata and metametadata structure size, number of + parsing node and encapsulation limits, root node for the + parse tree, success and failure case exit nodes. + + * node: + A node (a.k.a parse node) represents a specific protocol + header. Defining protocol handler involves multiple + work, i.e. configure the parser about the associated + protocol's packet header, e.g. minimum header length, + where to look for the next protocol field in the packet, + etc. Along with that, it also defines the rules/handlers + to parse and store the required metadata by + associating a metalist. The table to find the next + protocol node is attached to node. + node can be 3 types: + * PLAIN: + PLAIN nodes are the basic protocol headers. + TLVS: + TLVS nodes are the Type-Length-Value protocol + headers, such as TCP. They also binds a + tlvtable to a node. + FLAGFIELDS: + FLAGFIELDS are indexed flag and associated flag + fields protocol headers, such as GRE headers. + It also binds a flagstable with a node. + + * table: + A table is a protocol table, which associated a protocol + number with a node. e.g. ethernet protocol type 0x8000 + in network order means the next node after ethernet + header is IPv4. + + NOTE: table has key, key must be unique. Usually this + key is protocol number, such as ethernet type, or IPv4 + protocol number etc. + + * metadata-rule: + Defines the metadata structures that will be passed to + the kParser datapath parser API by the user. This + basically defines a specific metadata extraction rule. + This must match with the user passed metadata structure + in the datapath API. + + * metadata-ruleset: + A list of metadata(s) to associate it with packet + parsing action handlers, i.e. parse node. + + * tlvnode: + A tlvnode defines a specific TLV parsing rule, e.g. to + parse TCP option MSS, a new tlvnode needs to be defined. + Each tlvnode can also associate a metalist with the TLV + parsing rule, i.e. tlvnode + + * tlvtable: + This is a table of multiple tlvnode(s) where the key are + types of TLVs (e.g. tlvnode defined for TCP MSS should + have the type/kind value set to 2. + + * flags: + It describes parsing rules to extract certain protocol's + flags in bitfields, such as flag value, mask and size. + + * flagfields: + It defines flagfields in packet associated with flags in + bitfields of the same packet. + e.g. GRE flagfields such as checksum, key, sequence + number etc. + + * flagstable: + This defines a table of flagfields and associate them + with their respective flag values via their indexes. + Here the keys are usually indexes, because in typical + flag based protocol header, such as GRE, the flagfields + appear in protocol packet in the same order as the set + flag bits. The flag is defined by the flag value, mask, + size and associated metalist. + + * condexprs: + "Conditional expressions" used to define and configure + various complex conditional expressions in kParser. + They are used to validate certain conditions for + protocol packet field values. + + * condexprslist: + "List of Conditional expressions" used to create + more complex and composite expressions involving more + than one conditional expression(s). + + * condexprstable: + "A table of Conditional expressions" used to + associate one or more than one list of Conditional + expressions with a packet parsing action handlers, + i.e. parse node. + + * counter: + It is used to create and configure counter objects which + can be used for a wide range of usages such as count how + many VLAN headers were parsed, how many TCP options are + encountered etc. + + * countertable: + kParser has a global table of counters, which supports + various and unique counter configurations upto seven + entries. Multiple kParser parser instances can share + this countertable. + +.. kernel-figure:: parse_graph_example.svg + :alt: kParser parse graph example + :align: center + :figwidth: 28em + + An example of kParser parse graph + + +kParser KMOD datapath APIs +=========================== + +There are four kernel datatpath API functions: + +.. code-block:: c + + /* kparser_parse(): Function to parse a skb using a parser + * instance key. + * + * skb: input packet skb + * kparser_key: key of the associated kParser parser object + * which must be already created via CLI. + * _metadata: User provided metadata buffer. It must be same as + * configured metadata objects in CLI. + * metadata_len: Total length of the user provided metadata + * buffer. + * + * return: kParser error code as defined in + * include/uapi/linux/kparser.h + */ + + int kparser_parse(struct sk_buff *skb, + const struct kparser_hkey*kparser_key, + void *_metadata, size_t metadata_len); + + /* __kparser_parse(): Function to parse a void * packet buffer + * using a parser instance key. + * + * parser: Non NULL kparser_get_parser() returned and cached + * opaque pointer + * referencing a valid parser instance. + * _hdr: input packet buffer + * parse_len: length of input packet buffer + * _metadata: User provided metadata buffer. It must be same as + * configured + * metadata objects in CLI. + * metadata_len: Total length of the user provided metadata + * buffer. + * + * return: kParser error code as defined in + * include/uapi/linux/kparser.h + */ + int __kparser_parse(const void *parser, void *_hdr, + size_t parse_len, void *_metadata, + size_t metadata_len); + + /* kparser_get_parser(): Function to get an opaque reference of + * a parser instance and mark it + * immutable so that while actively using, + * it can not be deleted. The parser is + * identified by a key. It marks the + * associated parser and whole parse + * tree immutable so that when it is + * locked, it can not be deleted. + * + * kparser_key: key of the associated kParser parser object + * which must be already created via CLI. + * + * return: NULL if key not found, else an opaque parser instance + * pointer which can be used in the following APIs 3 and + * 4. + * + * NOTE: This call makes the whole parser tree immutable. If + * caller calls this more than once, later caller will + * need to release the same parser exactly that many times + * using the API kparser_put_parser(). + */ + const void *kparser_get_parser(const struct kparser_hkey + *kparser_key); + + /* kparser_put_parser(): Function to return and undo the read + * only operation done previously by + * kparser_get_parser(). The parser + * instance is identified by using a + * previously obtained opaque parser + * pointer via API kparser_get_parser(). + * This undo the immutable change so that + * any component of the whole parse tree + * can be deleted again. + * + * parser: void *, Non NULL opaque pointer which was previously + * returned by kparser_get_parser(). Caller can use + * cached opaque pointer as long as system does not + * restart and kparser.ko is not reloaded. + * + * return: boolean, true if put operation is success, else + * false. + * + * NOTE: This call makes the whole parser tree deletable for the + * very last call. + */ + + bool kparser_put_parser(const void *parser); + +Example: Five tuple parser with header offsets +============================================== + +Now we can refer to an example kParser configuration which can parse +simple IPv4 five tuples, i.e. IPv4 header offset, offset of IPv4 +addresses, IPv4 protocol number, L4 header offset (i.e. TCP/UDP) and +L4 port numbers. The sample ip commands are: + +.. code-block:: shell + + ip parser create md-rule name md.iphdr_offset type offset \ + md-off 0 + ip parser create md-rule name md.ipaddrs src-hdr-off 12 \ + length 8 md-off 4 + ip parser create md-rule name md.l4_hdr.offset type offset \ + md-off 2 + ip parser create md-rule name md.ports src-hdr-off 0 \ + length 4 md-off 12 isendianneeded true + ip parser create node name node.ports hdr.minlen 4 \ + md-rule md.l4_hdr.offset md-rule md.ports + ip parser create node name node.ipv4 hdr.minlen 20 \ + hdr.len-field-off 0 hdr.len-field-len 1 \ + hdr.len-field-mask 0x0f hdr.len-field-multiplier 4 \ + nxt.field-off 9 nxt.field-len 1 \ + nxt.table-ent 6:node.ports \ + nxt.table-ent 17:node.ports md-rule md.iphdr_offset \ + md-rule md.ipaddrs + ip parser create node name node.ether hdr.minlen 14 \ + nxt.offset 12 nxt.length 2 \ + nxt.table-ent 0x800:node.ipv4 + ip parser create parser name tuple_parser rootnode node.ether \ + base-metametadata-size 14 + +This sample parser will parse Ethernet/IPv4 to UDP and TCP, report the +offsets of the innermost IP and TCP or UDP header, extract IPv4 +addresses and UDP or TCP ports (into a frame). diff --git a/Documentation/networking/parse_graph_example.svg b/Documentation/networking/parse_graph_example.svg new file mode 100644 index 000000000000..f21a695e9bde --- /dev/null +++ b/Documentation/networking/parse_graph_example.svg @@ -0,0 +1,2039 @@ + + + + +Created by potrace 1.16, written by Peter Selinger 2001-2019 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- 2.34.1