docs: add Program Types/XDP documentation #155

shard77 · 2024-04-24T09:26:20Z

Added documentation for https://aya-rs.dev/book/programs/xdp/
Feel free to make reviews and suggest improvements.

netlify · 2024-04-24T09:26:37Z

✅ Deploy Preview for aya-rs ready!

Name	Link
🔨 Latest commit	`471d5b4`
🔍 Latest deploy log	https://app.netlify.com/sites/aya-rs/deploys/6658c95d68cf450008d7e950
😎 Deploy Preview	https://deploy-preview-155--aya-rs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

vadorovsky

Thanks for working on this 🙏 Left some comments, but I will review again later today.

vadorovsky · 2024-04-30T06:02:47Z

docs/book/programs/xdp.md

+
+## What is XBP in eBPF?
+
+XBP (eXpress Data Path) is a type of eBPF program that attaches to the network interface. It allows for the processing of network packets as soon as they are received from the network driver, even before they enter the networking stack. XDP enables efficient packet filtering, manipulation and redirection at the earliest possible stage, resulting in low-latency and high-throughput.


Can we stick to 80-100 character limit per line?

Can we stick to 80-100 character limit per line?

Not sure what you mean per line, you want to break to a newline after max 100 chars?
On my side I don't see the lines go further than > 100 chars, it's always around 90 chars max per line.

Yes, I want to break to a new line after max 100 characters.

This exact sentence which I commented exceeds this limit and it's quite hard to read in some editors. The whole line 10 has 317 characters:

