Skip to content

Styling update in README.md and CONTRIBUTING.md #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alan-maguire merged 2 commits into from
May 11, 2023
Merged

Styling update in README.md and CONTRIBUTING.md #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c516fd
Update CONTRIBUTING.md
spavlusieva May 10, 2023
839057c
Update README.md
spavlusieva May 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

We welcome your contributions! There are multiple ways to contribute.

# Opening issues
## Opening issues

For bugs or enhancement requests, please file a GitHub issue unless it is security related. When filing a bug remember that the better written the bug is, the more likely it is to be fixed. If you think you have found a security vulnerability, do not raise a GitHub issue and follow the instructions in our security policy documented in SECURITY.md.

# Contributing code
## Contributing code

We welcome your code contributions. Before submitting code via a pull request, you will need to have signed the Oracle Contributor Agreement (OCA) at

Expand All @@ -22,7 +22,7 @@ git commit --signoff

Only pull requests from committers that can be verified as having signed the OCA can be accepted.

# Pull request process
## Pull request process

- Ensure there is an issue created to track and discuss the fix or enhancement you intend to submit.
- Fork this repository.
Expand All @@ -34,13 +34,13 @@ Only pull requests from committers that can be verified as having signed the OCA
- Submit the pull request. Do not leave the pull request blank. Explain exactly what your changes are meant to do and provide simple steps on how to validate your changes. Ensure that you reference the issue you created as well.
- We will assign the pull request for review before it is submitted internally and the PR is closed.

# Code of conduct
## Code of conduct

Follow the Golden Rule. If you would like more specific guidelines, see the Contributor Covenant Code of Conduct at

https://www.contributor-covenant.org/version/1/4/code-of-conduct/

# Technical guide to contribution
## Technical guide to contribution

The architecture used is

Expand All @@ -50,7 +50,7 @@ The architecture used is
- a set of plug-in shared object tuners which are loaded when bpftune
starts; sysctl_tuner.[bpf.]c, neigh_table_tuner.[bpf.]c

# Adding a tuner
## Adding a tuner

Tuners are added as plug-in .so objects built as tuner_name.c, and each tuner
has a BPF program named tuner_name.bpf.c. To add a new tuner, add these
Expand All @@ -59,7 +59,7 @@ files and simply add tuner_name to TUNERS in src/Makefile.
Tuners can also be built outside of bpftune; see the sample_tuner/
subdirectory for a simple example and sample Makefile.

# BPF component (tuner_name.bpf.c)
## BPF component (tuner_name.bpf.c)

The BPF code must

Expand Down Expand Up @@ -137,7 +137,7 @@ possible as that will work for both kprobe and fentry for example.
For maps, use the BPF_MAP_DEF() definitions which will invoke
the older libbpf map definition if using an older libbpf.

# Userspace component - tuner_name.c
## Userspace component - tuner_name.c

It should #include <libbpftune.h>, and must consist of the following
functions
Expand Down Expand Up @@ -191,7 +191,7 @@ should be added to a tuner_name.h file which both include.

Remember to include both the skel.h and skel.legacy.h files.

# Events
## Events

When an event the user-space component needs to know about occurs,
a ringbuf event should be sent. The event structure is:
Expand All @@ -211,7 +211,7 @@ struct bpftune_event {
The scenario refers to the event type (seen packet loss to remote
system), and the payload can be a string, a raw data structure etc.

# Overhead
## Overhead

When choosing BPF events to instrument, please try to avoid very
high-frequency events. Try to use fentry instead of kprobe,
Expand All @@ -231,7 +231,7 @@ $ TUNER=tcp_buffer_tuner.so sh qperf_test.sh

Replace TUNER value with the name of the tuner you want to assess.

# Tests
## Tests

Tests are mandatory for tuners; in the test directory you can see
lots of examples. The test framework uses network namespaces to
Expand Down
20 changes: 10 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ behaviour. The key benefit it provides are
than using coarse system-wide stats), we can tune at a finer grain
too (individual socket policies, individual device policies etc)

# The problem
## The problem

The Linux kernel contains a large number of tunables; these
often take the form of sysctl(8) parameters, and are usually
Expand Down Expand Up @@ -55,7 +55,7 @@ not only can we observe the system and tune appropriately,
we can also observe the effect of that tuning and re-tune
if necessary.

# Key design principles
## Key design principles

- Minimize overhead. Use observability features sparingly; do not
trace very high frequency events.
Expand Down Expand Up @@ -85,7 +85,7 @@ if necessary.
round-trip time; if the correlation between these exceeds a
threshould (0.7) we stop increasing buffer size.

# Concepts
## Concepts

The key components are

Expand All @@ -104,7 +104,7 @@ The key components are
in the log is key; this allows an admin to understand what
changed and why.

# Architecture
## Architecture

- bpftune is a daemon which manages a set of .so plugin tuners;
each of these is a shared object that is loaded on start-up.
Expand All @@ -126,7 +126,7 @@ The key components are
the common map definitions (ringbuf, etc) and shared variables
such as learning rate and tuner ids that each tuner needs.

# Supported tuners
## Supported tuners

- congestion tuner: auto-tune choice of congestion control algorithm.
See bpftune-tcp-cong (8).
Expand All @@ -146,7 +146,7 @@ The key components are
Namespace awareness is important as we want to be able to auto-tune
containers also. See bpftune-netns (8).

# Code organization
## Code organization

Both core bpftune.c and individual tuners use the libbpftune library.
It handles logging, tuner init/fini, and BPF init/fini.
Expand All @@ -155,7 +155,7 @@ Each tuner shared object defines an init(), fini() and event_handler()
function. These respectively set up and clean up BPF and handle events
that originate from the BPF code.

# Tests
## Tests

Tests are supplied for each tuner in the tests/ subdirectory.
"make test" runs all the tests. Tests use network namespaces
Expand Down Expand Up @@ -184,7 +184,7 @@ SPDX-URL: https://spdx.org/licenses/GPL-2.0.html

See [the license file](./LICENSE.txt) for more details.

# Does my system support bpftune?
## Does my system support bpftune?

Simply run "bpftune -S" to see:

Expand All @@ -201,7 +201,7 @@ Two aspects are important here
- does the system support network namespace cookies? If so
per-network-namespace policy is supported.

# Demo
## Demo

Simply starting bpftune and observing changes made via /var/log/messages
can be instructive. For example, on a standard VM with sysctl defaults,
Expand Down Expand Up @@ -265,7 +265,7 @@ bpftune: Summary: scenario 'need to increase TCP buffer size(s)' occurred 9 time
bpftune: sysctl 'net.ipv4.tcp_rmem' changed from (4096 131072 1310720 ) -> (4096 131072 9765625 )
```

# For more info
## For more info

See the docs/ subdirectory for manual pages covering bpftune
and assoiated tuners.