Add page in Documentation/block describing overview of IO filter
Signed-off-by: Kjetil Ørbekk <orbekk@xxxxxxxxxx>
Signed-off-by: Harshad Shirwadkar <harshads@xxxxxxxxxx>
Signed-off-by: Leah Rumancik <leah.rumancik@xxxxxxxxx>
---
Documentation/block/bpf_io_filter.rst | 28 +++++++++++++++++++++++++++
Documentation/block/index.rst | 1 +
2 files changed, 29 insertions(+)
create mode 100644 Documentation/block/bpf_io_filter.rst
diff --git a/Documentation/block/bpf_io_filter.rst b/Documentation/block/bpf_io_filter.rst
new file mode 100644
index 000000000000..956997576ae5
--- /dev/null
+++ b/Documentation/block/bpf_io_filter.rst
@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+IO Filtering with eBPF
+======================
+
+Bio requests can be filtered with the eBPF IO filter program type (BPF_PROG_TYPE_IO_FILTER). To use this program type, the kernel must be compiled with CONFIG_BPF_IO_FILTER.
+
+Attachment
+==========
+
+IO filter programs can be attached to disks using the BPF_BIO_SUBMIT attach type. Up to 64 filter programs can be attached to a single disk. References to the attached programs are stored in the gendisk struct as a bpf_prog_array.
+
+API
+===
+
+Data is passed between the userspace and kernel eBPF code via a new struct bpf_io_request. This struct contains three fields: sector_start (starting sector of the bio request), sector_cnt (size of the request in sectors), and opf (operation information, opf field from the bio).
+
+Hook
+====
+
+The eBPF programs for a given disk are run whenever a bio request is submitted to that disk. The eBPF programs return IO_BLOCK or IO_ALLOW. If any of the programs return IO_BLOCK, the bio request is blocked. Because of the placement of the hook in submit_bio, as of this version, mechanisms which bypass submit_bio, such as SG_IO and NVMe passthrough, are not able to be filtered.
+
+Example
+=======
+
+An example, protect_gpt, is provided in the /samples/bpf/ folder. This sample uses an IO filter program to protect the GUID partition table by preventing writes to the first 34 sectors.
+
diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst
index 026addfc69bc..145930622a92 100644
--- a/Documentation/block/index.rst
+++ b/Documentation/block/index.rst
@@ -24,3 +24,4 @@ Block
stat
switching-sched
writeback_cache_control
+ bpf-io-filter
--
2.28.0.236.gb10cc79966-goog
