github.com/cilium/ebpf@v0.15.1-0.20240517100537-8079b37aa138/docs/ebpf/concepts/section-naming.md (about) 1 You may have seen the `SEC()` macro used around eBPF C code. This macro sends 2 a hint to the compiler to place a symbol (a variable or function) in a specific 3 section of the resulting eBPF object binary. 4 5 Typically, program binaries for Unix-like systems are divided into so-called 6 'sections'. All sections have names, many of which are assigned special meaning. 7 For example, `.text` is where [program 8 text](https://en.wikipedia.org/wiki/Code_segment) (executable instructions) goes 9 by default. 10 11 Like common application binaries, eBPF also relies heavily on section naming to 12 distinguish various parts of an application. As an example, the section name of 13 an individual eBPF program determines its program type, affecting the way the 14 program is verified by the kernel and defining what the program is allowed to 15 do. 16 17 ## Executable Linkable Format (ELF) 18 19 Executable Linkable Format (ELF) is the standard application binary format for 20 Linux. It is also used as the output format of LLVM's BPF backend. ELF binaries 21 are typically [executed directly by the 22 kernel](https://lwn.net/Articles/631631/), but for eBPF, a different approach is 23 needed. 24 25 eBPF programs are not executable in the traditional sense. They depend on a user 26 space component that loads them, manages their resources, and can interact with 27 their components. This is where projects such as libbpf and {{ proj }} come 28 in. 29 30 For compatibility reasons, {{ proj }} follows the section naming conventions 31 established by libbpf, since we consider upstream decisions to be authoritative 32 on this subject. There's also little reason to do things differently; section 33 names are essentially considered an API. 34 35 ??? tip "How do I explore an ELF's contents?" 36 You can display an ELF's section table using `readelf -S <binary>`. 37 38 For visualizing a program instructions or the contents of a map's data 39 section, you'll need a tool from the LLVM toolchain: `llvm-objdump`. For 40 example: `llvm-objdump -SD my_ebpf.o -j xdp`. This will limit output to 41 the `xdp` section (see [Program Sections](#program-sections)), display 42 corresponding source code lines if available using `-S`, and display 43 disassembled instructions using `-D`. The same can be done for data sections 44 like `.data` and `.rodata.` (see [Map Sections](#map-sections)). 45 46 Also worth mentioning: display an eBPF object's BTF type information using 47 `bpftool btf dump file my_object.o`. 48 49 ## Section Prefixes 50 51 To support encoding extra information into section names, a prefix convention 52 using forward slashes `/` is used. For example, a Kprobe-type program meant to 53 be attached to the `slub_flush` kernel symbol would be put into an ELF section 54 called `kprobe/slub_flush`. 55 56 ### Miscellaneous Sections 57 58 `license` 59 60 : In order to use certain BPF helpers in your program, it must be licensed 61 under a GPL-compatible license. BPF programs licensing follows the same 62 rules as kernel module licensing. This is explained in more detail in the 63 Linux kernel's [BPF licensing 64 documentation](https://docs.kernel.org/bpf/bpf_licensing.html#using-bpf-programs-in-the-linux-kernel). 65 See the 66 [`license_is_gpl_compatible`](https://elixir.bootlin.com/linux/v6.5.4/source/include/linux/license.h) 67 function in the Linux source code or the [Module Licensing 68 table](https://docs.kernel.org/process/license-rules.html#id1). 69 70 This section must only contain the license string of the programs in the 71 ELF. for example: `#!c char __license[] SEC("license") = "Dual MIT/GPL";`. 72 73 `version` 74 75 : **Deprecated.** Kernels <5.0 require this section to contain a value 76 matching the kernel's `LINUX_VERSION_CODE` for Kprobe-type programs. Always 77 omit this, {{ proj }} will populate this field automatically if needed. 78 79 ### Map Sections 80 81 `.maps` 82 83 : This section is dedicated to BTF-style Map definitions. 84 85 `maps` 86 87 : **Deprecated.** This section is expected to only contain fixed-width `struct 88 bpf_map_def` variables. Larger structs like iproute2's `struct bpf_elf_map` 89 can also be used for backwards compatibility. Any extra bytes past the end 90 of the size of a `struct bpf_map_def` are exposed by {{ 91 godoc('MapSpec.Extra') }} and must be drained before attempting to create 92 the Map. 93 94 #### :material-head-cog: Advanced: Special Map Sections 95 96 `.data` 97 98 : The LLVM BPF backend implements accesses to mutable global variables as 99 direct Array Map accesses. Since a single BPF program can be executed 100 concurrently as a result of the kernel processing packets and other events 101 asynchronously, `.data` and the global variables it represents are 102 considered shared memory. 103 104 This section is exposed by {{ godoc('CollectionSpec.Maps') }} as a 105 single-element BPF array and its contents are accessible through {{ 106 godoc('MapSpec.Contents') }}. Its layout is described by its {{ 107 godoc('MapSpec.Value') }}, a {{ godoc('btf/Datasec') }} containing all 108 global variables in the compilation unit. 109 110 The contents of the Map may be modified to control the default values 111 used for the eBPF program's global variables. 112 113 `.rodata*` 114 115 : Like `.data`, but for constants. This is a prefix and matches sections like 116 `.rodata.foo`. Constants can be emitted to different sections using e.g. 117 `#!c SEC(".rodata.foo") volatile const foobar = 123;`. This can prove useful 118 for isolating certain constants to well-known sections for Go code 119 generation or custom constant rewriting logic. 120 121 `.bss` 122 123 : Section emitted by the compiler when zero-initialized globals are present in 124 the ELF. Is typically zero-length. Exposed by {{ 125 godoc('CollectionSpec.Maps') }}, but not really useful. 126 127 `.rel*` 128 129 : Not exposed by {{ proj }}, only used behind the scenes. Relocation sections 130 contain relocation records against their non-`.rel` prefixed counterparts. 131 This is mainly used for fixing up BPF instructions referring to Maps and 132 global variables. 133 134 ### Program Sections 135 136 Names of Program sections mainly define the program's {{ godoc('ProgramType') 137 }}, but also its {{ godoc('AttachType') }} and {{ godoc('AttachFlags') }} are 138 automatically set for convenience based on its section name. 139 140 As described previously, section prefixes containing a forward slash `/` expect 141 a second component to follow the slash. For example, a program in the 142 `kprobe/slub_flush` section will automatically have its {{ 143 godoc('ProgramSpec.AttachTo') }} field set to `slub_flush` to facilitate 144 attaching the program later on. 145 146 Additionally, the program's original full section name can be found in {{ 147 godoc('ProgramSpec.SectionName') }}. 148 149 !!! tip "" 150 There's also [upstream libbpf 151 documentation](https://docs.kernel.org/bpf/libbpf/program_types.html) for 152 this. Not all of libbpf's program types may be supported by {{ proj }} yet. 153 If a program type you require is missing, please file an issue or send a 154 pull request! 155 156 | Section (Prefix) | {{ godoc('ProgramType') }} | {{ godoc('AttachType') }} | {{ godoc('AttachFlags') }} | 157 |:----------------------|:---------------------------|:---------------------------------|:---------------------------| 158 | socket | SocketFilter | | | 159 | sk_reuseport/migrate | SkReuseport | AttachSkReuseportSelectOrMigrate | | 160 | sk_reuseport | SkReuseport | AttachSkReuseportSelect | | 161 | kprobe/ | Kprobe | | | 162 | uprobe/ | Kprobe | | | 163 | kretprobe/ | Kprobe | | | 164 | uretprobe/ | Kprobe | | | 165 | tc | SchedCLS | | | 166 | classifier | SchedCLS | | | 167 | action | SchedACT | | | 168 | tracepoint/ | TracePoint | | | 169 | tp/ | TracePoint | | | 170 | raw_tracepoint/ | RawTracepoint | | | 171 | raw_tp/ | RawTracepoint | | | 172 | raw_tracepoint.w/ | RawTracepointWritable | | | 173 | raw_tp.w/ | RawTracepointWritable | | | 174 | tp_btf/ | Tracing | AttachTraceRawTp | | 175 | fentry/ | Tracing | AttachTraceFEntry | | 176 | fmod_ret/ | Tracing | AttachModifyReturn | | 177 | fexit/ | Tracing | AttachTraceFExit | | 178 | fentry.s/ | Tracing | AttachTraceFEntry | BPF_F_SLEEPABLE | 179 | fmod_ret.s/ | Tracing | AttachModifyReturn | BPF_F_SLEEPABLE | 180 | fexit.s/ | Tracing | AttachTraceFExit | BPF_F_SLEEPABLE | 181 | freplace/ | Extension | | | 182 | lsm/ | LSM | AttachLSMMac | | 183 | lsm.s/ | LSM | AttachLSMMac | BPF_F_SLEEPABLE | 184 | iter/ | Tracing | AttachTraceIter | | 185 | iter.s/ | Tracing | AttachTraceIter | BPF_F_SLEEPABLE | 186 | syscall | Syscall | | | 187 | xdp.frags_devmap/ | XDP | AttachXDPDevMap | BPF_F_XDP_HAS_FRAGS | 188 | xdp_devmap/ | XDP | AttachXDPDevMap | | 189 | xdp.frags_cpumap/ | XDP | AttachXDPCPUMap | BPF_F_XDP_HAS_FRAGS | 190 | xdp_cpumap/ | XDP | AttachXDPCPUMap | | 191 | xdp.frags | XDP | | BPF_F_XDP_HAS_FRAGS | 192 | xdp | XDP | | | 193 | perf_event | PerfEvent | | | 194 | lwt_in | LWTIn | | | 195 | lwt_out | LWTOut | | | 196 | lwt_xmit | LWTXmit | | | 197 | lwt_seg6local | LWTSeg6Local | | | 198 | cgroup_skb/ingress | CGroupSKB | AttachCGroupInetIngress | | 199 | cgroup_skb/egress | CGroupSKB | AttachCGroupInetEgress | | 200 | cgroup/skb | CGroupSKB | | | 201 | cgroup/sock_create | CGroupSock | AttachCGroupInetSockCreate | | 202 | cgroup/sock_release | CGroupSock | AttachCgroupInetSockRelease | | 203 | cgroup/sock | CGroupSock | AttachCGroupInetSockCreate | | 204 | cgroup/post_bind4 | CGroupSock | AttachCGroupInet4PostBind | | 205 | cgroup/post_bind6 | CGroupSock | AttachCGroupInet6PostBind | | 206 | cgroup/dev | CGroupDevice | AttachCGroupDevice | | 207 | sockops | SockOps | AttachCGroupSockOps | | 208 | sk_skb/stream_parser | SkSKB | AttachSkSKBStreamParser | | 209 | sk_skb/stream_verdict | SkSKB | AttachSkSKBStreamVerdict | | 210 | sk_skb | SkSKB | | | 211 | sk_msg | SkMsg | AttachSkMsgVerdict | | 212 | lirc_mode2 | LircMode2 | AttachLircMode2 | | 213 | flow_dissector | FlowDissector | AttachFlowDissector | | 214 | cgroup/bind4 | CGroupSockAddr | AttachCGroupInet4Bind | | 215 | cgroup/bind6 | CGroupSockAddr | AttachCGroupInet6Bind | | 216 | cgroup/connect4 | CGroupSockAddr | AttachCGroupInet4Connect | | 217 | cgroup/connect6 | CGroupSockAddr | AttachCGroupInet6Connect | | 218 | cgroup/sendmsg4 | CGroupSockAddr | AttachCGroupUDP4Sendmsg | | 219 | cgroup/sendmsg6 | CGroupSockAddr | AttachCGroupUDP6Sendmsg | | 220 | cgroup/recvmsg4 | CGroupSockAddr | AttachCGroupUDP4Recvmsg | | 221 | cgroup/recvmsg6 | CGroupSockAddr | AttachCGroupUDP6Recvmsg | | 222 | cgroup/getpeername4 | CGroupSockAddr | AttachCgroupInet4GetPeername | | 223 | cgroup/getpeername6 | CGroupSockAddr | AttachCgroupInet6GetPeername | | 224 | cgroup/getsockname4 | CGroupSockAddr | AttachCgroupInet4GetSockname | | 225 | cgroup/getsockname6 | CGroupSockAddr | AttachCgroupInet6GetSockname | | 226 | cgroup/sysctl | CGroupSysctl | AttachCGroupSysctl | | 227 | cgroup/getsockopt | CGroupSockopt | AttachCGroupGetsockopt | | 228 | cgroup/setsockopt | CGroupSockopt | AttachCGroupSetsockopt | | 229 | struct_ops+ | StructOps | | | 230 | sk_lookup/ | SkLookup | AttachSkLookup | | 231 | seccomp | SocketFilter | | | 232 | kprobe.multi | Kprobe | AttachTraceKprobeMulti | | 233 | kretprobe.multi | Kprobe | AttachTraceKprobeMulti | |