document cflags argument to BPF()

[ahrens]

This relates to #1707

[yonghong-song]

since you change it. How about make it complete, include debug and hdr_file as well?

[ahrens]

Happy to, if you can explain to me what they are.

[brendangregg]

I'm not sure, so I checked from src/python/bcc/init.py:

    def __init__(self, src_file=b"", hdr_file=b"", text=None, debug=0,
            cflags=[], usdt_contexts=[]):
        """Create a new BPF module with the given source code.

        Note:
            All fields are marked as optional, but either `src_file` or `text`
            must be supplied, and not both.

        Args:
            src_file (Optional[str]): Path to a source file for the module
            hdr_file (Optional[str]): Path to a helper header file for the `src_file`
            text (Optional[str]): Contents of a source file for the module
            debug (Optional[int]): Flags used for debug prints, can be |'d together
                                   See "Debug flags" for explanation
[...]
# Debug flags

# Debug output compiled LLVM IR.
DEBUG_LLVM_IR = 0x1
# Debug output loaded BPF bytecode and register state on branches.
DEBUG_BPF = 0x2
# Debug output pre-processor result.
DEBUG_PREPROCESSOR = 0x4
# Debug output ASM instructions embedded with source.
DEBUG_SOURCE = 0x8
#Debug output register state on all instructions in addition to DEBUG_BPF.
DEBUG_BPF_REGISTER_STATE = 0x10

I don't know the purpose of hdr_file.

[drzaeus77]

            src_file (Optional[str]): Path to a source file for the module
            hdr_file (Optional[str]): Path to a helper header file for the `src_file`

These are both holdovers from src/cc/frontends/b, and shouldn't be used when using restricted-c style programs.

[drzaeus77]

Sorry, I spoke without looking at the source. While hdr_file is for frontends/b, src_file is still used for both modes, though I think most if not all scripts use BPFModule::load_string and hence use the python text="" argument, which is mutually exclusive with src_file.

[yonghong-song]

Okay, so let just document debug flags since hdr_files is for b frontend.

[ahrens]

@yonghong-song I added documentation of the debug flags.

[yonghong-song]

[buildbot, ok to test]

[yonghong-song]

Looks good. Thanks for help improving our documentation!