Re: [PATCH man-pages] bpf.2: new page documenting bpf(2)
On Tue, Mar 10, 2015 at 6:16 AM, Silvan Jegen wrote: > Hi Alexei > > Please find some comments and suggestions below. Thanks a lot for review! I think I've addressed all comments: man2/bpf.2 | 187 1 file changed, 100 insertions(+), 87 deletions(-) :) the only thing I didn't change is 's/C/C dialect/ (?)' Because the word 'dialect' would mean that there are differences beyond reduced expressions. It's a normal C. Compiler doesn't allow certain C constructs. Like it's not possible to have global variables, loops, vararg functions, passing structures, etc. I'll add a license and will resend. Thanks! -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH man-pages] bpf.2: new page documenting bpf(2)
Hi Alexei
Please find some comments and suggestions below.
On Mon, Mar 9, 2015 at 11:10 PM, Alexei Starovoitov wrote:
> Signed-off-by: Alexei Starovoitov
> ---
> man2/bpf.2 | 593
>
> 1 file changed, 593 insertions(+)
> create mode 100644 man2/bpf.2
>
> diff --git a/man2/bpf.2 b/man2/bpf.2
> new file mode 100644
> index 000..21b42b4
> --- /dev/null
> +++ b/man2/bpf.2
> @@ -0,0 +1,593 @@
> +.TH BPF 2 2015-03-09 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +bpf - perform a command on extended BPF map or program
s/extended/an extended/
> +.SH SYNOPSIS
> +.nf
> +.B #include
> +.sp
> +.BI "int bpf(int cmd, union bpf_attr *attr, unsigned int size);
> +
> +.SH DESCRIPTION
> +.BR bpf()
> +syscall is a multiplexor for a range of different operations on extended BPF
> +which can be characterized as "universal in-kernel virtual machine".
> +Extended BPF (or eBPF) is similar to original Berkeley Packet Filter
s/original/the original/
> +(or "classic BPF") used to filter network packets. Both statically analyze
> +the programs before loading them into the kernel to ensure that programs
> cannot
s/programs/(e)BPF programs/ (?)
s/that programs/that they/
> +harm the running system.
> +.P
> +eBPF extends classic BPF in multiple ways including ability to call
s/ability/the ability/
> +in-kernel helper functions and access shared data structures like BPF maps.
> +The programs can be written in a restricted C that is compiled into
s/C/C dialect/ (?)
> +eBPF bytecode and executed on the in-kernel virtual machine or JITed into
> native
> +instruction set.
s/native instruction set/native code/ (?)
> +.SS Extended BPF Design/Architecture
> +.P
> +BPF maps is a generic storage of different types.
Maybe better:
+BPF maps are a generic data structure for storage of different data types.
> +User process can create multiple maps (with key/value being
s/User/A user/
s/key\/value/key\/value-pairs/
> +opaque bytes of data) and access them via file descriptor. In parallel BPF
> +programs can access maps from inside the kernel.
Better:
BPF programs can access maps from inside the kernel in parallel.
> +It's up to user process and BPF program to decide what they store inside
> maps.
s/to user process/to the user process/
> +.P
> +BPF programs are similar to kernel modules. They are loaded by the user
> +process and automatically unloaded when process exits. Each BPF program is
s/process/the process/
> +a safe run-to-completion set of instructions. BPF verifier statically
Maybe better:
Each BPF program is a set of instructions that is safe to run until
its completion.
s/BPF verifier/The BPF verifier/
> +determines that the program terminates and is safe to execute. During
> +verification the program takes a hold of maps that it intends to use,
s/takes a hold/takes hold/
> +so selected maps cannot be removed until the program is unloaded. The program
> +can be attached to different events. These events can be packets, tracing
> +events and other types in the future. A new event triggers execution of
s/in the future/that may be added in the future/
> +the program which may store information about the event in the maps.
> +Beyond storing data the programs may call into in-kernel helper functions.
> +The same program can be attached to multiple events. Different programs can
s/\. D/and d/ (?)
> +access the same map:
> +.nf
> + tracing tracing tracing packet packet
> + event A event B event C on eth0on eth1
> + | | | | |
> + | | | | |
> + --> tracing <-- tracing socket socket
> +prog_1 prog_2 prog_3 prog_4
> +| | ||
> + |--- -| |---| map_3
> + map_1 map_2
> +.fi
> +.SS Syscall Arguments
> +.B bpf()
> +syscall operation is determined by
> +.IR cmd
> +which can be one of the following:
> +.TP
> +.B BPF_MAP_CREATE
> +Create a map with given type and attributes and return map FD
s/given type/the given type/
> +.TP
> +.B BPF_MAP_LOOKUP_ELEM
> +Lookup element by key in a given map and return its value
> +.TP
> +.B BPF_MAP_UPDATE_ELEM
> +Create or update element (key/value pair) in a given map
> +.TP
> +.B BPF_MAP_DELETE_ELEM
> +Lookup and delete element by key in a given map
> +.TP
> +.B BPF_MAP_GET_NEXT_KEY
> +Lookup element by key in a given map and return key of next element
> +.TP
> +.B BPF_PROG_LOAD
> +Verify and load BPF program
> +.TP
> +.B attr
> +is a pointer to a union of type bpf_attr as defined below.
> +.TP
> +.B size
> +is the size of the union.
> +.P
> +.nf
> +union bpf_attr {
> +struct { /* anonymous struct used by BPF_MAP_CREATE command */
> +__u32 map_type;
> +__u32 key_size;/* size of key in bytes */
> +__u32
Re: [PATCH man-pages] bpf.2: new page documenting bpf(2)
Hi Alexei
Please find some comments and suggestions below.
On Mon, Mar 9, 2015 at 11:10 PM, Alexei Starovoitov a...@plumgrid.com wrote:
Signed-off-by: Alexei Starovoitov a...@plumgrid.com
---
man2/bpf.2 | 593
1 file changed, 593 insertions(+)
create mode 100644 man2/bpf.2
diff --git a/man2/bpf.2 b/man2/bpf.2
new file mode 100644
index 000..21b42b4
--- /dev/null
+++ b/man2/bpf.2
@@ -0,0 +1,593 @@
+.TH BPF 2 2015-03-09 Linux Linux Programmer's Manual
+.SH NAME
+bpf - perform a command on extended BPF map or program
s/extended/an extended/
+.SH SYNOPSIS
+.nf
+.B #include linux/bpf.h
+.sp
+.BI int bpf(int cmd, union bpf_attr *attr, unsigned int size);
+
+.SH DESCRIPTION
+.BR bpf()
+syscall is a multiplexor for a range of different operations on extended BPF
+which can be characterized as universal in-kernel virtual machine.
+Extended BPF (or eBPF) is similar to original Berkeley Packet Filter
s/original/the original/
+(or classic BPF) used to filter network packets. Both statically analyze
+the programs before loading them into the kernel to ensure that programs
cannot
s/programs/(e)BPF programs/ (?)
s/that programs/that they/
+harm the running system.
+.P
+eBPF extends classic BPF in multiple ways including ability to call
s/ability/the ability/
+in-kernel helper functions and access shared data structures like BPF maps.
+The programs can be written in a restricted C that is compiled into
s/C/C dialect/ (?)
+eBPF bytecode and executed on the in-kernel virtual machine or JITed into
native
+instruction set.
s/native instruction set/native code/ (?)
+.SS Extended BPF Design/Architecture
+.P
+BPF maps is a generic storage of different types.
Maybe better:
+BPF maps are a generic data structure for storage of different data types.
+User process can create multiple maps (with key/value being
s/User/A user/
s/key\/value/key\/value-pairs/
+opaque bytes of data) and access them via file descriptor. In parallel BPF
+programs can access maps from inside the kernel.
Better:
BPF programs can access maps from inside the kernel in parallel.
+It's up to user process and BPF program to decide what they store inside
maps.
s/to user process/to the user process/
+.P
+BPF programs are similar to kernel modules. They are loaded by the user
+process and automatically unloaded when process exits. Each BPF program is
s/process/the process/
+a safe run-to-completion set of instructions. BPF verifier statically
Maybe better:
Each BPF program is a set of instructions that is safe to run until
its completion.
s/BPF verifier/The BPF verifier/
+determines that the program terminates and is safe to execute. During
+verification the program takes a hold of maps that it intends to use,
s/takes a hold/takes hold/
+so selected maps cannot be removed until the program is unloaded. The program
+can be attached to different events. These events can be packets, tracing
+events and other types in the future. A new event triggers execution of
s/in the future/that may be added in the future/
+the program which may store information about the event in the maps.
+Beyond storing data the programs may call into in-kernel helper functions.
+The same program can be attached to multiple events. Different programs can
s/\. D/and d/ (?)
+access the same map:
+.nf
+ tracing tracing tracing packet packet
+ event A event B event C on eth0on eth1
+ | | | | |
+ | | | | |
+ -- tracing -- tracing socket socket
+prog_1 prog_2 prog_3 prog_4
+| | ||
+ |--- -| |---| map_3
+ map_1 map_2
+.fi
+.SS Syscall Arguments
+.B bpf()
+syscall operation is determined by
+.IR cmd
+which can be one of the following:
+.TP
+.B BPF_MAP_CREATE
+Create a map with given type and attributes and return map FD
s/given type/the given type/
+.TP
+.B BPF_MAP_LOOKUP_ELEM
+Lookup element by key in a given map and return its value
+.TP
+.B BPF_MAP_UPDATE_ELEM
+Create or update element (key/value pair) in a given map
+.TP
+.B BPF_MAP_DELETE_ELEM
+Lookup and delete element by key in a given map
+.TP
+.B BPF_MAP_GET_NEXT_KEY
+Lookup element by key in a given map and return key of next element
+.TP
+.B BPF_PROG_LOAD
+Verify and load BPF program
+.TP
+.B attr
+is a pointer to a union of type bpf_attr as defined below.
+.TP
+.B size
+is the size of the union.
+.P
+.nf
+union bpf_attr {
+struct { /* anonymous struct used by BPF_MAP_CREATE command */
+__u32 map_type;
+__u32 key_size;/* size of key in bytes */
+__u32 value_size; /* size of value in bytes */
+__u32
Re: [PATCH man-pages] bpf.2: new page documenting bpf(2)
On Tue, Mar 10, 2015 at 6:16 AM, Silvan Jegen s.je...@gmail.com wrote: Hi Alexei Please find some comments and suggestions below. Thanks a lot for review! I think I've addressed all comments: man2/bpf.2 | 187 1 file changed, 100 insertions(+), 87 deletions(-) :) the only thing I didn't change is 's/C/C dialect/ (?)' Because the word 'dialect' would mean that there are differences beyond reduced expressions. It's a normal C. Compiler doesn't allow certain C constructs. Like it's not possible to have global variables, loops, vararg functions, passing structures, etc. I'll add a license and will resend. Thanks! -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH man-pages] bpf.2: new page documenting bpf(2)
Hi Alexei,
The page needs a license. See
https://www.kernel.org/doc/man-pages/licenses.html
for some possible choices.
Thanks,
Michael
On 03/09/2015 11:10 PM, Alexei Starovoitov wrote:
> Signed-off-by: Alexei Starovoitov
> ---
> man2/bpf.2 | 593
>
> 1 file changed, 593 insertions(+)
> create mode 100644 man2/bpf.2
>
> diff --git a/man2/bpf.2 b/man2/bpf.2
> new file mode 100644
> index 000..21b42b4
> --- /dev/null
> +++ b/man2/bpf.2
> @@ -0,0 +1,593 @@
> +.TH BPF 2 2015-03-09 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +bpf - perform a command on extended BPF map or program
> +.SH SYNOPSIS
> +.nf
> +.B #include
> +.sp
> +.BI "int bpf(int cmd, union bpf_attr *attr, unsigned int size);
> +
> +.SH DESCRIPTION
> +.BR bpf()
> +syscall is a multiplexor for a range of different operations on extended BPF
> +which can be characterized as "universal in-kernel virtual machine".
> +Extended BPF (or eBPF) is similar to original Berkeley Packet Filter
> +(or "classic BPF") used to filter network packets. Both statically analyze
> +the programs before loading them into the kernel to ensure that programs
> cannot
> +harm the running system.
> +.P
> +eBPF extends classic BPF in multiple ways including ability to call
> +in-kernel helper functions and access shared data structures like BPF maps.
> +The programs can be written in a restricted C that is compiled into
> +eBPF bytecode and executed on the in-kernel virtual machine or JITed into
> native
> +instruction set.
> +.SS Extended BPF Design/Architecture
> +.P
> +BPF maps is a generic storage of different types.
> +User process can create multiple maps (with key/value being
> +opaque bytes of data) and access them via file descriptor. In parallel BPF
> +programs can access maps from inside the kernel.
> +It's up to user process and BPF program to decide what they store inside
> maps.
> +.P
> +BPF programs are similar to kernel modules. They are loaded by the user
> +process and automatically unloaded when process exits. Each BPF program is
> +a safe run-to-completion set of instructions. BPF verifier statically
> +determines that the program terminates and is safe to execute. During
> +verification the program takes a hold of maps that it intends to use,
> +so selected maps cannot be removed until the program is unloaded. The program
> +can be attached to different events. These events can be packets, tracing
> +events and other types in the future. A new event triggers execution of
> +the program which may store information about the event in the maps.
> +Beyond storing data the programs may call into in-kernel helper functions.
> +The same program can be attached to multiple events. Different programs can
> +access the same map:
> +.nf
> + tracing tracing tracing packet packet
> + event A event B event C on eth0on eth1
> + | | | | |
> + | | | | |
> + --> tracing <-- tracing socket socket
> +prog_1 prog_2 prog_3 prog_4
> +| | ||
> + |--- -| |---| map_3
> + map_1 map_2
> +.fi
> +.SS Syscall Arguments
> +.B bpf()
> +syscall operation is determined by
> +.IR cmd
> +which can be one of the following:
> +.TP
> +.B BPF_MAP_CREATE
> +Create a map with given type and attributes and return map FD
> +.TP
> +.B BPF_MAP_LOOKUP_ELEM
> +Lookup element by key in a given map and return its value
> +.TP
> +.B BPF_MAP_UPDATE_ELEM
> +Create or update element (key/value pair) in a given map
> +.TP
> +.B BPF_MAP_DELETE_ELEM
> +Lookup and delete element by key in a given map
> +.TP
> +.B BPF_MAP_GET_NEXT_KEY
> +Lookup element by key in a given map and return key of next element
> +.TP
> +.B BPF_PROG_LOAD
> +Verify and load BPF program
> +.TP
> +.B attr
> +is a pointer to a union of type bpf_attr as defined below.
> +.TP
> +.B size
> +is the size of the union.
> +.P
> +.nf
> +union bpf_attr {
> +struct { /* anonymous struct used by BPF_MAP_CREATE command */
> +__u32 map_type;
> +__u32 key_size;/* size of key in bytes */
> +__u32 value_size; /* size of value in bytes */
> +__u32 max_entries; /* max number of entries in a map */
> +};
> +
> +struct { /* anonymous struct used by BPF_MAP_*_ELEM commands */
> +__u32 map_fd;
> +__aligned_u64 key;
> +union {
> +__aligned_u64 value;
> +__aligned_u64 next_key;
> +};
> + __u64 flags;
> +};
> +
> +struct { /* anonymous struct used by BPF_PROG_LOAD command */
> +__u32 prog_type;
> +__u32 insn_cnt;
> +__aligned_u64 insns; /* 'const struct bpf_insn *' */
> +__aligned_u64 license; /* 'const char *' */
Re: [PATCH man-pages] bpf.2: new page documenting bpf(2)
Hi Alexei,
The page needs a license. See
https://www.kernel.org/doc/man-pages/licenses.html
for some possible choices.
Thanks,
Michael
On 03/09/2015 11:10 PM, Alexei Starovoitov wrote:
Signed-off-by: Alexei Starovoitov a...@plumgrid.com
---
man2/bpf.2 | 593
1 file changed, 593 insertions(+)
create mode 100644 man2/bpf.2
diff --git a/man2/bpf.2 b/man2/bpf.2
new file mode 100644
index 000..21b42b4
--- /dev/null
+++ b/man2/bpf.2
@@ -0,0 +1,593 @@
+.TH BPF 2 2015-03-09 Linux Linux Programmer's Manual
+.SH NAME
+bpf - perform a command on extended BPF map or program
+.SH SYNOPSIS
+.nf
+.B #include linux/bpf.h
+.sp
+.BI int bpf(int cmd, union bpf_attr *attr, unsigned int size);
+
+.SH DESCRIPTION
+.BR bpf()
+syscall is a multiplexor for a range of different operations on extended BPF
+which can be characterized as universal in-kernel virtual machine.
+Extended BPF (or eBPF) is similar to original Berkeley Packet Filter
+(or classic BPF) used to filter network packets. Both statically analyze
+the programs before loading them into the kernel to ensure that programs
cannot
+harm the running system.
+.P
+eBPF extends classic BPF in multiple ways including ability to call
+in-kernel helper functions and access shared data structures like BPF maps.
+The programs can be written in a restricted C that is compiled into
+eBPF bytecode and executed on the in-kernel virtual machine or JITed into
native
+instruction set.
+.SS Extended BPF Design/Architecture
+.P
+BPF maps is a generic storage of different types.
+User process can create multiple maps (with key/value being
+opaque bytes of data) and access them via file descriptor. In parallel BPF
+programs can access maps from inside the kernel.
+It's up to user process and BPF program to decide what they store inside
maps.
+.P
+BPF programs are similar to kernel modules. They are loaded by the user
+process and automatically unloaded when process exits. Each BPF program is
+a safe run-to-completion set of instructions. BPF verifier statically
+determines that the program terminates and is safe to execute. During
+verification the program takes a hold of maps that it intends to use,
+so selected maps cannot be removed until the program is unloaded. The program
+can be attached to different events. These events can be packets, tracing
+events and other types in the future. A new event triggers execution of
+the program which may store information about the event in the maps.
+Beyond storing data the programs may call into in-kernel helper functions.
+The same program can be attached to multiple events. Different programs can
+access the same map:
+.nf
+ tracing tracing tracing packet packet
+ event A event B event C on eth0on eth1
+ | | | | |
+ | | | | |
+ -- tracing -- tracing socket socket
+prog_1 prog_2 prog_3 prog_4
+| | ||
+ |--- -| |---| map_3
+ map_1 map_2
+.fi
+.SS Syscall Arguments
+.B bpf()
+syscall operation is determined by
+.IR cmd
+which can be one of the following:
+.TP
+.B BPF_MAP_CREATE
+Create a map with given type and attributes and return map FD
+.TP
+.B BPF_MAP_LOOKUP_ELEM
+Lookup element by key in a given map and return its value
+.TP
+.B BPF_MAP_UPDATE_ELEM
+Create or update element (key/value pair) in a given map
+.TP
+.B BPF_MAP_DELETE_ELEM
+Lookup and delete element by key in a given map
+.TP
+.B BPF_MAP_GET_NEXT_KEY
+Lookup element by key in a given map and return key of next element
+.TP
+.B BPF_PROG_LOAD
+Verify and load BPF program
+.TP
+.B attr
+is a pointer to a union of type bpf_attr as defined below.
+.TP
+.B size
+is the size of the union.
+.P
+.nf
+union bpf_attr {
+struct { /* anonymous struct used by BPF_MAP_CREATE command */
+__u32 map_type;
+__u32 key_size;/* size of key in bytes */
+__u32 value_size; /* size of value in bytes */
+__u32 max_entries; /* max number of entries in a map */
+};
+
+struct { /* anonymous struct used by BPF_MAP_*_ELEM commands */
+__u32 map_fd;
+__aligned_u64 key;
+union {
+__aligned_u64 value;
+__aligned_u64 next_key;
+};
+ __u64 flags;
+};
+
+struct { /* anonymous struct used by BPF_PROG_LOAD command */
+__u32 prog_type;
+__u32 insn_cnt;
+__aligned_u64 insns; /* 'const struct bpf_insn *' */
+__aligned_u64 license; /* 'const char *' */
+__u32 log_level; /* verbosity level of verifier */
+__u32 log_size; /*
