GitHub pull request #2989 of commit d7c82aed9f048ec69c4eae6459b9411819a25339, no merge conflicts.sha1origin/pr/2989/mergeghprbActualCommitd7c82aed9f048ec69c4eae6459b9411819a25339ghprbActualCommitAuthorghprbActualCommitAuthorEmailghprbAuthorRepoGitUrlhttps://github.com/willfindlay/bcc.gitghprbTriggerAuthorghprbTriggerAuthorEmailghprbTriggerAuthorLoginyonghong-songghprbTriggerAuthorLoginMention@yonghong-songghprbPullId2989ghprbTargetBranchmasterghprbSourceBranchringbuf_helpersGIT_BRANCHringbuf_helpersghprbPullAuthorEmailwilliam@williamfindlay.comghprbPullAuthorLoginwillfindlayghprbPullAuthorLoginMention@willfindlayghprbPullDescriptionGitHub pull request #2989 of commit d7c82aed9f048ec69c4eae6459b9411819a25339, no merge conflicts.ghprbPullTitleRingbuf Support for Python APIghprbPullLinkhttps://github.com/iovisor/bcc/pull/2989ghprbPullLongDescriptionThis pull request contains an implementation for ringbuf support in bcc's Python API. \r\n\r\nFixes #2985.\r\n\r\n## Summary of Changes\r\n\r\n- Added ringbuf helpers from libbpf API to libbcc\r\n- Added a new `RingBuf` class to represent the ringbuf map\r\n- Added a new `EventArrayBase` class to reduce code duplication between PerfEventArray and RingBuf\r\n- Added `BPF_RINGBUF_OUTPUT` macro for BPF programs\r\n- Added documentation\r\n\r\n## Examples\r\n\r\nThe following example programs describe how the API works.\r\n\r\nOn the BPF side, we have two choices for submitting events. `map.ringbuf_output` works like `map.perf_submit` for perf buffers,\r\nwhile `map.ringbuf_reserve`/`map.ringbuf_discard`/`map.ringbuf_submit` present an alternative approach that allows for finer control.\r\n\r\n`map.ringbuf_output` works like:\r\n```c\r\nBPF_RINGBUF_OUTPUT(events);\r\n\r\nstruct data_t data {\r\n u32 pid;\r\n};\r\n\r\nTRACEPOINT_PROBE(raw_syscalls, sys_enter) {\r\n u32 pid = bpf_get_current_pid_tgid();\r\n\r\n struct data_t data = { .pid = pid };\r\n\r\n events.ringbuf_output(&data, sizeof(data), 0 /* flags */);\r\n \r\n return 0;\r\n}\r\n```\r\n\r\n`map.ringbuf_reserve`/`map.ringbuf_discard`/`map.ringbuf_submit` work like:\r\n```c\r\nBPF_RINGBUF_OUTPUT(events);\r\n\r\nstruct data_t data {\r\n u32 pid;\r\n};\r\n\r\nTRACEPOINT_PROBE(raw_syscalls, sys_enter) {\r\n u32 pid = bpf_get_current_pid_tgid();\r\n\r\n struct data_t *data = events.ringbuf_reserve(sizeof(struct data_t));\r\n if (!data)\r\n return 1;\r\n\r\n data->pid = pid;\r\n\r\n events.ringbuf_submit(data, 0 /* flags */);\r\n // or, to discard the data...\r\n events.ringbuf_discard(data, 0 /* flags */);\r\n\r\n return 0;\r\n}\r\n```\r\n\r\nOn the Python side, the user calls `open_ring_buffer` to associate a callback with the buffer. There are two options for reading data from kernelspace: `ring_buffer_poll` which works like `perf_buffer_poll` and `ring_buffer_consume` which reads data without polling first.\r\n```python\r\nimport time\r\n\r\nfrom bcc import BPF\r\n\r\nb = BPF(src_file=b'source.c')\r\n\r\ndef callback(ctx, data, size):\r\n event = b['events'].event(data)\r\n print(event.pid)\r\n\r\nb['events'].open_ring_buffer(callback)\r\n\r\nwhile True:\r\n # Option 1...\r\n b.ring_buffer_poll(30)\r\n # Option 2...\r\n b.ring_buffer_consume()\r\n time.sleep(0.5)\r\n```\r\n\r\nUnlike perf buffer callbacks, ringbuf supports return values from the callback, which can be used to indicate error conditions to stop polling early. If a callback does not return an integer, we fall back to returning 0, which approximates perf buffer behavior.ghprbCommentBody[buildbot, test this please]ghprbGhRepositoryiovisor/bccghprbCredentialsId6d3daf13-69b8-48b1-9c8f-ec5353264113false<a title="Ringbuf Support for Python API" href="https://github.com/iovisor/bcc/pull/2989">PR #2989</a>: Ringbuf Support for Python API#57612839637460664bcc-pr #576576false5764616SUCCESS1593116308002https://buildbot.iovisor.org/jenkins/user/a.s.protopopov/my-views/view/all/job/bcc-pr/576/git576https://buildbot.iovisor.org/jenkins/user/a.s.protopopov/my-views/view/all/job/bcc-pr/label=fc25/576/576https://buildbot.iovisor.org/jenkins/user/a.s.protopopov/my-views/view/all/job/bcc-pr/label=fc26/576/576https://buildbot.iovisor.org/jenkins/user/a.s.protopopov/my-views/view/all/job/bcc-pr/label=fc27/576/576https://buildbot.iovisor.org/jenkins/user/a.s.protopopov/my-views/view/all/job/bcc-pr/label=fc28/576/576https://buildbot.iovisor.org/jenkins/user/a.s.protopopov/my-views/view/all/job/bcc-pr/label=ubuntu1604/576/576https://buildbot.iovisor.org/jenkins/user/a.s.protopopov/my-views/view/all/job/bcc-pr/label=ubuntu1710/576/576https://buildbot.iovisor.org/jenkins/user/a.s.protopopov/my-views/view/all/job/bcc-pr/label=ubuntu1804/576/