btf.rst 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970
  1. =====================
  2. BPF Type Format (BTF)
  3. =====================
  4. 1. Introduction
  5. ***************
  6. BTF (BPF Type Format) is the metadata format which encodes the debug info
  7. related to BPF program/map. The name BTF was used initially to describe data
  8. types. The BTF was later extended to include function info for defined
  9. subroutines, and line info for source/line information.
  10. The debug info is used for map pretty print, function signature, etc. The
  11. function signature enables better bpf program/function kernel symbol. The line
  12. info helps generate source annotated translated byte code, jited code and
  13. verifier log.
  14. The BTF specification contains two parts,
  15. * BTF kernel API
  16. * BTF ELF file format
  17. The kernel API is the contract between user space and kernel. The kernel
  18. verifies the BTF info before using it. The ELF file format is a user space
  19. contract between ELF file and libbpf loader.
  20. The type and string sections are part of the BTF kernel API, describing the
  21. debug info (mostly types related) referenced by the bpf program. These two
  22. sections are discussed in details in :ref:`BTF_Type_String`.
  23. .. _BTF_Type_String:
  24. 2. BTF Type and String Encoding
  25. *******************************
  26. The file ``include/uapi/linux/btf.h`` provides high-level definition of how
  27. types/strings are encoded.
  28. The beginning of data blob must be::
  29. struct btf_header {
  30. __u16 magic;
  31. __u8 version;
  32. __u8 flags;
  33. __u32 hdr_len;
  34. /* All offsets are in bytes relative to the end of this header */
  35. __u32 type_off; /* offset of type section */
  36. __u32 type_len; /* length of type section */
  37. __u32 str_off; /* offset of string section */
  38. __u32 str_len; /* length of string section */
  39. };
  40. The magic is ``0xeB9F``, which has different encoding for big and little
  41. endian systems, and can be used to test whether BTF is generated for big- or
  42. little-endian target. The ``btf_header`` is designed to be extensible with
  43. ``hdr_len`` equal to ``sizeof(struct btf_header)`` when a data blob is
  44. generated.
  45. 2.1 String Encoding
  46. ===================
  47. The first string in the string section must be a null string. The rest of
  48. string table is a concatenation of other null-terminated strings.
  49. 2.2 Type Encoding
  50. =================
  51. The type id ``0`` is reserved for ``void`` type. The type section is parsed
  52. sequentially and type id is assigned to each recognized type starting from id
  53. ``1``. Currently, the following types are supported::
  54. #define BTF_KIND_INT 1 /* Integer */
  55. #define BTF_KIND_PTR 2 /* Pointer */
  56. #define BTF_KIND_ARRAY 3 /* Array */
  57. #define BTF_KIND_STRUCT 4 /* Struct */
  58. #define BTF_KIND_UNION 5 /* Union */
  59. #define BTF_KIND_ENUM 6 /* Enumeration */
  60. #define BTF_KIND_FWD 7 /* Forward */
  61. #define BTF_KIND_TYPEDEF 8 /* Typedef */
  62. #define BTF_KIND_VOLATILE 9 /* Volatile */
  63. #define BTF_KIND_CONST 10 /* Const */
  64. #define BTF_KIND_RESTRICT 11 /* Restrict */
  65. #define BTF_KIND_FUNC 12 /* Function */
  66. #define BTF_KIND_FUNC_PROTO 13 /* Function Proto */
  67. #define BTF_KIND_VAR 14 /* Variable */
  68. #define BTF_KIND_DATASEC 15 /* Section */
  69. Note that the type section encodes debug info, not just pure types.
  70. ``BTF_KIND_FUNC`` is not a type, and it represents a defined subprogram.
  71. Each type contains the following common data::
  72. struct btf_type {
  73. __u32 name_off;
  74. /* "info" bits arrangement
  75. * bits 0-15: vlen (e.g. # of struct's members)
  76. * bits 16-23: unused
  77. * bits 24-27: kind (e.g. int, ptr, array...etc)
  78. * bits 28-30: unused
  79. * bit 31: kind_flag, currently used by
  80. * struct, union and fwd
  81. */
  82. __u32 info;
  83. /* "size" is used by INT, ENUM, STRUCT and UNION.
  84. * "size" tells the size of the type it is describing.
  85. *
  86. * "type" is used by PTR, TYPEDEF, VOLATILE, CONST, RESTRICT,
  87. * FUNC and FUNC_PROTO.
  88. * "type" is a type_id referring to another type.
  89. */
  90. union {
  91. __u32 size;
  92. __u32 type;
  93. };
  94. };
  95. For certain kinds, the common data are followed by kind-specific data. The
  96. ``name_off`` in ``struct btf_type`` specifies the offset in the string table.
  97. The following sections detail encoding of each kind.
  98. 2.2.1 BTF_KIND_INT
  99. ~~~~~~~~~~~~~~~~~~
  100. ``struct btf_type`` encoding requirement:
  101. * ``name_off``: any valid offset
  102. * ``info.kind_flag``: 0
  103. * ``info.kind``: BTF_KIND_INT
  104. * ``info.vlen``: 0
  105. * ``size``: the size of the int type in bytes.
  106. ``btf_type`` is followed by a ``u32`` with the following bits arrangement::
  107. #define BTF_INT_ENCODING(VAL) (((VAL) & 0x0f000000) >> 24)
  108. #define BTF_INT_OFFSET(VAL) (((VAL) & 0x00ff0000) >> 16)
  109. #define BTF_INT_BITS(VAL) ((VAL) & 0x000000ff)
  110. The ``BTF_INT_ENCODING`` has the following attributes::
  111. #define BTF_INT_SIGNED (1 << 0)
  112. #define BTF_INT_CHAR (1 << 1)
  113. #define BTF_INT_BOOL (1 << 2)
  114. The ``BTF_INT_ENCODING()`` provides extra information: signedness, char, or
  115. bool, for the int type. The char and bool encoding are mostly useful for
  116. pretty print. At most one encoding can be specified for the int type.
  117. The ``BTF_INT_BITS()`` specifies the number of actual bits held by this int
  118. type. For example, a 4-bit bitfield encodes ``BTF_INT_BITS()`` equals to 4.
  119. The ``btf_type.size * 8`` must be equal to or greater than ``BTF_INT_BITS()``
  120. for the type. The maximum value of ``BTF_INT_BITS()`` is 128.
  121. The ``BTF_INT_OFFSET()`` specifies the starting bit offset to calculate values
  122. for this int. For example, a bitfield struct member has:
  123. * btf member bit offset 100 from the start of the structure,
  124. * btf member pointing to an int type,
  125. * the int type has ``BTF_INT_OFFSET() = 2`` and ``BTF_INT_BITS() = 4``
  126. Then in the struct memory layout, this member will occupy ``4`` bits starting
  127. from bits ``100 + 2 = 102``.
  128. Alternatively, the bitfield struct member can be the following to access the
  129. same bits as the above:
  130. * btf member bit offset 102,
  131. * btf member pointing to an int type,
  132. * the int type has ``BTF_INT_OFFSET() = 0`` and ``BTF_INT_BITS() = 4``
  133. The original intention of ``BTF_INT_OFFSET()`` is to provide flexibility of
  134. bitfield encoding. Currently, both llvm and pahole generate
  135. ``BTF_INT_OFFSET() = 0`` for all int types.
  136. 2.2.2 BTF_KIND_PTR
  137. ~~~~~~~~~~~~~~~~~~
  138. ``struct btf_type`` encoding requirement:
  139. * ``name_off``: 0
  140. * ``info.kind_flag``: 0
  141. * ``info.kind``: BTF_KIND_PTR
  142. * ``info.vlen``: 0
  143. * ``type``: the pointee type of the pointer
  144. No additional type data follow ``btf_type``.
  145. 2.2.3 BTF_KIND_ARRAY
  146. ~~~~~~~~~~~~~~~~~~~~
  147. ``struct btf_type`` encoding requirement:
  148. * ``name_off``: 0
  149. * ``info.kind_flag``: 0
  150. * ``info.kind``: BTF_KIND_ARRAY
  151. * ``info.vlen``: 0
  152. * ``size/type``: 0, not used
  153. ``btf_type`` is followed by one ``struct btf_array``::
  154. struct btf_array {
  155. __u32 type;
  156. __u32 index_type;
  157. __u32 nelems;
  158. };
  159. The ``struct btf_array`` encoding:
  160. * ``type``: the element type
  161. * ``index_type``: the index type
  162. * ``nelems``: the number of elements for this array (``0`` is also allowed).
  163. The ``index_type`` can be any regular int type (``u8``, ``u16``, ``u32``,
  164. ``u64``, ``unsigned __int128``). The original design of including
  165. ``index_type`` follows DWARF, which has an ``index_type`` for its array type.
  166. Currently in BTF, beyond type verification, the ``index_type`` is not used.
  167. The ``struct btf_array`` allows chaining through element type to represent
  168. multidimensional arrays. For example, for ``int a[5][6]``, the following type
  169. information illustrates the chaining:
  170. * [1]: int
  171. * [2]: array, ``btf_array.type = [1]``, ``btf_array.nelems = 6``
  172. * [3]: array, ``btf_array.type = [2]``, ``btf_array.nelems = 5``
  173. Currently, both pahole and llvm collapse multidimensional array into
  174. one-dimensional array, e.g., for ``a[5][6]``, the ``btf_array.nelems`` is
  175. equal to ``30``. This is because the original use case is map pretty print
  176. where the whole array is dumped out so one-dimensional array is enough. As
  177. more BTF usage is explored, pahole and llvm can be changed to generate proper
  178. chained representation for multidimensional arrays.
  179. 2.2.4 BTF_KIND_STRUCT
  180. ~~~~~~~~~~~~~~~~~~~~~
  181. 2.2.5 BTF_KIND_UNION
  182. ~~~~~~~~~~~~~~~~~~~~
  183. ``struct btf_type`` encoding requirement:
  184. * ``name_off``: 0 or offset to a valid C identifier
  185. * ``info.kind_flag``: 0 or 1
  186. * ``info.kind``: BTF_KIND_STRUCT or BTF_KIND_UNION
  187. * ``info.vlen``: the number of struct/union members
  188. * ``info.size``: the size of the struct/union in bytes
  189. ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_member``.::
  190. struct btf_member {
  191. __u32 name_off;
  192. __u32 type;
  193. __u32 offset;
  194. };
  195. ``struct btf_member`` encoding:
  196. * ``name_off``: offset to a valid C identifier
  197. * ``type``: the member type
  198. * ``offset``: <see below>
  199. If the type info ``kind_flag`` is not set, the offset contains only bit offset
  200. of the member. Note that the base type of the bitfield can only be int or enum
  201. type. If the bitfield size is 32, the base type can be either int or enum
  202. type. If the bitfield size is not 32, the base type must be int, and int type
  203. ``BTF_INT_BITS()`` encodes the bitfield size.
  204. If the ``kind_flag`` is set, the ``btf_member.offset`` contains both member
  205. bitfield size and bit offset. The bitfield size and bit offset are calculated
  206. as below.::
  207. #define BTF_MEMBER_BITFIELD_SIZE(val) ((val) >> 24)
  208. #define BTF_MEMBER_BIT_OFFSET(val) ((val) & 0xffffff)
  209. In this case, if the base type is an int type, it must be a regular int type:
  210. * ``BTF_INT_OFFSET()`` must be 0.
  211. * ``BTF_INT_BITS()`` must be equal to ``{1,2,4,8,16} * 8``.
  212. The following kernel patch introduced ``kind_flag`` and explained why both
  213. modes exist:
  214. https://github.com/torvalds/linux/commit/9d5f9f701b1891466fb3dbb1806ad97716f95cc3#diff-fa650a64fdd3968396883d2fe8215ff3
  215. 2.2.6 BTF_KIND_ENUM
  216. ~~~~~~~~~~~~~~~~~~~
  217. ``struct btf_type`` encoding requirement:
  218. * ``name_off``: 0 or offset to a valid C identifier
  219. * ``info.kind_flag``: 0
  220. * ``info.kind``: BTF_KIND_ENUM
  221. * ``info.vlen``: number of enum values
  222. * ``size``: 4
  223. ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_enum``.::
  224. struct btf_enum {
  225. __u32 name_off;
  226. __s32 val;
  227. };
  228. The ``btf_enum`` encoding:
  229. * ``name_off``: offset to a valid C identifier
  230. * ``val``: any value
  231. 2.2.7 BTF_KIND_FWD
  232. ~~~~~~~~~~~~~~~~~~
  233. ``struct btf_type`` encoding requirement:
  234. * ``name_off``: offset to a valid C identifier
  235. * ``info.kind_flag``: 0 for struct, 1 for union
  236. * ``info.kind``: BTF_KIND_FWD
  237. * ``info.vlen``: 0
  238. * ``type``: 0
  239. No additional type data follow ``btf_type``.
  240. 2.2.8 BTF_KIND_TYPEDEF
  241. ~~~~~~~~~~~~~~~~~~~~~~
  242. ``struct btf_type`` encoding requirement:
  243. * ``name_off``: offset to a valid C identifier
  244. * ``info.kind_flag``: 0
  245. * ``info.kind``: BTF_KIND_TYPEDEF
  246. * ``info.vlen``: 0
  247. * ``type``: the type which can be referred by name at ``name_off``
  248. No additional type data follow ``btf_type``.
  249. 2.2.9 BTF_KIND_VOLATILE
  250. ~~~~~~~~~~~~~~~~~~~~~~~
  251. ``struct btf_type`` encoding requirement:
  252. * ``name_off``: 0
  253. * ``info.kind_flag``: 0
  254. * ``info.kind``: BTF_KIND_VOLATILE
  255. * ``info.vlen``: 0
  256. * ``type``: the type with ``volatile`` qualifier
  257. No additional type data follow ``btf_type``.
  258. 2.2.10 BTF_KIND_CONST
  259. ~~~~~~~~~~~~~~~~~~~~~
  260. ``struct btf_type`` encoding requirement:
  261. * ``name_off``: 0
  262. * ``info.kind_flag``: 0
  263. * ``info.kind``: BTF_KIND_CONST
  264. * ``info.vlen``: 0
  265. * ``type``: the type with ``const`` qualifier
  266. No additional type data follow ``btf_type``.
  267. 2.2.11 BTF_KIND_RESTRICT
  268. ~~~~~~~~~~~~~~~~~~~~~~~~
  269. ``struct btf_type`` encoding requirement:
  270. * ``name_off``: 0
  271. * ``info.kind_flag``: 0
  272. * ``info.kind``: BTF_KIND_RESTRICT
  273. * ``info.vlen``: 0
  274. * ``type``: the type with ``restrict`` qualifier
  275. No additional type data follow ``btf_type``.
  276. 2.2.12 BTF_KIND_FUNC
  277. ~~~~~~~~~~~~~~~~~~~~
  278. ``struct btf_type`` encoding requirement:
  279. * ``name_off``: offset to a valid C identifier
  280. * ``info.kind_flag``: 0
  281. * ``info.kind``: BTF_KIND_FUNC
  282. * ``info.vlen``: 0
  283. * ``type``: a BTF_KIND_FUNC_PROTO type
  284. No additional type data follow ``btf_type``.
  285. A BTF_KIND_FUNC defines not a type, but a subprogram (function) whose
  286. signature is defined by ``type``. The subprogram is thus an instance of that
  287. type. The BTF_KIND_FUNC may in turn be referenced by a func_info in the
  288. :ref:`BTF_Ext_Section` (ELF) or in the arguments to :ref:`BPF_Prog_Load`
  289. (ABI).
  290. 2.2.13 BTF_KIND_FUNC_PROTO
  291. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  292. ``struct btf_type`` encoding requirement:
  293. * ``name_off``: 0
  294. * ``info.kind_flag``: 0
  295. * ``info.kind``: BTF_KIND_FUNC_PROTO
  296. * ``info.vlen``: # of parameters
  297. * ``type``: the return type
  298. ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_param``.::
  299. struct btf_param {
  300. __u32 name_off;
  301. __u32 type;
  302. };
  303. If a BTF_KIND_FUNC_PROTO type is referred by a BTF_KIND_FUNC type, then
  304. ``btf_param.name_off`` must point to a valid C identifier except for the
  305. possible last argument representing the variable argument. The btf_param.type
  306. refers to parameter type.
  307. If the function has variable arguments, the last parameter is encoded with
  308. ``name_off = 0`` and ``type = 0``.
  309. 2.2.14 BTF_KIND_VAR
  310. ~~~~~~~~~~~~~~~~~~~
  311. ``struct btf_type`` encoding requirement:
  312. * ``name_off``: offset to a valid C identifier
  313. * ``info.kind_flag``: 0
  314. * ``info.kind``: BTF_KIND_VAR
  315. * ``info.vlen``: 0
  316. * ``type``: the type of the variable
  317. ``btf_type`` is followed by a single ``struct btf_variable`` with the
  318. following data::
  319. struct btf_var {
  320. __u32 linkage;
  321. };
  322. ``struct btf_var`` encoding:
  323. * ``linkage``: currently only static variable 0, or globally allocated
  324. variable in ELF sections 1
  325. Not all type of global variables are supported by LLVM at this point.
  326. The following is currently available:
  327. * static variables with or without section attributes
  328. * global variables with section attributes
  329. The latter is for future extraction of map key/value type id's from a
  330. map definition.
  331. 2.2.15 BTF_KIND_DATASEC
  332. ~~~~~~~~~~~~~~~~~~~~~~~
  333. ``struct btf_type`` encoding requirement:
  334. * ``name_off``: offset to a valid name associated with a variable or
  335. one of .data/.bss/.rodata
  336. * ``info.kind_flag``: 0
  337. * ``info.kind``: BTF_KIND_DATASEC
  338. * ``info.vlen``: # of variables
  339. * ``size``: total section size in bytes (0 at compilation time, patched
  340. to actual size by BPF loaders such as libbpf)
  341. ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_var_secinfo``.::
  342. struct btf_var_secinfo {
  343. __u32 type;
  344. __u32 offset;
  345. __u32 size;
  346. };
  347. ``struct btf_var_secinfo`` encoding:
  348. * ``type``: the type of the BTF_KIND_VAR variable
  349. * ``offset``: the in-section offset of the variable
  350. * ``size``: the size of the variable in bytes
  351. 3. BTF Kernel API
  352. *****************
  353. The following bpf syscall command involves BTF:
  354. * BPF_BTF_LOAD: load a blob of BTF data into kernel
  355. * BPF_MAP_CREATE: map creation with btf key and value type info.
  356. * BPF_PROG_LOAD: prog load with btf function and line info.
  357. * BPF_BTF_GET_FD_BY_ID: get a btf fd
  358. * BPF_OBJ_GET_INFO_BY_FD: btf, func_info, line_info
  359. and other btf related info are returned.
  360. The workflow typically looks like:
  361. ::
  362. Application:
  363. BPF_BTF_LOAD
  364. |
  365. v
  366. BPF_MAP_CREATE and BPF_PROG_LOAD
  367. |
  368. V
  369. ......
  370. Introspection tool:
  371. ......
  372. BPF_{PROG,MAP}_GET_NEXT_ID (get prog/map id's)
  373. |
  374. V
  375. BPF_{PROG,MAP}_GET_FD_BY_ID (get a prog/map fd)
  376. |
  377. V
  378. BPF_OBJ_GET_INFO_BY_FD (get bpf_prog_info/bpf_map_info with btf_id)
  379. | |
  380. V |
  381. BPF_BTF_GET_FD_BY_ID (get btf_fd) |
  382. | |
  383. V |
  384. BPF_OBJ_GET_INFO_BY_FD (get btf) |
  385. | |
  386. V V
  387. pretty print types, dump func signatures and line info, etc.
  388. 3.1 BPF_BTF_LOAD
  389. ================
  390. Load a blob of BTF data into kernel. A blob of data, described in
  391. :ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd``
  392. is returned to a userspace.
  393. 3.2 BPF_MAP_CREATE
  394. ==================
  395. A map can be created with ``btf_fd`` and specified key/value type id.::
  396. __u32 btf_fd; /* fd pointing to a BTF type data */
  397. __u32 btf_key_type_id; /* BTF type_id of the key */
  398. __u32 btf_value_type_id; /* BTF type_id of the value */
  399. In libbpf, the map can be defined with extra annotation like below:
  400. ::
  401. struct bpf_map_def SEC("maps") btf_map = {
  402. .type = BPF_MAP_TYPE_ARRAY,
  403. .key_size = sizeof(int),
  404. .value_size = sizeof(struct ipv_counts),
  405. .max_entries = 4,
  406. };
  407. BPF_ANNOTATE_KV_PAIR(btf_map, int, struct ipv_counts);
  408. Here, the parameters for macro BPF_ANNOTATE_KV_PAIR are map name, key and
  409. value types for the map. During ELF parsing, libbpf is able to extract
  410. key/value type_id's and assign them to BPF_MAP_CREATE attributes
  411. automatically.
  412. .. _BPF_Prog_Load:
  413. 3.3 BPF_PROG_LOAD
  414. =================
  415. During prog_load, func_info and line_info can be passed to kernel with proper
  416. values for the following attributes:
  417. ::
  418. __u32 insn_cnt;
  419. __aligned_u64 insns;
  420. ......
  421. __u32 prog_btf_fd; /* fd pointing to BTF type data */
  422. __u32 func_info_rec_size; /* userspace bpf_func_info size */
  423. __aligned_u64 func_info; /* func info */
  424. __u32 func_info_cnt; /* number of bpf_func_info records */
  425. __u32 line_info_rec_size; /* userspace bpf_line_info size */
  426. __aligned_u64 line_info; /* line info */
  427. __u32 line_info_cnt; /* number of bpf_line_info records */
  428. The func_info and line_info are an array of below, respectively.::
  429. struct bpf_func_info {
  430. __u32 insn_off; /* [0, insn_cnt - 1] */
  431. __u32 type_id; /* pointing to a BTF_KIND_FUNC type */
  432. };
  433. struct bpf_line_info {
  434. __u32 insn_off; /* [0, insn_cnt - 1] */
  435. __u32 file_name_off; /* offset to string table for the filename */
  436. __u32 line_off; /* offset to string table for the source line */
  437. __u32 line_col; /* line number and column number */
  438. };
  439. func_info_rec_size is the size of each func_info record, and
  440. line_info_rec_size is the size of each line_info record. Passing the record
  441. size to kernel make it possible to extend the record itself in the future.
  442. Below are requirements for func_info:
  443. * func_info[0].insn_off must be 0.
  444. * the func_info insn_off is in strictly increasing order and matches
  445. bpf func boundaries.
  446. Below are requirements for line_info:
  447. * the first insn in each func must have a line_info record pointing to it.
  448. * the line_info insn_off is in strictly increasing order.
  449. For line_info, the line number and column number are defined as below:
  450. ::
  451. #define BPF_LINE_INFO_LINE_NUM(line_col) ((line_col) >> 10)
  452. #define BPF_LINE_INFO_LINE_COL(line_col) ((line_col) & 0x3ff)
  453. 3.4 BPF_{PROG,MAP}_GET_NEXT_ID
  454. ==============================
  455. In kernel, every loaded program, map or btf has a unique id. The id won't
  456. change during the lifetime of a program, map, or btf.
  457. The bpf syscall command BPF_{PROG,MAP}_GET_NEXT_ID returns all id's, one for
  458. each command, to user space, for bpf program or maps, respectively, so an
  459. inspection tool can inspect all programs and maps.
  460. 3.5 BPF_{PROG,MAP}_GET_FD_BY_ID
  461. ===============================
  462. An introspection tool cannot use id to get details about program or maps.
  463. A file descriptor needs to be obtained first for reference-counting purpose.
  464. 3.6 BPF_OBJ_GET_INFO_BY_FD
  465. ==========================
  466. Once a program/map fd is acquired, an introspection tool can get the detailed
  467. information from kernel about this fd, some of which are BTF-related. For
  468. example, ``bpf_map_info`` returns ``btf_id`` and key/value type ids.
  469. ``bpf_prog_info`` returns ``btf_id``, func_info, and line info for translated
  470. bpf byte codes, and jited_line_info.
  471. 3.7 BPF_BTF_GET_FD_BY_ID
  472. ========================
  473. With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf
  474. syscall command BPF_BTF_GET_FD_BY_ID can retrieve a btf fd. Then, with
  475. command BPF_OBJ_GET_INFO_BY_FD, the btf blob, originally loaded into the
  476. kernel with BPF_BTF_LOAD, can be retrieved.
  477. With the btf blob, ``bpf_map_info``, and ``bpf_prog_info``, an introspection
  478. tool has full btf knowledge and is able to pretty print map key/values, dump
  479. func signatures and line info, along with byte/jit codes.
  480. 4. ELF File Format Interface
  481. ****************************
  482. 4.1 .BTF section
  483. ================
  484. The .BTF section contains type and string data. The format of this section is
  485. same as the one describe in :ref:`BTF_Type_String`.
  486. .. _BTF_Ext_Section:
  487. 4.2 .BTF.ext section
  488. ====================
  489. The .BTF.ext section encodes func_info and line_info which needs loader
  490. manipulation before loading into the kernel.
  491. The specification for .BTF.ext section is defined at ``tools/lib/bpf/btf.h``
  492. and ``tools/lib/bpf/btf.c``.
  493. The current header of .BTF.ext section::
  494. struct btf_ext_header {
  495. __u16 magic;
  496. __u8 version;
  497. __u8 flags;
  498. __u32 hdr_len;
  499. /* All offsets are in bytes relative to the end of this header */
  500. __u32 func_info_off;
  501. __u32 func_info_len;
  502. __u32 line_info_off;
  503. __u32 line_info_len;
  504. };
  505. It is very similar to .BTF section. Instead of type/string section, it
  506. contains func_info and line_info section. See :ref:`BPF_Prog_Load` for details
  507. about func_info and line_info record format.
  508. The func_info is organized as below.::
  509. func_info_rec_size
  510. btf_ext_info_sec for section #1 /* func_info for section #1 */
  511. btf_ext_info_sec for section #2 /* func_info for section #2 */
  512. ...
  513. ``func_info_rec_size`` specifies the size of ``bpf_func_info`` structure when
  514. .BTF.ext is generated. ``btf_ext_info_sec``, defined below, is a collection of
  515. func_info for each specific ELF section.::
  516. struct btf_ext_info_sec {
  517. __u32 sec_name_off; /* offset to section name */
  518. __u32 num_info;
  519. /* Followed by num_info * record_size number of bytes */
  520. __u8 data[0];
  521. };
  522. Here, num_info must be greater than 0.
  523. The line_info is organized as below.::
  524. line_info_rec_size
  525. btf_ext_info_sec for section #1 /* line_info for section #1 */
  526. btf_ext_info_sec for section #2 /* line_info for section #2 */
  527. ...
  528. ``line_info_rec_size`` specifies the size of ``bpf_line_info`` structure when
  529. .BTF.ext is generated.
  530. The interpretation of ``bpf_func_info->insn_off`` and
  531. ``bpf_line_info->insn_off`` is different between kernel API and ELF API. For
  532. kernel API, the ``insn_off`` is the instruction offset in the unit of ``struct
  533. bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the
  534. beginning of section (``btf_ext_info_sec->sec_name_off``).
  535. 4.2 .BTF_ids section
  536. ====================
  537. The .BTF_ids section encodes BTF ID values that are used within the kernel.
  538. This section is created during the kernel compilation with the help of
  539. macros defined in ``include/linux/btf_ids.h`` header file. Kernel code can
  540. use them to create lists and sets (sorted lists) of BTF ID values.
  541. The ``BTF_ID_LIST`` and ``BTF_ID`` macros define unsorted list of BTF ID values,
  542. with following syntax::
  543. BTF_ID_LIST(list)
  544. BTF_ID(type1, name1)
  545. BTF_ID(type2, name2)
  546. resulting in following layout in .BTF_ids section::
  547. __BTF_ID__type1__name1__1:
  548. .zero 4
  549. __BTF_ID__type2__name2__2:
  550. .zero 4
  551. The ``u32 list[];`` variable is defined to access the list.
  552. The ``BTF_ID_UNUSED`` macro defines 4 zero bytes. It's used when we
  553. want to define unused entry in BTF_ID_LIST, like::
  554. BTF_ID_LIST(bpf_skb_output_btf_ids)
  555. BTF_ID(struct, sk_buff)
  556. BTF_ID_UNUSED
  557. BTF_ID(struct, task_struct)
  558. The ``BTF_SET_START/END`` macros pair defines sorted list of BTF ID values
  559. and their count, with following syntax::
  560. BTF_SET_START(set)
  561. BTF_ID(type1, name1)
  562. BTF_ID(type2, name2)
  563. BTF_SET_END(set)
  564. resulting in following layout in .BTF_ids section::
  565. __BTF_ID__set__set:
  566. .zero 4
  567. __BTF_ID__type1__name1__3:
  568. .zero 4
  569. __BTF_ID__type2__name2__4:
  570. .zero 4
  571. The ``struct btf_id_set set;`` variable is defined to access the list.
  572. The ``typeX`` name can be one of following::
  573. struct, union, typedef, func
  574. and is used as a filter when resolving the BTF ID value.
  575. All the BTF ID lists and sets are compiled in the .BTF_ids section and
  576. resolved during the linking phase of kernel build by ``resolve_btfids`` tool.
  577. 5. Using BTF
  578. ************
  579. 5.1 bpftool map pretty print
  580. ============================
  581. With BTF, the map key/value can be printed based on fields rather than simply
  582. raw bytes. This is especially valuable for large structure or if your data
  583. structure has bitfields. For example, for the following map,::
  584. enum A { A1, A2, A3, A4, A5 };
  585. typedef enum A ___A;
  586. struct tmp_t {
  587. char a1:4;
  588. int a2:4;
  589. int :4;
  590. __u32 a3:4;
  591. int b;
  592. ___A b1:4;
  593. enum A b2:4;
  594. };
  595. struct bpf_map_def SEC("maps") tmpmap = {
  596. .type = BPF_MAP_TYPE_ARRAY,
  597. .key_size = sizeof(__u32),
  598. .value_size = sizeof(struct tmp_t),
  599. .max_entries = 1,
  600. };
  601. BPF_ANNOTATE_KV_PAIR(tmpmap, int, struct tmp_t);
  602. bpftool is able to pretty print like below:
  603. ::
  604. [{
  605. "key": 0,
  606. "value": {
  607. "a1": 0x2,
  608. "a2": 0x4,
  609. "a3": 0x6,
  610. "b": 7,
  611. "b1": 0x8,
  612. "b2": 0xa
  613. }
  614. }
  615. ]
  616. 5.2 bpftool prog dump
  617. =====================
  618. The following is an example showing how func_info and line_info can help prog
  619. dump with better kernel symbol names, function prototypes and line
  620. information.::
  621. $ bpftool prog dump jited pinned /sys/fs/bpf/test_btf_haskv
  622. [...]
  623. int test_long_fname_2(struct dummy_tracepoint_args * arg):
  624. bpf_prog_44a040bf25481309_test_long_fname_2:
  625. ; static int test_long_fname_2(struct dummy_tracepoint_args *arg)
  626. 0: push %rbp
  627. 1: mov %rsp,%rbp
  628. 4: sub $0x30,%rsp
  629. b: sub $0x28,%rbp
  630. f: mov %rbx,0x0(%rbp)
  631. 13: mov %r13,0x8(%rbp)
  632. 17: mov %r14,0x10(%rbp)
  633. 1b: mov %r15,0x18(%rbp)
  634. 1f: xor %eax,%eax
  635. 21: mov %rax,0x20(%rbp)
  636. 25: xor %esi,%esi
  637. ; int key = 0;
  638. 27: mov %esi,-0x4(%rbp)
  639. ; if (!arg->sock)
  640. 2a: mov 0x8(%rdi),%rdi
  641. ; if (!arg->sock)
  642. 2e: cmp $0x0,%rdi
  643. 32: je 0x0000000000000070
  644. 34: mov %rbp,%rsi
  645. ; counts = bpf_map_lookup_elem(&btf_map, &key);
  646. [...]
  647. 5.3 Verifier Log
  648. ================
  649. The following is an example of how line_info can help debugging verification
  650. failure.::
  651. /* The code at tools/testing/selftests/bpf/test_xdp_noinline.c
  652. * is modified as below.
  653. */
  654. data = (void *)(long)xdp->data;
  655. data_end = (void *)(long)xdp->data_end;
  656. /*
  657. if (data + 4 > data_end)
  658. return XDP_DROP;
  659. */
  660. *(u32 *)data = dst->dst;
  661. $ bpftool prog load ./test_xdp_noinline.o /sys/fs/bpf/test_xdp_noinline type xdp
  662. ; data = (void *)(long)xdp->data;
  663. 224: (79) r2 = *(u64 *)(r10 -112)
  664. 225: (61) r2 = *(u32 *)(r2 +0)
  665. ; *(u32 *)data = dst->dst;
  666. 226: (63) *(u32 *)(r2 +0) = r1
  667. invalid access to packet, off=0 size=4, R2(id=0,off=0,r=0)
  668. R2 offset is outside of the packet
  669. 6. BTF Generation
  670. *****************
  671. You need latest pahole
  672. https://git.kernel.org/pub/scm/devel/pahole/pahole.git/
  673. or llvm (8.0 or later). The pahole acts as a dwarf2btf converter. It doesn't
  674. support .BTF.ext and btf BTF_KIND_FUNC type yet. For example,::
  675. -bash-4.4$ cat t.c
  676. struct t {
  677. int a:2;
  678. int b:3;
  679. int c:2;
  680. } g;
  681. -bash-4.4$ gcc -c -O2 -g t.c
  682. -bash-4.4$ pahole -JV t.o
  683. File t.o:
  684. [1] STRUCT t kind_flag=1 size=4 vlen=3
  685. a type_id=2 bitfield_size=2 bits_offset=0
  686. b type_id=2 bitfield_size=3 bits_offset=2
  687. c type_id=2 bitfield_size=2 bits_offset=5
  688. [2] INT int size=4 bit_offset=0 nr_bits=32 encoding=SIGNED
  689. The llvm is able to generate .BTF and .BTF.ext directly with -g for bpf target
  690. only. The assembly code (-S) is able to show the BTF encoding in assembly
  691. format.::
  692. -bash-4.4$ cat t2.c
  693. typedef int __int32;
  694. struct t2 {
  695. int a2;
  696. int (*f2)(char q1, __int32 q2, ...);
  697. int (*f3)();
  698. } g2;
  699. int main() { return 0; }
  700. int test() { return 0; }
  701. -bash-4.4$ clang -c -g -O2 -target bpf t2.c
  702. -bash-4.4$ readelf -S t2.o
  703. ......
  704. [ 8] .BTF PROGBITS 0000000000000000 00000247
  705. 000000000000016e 0000000000000000 0 0 1
  706. [ 9] .BTF.ext PROGBITS 0000000000000000 000003b5
  707. 0000000000000060 0000000000000000 0 0 1
  708. [10] .rel.BTF.ext REL 0000000000000000 000007e0
  709. 0000000000000040 0000000000000010 16 9 8
  710. ......
  711. -bash-4.4$ clang -S -g -O2 -target bpf t2.c
  712. -bash-4.4$ cat t2.s
  713. ......
  714. .section .BTF,"",@progbits
  715. .short 60319 # 0xeb9f
  716. .byte 1
  717. .byte 0
  718. .long 24
  719. .long 0
  720. .long 220
  721. .long 220
  722. .long 122
  723. .long 0 # BTF_KIND_FUNC_PROTO(id = 1)
  724. .long 218103808 # 0xd000000
  725. .long 2
  726. .long 83 # BTF_KIND_INT(id = 2)
  727. .long 16777216 # 0x1000000
  728. .long 4
  729. .long 16777248 # 0x1000020
  730. ......
  731. .byte 0 # string offset=0
  732. .ascii ".text" # string offset=1
  733. .byte 0
  734. .ascii "/home/yhs/tmp-pahole/t2.c" # string offset=7
  735. .byte 0
  736. .ascii "int main() { return 0; }" # string offset=33
  737. .byte 0
  738. .ascii "int test() { return 0; }" # string offset=58
  739. .byte 0
  740. .ascii "int" # string offset=83
  741. ......
  742. .section .BTF.ext,"",@progbits
  743. .short 60319 # 0xeb9f
  744. .byte 1
  745. .byte 0
  746. .long 24
  747. .long 0
  748. .long 28
  749. .long 28
  750. .long 44
  751. .long 8 # FuncInfo
  752. .long 1 # FuncInfo section string offset=1
  753. .long 2
  754. .long .Lfunc_begin0
  755. .long 3
  756. .long .Lfunc_begin1
  757. .long 5
  758. .long 16 # LineInfo
  759. .long 1 # LineInfo section string offset=1
  760. .long 2
  761. .long .Ltmp0
  762. .long 7
  763. .long 33
  764. .long 7182 # Line 7 Col 14
  765. .long .Ltmp3
  766. .long 7
  767. .long 58
  768. .long 8206 # Line 8 Col 14
  769. 7. Testing
  770. **********
  771. Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests.