github.com/cilium/ebpf@v0.15.1-0.20240517100537-8079b37aa138/docs/ebpf/concepts/loader.md (about)

     1  # Loading Objects
     2  
     3  {{ proj }} ships an eBPF object (ELF) loader that aims to be compatible with the
     4  upstream libbpf and iproute2 (`tc`/`ip`) projects. An ELF is typically obtained
     5  by compiling a eBPF C program using the LLVM toolchain (`clang`).
     6  
     7  This page describes the journey from compiled eBPF ELF to resources in the
     8  kernel. This involves parsing the ELF into intermediate Go (Spec) types that
     9  can be modified and copied before loading them into the kernel.
    10  
    11  ```mermaid
    12  graph LR
    13      ELF --> ProgramSpec --> Program
    14      ELF --> Types
    15      ELF --> MapSpec --> Map
    16      Map & Program --> Links
    17      subgraph Collection
    18          Program & Map
    19      end
    20      subgraph CollectionSpec
    21          ProgramSpec & MapSpec & Types
    22      end
    23  ```
    24  
    25  ## {{ godoc('CollectionSpec') }}
    26  
    27  A CollectionSpec represents eBPF objects extracted from an ELF, and can be
    28  obtained by calling {{ godoc('LoadCollectionSpec') }}. In the examples below, we
    29  declare a Map and Program in eBPF C, then load and inspect them using Go. Use
    30  the tabs to explore the Go and C counterparts below.
    31  
    32  === ":simple-go: Go"
    33      {{ go_example('DocLoadCollectionSpec', title='Parse ELF and inspect its CollectionSpec') | indent(4) }}
    34  
    35      !!! warning ""
    36          All of a Spec's attributes can be modified, and those modifications
    37          influence the resources created in the kernel. Be aware that doing so
    38          may invalidate any assumptions made by the compiler, resulting in maps
    39          or programs being rejected by the kernel. Proceed with caution.
    40  
    41  === ":ebee-color: eBPF C"
    42      {{ c_example('DocMyMapProgram', title='Declare a minimal map and a program') | indent(4) }}
    43  
    44      !!! tip ""
    45          See [Section Naming](section-naming.md) to learn about the use of the
    46          `SEC()` macro in the example above.
    47  
    48  ## {{ godoc('NewCollection') }}
    49  
    50  After parsing the ELF into a CollectionSpec, it can be loaded into the kernel
    51  using {{ godoc('NewCollection') }}, resulting in a {{ godoc('Collection') }}.
    52  
    53  {{ go_example('DocNewCollection') }}
    54  
    55  !!! note ""
    56      {{ godoc('Collection.Close') }} closes all Maps and Programs in the
    57      Collection. Interacting with any resources after `Close()` will return an
    58      error, since their underlying file descriptors will be closed. See [Object
    59      Lifecycle](object-lifecycle.md) to gain a better understanding of how {{
    60      proj }} manages its resources and for best practices handling Maps and
    61      Programs.
    62  
    63  ## {{ godoc('CollectionSpec.LoadAndAssign', short=True) }}
    64  
    65  LoadAndAssign is a convenience API that can be used instead of `NewCollection`.
    66  It has two major benefits:
    67  
    68  - It automates pulling Maps and Programs out of a Collection. No more `#!go if m
    69    := coll.Maps["my_map"]; m == nil { return ... }`.
    70  - **Selective loading of Maps and Programs!** Only resources of interest and
    71    their dependencies are loaded into the kernel. Great for working with large
    72    CollectionSpecs that only need to be partially loaded.
    73  
    74  First, declare a struct that will receive pointers to a Map and a Program after
    75  loading them into the kernel. Give it a `#!go Close()` method to make cleanup
    76  easier.
    77  
    78  {{ go_example('DocLoadAndAssignObjs', title='Declare a custom struct myObjs') }}
    79  
    80  !!! note ""
    81      Use bpf2go if the preceding code snippet looks
    82      tedious. bpf2go can generate this kind of boilerplate code automatically
    83      and will make sure it stays in sync with your C code.
    84  
    85  Next, instantiate a variable of our newly-declared type and pass its pointer to
    86  `LoadAndAssign`.
    87  
    88  {{ go_example('DocLoadAndAssign', title='Pass a custom struct to LoadAndAssign') }}
    89  
    90  !!! warning ""
    91      If your use case requires dynamically renaming keys in CollectionSpec.Maps,
    92      you may need to use NewCollection instead. Map and Program names in struct
    93      tags are baked into the Go binary at compile time.
    94  
    95  ## Type Information (BTF)
    96  
    97  If an eBPF ELF was built with `clang -g`, it will automatically contain BTF type
    98  information. This information can be accessed programmatically through {{
    99  godoc('CollectionSpec.Types') }}. Note that this field will be `nil` if the ELF
   100  was built without BTF.
   101  
   102  {{ go_example('DocBTFTypeByName') }}
   103  
   104  !!! note ""
   105      Many eBPF features rely on ELFs to be built with BTF, and there is
   106      little to be gained by opting out of it. `clang -g` also includes DWARF
   107      information in the ELF which can be safely removed with `llvm-strip`. eBPF
   108      does not rely on DWARF information.