← Documents Documentation/bpf/bpf_prog_run.rst GitHub 원문 ↗

Linux 6.18.37 · BPF

Running BPF programs from userspace

BPF_PROG_RUN의 일반 test mode와 XDP live frame mode의 packet 처리, batch 실행 및 memory page recycling 규칙을 설명합니다.

Source pathDocumentation/bpf/bpf_prog_run.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

bpf_prog_run.rst:1-117

`BPF_PROG_RUN`은 userspace가 제공한 context와 packet data로 kernel의 BPF program을 실행합니다. 일반 mode는 side effect 없이 결과와 return code를 userspace로 돌려주므로 unit test에 적합합니다.

`BPF_F_TEST_XDP_LIVE_FRAMES`를 설정한 XDP live frame mode는 program의 drop·redirect·pass·transmit 결과를 kernel이 실제 수행합니다. interface context와 driver capability가 실제 packet 경로를 결정하며 packet processing failure는 trace point로 관찰해야 할 수 있습니다.

반복 실행은 기본 64개, 최대 256개 packet의 batch로 처리합니다. memory page pool을 재사용하며 recycle 시 packet boundary pointer만 초기화하므로, packet을 수정하는 program은 다음 invocation에서 원본 또는 수정본을 모두 만날 수 있도록 작성해야 합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===================================
4 Running BPF programs from userspace
5 ===================================
6
7 This document describes the ``BPF_PROG_RUN`` facility for running BPF programs
8 from userspace.
9
10 .. contents::
11 :local:
12 :depth: 2
13
14
15 Overview
16 --------
17
18 The ``BPF_PROG_RUN`` command can be used through the ``bpf()`` syscall to
19 execute a BPF program in the kernel and return the results to userspace. This
20 can be used to unit test BPF programs against user-supplied context objects, and
21 as way to explicitly execute programs in the kernel for their side effects. The
22 command was previously named ``BPF_PROG_TEST_RUN``, and both constants continue
23 to be defined in the UAPI header, aliased to the same value.
24
25 The ``BPF_PROG_RUN`` command can be used to execute BPF programs of the
26 following types:
27
28 - ``BPF_PROG_TYPE_SOCKET_FILTER``
29 - ``BPF_PROG_TYPE_SCHED_CLS``
30 - ``BPF_PROG_TYPE_SCHED_ACT``
31 - ``BPF_PROG_TYPE_XDP``
32 - ``BPF_PROG_TYPE_SK_LOOKUP``
33 - ``BPF_PROG_TYPE_CGROUP_SKB``
34 - ``BPF_PROG_TYPE_LWT_IN``
35 - ``BPF_PROG_TYPE_LWT_OUT``
36 - ``BPF_PROG_TYPE_LWT_XMIT``
37 - ``BPF_PROG_TYPE_LWT_SEG6LOCAL``
38 - ``BPF_PROG_TYPE_FLOW_DISSECTOR``
39 - ``BPF_PROG_TYPE_STRUCT_OPS``
40 - ``BPF_PROG_TYPE_RAW_TRACEPOINT``
41 - ``BPF_PROG_TYPE_SYSCALL``
42
43 When using the ``BPF_PROG_RUN`` command, userspace supplies an input context
44 object and (for program types operating on network packets) a buffer containing
45 the packet data that the BPF program will operate on. The kernel will then
46 execute the program and return the results to userspace. Note that programs will
47 not have any side effects while being run in this mode; in particular, packets
48 will not actually be redirected or dropped, the program return code will just be
49 returned to userspace. A separate mode for live execution of XDP programs is
50 provided, documented separately below.
51
52 Running XDP programs in "live frame mode"
53 -----------------------------------------
54
55 The ``BPF_PROG_RUN`` command has a separate mode for running live XDP programs,
56 which can be used to execute XDP programs in a way where packets will actually
57 be processed by the kernel after the execution of the XDP program as if they
58 arrived on a physical interface. This mode is activated by setting the
59 ``BPF_F_TEST_XDP_LIVE_FRAMES`` flag when supplying an XDP program to
60 ``BPF_PROG_RUN``.
61
62 The live packet mode is optimised for high performance execution of the supplied
63 XDP program many times (suitable for, e.g., running as a traffic generator),
64 which means the semantics are not quite as straight-forward as the regular test
65 run mode. Specifically:
66
67 - When executing an XDP program in live frame mode, the result of the execution
68 will not be returned to userspace; instead, the kernel will perform the
69 operation indicated by the program's return code (drop the packet, redirect
70 it, etc). For this reason, setting the ``data_out`` or ``ctx_out`` attributes
71 in the syscall parameters when running in this mode will be rejected. In
72 addition, not all failures will be reported back to userspace directly;
73 specifically, only fatal errors in setup or during execution (like memory
74 allocation errors) will halt execution and return an error. If an error occurs
75 in packet processing, like a failure to redirect to a given interface,
76 execution will continue with the next repetition; these errors can be detected
77 via the same trace points as for regular XDP programs.
78
79 - Userspace can supply an ifindex as part of the context object, just like in
80 the regular (non-live) mode. The XDP program will be executed as though the
81 packet arrived on this interface; i.e., the ``ingress_ifindex`` of the context
82 object will point to that interface. Furthermore, if the XDP program returns
83 ``XDP_PASS``, the packet will be injected into the kernel networking stack as
84 though it arrived on that ifindex, and if it returns ``XDP_TX``, the packet
85 will be transmitted *out* of that same interface. Do note, though, that
86 because the program execution is not happening in driver context, an
87 ``XDP_TX`` is actually turned into the same action as an ``XDP_REDIRECT`` to
88 that same interface (i.e., it will only work if the driver has support for the
89 ``ndo_xdp_xmit`` driver op).
90
91 - When running the program with multiple repetitions, the execution will happen
92 in batches. The batch size defaults to 64 packets (which is same as the
93 maximum NAPI receive batch size), but can be specified by userspace through
94 the ``batch_size`` parameter, up to a maximum of 256 packets. For each batch,
95 the kernel executes the XDP program repeatedly, each invocation getting a
96 separate copy of the packet data. For each repetition, if the program drops
97 the packet, the data page is immediately recycled (see below). Otherwise, the
98 packet is buffered until the end of the batch, at which point all packets
99 buffered this way during the batch are transmitted at once.
100
101 - When setting up the test run, the kernel will initialise a pool of memory
102 pages of the same size as the batch size. Each memory page will be initialised
103 with the initial packet data supplied by userspace at ``BPF_PROG_RUN``
104 invocation. When possible, the pages will be recycled on future program
105 invocations, to improve performance. Pages will generally be recycled a full
106 batch at a time, except when a packet is dropped (by return code or because
107 of, say, a redirection error), in which case that page will be recycled
108 immediately. If a packet ends up being passed to the regular networking stack
109 (because the XDP program returns ``XDP_PASS``, or because it ends up being
110 redirected to an interface that injects it into the stack), the page will be
111 released and a new one will be allocated when the pool is empty.
112
113 When recycling, the page content is not rewritten; only the packet boundary
114 pointers (``data``, ``data_end`` and ``data_meta``) in the context object will
115 be reset to the original values. This means that if a program rewrites the
116 packet contents, it has to be prepared to see either the original content or
117 the modified version on subsequent invocations.
118

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Userspace에서 BPF program 실행

