From patchwork Mon Aug 29 09:14:59 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Donald Hunter X-Patchwork-Id: 12957576 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 DBEBAECAAD4 for ; Mon, 29 Aug 2022 09:15:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229673AbiH2JPR (ORCPT ); Mon, 29 Aug 2022 05:15:17 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39632 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229754AbiH2JPQ (ORCPT ); Mon, 29 Aug 2022 05:15:16 -0400 Received: from mail-ed1-x530.google.com (mail-ed1-x530.google.com [IPv6:2a00:1450:4864:20::530]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BE9531ADB7; Mon, 29 Aug 2022 02:15:14 -0700 (PDT) Received: by mail-ed1-x530.google.com with SMTP id r4so9267809edi.8; Mon, 29 Aug 2022 02:15:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=Zvj5Ptf4ZB5FolY5aGzlhnaDTg1DsgEiRO9E3PeZKHA=; b=E5UDookjb1IdAyuRGgWlJj/RECqjr5LTMTJ97r3XUzIoKBQgOuUX7FSizOKQ7R0i31 o4LbCDXxVrk+DXoNV7Gmpz1RnIhTLqwSqkV1MwN4lG0PpYjR82hNxs5G1OZXqd3nsVSM XvpFnD6wtM7hpWs/hI7JerOMjaNbzCaAVR0et/ZADOm75FNc6AHCokBsVKJRzlaFIbEw 4TZfcoBzOL2o53rJp/4weY43/0zep9zsd+b8t2zAB1IF9ARbImPcDkMAmooBa+oIhD1B 2xvDOjvRkJ+TXeeS39Ro/Xeh8mrQ3pQlwensyQWtgnVaDgFLVqPDZAu2LWt8zyVjqWJe z8Hg== 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; bh=Zvj5Ptf4ZB5FolY5aGzlhnaDTg1DsgEiRO9E3PeZKHA=; b=iBDAh1xCShylkUpeDAIsk0L7Dum4glJZaEAH3Qg7ka/33YOs3a7sv7FcP0Mb6mTJk+ DKscu2W4FYZpaOSr1t6KmyWucuX+n5azrUqZgsEwhjZpyaiuNtssD2B1DsOvEqqtBlzK E/zy0km/vo7n2NTR0NZn3jjUTvZLQbVYcTbURLM/E4oFVThvTdCE+BWg6gjwfz3J5+KX 3hScglqIKZ78ryWYt2nd8Pfb4zfEVczuW3pru+4Yl9HAM9l8dOTphBzt8TPtIl5aN8tX Z2P9P3FWmqC9yYl1K2GpIyiRbwtvLiMFrkA5aVvNcZTYXrJu+6CRsAFjOZKGCrUn6e0u QB+Q== X-Gm-Message-State: ACgBeo0HtBG3H6L+oVrtgftnaITLx1CrahWL06TGA1324/n4yFyUcGkp c3q/HeT5gyiQspEGF4ezG1GcZ2XteVg= X-Google-Smtp-Source: AA6agR4wYKlqVXcdNijYcmD1XzB46vrxMVBL5ORdpDS9XtN1VKjFjLaGUuh/4xMzygmbuAswocciJQ== X-Received: by 2002:a05:6402:5008:b0:440:941a:93c3 with SMTP id p8-20020a056402500800b00440941a93c3mr15794292eda.47.1661764512851; Mon, 29 Aug 2022 02:15:12 -0700 (PDT) Received: from imac.fritz.box ([2a02:8010:60a0:0:612e:4c5:1fc2:7d5d]) by smtp.gmail.com with ESMTPSA id r1-20020a17090609c100b0073cb0801104sm4287382eje.147.2022.08.29.02.15.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 29 Aug 2022 02:15:12 -0700 (PDT) From: Donald Hunter To: bpf@vger.kernel.org, linux-doc@vger.kernel.org, Jonathan Corbet , Andrii Nakryiko Cc: Donald Hunter Subject: [PATCH bpf-next v3 1/2] Add subdir support to Documentation makefile Date: Mon, 29 Aug 2022 10:14:59 +0100 Message-Id: <20220829091500.24115-2-donald.hunter@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220829091500.24115-1-donald.hunter@gmail.com> References: <20220829091500.24115-1-donald.hunter@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Run make in list of subdirs to build generated sources and migrate userspace-api/media to use this instead of being a special case. Signed-off-by: Donald Hunter --- Documentation/Makefile | 15 +++++++++++++-- Documentation/userspace-api/media/Makefile | 2 ++ 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 64d44c1ecad3..8a63ef2dcd1c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -65,6 +65,12 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # commands; the 'cmd' from scripts/Kbuild.include is not *loopable* loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; +BUILD_SUBDIRS = \ + Documentation/userspace-api/media + +quiet_cmd_build_subdir = SUBDIR $2 + cmd_build_subdir = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=$2 $3 + # $2 sphinx builder e.g. "html" # $3 name of the build subfolder / e.g. "userspace-api/media", used as: # * dest folder relative to $(BUILDDIR) and @@ -74,7 +80,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; # e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) - cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ + cmd_sphinx = \ PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(PYTHON3) $(srctree)/scripts/jobserver-exec \ @@ -93,6 +99,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),html)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) linkcheckdocs: @@ -100,6 +107,7 @@ linkcheckdocs: latexdocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),latex)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) ifeq ($(HAVE_PDFLATEX),0) @@ -112,6 +120,7 @@ else # HAVE_PDFLATEX pdfdocs: latexdocs @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),latex)) $(foreach var,$(SPHINXDIRS), \ $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \ mkdir -p $(BUILDDIR)/$(var)/pdf; \ @@ -122,10 +131,12 @@ endif # HAVE_PDFLATEX epubdocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),epub)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),xml)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) endif # HAVE_SPHINX @@ -138,7 +149,7 @@ refcheckdocs: cleandocs: $(Q)rm -rf $(BUILDDIR) - $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),clean)) dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:' diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile index 00922aa7efde..783c6f880b72 100644 --- a/Documentation/userspace-api/media/Makefile +++ b/Documentation/userspace-api/media/Makefile @@ -50,6 +50,8 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception .PHONY: all html epub xml latex all: $(IMGDOT) $(BUILDDIR) ${TARGETS} + @: + html: all epub: all xml: all From patchwork Mon Aug 29 09:15:00 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Donald Hunter X-Patchwork-Id: 12957577 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 860BAECAAD5 for ; Mon, 29 Aug 2022 09:15:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229897AbiH2JPU (ORCPT ); Mon, 29 Aug 2022 05:15:20 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39776 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229754AbiH2JPT (ORCPT ); Mon, 29 Aug 2022 05:15:19 -0400 Received: from mail-ej1-x631.google.com (mail-ej1-x631.google.com [IPv6:2a00:1450:4864:20::631]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 78A5A1C110; Mon, 29 Aug 2022 02:15:17 -0700 (PDT) Received: by mail-ej1-x631.google.com with SMTP id se27so6680570ejb.8; Mon, 29 Aug 2022 02:15:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc; bh=vr2KR0kpkzOU3iCxlbjFB0Xu1rOwulObIcfuCs6jByc=; b=P60X7mx3WNgJ/KRbXMDAp/TeiFsnHnV/r3LpHb6fIo+orSmgY6T6CiZTAOTeOgE8kt agJ7G8azspMm2gO8cmCqVTrtp8Sr33B+43aWwnw+8i8cwBDyShtlrBp6nLyaxC7wd2j/ mu/Z9Z/fY8iy56saXXthUWFGllG4lyN9Z07+6kNODnGB1ccCeRXWTp7hdFWzn20xBuhO ECSpFHamPKMLdYTJ3Ig8jykKZOZyVhTV0XndWlUAgEyrfq4QednBFjtXEmK7jlbGrG47 QBlM0ZW0N99ryHt75lGKN/lIC6JTUe9wDTTz/5v/tfFxO11W8R8ot0Sl0JeAVI5hBecj VVHg== 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; bh=vr2KR0kpkzOU3iCxlbjFB0Xu1rOwulObIcfuCs6jByc=; b=7Ju9p3UdsGsLpn6o/0qYNnHsnzlJlVN+u/1uCeRIyLQ8IZAzon+mfpMCNUe8pNQ/tR NMWX1lEWbYnRHYltWP6Z5qHKx8DxEZPtDagHdNEnl+Dx1IFmAEk06BeWtwlHXodVg6+x 1bGN/nREdXEbp4vDaJ2ckoCJYQpJV9OjmwGNr1gqJF9/PYsH5wV9nj4/cFzgqSb33z1F +j7c5STYqXYnxVO+oonfupefsxNBiq18H9hDoA1IcnOuOJiTQalnUG0l86n9Qdrg5Lgg pidwsGq9+H1IEJ0CXKy6C1sUiUZd9EIwukXJ901eh5TeCVNjNqjaVm0IIQaMldVfgktO 6/pQ== X-Gm-Message-State: ACgBeo1vmOd5FGuyxip/IGe9SEBYbk3yHFmIIYyTRLVSE9K8At2wthmL YmhMcUZV/3FksvvkcUrIFewGdaP9S68= X-Google-Smtp-Source: AA6agR4NrMnICbNHKf9+32lw5z0UO62MaAKkuN57ThLlWa6rGHBAa7rzecD3DRLsDm+DgJURwO+TTg== X-Received: by 2002:a17:906:4795:b0:73d:d6e8:52a7 with SMTP id cw21-20020a170906479500b0073dd6e852a7mr11607261ejc.59.1661764515543; Mon, 29 Aug 2022 02:15:15 -0700 (PDT) Received: from imac.fritz.box ([2a02:8010:60a0:0:612e:4c5:1fc2:7d5d]) by smtp.gmail.com with ESMTPSA id r1-20020a17090609c100b0073cb0801104sm4287382eje.147.2022.08.29.02.15.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 29 Aug 2022 02:15:14 -0700 (PDT) From: Donald Hunter To: bpf@vger.kernel.org, linux-doc@vger.kernel.org, Jonathan Corbet , Andrii Nakryiko Cc: Donald Hunter Subject: [PATCH bpf-next v3 2/2] Add table of BPF program types to libbpf docs Date: Mon, 29 Aug 2022 10:15:00 +0100 Message-Id: <20220829091500.24115-3-donald.hunter@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220829091500.24115-1-donald.hunter@gmail.com> References: <20220829091500.24115-1-donald.hunter@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Extend the libbpf documentation with a table of program types, attach points and ELF section names. This table uses data from program_types.csv which is generated from tools/lib/bpf/libbpf.c during the documentation build. Signed-off-by: Donald Hunter --- Documentation/Makefile | 3 +- Documentation/bpf/libbpf/Makefile | 49 ++++++++++++++++++++++ Documentation/bpf/libbpf/index.rst | 3 ++ Documentation/bpf/libbpf/program_types.rst | 32 ++++++++++++++ Documentation/bpf/programs.rst | 3 ++ 5 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 Documentation/bpf/libbpf/Makefile create mode 100644 Documentation/bpf/libbpf/program_types.rst diff --git a/Documentation/Makefile b/Documentation/Makefile index 8a63ef2dcd1c..f007314770e1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -66,7 +66,8 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; BUILD_SUBDIRS = \ - Documentation/userspace-api/media + Documentation/userspace-api/media \ + Documentation/bpf/libbpf quiet_cmd_build_subdir = SUBDIR $2 cmd_build_subdir = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=$2 $3 diff --git a/Documentation/bpf/libbpf/Makefile b/Documentation/bpf/libbpf/Makefile new file mode 100644 index 000000000000..b3dc096c4a96 --- /dev/null +++ b/Documentation/bpf/libbpf/Makefile @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Rules to convert BPF program types in tools/lib/bpf/libbpf.c +# into a .csv file + +FILES = program_types.csv + +TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) + +# Extract program types and properties from the section definitions in libbpf.c such as +# SEC_DEF("socket", SOCKET_FILTER, 0, SEC_NONE) to generate program_types.csv +# +# Here is a sample of the generated output that includes .rst formatting: +# +# Program Type,Attach Type,ELF Section Name,Sleepable +# ``BPF_PROG_TYPE_SOCKET_FILTER``,,``socket``, +# ``BPF_PROG_TYPE_SK_REUSEPORT``,``BPF_SK_REUSEPORT_SELECT_OR_MIGRATE``,``sk_reuseport/migrate``, +# ``BPF_PROG_TYPE_SK_REUSEPORT``,``BPF_SK_REUSEPORT_SELECT``,``sk_reuseport``, +# ``BPF_PROG_TYPE_KPROBE``,,``kprobe+``, +# ``BPF_PROG_TYPE_KPROBE``,,``uprobe+``, +# ``BPF_PROG_TYPE_KPROBE``,,``uprobe.s+``,Yes + +$(BUILDDIR)/program_types.csv: $(srctree)/tools/lib/bpf/libbpf.c + $(Q)awk -F'[",[:space:]]+' \ + 'BEGIN { print "Program Type,Attach Type,ELF Section Name,Sleepable" } \ + /SEC_DEF\(\"/ && !/SEC_DEPRECATED/ { \ + type = "``BPF_PROG_TYPE_" $$4 "``"; \ + attach = index($$5, "0") ? "" : "``" $$5 "``"; \ + section = "``" $$3 "``"; \ + sleepable = index($$0, "SEC_SLEEPABLE") ? "Yes" : ""; \ + print type "," attach "," section "," sleepable }' \ + $< > $@ + +.PHONY: all html epub xml latex linkcheck clean + +all: $(BUILDDIR) ${TARGETS} + @: + +html: all +epub: all +xml: all +latex: all +linkcheck: + +clean: + -$(Q)rm -f ${TARGETS} 2>/dev/null + +$(BUILDDIR): + $(Q)mkdir -p $@ diff --git a/Documentation/bpf/libbpf/index.rst b/Documentation/bpf/libbpf/index.rst index 3722537d1384..f9b3b252e28f 100644 --- a/Documentation/bpf/libbpf/index.rst +++ b/Documentation/bpf/libbpf/index.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) +.. _libbpf: + libbpf ====== @@ -7,6 +9,7 @@ libbpf :maxdepth: 1 API Documentation + program_types libbpf_naming_convention libbpf_build diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst new file mode 100644 index 000000000000..04fbb48b8a6a --- /dev/null +++ b/Documentation/bpf/libbpf/program_types.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + +.. _program_types_and_elf: + +Program Types and ELF Sections +============================== + +The table below lists the program types, their attach types where relevant and the ELF section +names supported by libbpf for them. The ELF section names follow these rules: + +- ``type`` is an exact match, e.g. ``SEC("socket")`` +- ``type+`` means it can be either exact ``SEC("type")`` or well-formed ``SEC("type/extras")`` + with a ‘``/``’ separator between ``type`` and ``extras``. + +When ``extras`` are specified, they provide details of how to auto-attach the BPF program. +The format of ``extras`` depends on the program type, e.g. ``SEC("tracepoint//")`` +for tracepoints or ``SEC("usdt/::")`` for USDT probes. + +.. + program_types.csv is generated from tools/lib/bpf/libbpf.c and is fomatted like this: + Program Type,Attach Type,ELF Section Name,Sleepable + ``BPF_PROG_TYPE_SOCKET_FILTER``,,``socket``, + ``BPF_PROG_TYPE_SK_REUSEPORT``,``BPF_SK_REUSEPORT_SELECT_OR_MIGRATE``,``sk_reuseport/migrate``, + ``BPF_PROG_TYPE_SK_REUSEPORT``,``BPF_SK_REUSEPORT_SELECT``,``sk_reuseport``, + ``BPF_PROG_TYPE_KPROBE``,,``kprobe+``, + ``BPF_PROG_TYPE_KPROBE``,,``uprobe+``, + ``BPF_PROG_TYPE_KPROBE``,,``uprobe.s+``,Yes + +.. csv-table:: Program Types and Their ELF Section Names + :file: ../../output/program_types.csv + :widths: 40 30 20 10 + :header-rows: 1 diff --git a/Documentation/bpf/programs.rst b/Documentation/bpf/programs.rst index 620eb667ac7a..c99000ab6d9b 100644 --- a/Documentation/bpf/programs.rst +++ b/Documentation/bpf/programs.rst @@ -7,3 +7,6 @@ Program Types :glob: prog_* + +For a list of all program types, see :ref:`program_types_and_elf` in +the :ref:`libbpf` documentation.