~> python3 04/30/24 13:30:49 PM Python 3.11.5 (main, Aug 24 2023, 15:09:45) [Clang 14.0.3 (clang-1403.0.22.14.1)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> len("XDP (eXpress Data Path) is a type of eBPF program that attaches to the network interface. It enables filtering, manipulation and refirection of network packets as soon as they are received from the network driver, even before they enter the Linux kernel networking stack, resulting in low latency and high throughput.") 317

We should probably introduce some markdown linter to catch stuff like that, but for now can we just split the obviously too large lines?

Yes, I want to break to a new line after max 100 characters.

This exact sentence which I commented exceeds this limit and it's quite hard to read in some editors. The whole line 10 has 317 characters:

~> python3 04/30/24 13:30:49 PM Python 3.11.5 (main, Aug 24 2023, 15:09:45) [Clang 14.0.3 (clang-1403.0.22.14.1)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> len("XDP (eXpress Data Path) is a type of eBPF program that attaches to the network interface. It enables filtering, manipulation and refirection of network packets as soon as they are received from the network driver, even before they enter the Linux kernel networking stack, resulting in low latency and high throughput.") 317

We should probably introduce some markdown linter to catch stuff like that, but for now can we just split the obviously too large lines?

Sure, makes sense, the only thing I'm worried about is that it may be less nice to read on bigger screens or on the site directly

For example, on a bigger screen/on the site, it would look like:

Maybe it's just me but I find it harder to read with all the line breaks here

For example, on a bigger screen/on the site, it would look like:

Maybe it's just me but I find it harder to read with all the line breaks here

@vadorovsky Any news? I don't mind adding the line breaks, just thought it would make sense to reconsider it.

OK, I had no idea that breaking the lines even with a single \n makes it being rendered on the website. Let me test myself. If that's really the case, let's leave the long lines.

OK, I had no idea that breaking the lines even with a single \n makes it being rendered on the website. Let me test myself. If that's really the case, let's leave the long lines.

my bad, I tried with <br> for line breaks (for some reason I thought you'd also like to render those on the website), going to try with single \n, it shouldn't render on the website.

@vadorovsky indeed it doesn't change anything on the website when adding single \n, I have added some line breaks for bigger sentences, let me know if I should change anything else 👍

docs/book/programs/xdp.md

Co-authored-by: Michal Rostecki <vadorovsky@protonmail.com>

shard77 · 2024-04-30T08:06:43Z

Applied your reviews, also corrected some typos

vadorovsky

Sorry for very late review!

Unfortunately I'm still nitpicking few things. After addressing them it should be good to go.

vadorovsky · 2024-09-01T19:48:18Z

docs/book/programs/xdp.md

+!!! example "Source Code"
+
+    Full code for the example in this chapter is available [here](https://github.com/aya-rs/book/tree/main/examples/xdp-drop)
+


Can we stick to having one empty line, not multiple?

Suggested change

vadorovsky · 2024-09-01T19:48:37Z

docs/book/programs/xdp.md

+    Full code for the example in this chapter is available [here](https://github.com/aya-rs/book/tree/main/examples/xdp-drop)
+
+
+## What is XDP in eBPF?


And let's add empty lines after headers.

Suggested change

## What is XDP in eBPF?

## What is XDP in eBPF?

vadorovsky · 2024-09-01T19:48:46Z

docs/book/programs/xdp.md

+* `XDP_REDIRECT`: redirect the packet to another NIC or user space socket via the
+[`AF_XDP`](https://www.kernel.org/doc/html/latest/networking/af_xdp.html) address family
+
+## AF_XDP


Suggested change

## AF_XDP

## AF_XDP

vadorovsky · 2024-09-01T20:04:34Z

docs/book/programs/xdp.md

+If you want a more extensive explanation about `AF_XDP`,
+you can find it in the [kernel documentation](https://www.kernel.org/doc/html/latest/networking/af_xdp.html).
+
+## XDP Operation Modes


I'm personally not a big fan of using the title case (capitalizing all nouns, regardless of whether they're proper nouns or common nouns). As far as I remember, @alessandrod doesn't like it either.

The reasons being:

I Find it Quite Difficult to Read. 😛

In all seriousness, I like the opposite style - sentence case capitalization - because it highlights the important words. When reading technical documentation, I prefer the names of specific technologies or projects (XDP, Linux etc.) to stand out from the rest of the title.

Title case is not really standardized, there are multiple styles and rules. I find sentence case capitalization much more obvious, since everyone is using it on daily basis.

In Aya book, even though there are some places using title case, it's not being used consistently. It's also not being used consistently here. 😅 It would be easier to convert all existing title cases to sentence cases - I would be happy to see an another PR doing that.

Therefore,

Suggested change

## XDP Operation Modes

## XDP operation modes

vadorovsky · 2024-09-01T20:04:47Z

docs/book/programs/xdp.md

+## XDP Operation Modes
+You can connect an XDP program to an interface using the following modes:
+
+### Generic XDP


Suggested change

### Generic XDP

### Generic XDP

vadorovsky · 2024-09-01T20:06:32Z

docs/book/programs/xdp.md

+Logging is initialized using [`env_logger::init()`](https://docs.rs/env_logger/latest/env_logger/fn.init.html),
+we will make use of the environment logger later in our code.
+
+##### Loading the eBPF program


Suggested change

##### Loading the eBPF program

##### Loading the eBPF program

vadorovsky · 2024-09-01T20:06:39Z

docs/book/programs/xdp.md

+The eBPF program is loaded using `Bpf::load()`, choosing the debug or
+release version based on the build configuration (`debug_assertions`).
+
+##### Loading and attaching our XDP


Suggested change

##### Loading and attaching our XDP

##### Loading and attaching our XDP

vadorovsky · 2024-09-01T20:07:04Z

docs/book/programs/xdp.md

+ we defined earlier using `bpf.program_mut()`.
+ The XDP program is then loaded and attached to our network interface.
+
+##### Setting up the ip blocklist


"IP" should be all upper-case:

Suggested change

##### Setting up the ip blocklist

##### Setting up the IP blocklist

vadorovsky · 2024-09-01T20:07:11Z

docs/book/programs/xdp.md

+The IP blocklist (`BLOCKLIST` map) is loaded from the eBPF program and converted to a `HashMap`.
+The IP `1.1.1.1` is added to the blocklist.
+
+##### Waiting for the exit signal


Suggested change

##### Waiting for the exit signal

##### Waiting for the exit signal

vadorovsky · 2024-09-01T20:07:18Z

docs/book/programs/xdp.md

+}
+```
+
+### Running our program!


Suggested change

### Running our program!

### Running our program!

docs: add Program Types/XDP documentation

04b92d7

vadorovsky reviewed Apr 30, 2024

View reviewed changes

shard77 and others added 5 commits April 30, 2024 09:32

Update docs/book/programs/xdp.md

92d2afc

Co-authored-by: Michal Rostecki <vadorovsky@protonmail.com>

Update docs/book/programs/xdp.md

b556b61

Co-authored-by: Michal Rostecki <vadorovsky@protonmail.com>

Update xdp.md

a6125f1

Update xdp.md

4367ea9

Update xdp.md

3dfcf85

Update xdp.md

471d5b4

vadorovsky reviewed Sep 1, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add Program Types/XDP documentation #155

docs: add Program Types/XDP documentation #155

shard77 commented Apr 24, 2024

netlify bot commented Apr 24, 2024 •

edited

Loading

vadorovsky left a comment

vadorovsky Apr 30, 2024

shard77 Apr 30, 2024

vadorovsky Apr 30, 2024

shard77 Apr 30, 2024

shard77 Apr 30, 2024 •

edited

Loading

shard77 May 7, 2024 •

edited

Loading

vadorovsky May 30, 2024

shard77 May 30, 2024 •

edited

Loading

shard77 May 30, 2024

shard77 commented Apr 30, 2024

vadorovsky left a comment

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024

vadorovsky Sep 1, 2024


		## What is XBP in eBPF?

		XBP (eXpress Data Path) is a type of eBPF program that attaches to the network interface. It allows for the processing of network packets as soon as they are received from the network driver, even before they enter the networking stack. XDP enables efficient packet filtering, manipulation and redirection at the earliest possible stage, resulting in low-latency and high-throughput.

		!!! example "Source Code"

		Full code for the example in this chapter is available [here](https://github.com/aya-rs/book/tree/main/examples/xdp-drop)

		Full code for the example in this chapter is available [here](https://github.com/aya-rs/book/tree/main/examples/xdp-drop)


		## What is XDP in eBPF?

	##### Loading the eBPF program
	##### Loading the eBPF program

	##### Loading and attaching our XDP
	##### Loading and attaching our XDP

	##### Setting up the ip blocklist
	##### Setting up the IP blocklist

	##### Waiting for the exit signal
	##### Waiting for the exit signal

docs: add Program Types/XDP documentation #155

Are you sure you want to change the base?

docs: add Program Types/XDP documentation #155

Conversation

shard77 commented Apr 24, 2024

netlify bot commented Apr 24, 2024 • edited Loading

✅ Deploy Preview for aya-rs ready!

vadorovsky left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shard77 Apr 30, 2024 • edited Loading

Choose a reason for hiding this comment

shard77 May 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shard77 May 30, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shard77 commented Apr 30, 2024

vadorovsky left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Apr 24, 2024 •

edited

Loading

shard77 Apr 30, 2024 •

edited

Loading

shard77 May 7, 2024 •

edited

Loading

shard77 May 30, 2024 •

edited

Loading