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 00C3CC4708E for ; Tue, 6 Dec 2022 02:46:03 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231530AbiLFCp7 (ORCPT ); Mon, 5 Dec 2022 21:45:59 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54500 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233609AbiLFCp6 (ORCPT ); Mon, 5 Dec 2022 21:45:58 -0500 Received: from mail-pg1-x549.google.com (mail-pg1-x549.google.com [IPv6:2607:f8b0:4864:20::549]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 021E617A8C for ; Mon, 5 Dec 2022 18:45:58 -0800 (PST) Received: by mail-pg1-x549.google.com with SMTP id q63-20020a632a42000000b0045724b1dfb9so11217367pgq.3 for ; Mon, 05 Dec 2022 18:45:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20210112; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=7URUgBrKGQOFuDlwYgH7mee65ML5TVjzybnoYHjmOmM=; b=I5/Lw17fhc9vXOYi/OJsnQgTZJaqys/GeFO51fPwrlIsiYeJITRci+DqPjfJDk2HXg JWeAXs/iV929rIXxW9i2gYoUMt+awNjlli6SsmQ3QkpKC0hzfBdeoPpQ7Ux8RZ2w64CU 3PwxSDAlKrFzuDxd/xpuNDXE8P9+r4F7Pqm+7Xutiej4aTTmM2M9sZGVMoWiY4rIyDTq ediYERVb+XyBRhlgsm+CQyYUbeAXttWIXiJ0IeQqecmiTCu8M2YXCHqAQne0lbxK3eY6 BE4ZKiRJbB5/JIeoJWhoEQ/DpI1iLvv9VflTBnFBYGCBdu1c5uzMqOp1npAvZmAoq1Fl ZoXw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=7URUgBrKGQOFuDlwYgH7mee65ML5TVjzybnoYHjmOmM=; b=ESLs2FSnkCwPAD7KoXCN+wNiaHPzVES//JIDLly360qbue6BwJtKuCQb547TrIpgMx S5GAlTmun9k3zYrnGteu4JNFHtHnCqCMY/0EqCQXtXqnsFWmSGkcguERMqqzCOTSRpjt laj6glGTSjCnCeYj90SM4+HmwSpmWAW9VqxF8x4OKdGSlotKosZsjvFB3H84QIOos3hV gYwbD/1Dj0EeMunpUnVhdHpWKYu8SlSwp/MXvvpJIXEZ2k2GRmL5ngiJJZHO+wvLJfCE gAG4Sd1kA99kg9K7Zo8O+bpPxP9qeUwU45h+i6QNGBZ4Q37aqex0jKTjaryjp5ZhY8lR qymg== X-Gm-Message-State: ANoB5pnHA9hLAO/RRGpHY7d0EtdxoOBQvnLKbvCb3eSTS1LPlXuhXR0f lO9r9H1SQIeKH3yqO/93rRLwgRtAmZxx3CL7g68mLhvmZWFmi756wLM+8UbFQ+tVL5v4GptBOcp 31Yy8OafT6MYr45W8X1M7qCnWy2mM2LAV9+SMUx97mxtIGPOolA== X-Google-Smtp-Source: AA0mqf4p2h/2PUlIFQX1WrqE0/czaGBnrfl6K5ORPaeW8AetNwJEA4yNULch3vpqdJrhv3K47x08FcY= X-Received: from sdf.c.googlers.com ([fda3:e722:ac3:cc00:7f:e700:c0a8:5935]) (user=sdf job=sendgmr) by 2002:a17:90a:4313:b0:212:e24e:16b3 with SMTP id q19-20020a17090a431300b00212e24e16b3mr96814794pjg.69.1670294757435; Mon, 05 Dec 2022 18:45:57 -0800 (PST) Date: Mon, 5 Dec 2022 18:45:43 -0800 In-Reply-To: <20221206024554.3826186-1-sdf@google.com> Mime-Version: 1.0 References: <20221206024554.3826186-1-sdf@google.com> X-Mailer: git-send-email 2.39.0.rc0.267.gcb52ba06e7-goog Message-ID: <20221206024554.3826186-2-sdf@google.com> Subject: [PATCH bpf-next v3 01/12] bpf: Document XDP RX metadata From: Stanislav Fomichev To: bpf@vger.kernel.org Cc: ast@kernel.org, daniel@iogearbox.net, andrii@kernel.org, martin.lau@linux.dev, song@kernel.org, yhs@fb.com, john.fastabend@gmail.com, kpsingh@kernel.org, sdf@google.com, haoluo@google.com, jolsa@kernel.org, David Ahern , Jakub Kicinski , Willem de Bruijn , Jesper Dangaard Brouer , Anatoly Burakov , Alexander Lobakin , Magnus Karlsson , Maryam Tahhan , xdp-hints@xdp-project.net, netdev@vger.kernel.org Content-Type: text/plain; charset="UTF-8" Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org Document all current use-cases and assumptions. Cc: John Fastabend Cc: David Ahern Cc: Martin KaFai Lau Cc: Jakub Kicinski Cc: Willem de Bruijn Cc: Jesper Dangaard Brouer Cc: Anatoly Burakov Cc: Alexander Lobakin Cc: Magnus Karlsson Cc: Maryam Tahhan Cc: xdp-hints@xdp-project.net Cc: netdev@vger.kernel.org Signed-off-by: Stanislav Fomichev --- Documentation/bpf/xdp-rx-metadata.rst | 90 +++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 Documentation/bpf/xdp-rx-metadata.rst diff --git a/Documentation/bpf/xdp-rx-metadata.rst b/Documentation/bpf/xdp-rx-metadata.rst new file mode 100644 index 000000000000..498eae718275 --- /dev/null +++ b/Documentation/bpf/xdp-rx-metadata.rst @@ -0,0 +1,90 @@ +=============== +XDP RX Metadata +=============== + +XDP programs support creating and passing custom metadata via +``bpf_xdp_adjust_meta``. This metadata can be consumed by the following +entities: + +1. ``AF_XDP`` consumer. +2. Kernel core stack via ``XDP_PASS``. +3. Another device via ``bpf_redirect_map``. +4. Other BPF programs via ``bpf_tail_call``. + +General Design +============== + +XDP has access to a set of kfuncs to manipulate the metadata. Every +device driver implements these kfuncs. The set of kfuncs is +declared in ``include/net/xdp.h`` via ``XDP_METADATA_KFUNC_xxx``. + +Currently, the following kfuncs are supported. In the future, as more +metadata is supported, this set will grow: + +- ``bpf_xdp_metadata_rx_timestamp_supported`` returns true/false to + indicate whether the device supports RX timestamps +- ``bpf_xdp_metadata_rx_timestamp`` returns packet RX timestamp +- ``bpf_xdp_metadata_rx_hash_supported`` returns true/false to + indicate whether the device supports RX hash +- ``bpf_xdp_metadata_rx_hash`` returns packet RX hash + +Within the XDP frame, the metadata layout is as follows:: + + +----------+-----------------+------+ + | headroom | custom metadata | data | + +----------+-----------------+------+ + ^ ^ + | | + xdp_buff->data_meta xdp_buff->data + +AF_XDP +====== + +``AF_XDP`` use-case implies that there is a contract between the BPF program +that redirects XDP frames into the ``XSK`` and the final consumer. +Thus the BPF program manually allocates a fixed number of +bytes out of metadata via ``bpf_xdp_adjust_meta`` and calls a subset +of kfuncs to populate it. User-space ``XSK`` consumer, looks +at ``xsk_umem__get_data() - METADATA_SIZE`` to locate its metadata. + +Here is the ``AF_XDP`` consumer layout (note missing ``data_meta`` pointer):: + + +----------+-----------------+------+ + | headroom | custom metadata | data | + +----------+-----------------+------+ + ^ + | + rx_desc->address + +XDP_PASS +======== + +This is the path where the packets processed by the XDP program are passed +into the kernel. The kernel creates ``skb`` out of the ``xdp_buff`` contents. +Currently, every driver has a custom kernel code to parse the descriptors and +populate ``skb`` metadata when doing this ``xdp_buff->skb`` conversion. +In the future, we'd like to support a case where XDP program can override +some of that metadata. + +The plan of record is to make this path similar to ``bpf_redirect_map`` +so the program can control which metadata is passed to the skb layer. + +bpf_redirect_map +================ + +``bpf_redirect_map`` can redirect the frame to a different device. +In this case we don't know ahead of time whether that final consumer +will further redirect to an ``XSK`` or pass it to the kernel via ``XDP_PASS``. +Additionally, the final consumer doesn't have access to the original +hardware descriptor and can't access any of the original metadata. + +For this use-case, only custom metadata is currently supported. If +the frame is eventually passed to the kernel, the skb created from such +a frame won't have any skb metadata. The ``XSK`` consumer will only +have access to the custom metadata. + +bpf_tail_call +============= + +No special handling here. Tail-called program operates on the same context +as the original one. -- 2.39.0.rc0.267.gcb52ba06e7-goog