Commit db7a2382977a12e3ad95e3f2249c538d9c31cd87 | zig

author	Matthew Knight <mattnite@protonmail.com> 2020-09-07 12:41:29-07:00
committer	GitHub <noreply@github.com> 2020-09-07 15:41:29-04:00
log	db7a2382977a12e3ad95e3f2249c538d9c31cd87
tree	eee18ab6bd453284268700ed941872fcebbd46f3
parent	f96f3265b56bddb4d4faa89d65b865d0a42ad5ed
signature	Signed by PGP key 4AEE18F83AFDEB23

BPF: add some more documentation (#6268)

* added documentation for ringbuffers, which context type maps to which program type, and added some formatting

1 files changed, 284 insertions(+), 4 deletions(-)

lib
- std
  - os
    linux
    bpf.zig

lib/std/os/linux/bpf.zig+284-4

...	...	@@ -62,6 +62,7 @@ pub const MAXINSNS = 4096;
62	62	// instruction classes
63	63	/// jmp mode in word width
64	64	pub const JMP32 = 0x06;
	65
65	66	/// alu mode in double word width
66	67	pub const ALU64 = 0x07;
67	68
...	...	@@ -72,14 +73,17 @@ pub const XADD = 0xc0;
72	73	// alu/jmp fields
73	74	/// mov reg to reg
74	75	pub const MOV = 0xb0;
	76
75	77	/// sign extending arithmetic shift right */
76	78	pub const ARSH = 0xc0;
77	79
78	80	// change endianness of a register
79	81	/// flags for endianness conversion:
80	82	pub const END = 0xd0;
	83
81	84	/// convert to little-endian */
82	85	pub const TO_LE = 0x00;
	86
83	87	/// convert to big-endian
84	88	pub const TO_BE = 0x08;
85	89	pub const FROM_LE = TO_LE;
...	...	@@ -88,29 +92,39 @@ pub const FROM_BE = TO_BE;
88	92	// jmp encodings
89	93	/// jump != *
90	94	pub const JNE = 0x50;
	95
91	96	/// LT is unsigned, '<'
92	97	pub const JLT = 0xa0;
	98
93	99	/// LE is unsigned, '<=' *
94	100	pub const JLE = 0xb0;
	101
95	102	/// SGT is signed '>', GT in x86
96	103	pub const JSGT = 0x60;
	104
97	105	/// SGE is signed '>=', GE in x86
98	106	pub const JSGE = 0x70;
	107
99	108	/// SLT is signed, '<'
100	109	pub const JSLT = 0xc0;
	110
101	111	/// SLE is signed, '<='
102	112	pub const JSLE = 0xd0;
	113
103	114	/// function call
104	115	pub const CALL = 0x80;
	116
105	117	/// function return
106	118	pub const EXIT = 0x90;
107	119
108	120	/// Flag for prog_attach command. If a sub-cgroup installs some bpf program, the
109	121	/// program in this cgroup yields to sub-cgroup program.
110	122	pub const F_ALLOW_OVERRIDE = 0x1;
	123
111	124	/// Flag for prog_attach command. If a sub-cgroup installs some bpf program,
112	125	/// that cgroup program gets run in addition to the program in this cgroup.
113	126	pub const F_ALLOW_MULTI = 0x2;
	127
114	128	/// Flag for prog_attach command.
115	129	pub const F_REPLACE = 0x4;
116	130
...	...	@@ -164,47 +178,61 @@ pub const PSEUDO_CALL = 1;
164	178
165	179	/// flag for BPF_MAP_UPDATE_ELEM command. create new element or update existing
166	180	pub const ANY = 0;
	181
167	182	/// flag for BPF_MAP_UPDATE_ELEM command. create new element if it didn't exist
168	183	pub const NOEXIST = 1;
	184
169	185	/// flag for BPF_MAP_UPDATE_ELEM command. update existing element
170	186	pub const EXIST = 2;
	187
171	188	/// flag for BPF_MAP_UPDATE_ELEM command. spin_lock-ed map_lookup/map_update
172	189	pub const F_LOCK = 4;
173	190
174	191	/// flag for BPF_MAP_CREATE command */
175	192	pub const BPF_F_NO_PREALLOC = 0x1;
	193
176	194	/// flag for BPF_MAP_CREATE command. Instead of having one common LRU list in
177	195	/// the BPF_MAP_TYPE_LRU_[PERCPU_]HASH map, use a percpu LRU list which can
178	196	/// scale and perform better. Note, the LRU nodes (including free nodes) cannot
179	197	/// be moved across different LRU lists.
180	198	pub const BPF_F_NO_COMMON_LRU = 0x2;
	199
181	200	/// flag for BPF_MAP_CREATE command. Specify numa node during map creation
182	201	pub const BPF_F_NUMA_NODE = 0x4;
	202
183	203	/// flag for BPF_MAP_CREATE command. Flags for BPF object read access from
184	204	/// syscall side
185	205	pub const BPF_F_RDONLY = 0x8;
	206
186	207	/// flag for BPF_MAP_CREATE command. Flags for BPF object write access from
187	208	/// syscall side
188	209	pub const BPF_F_WRONLY = 0x10;
	210
189	211	/// flag for BPF_MAP_CREATE command. Flag for stack_map, store build_id+offset
190	212	/// instead of pointer
191	213	pub const BPF_F_STACK_BUILD_ID = 0x20;
	214
192	215	/// flag for BPF_MAP_CREATE command. Zero-initialize hash function seed. This
193	216	/// should only be used for testing.
194	217	pub const BPF_F_ZERO_SEED = 0x40;
	218
195	219	/// flag for BPF_MAP_CREATE command Flags for accessing BPF object from program
196	220	/// side.
197	221	pub const BPF_F_RDONLY_PROG = 0x80;
	222
198	223	/// flag for BPF_MAP_CREATE command. Flags for accessing BPF object from program
199	224	/// side.
200	225	pub const BPF_F_WRONLY_PROG = 0x100;
	226
201	227	/// flag for BPF_MAP_CREATE command. Clone map from listener for newly accepted
202	228	/// socket
203	229	pub const BPF_F_CLONE = 0x200;
	230
204	231	/// flag for BPF_MAP_CREATE command. Enable memory-mapping BPF map
205	232	pub const BPF_F_MMAPABLE = 0x400;
206	233
207		/// These values correspond to "syscalls" within the BPF program's environment
	234	/// These values correspond to "syscalls" within the BPF program's environment,
	235	/// each one is documented in std.os.linux.BPF.kern
208	236	pub const Helper = enum(i32) {
209	237	unspec,
210	238	map_lookup_elem,
...	...	@@ -325,6 +353,29 @@ pub const Helper = enum(i32) {
325	353	tcp_send_ack,
326	354	send_signal_thread,
327	355	jiffies64,
	356	read_branch_records,
	357	get_ns_current_pid_tgid,
	358	xdp_output,
	359	get_netns_cookie,
	360	get_current_ancestor_cgroup_id,
	361	sk_assign,
	362	ktime_get_boot_ns,
	363	seq_printf,
	364	seq_write,
	365	sk_cgroup_id,
	366	sk_ancestor_cgroup_id,
	367	ringbuf_output,
	368	ringbuf_reserve,
	369	ringbuf_submit,
	370	ringbuf_discard,
	371	ringbuf_query,
	372	csum_level,
	373	skc_to_tcp6_sock,
	374	skc_to_tcp_sock,
	375	skc_to_tcp_timewait_sock,
	376	skc_to_tcp_request_sock,
	377	skc_to_udp6_sock,
	378	get_task_stack,
328	379	_,
329	380	};
330	381
...	...	@@ -797,39 +848,123 @@ test "opcodes" {
797	848	}
798	849
799	850	pub const Cmd = extern enum(usize) {
	851	/// Create a map and return a file descriptor that refers to the map. The
	852	/// close-on-exec file descriptor flag is automatically enabled for the new
	853	/// file descriptor.
	854	///
	855	/// uses MapCreateAttr
800	856	map_create,
	857
	858	/// Look up an element by key in a specified map and return its value.
	859	///
	860	/// uses MapElemAttr
801	861	map_lookup_elem,
	862
	863	/// Create or update an element (key/value pair) in a specified map.
	864	///
	865	/// uses MapElemAttr
802	866	map_update_elem,
	867
	868	/// Look up and delete an element by key in a specified map.
	869	///
	870	/// uses MapElemAttr
803	871	map_delete_elem,
	872
	873	/// Look up an element by key in a specified map and return the key of the
	874	/// next element.
804	875	map_get_next_key,
	876
	877	/// Verify and load an eBPF program, returning a new file descriptor
	878	/// associated with the program. The close-on-exec file descriptor flag
	879	/// is automatically enabled for the new file descriptor.
	880	///
	881	/// uses ProgLoadAttr
805	882	prog_load,
	883
	884	/// Pin a map or eBPF program to a path within the minimal BPF filesystem
	885	///
	886	/// uses ObjAttr
806	887	obj_pin,
	888
	889	/// Get the file descriptor of a BPF object pinned to a certain path
	890	///
	891	/// uses ObjAttr
807	892	obj_get,
	893
	894	/// uses ProgAttachAttr
808	895	prog_attach,
	896
	897	/// uses ProgAttachAttr
809	898	prog_detach,
	899
	900	/// uses TestRunAttr
810	901	prog_test_run,
	902
	903	/// uses GetIdAttr
811	904	prog_get_next_id,
	905
	906	/// uses GetIdAttr
812	907	map_get_next_id,
	908
	909	/// uses GetIdAttr
813	910	prog_get_fd_by_id,
	911
	912	/// uses GetIdAttr
814	913	map_get_fd_by_id,
	914
	915	/// uses InfoAttr
815	916	obj_get_info_by_fd,
	917
	918	/// uses QueryAttr
816	919	prog_query,
	920
	921	/// uses RawTracepointAttr
817	922	raw_tracepoint_open,
	923
	924	/// uses BtfLoadAttr
818	925	btf_load,
	926
	927	/// uses GetIdAttr
819	928	btf_get_fd_by_id,
	929
	930	/// uses TaskFdQueryAttr
820	931	task_fd_query,
	932
	933	/// uses MapElemAttr
821	934	map_lookup_and_delete_elem,
822	935	map_freeze,
	936
	937	/// uses GetIdAttr
823	938	btf_get_next_id,
	939
	940	/// uses MapBatchAttr
824	941	map_lookup_batch,
	942
	943	/// uses MapBatchAttr
825	944	map_lookup_and_delete_batch,
	945
	946	/// uses MapBatchAttr
826	947	map_update_batch,
	948
	949	/// uses MapBatchAttr
827	950	map_delete_batch,
	951
	952	/// uses LinkCreateAttr
828	953	link_create,
	954
	955	/// uses LinkUpdateAttr
829	956	link_update,
	957
	958	/// uses GetIdAttr
830	959	link_get_fd_by_id,
	960
	961	/// uses GetIdAttr
831	962	link_get_next_id,
	963
	964	/// uses EnableStatsAttr
832	965	enable_stats,
	966
	967	/// uses IterCreateAttr
833	968	iter_create,
834	969	link_detach,
835	970	_,
...	...	@@ -863,42 +998,138 @@ pub const MapType = extern enum(u32) {
863	998	sk_storage,
864	999	devmap_hash,
865	1000	struct_ops,
	1001
	1002	/// An ordered and shared CPU version of perf_event_array. They have
	1003	/// similar semantics:
	1004	/// - variable length records
	1005	/// - no blocking: when full, reservation fails
	1006	/// - memory mappable for ease and speed
	1007	/// - epoll notifications for new data, but can busy poll
	1008	///
	1009	/// Ringbufs give BPF programs two sets of APIs:
	1010	/// - ringbuf_output() allows copy data from one place to a ring
	1011	/// buffer, similar to bpf_perf_event_output()
	1012	/// - ringbuf_reserve()/ringbuf_commit()/ringbuf_discard() split the
	1013	/// process into two steps. First a fixed amount of space is reserved,
	1014	/// if that is successful then the program gets a pointer to a chunk of
	1015	/// memory and can be submitted with commit() or discarded with
	1016	/// discard()
	1017	///
	1018	/// ringbuf_output() will incurr an extra memory copy, but allows to submit
	1019	/// records of the length that's not known beforehand, and is an easy
	1020	/// replacement for perf_event_outptu().
	1021	///
	1022	/// ringbuf_reserve() avoids the extra memory copy but requires a known size
	1023	/// of memory beforehand.
	1024	///
	1025	/// ringbuf_query() allows to query properties of the map, 4 are currently
	1026	/// supported:
	1027	/// - BPF_RB_AVAIL_DATA: amount of unconsumed data in ringbuf
	1028	/// - BPF_RB_RING_SIZE: returns size of ringbuf
	1029	/// - BPF_RB_CONS_POS/BPF_RB_PROD_POS returns current logical position
	1030	/// of consumer and producer respectively
	1031	///
	1032	/// key size: 0
	1033	/// value size: 0
	1034	/// max entries: size of ringbuf, must be power of 2
866	1035	ringbuf,
	1036
867	1037	_,
868	1038	};
869	1039
870	1040	pub const ProgType = extern enum(u32) {
871	1041	unspec,
	1042
	1043	/// context type: __sk_buff
872	1044	socket_filter,
	1045
	1046	/// context type: bpf_user_pt_regs_t
873	1047	kprobe,
	1048
	1049	/// context type: __sk_buff
874	1050	sched_cls,
	1051
	1052	/// context type: __sk_buff
875	1053	sched_act,
	1054
	1055	/// context type: u64
876	1056	tracepoint,
	1057
	1058	/// context type: xdp_md
877	1059	xdp,
	1060
	1061	/// context type: bpf_perf_event_data
878	1062	perf_event,
	1063
	1064	/// context type: __sk_buff
879	1065	cgroup_skb,
	1066
	1067	/// context type: bpf_sock
880	1068	cgroup_sock,
	1069
	1070	/// context type: __sk_buff
881	1071	lwt_in,
	1072
	1073	/// context type: __sk_buff
882	1074	lwt_out,
	1075
	1076	/// context type: __sk_buff
883	1077	lwt_xmit,
	1078
	1079	/// context type: bpf_sock_ops
884	1080	sock_ops,
	1081
	1082	/// context type: __sk_buff
885	1083	sk_skb,
	1084
	1085	/// context type: bpf_cgroup_dev_ctx
886	1086	cgroup_device,
	1087
	1088	/// context type: sk_msg_md
887	1089	sk_msg,
	1090
	1091	/// context type: bpf_raw_tracepoint_args
888	1092	raw_tracepoint,
	1093
	1094	/// context type: bpf_sock_addr
889	1095	cgroup_sock_addr,
	1096
	1097	/// context type: __sk_buff
890	1098	lwt_seg6local,
	1099
	1100	/// context type: u32
891	1101	lirc_mode2,
	1102
	1103	/// context type: sk_reuseport_md
892	1104	sk_reuseport,
	1105
	1106	/// context type: __sk_buff
893	1107	flow_dissector,
	1108
	1109	/// context type: bpf_sysctl
894	1110	cgroup_sysctl,
	1111
	1112	/// context type: bpf_raw_tracepoint_args
895	1113	raw_tracepoint_writable,
	1114
	1115	/// context type: bpf_sockopt
896	1116	cgroup_sockopt,
	1117
	1118	/// context type: void *
897	1119	tracing,
	1120
	1121	/// context type: void *
898	1122	struct_ops,
	1123
	1124	/// context type: void *
899	1125	ext,
	1126
	1127	/// context type: void *
900	1128	lsm,
	1129
	1130	/// context type: bpf_sk_lookup
901	1131	sk_lookup,
	1132	_,
902	1133	};
903	1134
904	1135	pub const AttachType = extern enum(u32) {
...	...	@@ -948,27 +1179,38 @@ const obj_name_len = 16;
948	1179	pub const MapCreateAttr = extern struct {
949	1180	/// one of MapType
950	1181	map_type: u32,
	1182
951	1183	/// size of key in bytes
952	1184	key_size: u32,
	1185
953	1186	/// size of value in bytes
954	1187	value_size: u32,
	1188
955	1189	/// max number of entries in a map
956	1190	max_entries: u32,
	1191
957	1192	/// .map_create related flags
958	1193	map_flags: u32,
	1194
959	1195	/// fd pointing to the inner map
960	1196	inner_map_fd: fd_t,
	1197
961	1198	/// numa node (effective only if MapCreateFlags.numa_node is set)
962	1199	numa_node: u32,
963	1200	map_name: [obj_name_len]u8,
	1201
964	1202	/// ifindex of netdev to create on
965	1203	map_ifindex: u32,
	1204
966	1205	/// fd pointing to a BTF type data
967	1206	btf_fd: fd_t,
	1207
968	1208	/// BTF type_id of the key
969	1209	btf_key_type_id: u32,
	1210
970	1211	/// BTF type_id of the value
971	1212	bpf_value_type_id: u32,
	1213
972	1214	/// BTF type_id of a kernel struct stored as the map value
973	1215	btf_vmlinux_value_type_id: u32,
974	1216	};
...	...	@@ -988,10 +1230,12 @@ pub const MapElemAttr = extern struct {
988	1230	pub const MapBatchAttr = extern struct {
989	1231	/// start batch, NULL to start from beginning
990	1232	in_batch: u64,
	1233
991	1234	/// output: next start batch
992	1235	out_batch: u64,
993	1236	keys: u64,
994	1237	values: u64,
	1238
995	1239	/// input/output:
996	1240	/// input: # of key/value elements
997	1241	/// output: # of filled elements
...	...	@@ -1008,35 +1252,49 @@ pub const ProgLoadAttr = extern struct {
1008	1252	insn_cnt: u32,
1009	1253	insns: u64,
1010	1254	license: u64,
	1255
1011	1256	/// verbosity level of verifier
1012	1257	log_level: u32,
	1258
1013	1259	/// size of user buffer
1014	1260	log_size: u32,
	1261
1015	1262	/// user supplied buffer
1016	1263	log_buf: u64,
	1264
1017	1265	/// not used
1018	1266	kern_version: u32,
1019	1267	prog_flags: u32,
1020	1268	prog_name: [obj_name_len]u8,
1021		/// ifindex of netdev to prep for. For some prog types expected attach
1022		/// type must be known at load time to verify attach type specific parts
1023		/// of prog (context accesses, allowed helpers, etc).
	1269
	1270	/// ifindex of netdev to prep for.
1024	1271	prog_ifindex: u32,
	1272
	1273	/// For some prog types expected attach type must be known at load time to
	1274	/// verify attach type specific parts of prog (context accesses, allowed
	1275	/// helpers, etc).
1025	1276	expected_attach_type: u32,
	1277
1026	1278	/// fd pointing to BTF type data
1027	1279	prog_btf_fd: fd_t,
	1280
1028	1281	/// userspace bpf_func_info size
1029	1282	func_info_rec_size: u32,
1030	1283	func_info: u64,
	1284
1031	1285	/// number of bpf_func_info records
1032	1286	func_info_cnt: u32,
	1287
1033	1288	/// userspace bpf_line_info size
1034	1289	line_info_rec_size: u32,
1035	1290	line_info: u64,
	1291
1036	1292	/// number of bpf_line_info records
1037	1293	line_info_cnt: u32,
	1294
1038	1295	/// in-kernel BTF type id to attach to
1039	1296	attact_btf_id: u32,
	1297
1040	1298	/// 0 to attach to vmlinux
1041	1299	attach_prog_id: u32,
1042	1300	};
...	...	@@ -1052,10 +1310,13 @@ pub const ObjAttr = extern struct {
1052	1310	pub const ProgAttachAttr = extern struct {
1053	1311	/// container object to attach to
1054	1312	target_fd: fd_t,
	1313
1055	1314	/// eBPF program to attach
1056	1315	attach_bpf_fd: fd_t,
	1316
1057	1317	attach_type: u32,
1058	1318	attach_flags: u32,
	1319
1059	1320	// TODO: BPF_F_REPLACE flags
1060	1321	/// previously attached eBPF program to replace if .replace is used
1061	1322	replace_bpf_fd: fd_t,
...	...	@@ -1065,16 +1326,20 @@ pub const ProgAttachAttr = extern struct {
1065	1326	pub const TestAttr = extern struct {
1066	1327	prog_fd: fd_t,
1067	1328	retval: u32,
	1329
1068	1330	/// input: len of data_in
1069	1331	data_size_in: u32,
	1332
1070	1333	/// input/output: len of data_out. returns ENOSPC if data_out is too small.
1071	1334	data_size_out: u32,
1072	1335	data_in: u64,
1073	1336	data_out: u64,
1074	1337	repeat: u32,
1075	1338	duration: u32,
	1339
1076	1340	/// input: len of ctx_in
1077	1341	ctx_size_in: u32,
	1342
1078	1343	/// input/output: len of ctx_out. returns ENOSPC if ctx_out is too small.
1079	1344	ctx_size_out: u32,
1080	1345	ctx_in: u64,
...	...	@@ -1127,26 +1392,35 @@ pub const BtfLoadAttr = extern struct {
1127	1392	btf_log_level: u32,
1128	1393	};
1129	1394
	1395	/// struct used by Cmd.task_fd_query
1130	1396	pub const TaskFdQueryAttr = extern struct {
1131	1397	/// input: pid
1132	1398	pid: pid_t,
	1399
1133	1400	/// input: fd
1134	1401	fd: fd_t,
	1402
1135	1403	/// input: flags
1136	1404	flags: u32,
	1405
1137	1406	/// input/output: buf len
1138	1407	buf_len: u32,
	1408
1139	1409	/// input/output:
1140	1410	/// tp_name for tracepoint
1141	1411	/// symbol for kprobe
1142	1412	/// filename for uprobe
1143	1413	buf: u64,
	1414
1144	1415	/// output: prod_id
1145	1416	prog_id: u32,
	1417
1146	1418	/// output: BPF_FD_TYPE
1147	1419	fd_type: u32,
	1420
1148	1421	/// output: probe_offset
1149	1422	probe_offset: u64,
	1423
1150	1424	/// output: probe_addr
1151	1425	probe_addr: u64,
1152	1426	};
...	...	@@ -1155,9 +1429,11 @@ pub const TaskFdQueryAttr = extern struct {
1155	1429	pub const LinkCreateAttr = extern struct {
1156	1430	/// eBPF program to attach
1157	1431	prog_fd: fd_t,
	1432
1158	1433	/// object to attach to
1159	1434	target_fd: fd_t,
1160	1435	attach_type: u32,
	1436
1161	1437	/// extra flags
1162	1438	flags: u32,
1163	1439	};
...	...	@@ -1165,10 +1441,13 @@ pub const LinkCreateAttr = extern struct {
1165	1441	/// struct used by Cmd.link_update command
1166	1442	pub const LinkUpdateAttr = extern struct {
1167	1443	link_fd: fd_t,
	1444
1168	1445	/// new program to update link with
1169	1446	new_prog_fd: fd_t,
	1447
1170	1448	/// extra flags
1171	1449	flags: u32,
	1450
1172	1451	/// expected link's program fd, it is specified only if BPF_F_REPLACE is
1173	1452	/// set in flags
1174	1453	old_prog_fd: fd_t,
...	...	@@ -1185,6 +1464,7 @@ pub const IterCreateAttr = extern struct {
1185	1464	flags: u32,
1186	1465	};
1187	1466
	1467	/// Mega struct that is passed to the bpf() syscall
1188	1468	pub const Attr = extern union {
1189	1469	map_create: MapCreateAttr,
1190	1470	map_elem: MapElemAttr,