1-23

이 문서는 userspace에서 BPF program을 실행하는 `BPF_PROG_RUN` facility를 설명하며 `SPDX-License-Identifier: GPL-2.0`으로 배포됩니다.

`BPF_PROG_RUN` command는 `bpf()` syscall을 통해 kernel에서 BPF program을 실행하고 결과를 userspace로 반환합니다. user가 제공한 context object를 대상으로 BPF program을 unit test하거나, program의 side effects를 위해 kernel에서 program을 명시적으로 실행하는 데 사용할 수 있습니다.

이 command의 이전 이름은 `BPF_PROG_TEST_RUN`입니다. 두 constant는 계속 UAPI header에 정의되며 같은 값의 alias입니다.

지원 program type과 일반 test mode

24-50

`BPF_PROG_RUN` command로 다음 type의 BPF program을 실행할 수 있습니다.

  • `BPF_PROG_TYPE_SOCKET_FILTER`
  • `BPF_PROG_TYPE_SCHED_CLS`
  • `BPF_PROG_TYPE_SCHED_ACT`
  • `BPF_PROG_TYPE_XDP`
  • `BPF_PROG_TYPE_SK_LOOKUP`
  • `BPF_PROG_TYPE_CGROUP_SKB`
  • `BPF_PROG_TYPE_LWT_IN`
  • `BPF_PROG_TYPE_LWT_OUT`
  • `BPF_PROG_TYPE_LWT_XMIT`
  • `BPF_PROG_TYPE_LWT_SEG6LOCAL`
  • `BPF_PROG_TYPE_FLOW_DISSECTOR`
  • `BPF_PROG_TYPE_STRUCT_OPS`
  • `BPF_PROG_TYPE_RAW_TRACEPOINT`
  • `BPF_PROG_TYPE_SYSCALL`

