From patchwork Wed Feb 8 16:41:43 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= X-Patchwork-Id: 13133258 X-Patchwork-Delegate: bpf@iogearbox.net 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 8A9D0C636CC for ; Wed, 8 Feb 2023 16:45:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231565AbjBHQpE (ORCPT ); Wed, 8 Feb 2023 11:45:04 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53272 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231834AbjBHQov (ORCPT ); Wed, 8 Feb 2023 11:44:51 -0500 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3160E30C0 for ; Wed, 8 Feb 2023 08:43:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1675874512; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=1YNZbpe0n60mPrJnwiUAdm1/ZMHBphP6DStDV17ccyQ=; b=Nlt94guvwrB9HjEyOoZH6NSMEdbo0aOvnooBFgzfbGBwHr32Lb4Y4CEZ7qKG4TzncXog9s G3TUZVU925F8kkwWOFeMOPqPR6EHuKuor5RXGZZwj4XW+06yoaJFiOrNIXufu2rjy3R2A0 24iNTYOK8VoOQ5P02BURlb3vMmajIk0= Received: from mail-ej1-f70.google.com (mail-ej1-f70.google.com [209.85.218.70]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_128_GCM_SHA256) id us-mta-568-nmoY7XMuNxC358zbsT9oeg-1; Wed, 08 Feb 2023 11:41:48 -0500 X-MC-Unique: nmoY7XMuNxC358zbsT9oeg-1 Received: by mail-ej1-f70.google.com with SMTP id vq12-20020a170907a4cc00b00896db1c78aaso7968296ejc.9 for ; Wed, 08 Feb 2023 08:41:48 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=1YNZbpe0n60mPrJnwiUAdm1/ZMHBphP6DStDV17ccyQ=; b=x/JL3u/XmyV54EauFbLz9BbiWi1JMTUD0v0TDQhOGg9fNDj+xYIEZc2dvJUFpq4eLY /TogqzG25j1E0g74uwnlqCfy5PsPQQoO1VKUTOG5WBjgMnkLubsw0GZ+4/HCeRRvH7KA ofTvw5hCA7WhwK8HPp00VkfHJgcSYzH5QAj842ATocZZpJcnmjxp4cn0vEonNJhMI2pk ZMFb0NTOaxhsR5f1JdoiOMT1VyLBlcDTGs2tZsnlr12vptGsRT9KrUMqiV03M1+akGUq MmRZnNUfTd/LxezV+zvAZ2PTL4tqU6fMPJNiKIcEf82VF80cbGRXLiGcHdAFdlbtmXM+ jW/g== X-Gm-Message-State: AO0yUKUe7rEQoFN0TTmpCWn1eEWCQ01d0qa3zEG3YWrw74RoEFb50UgW MsN2gtSOvdLA9XD/UdlbcSqWPNy75HwLSzpCESbBwAhm/CtTFwIaFtS1beUB4kWP8us+scJHvy2 wFeneNqTWmXA3 X-Received: by 2002:a50:8e5b:0:b0:4aa:aa90:eeb0 with SMTP id 27-20020a508e5b000000b004aaaa90eeb0mr8686718edx.10.1675874506972; Wed, 08 Feb 2023 08:41:46 -0800 (PST) X-Google-Smtp-Source: AK7set8hipcNP0yhKThKsAPXHkhiewTa/uYVgDASPJB06br2zp93oOwb/wVBxDoSNQXEboSlumCupw== X-Received: by 2002:a50:8e5b:0:b0:4aa:aa90:eeb0 with SMTP id 27-20020a508e5b000000b004aaaa90eeb0mr8686676edx.10.1675874506015; Wed, 08 Feb 2023 08:41:46 -0800 (PST) Received: from alrua-x1.borgediget.toke.dk ([2a0c:4d80:42:443::2]) by smtp.gmail.com with ESMTPSA id a30-20020a50c31e000000b004aaf8decec4sm1192212edb.44.2023.02.08.08.41.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 08 Feb 2023 08:41:45 -0800 (PST) Received: by alrua-x1.borgediget.toke.dk (Postfix, from userid 1000) id 37F9B973CE0; Wed, 8 Feb 2023 17:41:44 +0100 (CET) From: =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= To: Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko , Martin KaFai Lau , Song Liu , Yonghong Song , John Fastabend , KP Singh , Stanislav Fomichev , Hao Luo , Jiri Olsa Cc: =?utf-8?q?Toke_H=C3=B8iland-J=C3=B8rgensen?= , Cong Wang , David Vernet , Jonathan Corbet , bpf@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH bpf-next v3] bpf/docs: Update design QA to be consistent with kfunc lifecycle docs Date: Wed, 8 Feb 2023 17:41:43 +0100 Message-Id: <20230208164143.286392-1-toke@redhat.com> X-Mailer: git-send-email 2.39.1 MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Cong pointed out that there are some inconsistencies between the BPF design QA and the lifecycle expectations documentation we added for kfuncs. Let's update the QA file to be consistent with the kfunc docs, and add references where it makes sense. Also document that modules may export kfuncs now. v3: - Grammar nit + ack from David v2: - Fix repeated word (s/defined defined/defined/) Reported-by: Cong Wang Acked-by: David Vernet Signed-off-by: Toke Høiland-Jørgensen --- Documentation/bpf/bpf_design_QA.rst | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index cec2371173d7..bfff0e7e37c2 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -208,6 +208,10 @@ data structures and compile with kernel internal headers. Both of these kernel internals are subject to change and can break with newer kernels such that the program needs to be adapted accordingly. +New BPF functionality is generally added through the use of kfuncs instead of +new helpers. Kfuncs are not considered part of the stable API, and have their own +lifecycle expectations as described in :ref:`BPF_kfunc_lifecycle_expectations`. + Q: Are tracepoints part of the stable ABI? ------------------------------------------ A: NO. Tracepoints are tied to internal implementation details hence they are @@ -236,8 +240,8 @@ A: NO. Classic BPF programs are converted into extend BPF instructions. Q: Can BPF call arbitrary kernel functions? ------------------------------------------- -A: NO. BPF programs can only call a set of helper functions which -is defined for every program type. +A: NO. BPF programs can only call specific functions exposed as BPF helpers or +kfuncs. The set of available functions is defined for every program type. Q: Can BPF overwrite arbitrary kernel memory? --------------------------------------------- @@ -263,7 +267,12 @@ Q: New functionality via kernel modules? Q: Can BPF functionality such as new program or map types, new helpers, etc be added out of kernel module code? -A: NO. +A: Yes, through kfuncs and kptrs + +The core BPF functionality such as program types, maps and helpers cannot be +added to by modules. However, modules can expose functionality to BPF programs +by exporting kfuncs (which may return pointers to module-internal data +structures as kptrs). Q: Directly calling kernel function is an ABI? ---------------------------------------------- @@ -278,7 +287,8 @@ kernel functions have already been used by other kernel tcp cc (congestion-control) implementations. If any of these kernel functions has changed, both the in-tree and out-of-tree kernel tcp cc implementations have to be changed. The same goes for the bpf -programs and they have to be adjusted accordingly. +programs and they have to be adjusted accordingly. See +:ref:`BPF_kfunc_lifecycle_expectations` for details. Q: Attaching to arbitrary kernel functions is an ABI? ----------------------------------------------------- @@ -340,6 +350,7 @@ compatibility for these features? A: NO. -Unlike map value types, there are no stability guarantees for this case. The -whole API to work with allocated objects and any support for special fields -inside them is unstable (since it is exposed through kfuncs). +Unlike map value types, the API to work with allocated objects and any support +for special fields inside them is exposed through kfuncs, and thus has the same +lifecycle expectations as the kfuncs themselves. See +:ref:`BPF_kfunc_lifecycle_expectations` for details.