154222838SJesper Dangaard Brouer================================= 254222838SJesper Dangaard BrouerHOWTO interact with BPF subsystem 354222838SJesper Dangaard Brouer================================= 454222838SJesper Dangaard Brouer 5192092faSJesper Dangaard BrouerThis document provides information for the BPF subsystem about various 6192092faSJesper Dangaard Brouerworkflows related to reporting bugs, submitting patches, and queueing 7192092faSJesper Dangaard Brouerpatches for stable kernels. 8192092faSJesper Dangaard Brouer 9192092faSJesper Dangaard BrouerFor general information about submitting patches, please refer to 1054222838SJesper Dangaard Brouer`Documentation/process/`_. This document only describes additional specifics 11192092faSJesper Dangaard Brouerrelated to BPF. 12192092faSJesper Dangaard Brouer 1354222838SJesper Dangaard Brouer.. contents:: 1454222838SJesper Dangaard Brouer :local: 1554222838SJesper Dangaard Brouer :depth: 2 1654222838SJesper Dangaard Brouer 1754222838SJesper Dangaard BrouerReporting bugs 1854222838SJesper Dangaard Brouer============== 19192092faSJesper Dangaard Brouer 20192092faSJesper Dangaard BrouerQ: How do I report bugs for BPF kernel code? 2154222838SJesper Dangaard Brouer-------------------------------------------- 22192092faSJesper Dangaard BrouerA: Since all BPF kernel development as well as bpftool and iproute2 BPF 23e42da4c6SYonghong Songloader development happens through the bpf kernel mailing list, 24192092faSJesper Dangaard Brouerplease report any found issues around BPF to the following mailing 25192092faSJesper Dangaard Brouerlist: 26192092faSJesper Dangaard Brouer 27e42da4c6SYonghong Song bpf@vger.kernel.org 28192092faSJesper Dangaard Brouer 29192092faSJesper Dangaard BrouerThis may also include issues related to XDP, BPF tracing, etc. 30192092faSJesper Dangaard Brouer 31192092faSJesper Dangaard BrouerGiven netdev has a high volume of traffic, please also add the BPF 3264ef3ddfSTiezhu Yangmaintainers to Cc (from kernel ``MAINTAINERS`` file): 33192092faSJesper Dangaard Brouer 3454222838SJesper Dangaard Brouer* Alexei Starovoitov <ast@kernel.org> 3554222838SJesper Dangaard Brouer* Daniel Borkmann <daniel@iogearbox.net> 36192092faSJesper Dangaard Brouer 37192092faSJesper Dangaard BrouerIn case a buggy commit has already been identified, make sure to keep 38192092faSJesper Dangaard Brouerthe actual commit authors in Cc as well for the report. They can 39192092faSJesper Dangaard Brouertypically be identified through the kernel's git tree. 40192092faSJesper Dangaard Brouer 4154222838SJesper Dangaard Brouer**Please do NOT report BPF issues to bugzilla.kernel.org since it 4254222838SJesper Dangaard Broueris a guarantee that the reported issue will be overlooked.** 43192092faSJesper Dangaard Brouer 4454222838SJesper Dangaard BrouerSubmitting patches 4554222838SJesper Dangaard Brouer================== 46192092faSJesper Dangaard Brouer 47*26a9b433SDaniel MüllerQ: How do I run BPF CI on my changes before sending them out for review? 48*26a9b433SDaniel Müller------------------------------------------------------------------------ 49*26a9b433SDaniel MüllerA: BPF CI is GitHub based and hosted at https://github.com/kernel-patches/bpf. 50*26a9b433SDaniel MüllerWhile GitHub also provides a CLI that can be used to accomplish the same 51*26a9b433SDaniel Müllerresults, here we focus on the UI based workflow. 52*26a9b433SDaniel Müller 53*26a9b433SDaniel MüllerThe following steps lay out how to start a CI run for your patches: 54*26a9b433SDaniel Müller- Create a fork of the aforementioned repository in your own account (one time 55*26a9b433SDaniel Müller action) 56*26a9b433SDaniel Müller- Clone the fork locally, check out a new branch tracking either the bpf-next 57*26a9b433SDaniel Müller or bpf branch, and apply your to-be-tested patches on top of it 58*26a9b433SDaniel Müller- Push the local branch to your fork and create a pull request against 59*26a9b433SDaniel Müller kernel-patches/bpf's bpf-next_base or bpf_base branch, respectively 60*26a9b433SDaniel Müller 61*26a9b433SDaniel MüllerShortly after the pull request has been created, the CI workflow will run. Note 62*26a9b433SDaniel Müllerthat capacity is shared with patches submitted upstream being checked and so 63*26a9b433SDaniel Müllerdepending on utilization the run can take a while to finish. 64*26a9b433SDaniel Müller 65*26a9b433SDaniel MüllerNote furthermore that both base branches (bpf-next_base and bpf_base) will be 66*26a9b433SDaniel Müllerupdated as patches are pushed to the respective upstream branches they track. As 67*26a9b433SDaniel Müllersuch, your patch set will automatically (be attempted to) be rebased as well. 68*26a9b433SDaniel MüllerThis behavior can result in a CI run being aborted and restarted with the new 69*26a9b433SDaniel Müllerbase line. 70*26a9b433SDaniel Müller 71192092faSJesper Dangaard BrouerQ: To which mailing list do I need to submit my BPF patches? 7254222838SJesper Dangaard Brouer------------------------------------------------------------ 73e42da4c6SYonghong SongA: Please submit your BPF patches to the bpf kernel mailing list: 74192092faSJesper Dangaard Brouer 75e42da4c6SYonghong Song bpf@vger.kernel.org 76192092faSJesper Dangaard Brouer 77192092faSJesper Dangaard BrouerIn case your patch has changes in various different subsystems (e.g. 78e42da4c6SYonghong Songnetworking, tracing, security, etc), make sure to Cc the related kernel mailing 79192092faSJesper Dangaard Brouerlists and maintainers from there as well, so they are able to review 80192092faSJesper Dangaard Brouerthe changes and provide their Acked-by's to the patches. 81192092faSJesper Dangaard Brouer 82192092faSJesper Dangaard BrouerQ: Where can I find patches currently under discussion for BPF subsystem? 8354222838SJesper Dangaard Brouer------------------------------------------------------------------------- 84192092faSJesper Dangaard BrouerA: All patches that are Cc'ed to netdev are queued for review under netdev 85192092faSJesper Dangaard Brouerpatchwork project: 86192092faSJesper Dangaard Brouer 87ebb034b1SAlexei Starovoitov https://patchwork.kernel.org/project/netdevbpf/list/ 88192092faSJesper Dangaard Brouer 89192092faSJesper Dangaard BrouerThose patches which target BPF, are assigned to a 'bpf' delegate for 90192092faSJesper Dangaard Brouerfurther processing from BPF maintainers. The current queue with 91192092faSJesper Dangaard Brouerpatches under review can be found at: 92192092faSJesper Dangaard Brouer 93ebb034b1SAlexei Starovoitov https://patchwork.kernel.org/project/netdevbpf/list/?delegate=121173 94192092faSJesper Dangaard Brouer 95192092faSJesper Dangaard BrouerOnce the patches have been reviewed by the BPF community as a whole 96192092faSJesper Dangaard Brouerand approved by the BPF maintainers, their status in patchwork will be 97192092faSJesper Dangaard Brouerchanged to 'Accepted' and the submitter will be notified by mail. This 98192092faSJesper Dangaard Brouermeans that the patches look good from a BPF perspective and have been 99192092faSJesper Dangaard Brouerapplied to one of the two BPF kernel trees. 100192092faSJesper Dangaard Brouer 101192092faSJesper Dangaard BrouerIn case feedback from the community requires a respin of the patches, 102192092faSJesper Dangaard Brouertheir status in patchwork will be set to 'Changes Requested', and purged 103192092faSJesper Dangaard Brouerfrom the current review queue. Likewise for cases where patches would 104192092faSJesper Dangaard Brouerget rejected or are not applicable to the BPF trees (but assigned to 105192092faSJesper Dangaard Brouerthe 'bpf' delegate). 106192092faSJesper Dangaard Brouer 107192092faSJesper Dangaard BrouerQ: How do the changes make their way into Linux? 10854222838SJesper Dangaard Brouer------------------------------------------------ 109192092faSJesper Dangaard BrouerA: There are two BPF kernel trees (git repositories). Once patches have 110192092faSJesper Dangaard Brouerbeen accepted by the BPF maintainers, they will be applied to one 111192092faSJesper Dangaard Brouerof the two BPF trees: 112192092faSJesper Dangaard Brouer 11354222838SJesper Dangaard Brouer * https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf.git/ 11454222838SJesper Dangaard Brouer * https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/ 115192092faSJesper Dangaard Brouer 116192092faSJesper Dangaard BrouerThe bpf tree itself is for fixes only, whereas bpf-next for features, 117192092faSJesper Dangaard Brouercleanups or other kind of improvements ("next-like" content). This is 118192092faSJesper Dangaard Broueranalogous to net and net-next trees for networking. Both bpf and 119192092faSJesper Dangaard Brouerbpf-next will only have a master branch in order to simplify against 120192092faSJesper Dangaard Brouerwhich branch patches should get rebased to. 121192092faSJesper Dangaard Brouer 122192092faSJesper Dangaard BrouerAccumulated BPF patches in the bpf tree will regularly get pulled 123192092faSJesper Dangaard Brouerinto the net kernel tree. Likewise, accumulated BPF patches accepted 124192092faSJesper Dangaard Brouerinto the bpf-next tree will make their way into net-next tree. net and 125192092faSJesper Dangaard Brouernet-next are both run by David S. Miller. From there, they will go 126192092faSJesper Dangaard Brouerinto the kernel mainline tree run by Linus Torvalds. To read up on the 127192092faSJesper Dangaard Brouerprocess of net and net-next being merged into the mainline tree, see 128287f4fa9STobin C. Hardingthe :ref:`netdev-FAQ` 129192092faSJesper Dangaard Brouer 130287f4fa9STobin C. Harding 131192092faSJesper Dangaard Brouer 132192092faSJesper Dangaard BrouerOccasionally, to prevent merge conflicts, we might send pull requests 133192092faSJesper Dangaard Brouerto other trees (e.g. tracing) with a small subset of the patches, but 134192092faSJesper Dangaard Brouernet and net-next are always the main trees targeted for integration. 135192092faSJesper Dangaard Brouer 136192092faSJesper Dangaard BrouerThe pull requests will contain a high-level summary of the accumulated 137192092faSJesper Dangaard Brouerpatches and can be searched on netdev kernel mailing list through the 13854222838SJesper Dangaard Brouerfollowing subject lines (``yyyy-mm-dd`` is the date of the pull 13954222838SJesper Dangaard Brouerrequest):: 140192092faSJesper Dangaard Brouer 141192092faSJesper Dangaard Brouer pull-request: bpf yyyy-mm-dd 142192092faSJesper Dangaard Brouer pull-request: bpf-next yyyy-mm-dd 143192092faSJesper Dangaard Brouer 14454222838SJesper Dangaard BrouerQ: How do I indicate which tree (bpf vs. bpf-next) my patch should be applied to? 14554222838SJesper Dangaard Brouer--------------------------------------------------------------------------------- 146192092faSJesper Dangaard Brouer 147287f4fa9STobin C. HardingA: The process is the very same as described in the :ref:`netdev-FAQ`, 148287f4fa9STobin C. Hardingso please read up on it. The subject line must indicate whether the 149192092faSJesper Dangaard Brouerpatch is a fix or rather "next-like" content in order to let the 150192092faSJesper Dangaard Brouermaintainers know whether it is targeted at bpf or bpf-next. 151192092faSJesper Dangaard Brouer 152192092faSJesper Dangaard BrouerFor fixes eventually landing in bpf -> net tree, the subject must 15354222838SJesper Dangaard Brouerlook like:: 154192092faSJesper Dangaard Brouer 155192092faSJesper Dangaard Brouer git format-patch --subject-prefix='PATCH bpf' start..finish 156192092faSJesper Dangaard Brouer 157192092faSJesper Dangaard BrouerFor features/improvements/etc that should eventually land in 15854222838SJesper Dangaard Brouerbpf-next -> net-next, the subject must look like:: 159192092faSJesper Dangaard Brouer 160192092faSJesper Dangaard Brouer git format-patch --subject-prefix='PATCH bpf-next' start..finish 161192092faSJesper Dangaard Brouer 162192092faSJesper Dangaard BrouerIf unsure whether the patch or patch series should go into bpf 163192092faSJesper Dangaard Broueror net directly, or bpf-next or net-next directly, it is not a 164192092faSJesper Dangaard Brouerproblem either if the subject line says net or net-next as target. 165192092faSJesper Dangaard BrouerIt is eventually up to the maintainers to do the delegation of 166192092faSJesper Dangaard Brouerthe patches. 167192092faSJesper Dangaard Brouer 168192092faSJesper Dangaard BrouerIf it is clear that patches should go into bpf or bpf-next tree, 169192092faSJesper Dangaard Brouerplease make sure to rebase the patches against those trees in 170192092faSJesper Dangaard Brouerorder to reduce potential conflicts. 171192092faSJesper Dangaard Brouer 172192092faSJesper Dangaard BrouerIn case the patch or patch series has to be reworked and sent out 173192092faSJesper Dangaard Broueragain in a second or later revision, it is also required to add a 17454222838SJesper Dangaard Brouerversion number (``v2``, ``v3``, ...) into the subject prefix:: 175192092faSJesper Dangaard Brouer 1764d0d1673SJianlin Lv git format-patch --subject-prefix='PATCH bpf-next v2' start..finish 177192092faSJesper Dangaard Brouer 178192092faSJesper Dangaard BrouerWhen changes have been requested to the patch series, always send the 179192092faSJesper Dangaard Brouerwhole patch series again with the feedback incorporated (never send 180192092faSJesper Dangaard Brouerindividual diffs on top of the old series). 181192092faSJesper Dangaard Brouer 182192092faSJesper Dangaard BrouerQ: What does it mean when a patch gets applied to bpf or bpf-next tree? 18354222838SJesper Dangaard Brouer----------------------------------------------------------------------- 184192092faSJesper Dangaard BrouerA: It means that the patch looks good for mainline inclusion from 185192092faSJesper Dangaard Brouera BPF point of view. 186192092faSJesper Dangaard Brouer 187192092faSJesper Dangaard BrouerBe aware that this is not a final verdict that the patch will 188192092faSJesper Dangaard Brouerautomatically get accepted into net or net-next trees eventually: 189192092faSJesper Dangaard Brouer 190e42da4c6SYonghong SongOn the bpf kernel mailing list reviews can come in at any point 191192092faSJesper Dangaard Brouerin time. If discussions around a patch conclude that they cannot 192192092faSJesper Dangaard Brouerget included as-is, we will either apply a follow-up fix or drop 193192092faSJesper Dangaard Brouerthem from the trees entirely. Therefore, we also reserve to rebase 194192092faSJesper Dangaard Brouerthe trees when deemed necessary. After all, the purpose of the tree 19554222838SJesper Dangaard Broueris to: 19654222838SJesper Dangaard Brouer 19754222838SJesper Dangaard Broueri) accumulate and stage BPF patches for integration into trees 19854222838SJesper Dangaard Brouer like net and net-next, and 19954222838SJesper Dangaard Brouer 20054222838SJesper Dangaard Brouerii) run extensive BPF test suite and 201192092faSJesper Dangaard Brouer workloads on the patches before they make their way any further. 202192092faSJesper Dangaard Brouer 203192092faSJesper Dangaard BrouerOnce the BPF pull request was accepted by David S. Miller, then 204192092faSJesper Dangaard Brouerthe patches end up in net or net-next tree, respectively, and 205192092faSJesper Dangaard Brouermake their way from there further into mainline. Again, see the 206287f4fa9STobin C. Harding:ref:`netdev-FAQ` for additional information e.g. on how often they are 207192092faSJesper Dangaard Brouermerged to mainline. 208192092faSJesper Dangaard Brouer 209192092faSJesper Dangaard BrouerQ: How long do I need to wait for feedback on my BPF patches? 21054222838SJesper Dangaard Brouer------------------------------------------------------------- 211192092faSJesper Dangaard BrouerA: We try to keep the latency low. The usual time to feedback will 212192092faSJesper Dangaard Brouerbe around 2 or 3 business days. It may vary depending on the 213192092faSJesper Dangaard Brouercomplexity of changes and current patch load. 214192092faSJesper Dangaard Brouer 21554222838SJesper Dangaard BrouerQ: How often do you send pull requests to major kernel trees like net or net-next? 21654222838SJesper Dangaard Brouer---------------------------------------------------------------------------------- 217192092faSJesper Dangaard Brouer 218192092faSJesper Dangaard BrouerA: Pull requests will be sent out rather often in order to not 219192092faSJesper Dangaard Broueraccumulate too many patches in bpf or bpf-next. 220192092faSJesper Dangaard Brouer 221192092faSJesper Dangaard BrouerAs a rule of thumb, expect pull requests for each tree regularly 222192092faSJesper Dangaard Brouerat the end of the week. In some cases pull requests could additionally 223192092faSJesper Dangaard Brouercome also in the middle of the week depending on the current patch 224192092faSJesper Dangaard Brouerload or urgency. 225192092faSJesper Dangaard Brouer 226192092faSJesper Dangaard BrouerQ: Are patches applied to bpf-next when the merge window is open? 22754222838SJesper Dangaard Brouer----------------------------------------------------------------- 228192092faSJesper Dangaard BrouerA: For the time when the merge window is open, bpf-next will not be 229192092faSJesper Dangaard Brouerprocessed. This is roughly analogous to net-next patch processing, 230287f4fa9STobin C. Hardingso feel free to read up on the :ref:`netdev-FAQ` about further details. 231192092faSJesper Dangaard Brouer 232192092faSJesper Dangaard BrouerDuring those two weeks of merge window, we might ask you to resend 233192092faSJesper Dangaard Broueryour patch series once bpf-next is open again. Once Linus released 23454222838SJesper Dangaard Brouera ``v*-rc1`` after the merge window, we continue processing of bpf-next. 235192092faSJesper Dangaard Brouer 236192092faSJesper Dangaard BrouerFor non-subscribers to kernel mailing lists, there is also a status 237192092faSJesper Dangaard Brouerpage run by David S. Miller on net-next that provides guidance: 238192092faSJesper Dangaard Brouer 239192092faSJesper Dangaard Brouer http://vger.kernel.org/~davem/net-next.html 240192092faSJesper Dangaard Brouer 24154222838SJesper Dangaard BrouerQ: Verifier changes and test cases 24254222838SJesper Dangaard Brouer---------------------------------- 243192092faSJesper Dangaard BrouerQ: I made a BPF verifier change, do I need to add test cases for 24454222838SJesper Dangaard BrouerBPF kernel selftests_? 245192092faSJesper Dangaard Brouer 246192092faSJesper Dangaard BrouerA: If the patch has changes to the behavior of the verifier, then yes, 247192092faSJesper Dangaard Brouerit is absolutely necessary to add test cases to the BPF kernel 24854222838SJesper Dangaard Brouerselftests_ suite. If they are not present and we think they are 249192092faSJesper Dangaard Brouerneeded, then we might ask for them before accepting any changes. 250192092faSJesper Dangaard Brouer 251192092faSJesper Dangaard BrouerIn particular, test_verifier.c is tracking a high number of BPF test 252192092faSJesper Dangaard Brouercases, including a lot of corner cases that LLVM BPF back end may 253192092faSJesper Dangaard Brouergenerate out of the restricted C code. Thus, adding test cases is 254192092faSJesper Dangaard Brouerabsolutely crucial to make sure future changes do not accidentally 255192092faSJesper Dangaard Broueraffect prior use-cases. Thus, treat those test cases as: verifier 256192092faSJesper Dangaard Brouerbehavior that is not tracked in test_verifier.c could potentially 257192092faSJesper Dangaard Brouerbe subject to change. 258192092faSJesper Dangaard Brouer 25954222838SJesper Dangaard BrouerQ: samples/bpf preference vs selftests? 26054222838SJesper Dangaard Brouer--------------------------------------- 26164ef3ddfSTiezhu YangQ: When should I add code to ``samples/bpf/`` and when to BPF kernel 26254222838SJesper Dangaard Brouerselftests_? 263192092faSJesper Dangaard Brouer 26454222838SJesper Dangaard BrouerA: In general, we prefer additions to BPF kernel selftests_ rather than 26564ef3ddfSTiezhu Yang``samples/bpf/``. The rationale is very simple: kernel selftests are 266192092faSJesper Dangaard Brouerregularly run by various bots to test for kernel regressions. 267192092faSJesper Dangaard Brouer 268192092faSJesper Dangaard BrouerThe more test cases we add to BPF selftests, the better the coverage 269192092faSJesper Dangaard Brouerand the less likely it is that those could accidentally break. It is 270192092faSJesper Dangaard Brouernot that BPF kernel selftests cannot demo how a specific feature can 271192092faSJesper Dangaard Brouerbe used. 272192092faSJesper Dangaard Brouer 27364ef3ddfSTiezhu YangThat said, ``samples/bpf/`` may be a good place for people to get started, 274192092faSJesper Dangaard Brouerso it might be advisable that simple demos of features could go into 27564ef3ddfSTiezhu Yang``samples/bpf/``, but advanced functional and corner-case testing rather 276192092faSJesper Dangaard Brouerinto kernel selftests. 277192092faSJesper Dangaard Brouer 278192092faSJesper Dangaard BrouerIf your sample looks like a test case, then go for BPF kernel selftests 279192092faSJesper Dangaard Brouerinstead! 280192092faSJesper Dangaard Brouer 281192092faSJesper Dangaard BrouerQ: When should I add code to the bpftool? 28254222838SJesper Dangaard Brouer----------------------------------------- 283192092faSJesper Dangaard BrouerA: The main purpose of bpftool (under tools/bpf/bpftool/) is to provide 284192092faSJesper Dangaard Brouera central user space tool for debugging and introspection of BPF programs 285192092faSJesper Dangaard Brouerand maps that are active in the kernel. If UAPI changes related to BPF 286192092faSJesper Dangaard Brouerenable for dumping additional information of programs or maps, then 287192092faSJesper Dangaard Brouerbpftool should be extended as well to support dumping them. 288192092faSJesper Dangaard Brouer 289192092faSJesper Dangaard BrouerQ: When should I add code to iproute2's BPF loader? 29054222838SJesper Dangaard Brouer--------------------------------------------------- 29154222838SJesper Dangaard BrouerA: For UAPI changes related to the XDP or tc layer (e.g. ``cls_bpf``), 29254222838SJesper Dangaard Brouerthe convention is that those control-path related changes are added to 293192092faSJesper Dangaard Broueriproute2's BPF loader as well from user space side. This is not only 294192092faSJesper Dangaard Broueruseful to have UAPI changes properly designed to be usable, but also 295192092faSJesper Dangaard Brouerto make those changes available to a wider user base of major 296192092faSJesper Dangaard Brouerdownstream distributions. 297192092faSJesper Dangaard Brouer 298192092faSJesper Dangaard BrouerQ: Do you accept patches as well for iproute2's BPF loader? 29954222838SJesper Dangaard Brouer----------------------------------------------------------- 300192092faSJesper Dangaard BrouerA: Patches for the iproute2's BPF loader have to be sent to: 301192092faSJesper Dangaard Brouer 302192092faSJesper Dangaard Brouer netdev@vger.kernel.org 303192092faSJesper Dangaard Brouer 304192092faSJesper Dangaard BrouerWhile those patches are not processed by the BPF kernel maintainers, 305192092faSJesper Dangaard Brouerplease keep them in Cc as well, so they can be reviewed. 306192092faSJesper Dangaard Brouer 307192092faSJesper Dangaard BrouerThe official git repository for iproute2 is run by Stephen Hemminger 308192092faSJesper Dangaard Brouerand can be found at: 309192092faSJesper Dangaard Brouer 310192092faSJesper Dangaard Brouer https://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git/ 311192092faSJesper Dangaard Brouer 31254222838SJesper Dangaard BrouerThe patches need to have a subject prefix of '``[PATCH iproute2 31354222838SJesper Dangaard Brouermaster]``' or '``[PATCH iproute2 net-next]``'. '``master``' or 31454222838SJesper Dangaard Brouer'``net-next``' describes the target branch where the patch should be 31554222838SJesper Dangaard Brouerapplied to. Meaning, if kernel changes went into the net-next kernel 31654222838SJesper Dangaard Brouertree, then the related iproute2 changes need to go into the iproute2 31754222838SJesper Dangaard Brouernet-next branch, otherwise they can be targeted at master branch. The 31854222838SJesper Dangaard Broueriproute2 net-next branch will get merged into the master branch after 31954222838SJesper Dangaard Brouerthe current iproute2 version from master has been released. 320192092faSJesper Dangaard Brouer 321192092faSJesper Dangaard BrouerLike BPF, the patches end up in patchwork under the netdev project and 322192092faSJesper Dangaard Brouerare delegated to 'shemminger' for further processing: 323192092faSJesper Dangaard Brouer 324192092faSJesper Dangaard Brouer http://patchwork.ozlabs.org/project/netdev/list/?delegate=389 325192092faSJesper Dangaard Brouer 326192092faSJesper Dangaard BrouerQ: What is the minimum requirement before I submit my BPF patches? 32754222838SJesper Dangaard Brouer------------------------------------------------------------------ 328192092faSJesper Dangaard BrouerA: When submitting patches, always take the time and properly test your 329192092faSJesper Dangaard Brouerpatches *prior* to submission. Never rush them! If maintainers find 330192092faSJesper Dangaard Brouerthat your patches have not been properly tested, it is a good way to 331192092faSJesper Dangaard Brouerget them grumpy. Testing patch submissions is a hard requirement! 332192092faSJesper Dangaard Brouer 33354222838SJesper Dangaard BrouerNote, fixes that go to bpf tree *must* have a ``Fixes:`` tag included. 33454222838SJesper Dangaard BrouerThe same applies to fixes that target bpf-next, where the affected 33554222838SJesper Dangaard Brouercommit is in net-next (or in some cases bpf-next). The ``Fixes:`` tag is 33654222838SJesper Dangaard Brouercrucial in order to identify follow-up commits and tremendously helps 33754222838SJesper Dangaard Brouerfor people having to do backporting, so it is a must have! 338192092faSJesper Dangaard Brouer 339192092faSJesper Dangaard BrouerWe also don't accept patches with an empty commit message. Take your 340192092faSJesper Dangaard Brouertime and properly write up a high quality commit message, it is 341192092faSJesper Dangaard Broueressential! 342192092faSJesper Dangaard Brouer 343192092faSJesper Dangaard BrouerThink about it this way: other developers looking at your code a month 344192092faSJesper Dangaard Brouerfrom now need to understand *why* a certain change has been done that 345192092faSJesper Dangaard Brouerway, and whether there have been flaws in the analysis or assumptions 346192092faSJesper Dangaard Brouerthat the original author did. Thus providing a proper rationale and 347192092faSJesper Dangaard Brouerdescribing the use-case for the changes is a must. 348192092faSJesper Dangaard Brouer 349192092faSJesper Dangaard BrouerPatch submissions with >1 patch must have a cover letter which includes 350192092faSJesper Dangaard Brouera high level description of the series. This high level summary will 351192092faSJesper Dangaard Brouerthen be placed into the merge commit by the BPF maintainers such that 352192092faSJesper Dangaard Brouerit is also accessible from the git log for future reference. 353192092faSJesper Dangaard Brouer 35454222838SJesper Dangaard BrouerQ: Features changing BPF JIT and/or LLVM 35554222838SJesper Dangaard Brouer---------------------------------------- 356192092faSJesper Dangaard BrouerQ: What do I need to consider when adding a new instruction or feature 357192092faSJesper Dangaard Brouerthat would require BPF JIT and/or LLVM integration as well? 358192092faSJesper Dangaard Brouer 359192092faSJesper Dangaard BrouerA: We try hard to keep all BPF JITs up to date such that the same user 360192092faSJesper Dangaard Brouerexperience can be guaranteed when running BPF programs on different 361192092faSJesper Dangaard Brouerarchitectures without having the program punt to the less efficient 362192092faSJesper Dangaard Brouerinterpreter in case the in-kernel BPF JIT is enabled. 363192092faSJesper Dangaard Brouer 364192092faSJesper Dangaard BrouerIf you are unable to implement or test the required JIT changes for 365192092faSJesper Dangaard Brouercertain architectures, please work together with the related BPF JIT 366192092faSJesper Dangaard Brouerdevelopers in order to get the feature implemented in a timely manner. 36754222838SJesper Dangaard BrouerPlease refer to the git log (``arch/*/net/``) to locate the necessary 368192092faSJesper Dangaard Brouerpeople for helping out. 369192092faSJesper Dangaard Brouer 370192092faSJesper Dangaard BrouerAlso always make sure to add BPF test cases (e.g. test_bpf.c and 371192092faSJesper Dangaard Brouertest_verifier.c) for new instructions, so that they can receive 372192092faSJesper Dangaard Brouerbroad test coverage and help run-time testing the various BPF JITs. 373192092faSJesper Dangaard Brouer 374192092faSJesper Dangaard BrouerIn case of new BPF instructions, once the changes have been accepted 375192092faSJesper Dangaard Brouerinto the Linux kernel, please implement support into LLVM's BPF back 37654222838SJesper Dangaard Brouerend. See LLVM_ section below for further information. 377192092faSJesper Dangaard Brouer 37854222838SJesper Dangaard BrouerStable submission 37954222838SJesper Dangaard Brouer================= 380192092faSJesper Dangaard Brouer 381192092faSJesper Dangaard BrouerQ: I need a specific BPF commit in stable kernels. What should I do? 38254222838SJesper Dangaard Brouer-------------------------------------------------------------------- 383192092faSJesper Dangaard BrouerA: In case you need a specific fix in stable kernels, first check whether 38454222838SJesper Dangaard Brouerthe commit has already been applied in the related ``linux-*.y`` branches: 385192092faSJesper Dangaard Brouer 386192092faSJesper Dangaard Brouer https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/ 387192092faSJesper Dangaard Brouer 388192092faSJesper Dangaard BrouerIf not the case, then drop an email to the BPF maintainers with the 389192092faSJesper Dangaard Brouernetdev kernel mailing list in Cc and ask for the fix to be queued up: 390192092faSJesper Dangaard Brouer 391192092faSJesper Dangaard Brouer netdev@vger.kernel.org 392192092faSJesper Dangaard Brouer 393192092faSJesper Dangaard BrouerThe process in general is the same as on netdev itself, see also the 394287f4fa9STobin C. Harding:ref:`netdev-FAQ`. 395192092faSJesper Dangaard Brouer 396192092faSJesper Dangaard BrouerQ: Do you also backport to kernels not currently maintained as stable? 39754222838SJesper Dangaard Brouer---------------------------------------------------------------------- 398192092faSJesper Dangaard BrouerA: No. If you need a specific BPF commit in kernels that are currently not 399192092faSJesper Dangaard Brouermaintained by the stable maintainers, then you are on your own. 400192092faSJesper Dangaard Brouer 401192092faSJesper Dangaard BrouerThe current stable and longterm stable kernels are all listed here: 402192092faSJesper Dangaard Brouer 403192092faSJesper Dangaard Brouer https://www.kernel.org/ 404192092faSJesper Dangaard Brouer 40554222838SJesper Dangaard BrouerQ: The BPF patch I am about to submit needs to go to stable as well 40654222838SJesper Dangaard Brouer------------------------------------------------------------------- 40754222838SJesper Dangaard BrouerWhat should I do? 408192092faSJesper Dangaard Brouer 409192092faSJesper Dangaard BrouerA: The same rules apply as with netdev patch submissions in general, see 410287f4fa9STobin C. Hardingthe :ref:`netdev-FAQ`. 411192092faSJesper Dangaard Brouer 41254222838SJesper Dangaard BrouerNever add "``Cc: stable@vger.kernel.org``" to the patch description, but 413192092faSJesper Dangaard Brouerask the BPF maintainers to queue the patches instead. This can be done 41454222838SJesper Dangaard Brouerwith a note, for example, under the ``---`` part of the patch which does 415192092faSJesper Dangaard Brouernot go into the git log. Alternatively, this can be done as a simple 416192092faSJesper Dangaard Brouerrequest by mail instead. 417192092faSJesper Dangaard Brouer 41854222838SJesper Dangaard BrouerQ: Queue stable patches 41954222838SJesper Dangaard Brouer----------------------- 420192092faSJesper Dangaard BrouerQ: Where do I find currently queued BPF patches that will be submitted 421192092faSJesper Dangaard Brouerto stable? 422192092faSJesper Dangaard Brouer 423192092faSJesper Dangaard BrouerA: Once patches that fix critical bugs got applied into the bpf tree, they 424192092faSJesper Dangaard Brouerare queued up for stable submission under: 425192092faSJesper Dangaard Brouer 426192092faSJesper Dangaard Brouer http://patchwork.ozlabs.org/bundle/bpf/stable/?state=* 427192092faSJesper Dangaard Brouer 428192092faSJesper Dangaard BrouerThey will be on hold there at minimum until the related commit made its 429192092faSJesper Dangaard Brouerway into the mainline kernel tree. 430192092faSJesper Dangaard Brouer 431192092faSJesper Dangaard BrouerAfter having been under broader exposure, the queued patches will be 432192092faSJesper Dangaard Brouersubmitted by the BPF maintainers to the stable maintainers. 433192092faSJesper Dangaard Brouer 43454222838SJesper Dangaard BrouerTesting patches 43554222838SJesper Dangaard Brouer=============== 436192092faSJesper Dangaard Brouer 437b7a27c3aSJesper Dangaard BrouerQ: How to run BPF selftests 438b7a27c3aSJesper Dangaard Brouer--------------------------- 439b7a27c3aSJesper Dangaard BrouerA: After you have booted into the newly compiled kernel, navigate to 440b7a27c3aSJesper Dangaard Brouerthe BPF selftests_ suite in order to test BPF functionality (current 441b7a27c3aSJesper Dangaard Brouerworking directory points to the root of the cloned git tree):: 442b7a27c3aSJesper Dangaard Brouer 443b7a27c3aSJesper Dangaard Brouer $ cd tools/testing/selftests/bpf/ 444b7a27c3aSJesper Dangaard Brouer $ make 445b7a27c3aSJesper Dangaard Brouer 446b7a27c3aSJesper Dangaard BrouerTo run the verifier tests:: 447b7a27c3aSJesper Dangaard Brouer 448b7a27c3aSJesper Dangaard Brouer $ sudo ./test_verifier 449b7a27c3aSJesper Dangaard Brouer 450b7a27c3aSJesper Dangaard BrouerThe verifier tests print out all the current checks being 451b7a27c3aSJesper Dangaard Brouerperformed. The summary at the end of running all tests will dump 452b7a27c3aSJesper Dangaard Brouerinformation of test successes and failures:: 453b7a27c3aSJesper Dangaard Brouer 454b7a27c3aSJesper Dangaard Brouer Summary: 418 PASSED, 0 FAILED 455b7a27c3aSJesper Dangaard Brouer 456b7a27c3aSJesper Dangaard BrouerIn order to run through all BPF selftests, the following command is 457b7a27c3aSJesper Dangaard Brouerneeded:: 458b7a27c3aSJesper Dangaard Brouer 459b7a27c3aSJesper Dangaard Brouer $ sudo make run_tests 460b7a27c3aSJesper Dangaard Brouer 461b7a27c3aSJesper Dangaard BrouerSee the kernels selftest `Documentation/dev-tools/kselftest.rst`_ 462b7a27c3aSJesper Dangaard Brouerdocument for further documentation. 463b7a27c3aSJesper Dangaard Brouer 4646736aa79SAlan MaguireTo maximize the number of tests passing, the .config of the kernel 4656736aa79SAlan Maguireunder test should match the config file fragment in 4666736aa79SAlan Maguiretools/testing/selftests/bpf as closely as possible. 4676736aa79SAlan Maguire 4686736aa79SAlan MaguireFinally to ensure support for latest BPF Type Format features - 4696736aa79SAlan Maguirediscussed in `Documentation/bpf/btf.rst`_ - pahole version 1.16 4706736aa79SAlan Maguireis required for kernels built with CONFIG_DEBUG_INFO_BTF=y. 4716736aa79SAlan Maguirepahole is delivered in the dwarves package or can be built 4726736aa79SAlan Maguirefrom source at 4736736aa79SAlan Maguire 4746736aa79SAlan Maguirehttps://github.com/acmel/dwarves 4756736aa79SAlan Maguire 476350a62caSTiezhu Yangpahole starts to use libbpf definitions and APIs since v1.13 after the 477350a62caSTiezhu Yangcommit 21507cd3e97b ("pahole: add libbpf as submodule under lib/bpf"). 478350a62caSTiezhu YangIt works well with the git repository because the libbpf submodule will 479350a62caSTiezhu Yanguse "git submodule update --init --recursive" to update. 480350a62caSTiezhu Yang 481350a62caSTiezhu YangUnfortunately, the default github release source code does not contain 482350a62caSTiezhu Yanglibbpf submodule source code and this will cause build issues, the tarball 483350a62caSTiezhu Yangfrom https://git.kernel.org/pub/scm/devel/pahole/pahole.git/ is same with 484350a62caSTiezhu Yanggithub, you can get the source tarball with corresponding libbpf submodule 485350a62caSTiezhu Yangcodes from 486350a62caSTiezhu Yang 487350a62caSTiezhu Yanghttps://fedorapeople.org/~acme/dwarves 488350a62caSTiezhu Yang 4896736aa79SAlan MaguireSome distros have pahole version 1.16 packaged already, e.g. 4906736aa79SAlan MaguireFedora, Gentoo. 4916736aa79SAlan Maguire 492192092faSJesper Dangaard BrouerQ: Which BPF kernel selftests version should I run my kernel against? 49354222838SJesper Dangaard Brouer--------------------------------------------------------------------- 49454222838SJesper Dangaard BrouerA: If you run a kernel ``xyz``, then always run the BPF kernel selftests 49554222838SJesper Dangaard Brouerfrom that kernel ``xyz`` as well. Do not expect that the BPF selftest 49654222838SJesper Dangaard Brouerfrom the latest mainline tree will pass all the time. 497192092faSJesper Dangaard Brouer 498192092faSJesper Dangaard BrouerIn particular, test_bpf.c and test_verifier.c have a large number of 499192092faSJesper Dangaard Brouertest cases and are constantly updated with new BPF test sequences, or 500192092faSJesper Dangaard Brouerexisting ones are adapted to verifier changes e.g. due to verifier 501192092faSJesper Dangaard Brouerbecoming smarter and being able to better track certain things. 502192092faSJesper Dangaard Brouer 50354222838SJesper Dangaard BrouerLLVM 50454222838SJesper Dangaard Brouer==== 505192092faSJesper Dangaard Brouer 506192092faSJesper Dangaard BrouerQ: Where do I find LLVM with BPF support? 50754222838SJesper Dangaard Brouer----------------------------------------- 508192092faSJesper Dangaard BrouerA: The BPF back end for LLVM is upstream in LLVM since version 3.7.1. 509192092faSJesper Dangaard Brouer 510192092faSJesper Dangaard BrouerAll major distributions these days ship LLVM with BPF back end enabled, 511192092faSJesper Dangaard Brouerso for the majority of use-cases it is not required to compile LLVM by 512192092faSJesper Dangaard Brouerhand anymore, just install the distribution provided package. 513192092faSJesper Dangaard Brouer 51454222838SJesper Dangaard BrouerLLVM's static compiler lists the supported targets through 51554222838SJesper Dangaard Brouer``llc --version``, make sure BPF targets are listed. Example:: 516192092faSJesper Dangaard Brouer 517192092faSJesper Dangaard Brouer $ llc --version 518192092faSJesper Dangaard Brouer LLVM (http://llvm.org/): 5194d0d1673SJianlin Lv LLVM version 10.0.0 520192092faSJesper Dangaard Brouer Optimized build. 521192092faSJesper Dangaard Brouer Default target: x86_64-unknown-linux-gnu 522192092faSJesper Dangaard Brouer Host CPU: skylake 523192092faSJesper Dangaard Brouer 524192092faSJesper Dangaard Brouer Registered Targets: 5254d0d1673SJianlin Lv aarch64 - AArch64 (little endian) 526192092faSJesper Dangaard Brouer bpf - BPF (host endian) 527192092faSJesper Dangaard Brouer bpfeb - BPF (big endian) 528192092faSJesper Dangaard Brouer bpfel - BPF (little endian) 529192092faSJesper Dangaard Brouer x86 - 32-bit X86: Pentium-Pro and above 530192092faSJesper Dangaard Brouer x86-64 - 64-bit X86: EM64T and AMD64 531192092faSJesper Dangaard Brouer 532192092faSJesper Dangaard BrouerFor developers in order to utilize the latest features added to LLVM's 533192092faSJesper Dangaard BrouerBPF back end, it is advisable to run the latest LLVM releases. Support 534192092faSJesper Dangaard Brouerfor new BPF kernel features such as additions to the BPF instruction 535192092faSJesper Dangaard Brouerset are often developed together. 536192092faSJesper Dangaard Brouer 537192092faSJesper Dangaard BrouerAll LLVM releases can be found at: http://releases.llvm.org/ 538192092faSJesper Dangaard Brouer 539192092faSJesper Dangaard BrouerQ: Got it, so how do I build LLVM manually anyway? 54054222838SJesper Dangaard Brouer-------------------------------------------------- 541628add78STiezhu YangA: We recommend that developers who want the fastest incremental builds 542628add78STiezhu Yanguse the Ninja build system, you can find it in your system's package 543628add78STiezhu Yangmanager, usually the package is ninja or ninja-build. 544628add78STiezhu Yang 545628add78STiezhu YangYou need ninja, cmake and gcc-c++ as build requisites for LLVM. Once you 546628add78STiezhu Yanghave that set up, proceed with building the latest LLVM and clang version 54754222838SJesper Dangaard Brouerfrom the git repositories:: 548192092faSJesper Dangaard Brouer 549e42da4c6SYonghong Song $ git clone https://github.com/llvm/llvm-project.git 550628add78STiezhu Yang $ mkdir -p llvm-project/llvm/build 551e42da4c6SYonghong Song $ cd llvm-project/llvm/build 552e42da4c6SYonghong Song $ cmake .. -G "Ninja" -DLLVM_TARGETS_TO_BUILD="BPF;X86" \ 553e42da4c6SYonghong Song -DLLVM_ENABLE_PROJECTS="clang" \ 554192092faSJesper Dangaard Brouer -DCMAKE_BUILD_TYPE=Release \ 555192092faSJesper Dangaard Brouer -DLLVM_BUILD_RUNTIME=OFF 556e42da4c6SYonghong Song $ ninja 557192092faSJesper Dangaard Brouer 558192092faSJesper Dangaard BrouerThe built binaries can then be found in the build/bin/ directory, where 559192092faSJesper Dangaard Broueryou can point the PATH variable to. 560192092faSJesper Dangaard Brouer 5614d0d1673SJianlin LvSet ``-DLLVM_TARGETS_TO_BUILD`` equal to the target you wish to build, you 5624d0d1673SJianlin Lvwill find a full list of targets within the llvm-project/llvm/lib/Target 5634d0d1673SJianlin Lvdirectory. 5644d0d1673SJianlin Lv 56554222838SJesper Dangaard BrouerQ: Reporting LLVM BPF issues 56654222838SJesper Dangaard Brouer---------------------------- 567192092faSJesper Dangaard BrouerQ: Should I notify BPF kernel maintainers about issues in LLVM's BPF code 568192092faSJesper Dangaard Brouergeneration back end or about LLVM generated code that the verifier 569192092faSJesper Dangaard Brouerrefuses to accept? 570192092faSJesper Dangaard Brouer 57154222838SJesper Dangaard BrouerA: Yes, please do! 57254222838SJesper Dangaard Brouer 57354222838SJesper Dangaard BrouerLLVM's BPF back end is a key piece of the whole BPF 574192092faSJesper Dangaard Brouerinfrastructure and it ties deeply into verification of programs from the 575192092faSJesper Dangaard Brouerkernel side. Therefore, any issues on either side need to be investigated 576192092faSJesper Dangaard Brouerand fixed whenever necessary. 577192092faSJesper Dangaard Brouer 578192092faSJesper Dangaard BrouerTherefore, please make sure to bring them up at netdev kernel mailing 579192092faSJesper Dangaard Brouerlist and Cc BPF maintainers for LLVM and kernel bits: 580192092faSJesper Dangaard Brouer 58154222838SJesper Dangaard Brouer* Yonghong Song <yhs@fb.com> 58254222838SJesper Dangaard Brouer* Alexei Starovoitov <ast@kernel.org> 58354222838SJesper Dangaard Brouer* Daniel Borkmann <daniel@iogearbox.net> 584192092faSJesper Dangaard Brouer 585192092faSJesper Dangaard BrouerLLVM also has an issue tracker where BPF related bugs can be found: 586192092faSJesper Dangaard Brouer 587192092faSJesper Dangaard Brouer https://bugs.llvm.org/buglist.cgi?quicksearch=bpf 588192092faSJesper Dangaard Brouer 589192092faSJesper Dangaard BrouerHowever, it is better to reach out through mailing lists with having 590192092faSJesper Dangaard Brouermaintainers in Cc. 591192092faSJesper Dangaard Brouer 59254222838SJesper Dangaard BrouerQ: New BPF instruction for kernel and LLVM 59354222838SJesper Dangaard Brouer------------------------------------------ 594192092faSJesper Dangaard BrouerQ: I have added a new BPF instruction to the kernel, how can I integrate 595192092faSJesper Dangaard Brouerit into LLVM? 596192092faSJesper Dangaard Brouer 59754222838SJesper Dangaard BrouerA: LLVM has a ``-mcpu`` selector for the BPF back end in order to allow 59854222838SJesper Dangaard Brouerthe selection of BPF instruction set extensions. By default the 59954222838SJesper Dangaard Brouer``generic`` processor target is used, which is the base instruction set 60054222838SJesper Dangaard Brouer(v1) of BPF. 601192092faSJesper Dangaard Brouer 60254222838SJesper Dangaard BrouerLLVM has an option to select ``-mcpu=probe`` where it will probe the host 603192092faSJesper Dangaard Brouerkernel for supported BPF instruction set extensions and selects the 604192092faSJesper Dangaard Broueroptimal set automatically. 605192092faSJesper Dangaard Brouer 60654222838SJesper Dangaard BrouerFor cross-compilation, a specific version can be select manually as well :: 607192092faSJesper Dangaard Brouer 608192092faSJesper Dangaard Brouer $ llc -march bpf -mcpu=help 609192092faSJesper Dangaard Brouer Available CPUs for this target: 610192092faSJesper Dangaard Brouer 611192092faSJesper Dangaard Brouer generic - Select the generic processor. 612192092faSJesper Dangaard Brouer probe - Select the probe processor. 613192092faSJesper Dangaard Brouer v1 - Select the v1 processor. 614192092faSJesper Dangaard Brouer v2 - Select the v2 processor. 615192092faSJesper Dangaard Brouer [...] 616192092faSJesper Dangaard Brouer 617192092faSJesper Dangaard BrouerNewly added BPF instructions to the Linux kernel need to follow the same 618192092faSJesper Dangaard Brouerscheme, bump the instruction set version and implement probing for the 61954222838SJesper Dangaard Brouerextensions such that ``-mcpu=probe`` users can benefit from the 62054222838SJesper Dangaard Broueroptimization transparently when upgrading their kernels. 621192092faSJesper Dangaard Brouer 622192092faSJesper Dangaard BrouerIf you are unable to implement support for the newly added BPF instruction 623192092faSJesper Dangaard Brouerplease reach out to BPF developers for help. 624192092faSJesper Dangaard Brouer 62554222838SJesper Dangaard BrouerBy the way, the BPF kernel selftests run with ``-mcpu=probe`` for better 626192092faSJesper Dangaard Brouertest coverage. 627192092faSJesper Dangaard Brouer 62854222838SJesper Dangaard BrouerQ: clang flag for target bpf? 62954222838SJesper Dangaard Brouer----------------------------- 63054222838SJesper Dangaard BrouerQ: In some cases clang flag ``-target bpf`` is used but in other cases the 631192092faSJesper Dangaard Brouerdefault clang target, which matches the underlying architecture, is used. 632192092faSJesper Dangaard BrouerWhat is the difference and when I should use which? 633192092faSJesper Dangaard Brouer 634192092faSJesper Dangaard BrouerA: Although LLVM IR generation and optimization try to stay architecture 63554222838SJesper Dangaard Brouerindependent, ``-target <arch>`` still has some impact on generated code: 636192092faSJesper Dangaard Brouer 637192092faSJesper Dangaard Brouer- BPF program may recursively include header file(s) with file scope 638192092faSJesper Dangaard Brouer inline assembly codes. The default target can handle this well, 63954222838SJesper Dangaard Brouer while ``bpf`` target may fail if bpf backend assembler does not 640192092faSJesper Dangaard Brouer understand these assembly codes, which is true in most cases. 641192092faSJesper Dangaard Brouer 64254222838SJesper Dangaard Brouer- When compiled without ``-g``, additional elf sections, e.g., 643192092faSJesper Dangaard Brouer .eh_frame and .rela.eh_frame, may be present in the object file 64454222838SJesper Dangaard Brouer with default target, but not with ``bpf`` target. 645192092faSJesper Dangaard Brouer 646192092faSJesper Dangaard Brouer- The default target may turn a C switch statement into a switch table 647192092faSJesper Dangaard Brouer lookup and jump operation. Since the switch table is placed 648192092faSJesper Dangaard Brouer in the global readonly section, the bpf program will fail to load. 649192092faSJesper Dangaard Brouer The bpf target does not support switch table optimization. 65054222838SJesper Dangaard Brouer The clang option ``-fno-jump-tables`` can be used to disable 651192092faSJesper Dangaard Brouer switch table generation. 652192092faSJesper Dangaard Brouer 65354222838SJesper Dangaard Brouer- For clang ``-target bpf``, it is guaranteed that pointer or long / 654192092faSJesper Dangaard Brouer unsigned long types will always have a width of 64 bit, no matter 655192092faSJesper Dangaard Brouer whether underlying clang binary or default target (or kernel) is 656192092faSJesper Dangaard Brouer 32 bit. However, when native clang target is used, then it will 657192092faSJesper Dangaard Brouer compile these types based on the underlying architecture's conventions, 658192092faSJesper Dangaard Brouer meaning in case of 32 bit architecture, pointer or long / unsigned 659192092faSJesper Dangaard Brouer long types e.g. in BPF context structure will have width of 32 bit 660192092faSJesper Dangaard Brouer while the BPF LLVM back end still operates in 64 bit. The native 66154222838SJesper Dangaard Brouer target is mostly needed in tracing for the case of walking ``pt_regs`` 662192092faSJesper Dangaard Brouer or other kernel structures where CPU's register width matters. 66354222838SJesper Dangaard Brouer Otherwise, ``clang -target bpf`` is generally recommended. 664192092faSJesper Dangaard Brouer 665192092faSJesper Dangaard BrouerYou should use default target when: 666192092faSJesper Dangaard Brouer 667192092faSJesper Dangaard Brouer- Your program includes a header file, e.g., ptrace.h, which eventually 668192092faSJesper Dangaard Brouer pulls in some header files containing file scope host assembly codes. 669192092faSJesper Dangaard Brouer 67054222838SJesper Dangaard Brouer- You can add ``-fno-jump-tables`` to work around the switch table issue. 67154222838SJesper Dangaard Brouer 67254222838SJesper Dangaard BrouerOtherwise, you can use ``bpf`` target. Additionally, you *must* use bpf target 673192092faSJesper Dangaard Brouerwhen: 674192092faSJesper Dangaard Brouer 675192092faSJesper Dangaard Brouer- Your program uses data structures with pointer or long / unsigned long 676192092faSJesper Dangaard Brouer types that interface with BPF helpers or context data structures. Access 677192092faSJesper Dangaard Brouer into these structures is verified by the BPF verifier and may result 678192092faSJesper Dangaard Brouer in verification failures if the native architecture is not aligned with 679192092faSJesper Dangaard Brouer the BPF architecture, e.g. 64-bit. An example of this is 68054222838SJesper Dangaard Brouer BPF_PROG_TYPE_SK_MSG require ``-target bpf`` 68154222838SJesper Dangaard Brouer 68254222838SJesper Dangaard Brouer 68354222838SJesper Dangaard Brouer.. Links 68454222838SJesper Dangaard Brouer.. _Documentation/process/: https://www.kernel.org/doc/html/latest/process/ 6858df01363SJakub Kicinski.. _netdev-FAQ: Documentation/process/maintainer-netdev.rst 68664ef3ddfSTiezhu Yang.. _selftests: 68764ef3ddfSTiezhu Yang https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/ 688b7a27c3aSJesper Dangaard Brouer.. _Documentation/dev-tools/kselftest.rst: 689b7a27c3aSJesper Dangaard Brouer https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html 690009abf5bSDaniel W. S. Almeida.. _Documentation/bpf/btf.rst: btf.rst 691192092faSJesper Dangaard Brouer 692192092faSJesper Dangaard BrouerHappy BPF hacking! 693