`BPF_PROG_RUN`을 사용할 때 userspace는 input context object와, network packet을 다루는 program type이라면 BPF program이 처리할 packet data buffer를 제공합니다. kernel은 program을 실행하고 결과를 userspace에 반환합니다.

이 mode에서 실행하는 program에는 side effect가 없습니다. 특히 packet이 실제로 redirect되거나 drop되지 않으며 program return code만 userspace로 반환됩니다. XDP program을 live로 실행하는 별도 mode는 다음 절에서 설명합니다.

XDP live frame mode

51-117

`BPF_PROG_RUN`에는 live XDP program을 실행하는 별도 mode가 있습니다. XDP program 실행 뒤 packet이 physical interface에 도착한 것처럼 kernel에서 실제로 처리되게 할 수 있습니다. XDP program을 `BPF_PROG_RUN`에 제공할 때 `BPF_F_TEST_XDP_LIVE_FRAMES` flag를 설정하면 이 mode가 활성화됩니다.

live packet mode는 traffic generator처럼 제공된 XDP program을 여러 번 고성능으로 실행하는 데 최적화됐으므로 semantics가 일반 test run mode만큼 단순하지 않습니다. 구체적인 규칙은 다음과 같습니다.

  • live frame mode에서 XDP program을 실행하면 실행 결과를 userspace에 반환하지 않습니다. 대신 kernel이 program return code가 가리키는 operation, 즉 packet drop이나 redirect 등을 수행합니다. 따라서 이 mode에서 syscall parameter의 `data_out` 또는 `ctx_out` attribute를 설정하면 reject됩니다. 모든 failure가 userspace에 직접 보고되는 것도 아닙니다. memory allocation error처럼 setup 또는 실행 중 발생한 fatal error만 실행을 중단하고 error를 반환합니다. 특정 interface redirect 실패 같은 packet processing error가 나면 다음 repetition을 계속하며, 일반 XDP program과 같은 trace point로 이 error를 감지할 수 있습니다.
  • userspace는 일반 non-live mode처럼 context object의 일부로 ifindex를 제공할 수 있습니다. XDP program은 packet이 이 interface에 도착한 것처럼 실행되므로 context object의 `ingress_ifindex`가 해당 interface를 가리킵니다. program이 `XDP_PASS`를 반환하면 packet이 그 ifindex에 도착한 것처럼 kernel networking stack에 inject되고, `XDP_TX`를 반환하면 같은 interface 밖으로 transmit됩니다. 다만 program이 driver context에서 실행되지 않으므로 `XDP_TX`는 실제로 같은 interface를 대상으로 한 `XDP_REDIRECT`와 같은 action으로 변환됩니다. 따라서 driver가 `ndo_xdp_xmit` driver op를 지원할 때만 동작합니다.
  • 여러 repetition으로 program을 실행하면 batch 단위로 처리합니다. 기본 batch size는 maximum NAPI receive batch size와 같은 64 packets이며 userspace가 `batch_size` parameter로 최대 256 packets까지 지정할 수 있습니다. 각 batch에서 kernel은 XDP program을 반복 실행하며 invocation마다 packet data의 별도 copy를 받습니다. program이 packet을 drop하면 매 repetition에서 data page를 즉시 recycle합니다. 그렇지 않으면 batch가 끝날 때까지 packet을 buffer한 뒤 그 batch에서 buffer한 모든 packet을 한 번에 transmit합니다.
  • test run을 setup할 때 kernel은 batch size와 같은 수의 memory page pool을 initialize합니다. 각 page는 `BPF_PROG_RUN` invocation에서 userspace가 제공한 initial packet data로 initialize됩니다. 성능을 높이기 위해 가능하면 이후 program invocation에서 page를 recycle합니다. 일반적으로 한 batch 전체를 한 번에 recycle하지만 return code나 redirect error 때문에 packet이 drop되면 그 page를 즉시 recycle합니다. `XDP_PASS`를 반환하거나 networking stack에 inject하는 interface로 redirect돼 packet이 regular networking stack에 전달되면 page를 release하고 pool이 빌 때 새 page를 allocate합니다. recycle할 때 page content는 다시 쓰지 않고 context object의 packet boundary pointer인 `data`, `data_end`, `data_meta`만 original value로 reset합니다. 따라서 program이 packet content를 rewrite한다면 이후 invocation에서 original content 또는 modified version을 볼 수 있음에 대비해야 합니다.