History

bpf: add documentation for eBPF helpers (51-57)

Add documentation for eBPF helper functions to bpf.h user header file. This documentation can be parsed with the Python script provided in another commit of the patch series, in order to provide a RST document that can later be converted into a man page. The objective is to make the documentation easily understandable and accessible to all eBPF developers, including beginners. This patch contains descriptions for the following helper functions: Helpers from Lawrence: - bpf_setsockopt() - bpf_getsockopt() - bpf_sock_ops_cb_flags_set() Helpers from Yonghong: - bpf_perf_event_read_value() - bpf_perf_prog_read_value() Helper from Josef: - bpf_override_return() Helper from Andrey: - bpf_bind() v4: - bpf_perf_event_read_value(): State that this helper should be preferred over bpf_perf_event_read(). v3: - bpf_perf_event_read_value(): Fix time of selection for perf event type in description. Remove occurences of "cores" to avoid confusion with "CPU". - bpf_bind(): Remove last paragraph of description, which was off topic.

Quentin Monnet committed 8 years ago

Commit 7aa79a81 parent c6b5fb81 file · +180 −0Browse files

Showing the changes to include/uapi/linux (1 of 1 file). Show all

Unified · Split

include/uapi/linux/bpf.h+180−0
@@ -1361,6 +1361,28 @@ union bpf_attr { · 1360 unmodified lines
13611361 * Return
13621362 * 0
13631363 *
1364+ * int bpf_setsockopt(struct bpf_sock_ops_kern *bpf_socket, int level, int optname, char *optval, int optlen)
1365+ * Description
1366+ * Emulate a call to **setsockopt()** on the socket associated to
1367+ * *bpf_socket*, which must be a full socket. The *level* at
1368+ * which the option resides and the name *optname* of the option
1369+ * must be specified, see **setsockopt(2)** for more information.
1370+ * The option value of length *optlen* is pointed by *optval*.
1371+ *
1372+ * This helper actually implements a subset of **setsockopt()**.
1373+ * It supports the following *level*\ s:
1374+ *
1375+ * * **SOL_SOCKET**, which supports the following *optname*\ s:
1376+ * **SO_RCVBUF**, **SO_SNDBUF**, **SO_MAX_PACING_RATE**,
1377+ * **SO_PRIORITY**, **SO_RCVLOWAT**, **SO_MARK**.
1378+ * * **IPPROTO_TCP**, which supports the following *optname*\ s:
1379+ * **TCP_CONGESTION**, **TCP_BPF_IW**,
1380+ * **TCP_BPF_SNDCWND_CLAMP**.
1381+ * * **IPPROTO_IP**, which supports *optname* **IP_TOS**.
1382+ * * **IPPROTO_IPV6**, which supports *optname* **IPV6_TCLASS**.
1383+ * Return
1384+ * 0 on success, or a negative error in case of failure.
1385+ *
13641386 * int bpf_skb_adjust_room(struct sk_buff *skb, u32 len_diff, u32 mode, u64 flags)
13651387 * Description
13661388 * Grow or shrink the room for data in the packet associated to
@@ -1410,6 +1432,164 @@ union bpf_attr { · 43 unmodified lines
14101432 * direct packet access.
14111433 * Return
14121434 * 0 on success, or a negative error in case of failure.
1435+ *
1436+ * int bpf_perf_event_read_value(struct bpf_map *map, u64 flags, struct bpf_perf_event_value *buf, u32 buf_size)
1437+ * Description
1438+ * Read the value of a perf event counter, and store it into *buf*
1439+ * of size *buf_size*. This helper relies on a *map* of type
1440+ * **BPF_MAP_TYPE_PERF_EVENT_ARRAY**. The nature of the perf event
1441+ * counter is selected when *map* is updated with perf event file
1442+ * descriptors. The *map* is an array whose size is the number of
1443+ * available CPUs, and each cell contains a value relative to one
1444+ * CPU. The value to retrieve is indicated by *flags*, that
1445+ * contains the index of the CPU to look up, masked with
1446+ * **BPF_F_INDEX_MASK**. Alternatively, *flags* can be set to
1447+ * **BPF_F_CURRENT_CPU** to indicate that the value for the
1448+ * current CPU should be retrieved.
1449+ *
1450+ * This helper behaves in a way close to
1451+ * **bpf_perf_event_read**\ () helper, save that instead of
1452+ * just returning the value observed, it fills the *buf*
1453+ * structure. This allows for additional data to be retrieved: in
1454+ * particular, the enabled and running times (in *buf*\
1455+ * **->enabled** and *buf*\ **->running**, respectively) are
1456+ * copied. In general, **bpf_perf_event_read_value**\ () is
1457+ * recommended over **bpf_perf_event_read**\ (), which has some
1458+ * ABI issues and provides fewer functionalities.
1459+ *
1460+ * These values are interesting, because hardware PMU (Performance
1461+ * Monitoring Unit) counters are limited resources. When there are
1462+ * more PMU based perf events opened than available counters,
1463+ * kernel will multiplex these events so each event gets certain
1464+ * percentage (but not all) of the PMU time. In case that
1465+ * multiplexing happens, the number of samples or counter value
1466+ * will not reflect the case compared to when no multiplexing
1467+ * occurs. This makes comparison between different runs difficult.
1468+ * Typically, the counter value should be normalized before
1469+ * comparing to other experiments. The usual normalization is done
1470+ * as follows.
1471+ *
1472+ * ::
1473+ *
1474+ * normalized_counter = counter * t_enabled / t_running
1475+ *
1476+ * Where t_enabled is the time enabled for event and t_running is
1477+ * the time running for event since last normalization. The
1478+ * enabled and running times are accumulated since the perf event
1479+ * open. To achieve scaling factor between two invocations of an
1480+ * eBPF program, users can can use CPU id as the key (which is
1481+ * typical for perf array usage model) to remember the previous
1482+ * value and do the calculation inside the eBPF program.
1483+ * Return
1484+ * 0 on success, or a negative error in case of failure.
1485+ *
1486+ * int bpf_perf_prog_read_value(struct bpf_perf_event_data_kern *ctx, struct bpf_perf_event_value *buf, u32 buf_size)
1487+ * Description
1488+ * For en eBPF program attached to a perf event, retrieve the
1489+ * value of the event counter associated to *ctx* and store it in
1490+ * the structure pointed by *buf* and of size *buf_size*. Enabled
1491+ * and running times are also stored in the structure (see
1492+ * description of helper **bpf_perf_event_read_value**\ () for
1493+ * more details).
1494+ * Return
1495+ * 0 on success, or a negative error in case of failure.
1496+ *
1497+ * int bpf_getsockopt(struct bpf_sock_ops_kern *bpf_socket, int level, int optname, char *optval, int optlen)
1498+ * Description
1499+ * Emulate a call to **getsockopt()** on the socket associated to
1500+ * *bpf_socket*, which must be a full socket. The *level* at
1501+ * which the option resides and the name *optname* of the option
1502+ * must be specified, see **getsockopt(2)** for more information.
1503+ * The retrieved value is stored in the structure pointed by
1504+ * *opval* and of length *optlen*.
1505+ *
1506+ * This helper actually implements a subset of **getsockopt()**.
1507+ * It supports the following *level*\ s:
1508+ *
1509+ * * **IPPROTO_TCP**, which supports *optname*
1510+ * **TCP_CONGESTION**.
1511+ * * **IPPROTO_IP**, which supports *optname* **IP_TOS**.
1512+ * * **IPPROTO_IPV6**, which supports *optname* **IPV6_TCLASS**.
1513+ * Return
1514+ * 0 on success, or a negative error in case of failure.
1515+ *
1516+ * int bpf_override_return(struct pt_reg *regs, u64 rc)
1517+ * Description
1518+ * Used for error injection, this helper uses kprobes to override
1519+ * the return value of the probed function, and to set it to *rc*.
1520+ * The first argument is the context *regs* on which the kprobe
1521+ * works.
1522+ *
1523+ * This helper works by setting setting the PC (program counter)
1524+ * to an override function which is run in place of the original
1525+ * probed function. This means the probed function is not run at
1526+ * all. The replacement function just returns with the required
1527+ * value.
1528+ *
1529+ * This helper has security implications, and thus is subject to
1530+ * restrictions. It is only available if the kernel was compiled
1531+ * with the **CONFIG_BPF_KPROBE_OVERRIDE** configuration
1532+ * option, and in this case it only works on functions tagged with
1533+ * **ALLOW_ERROR_INJECTION** in the kernel code.
1534+ *
1535+ * Also, the helper is only available for the architectures having
1536+ * the CONFIG_FUNCTION_ERROR_INJECTION option. As of this writing,
1537+ * x86 architecture is the only one to support this feature.
1538+ * Return
1539+ * 0
1540+ *
1541+ * int bpf_sock_ops_cb_flags_set(struct bpf_sock_ops_kern *bpf_sock, int argval)
1542+ * Description
1543+ * Attempt to set the value of the **bpf_sock_ops_cb_flags** field
1544+ * for the full TCP socket associated to *bpf_sock_ops* to
1545+ * *argval*.
1546+ *
1547+ * The primary use of this field is to determine if there should
1548+ * be calls to eBPF programs of type
1549+ * **BPF_PROG_TYPE_SOCK_OPS** at various points in the TCP
1550+ * code. A program of the same type can change its value, per
1551+ * connection and as necessary, when the connection is
1552+ * established. This field is directly accessible for reading, but
1553+ * this helper must be used for updates in order to return an
1554+ * error if an eBPF program tries to set a callback that is not
1555+ * supported in the current kernel.
1556+ *
1557+ * The supported callback values that *argval* can combine are:
1558+ *
1559+ * * **BPF_SOCK_OPS_RTO_CB_FLAG** (retransmission time out)
1560+ * * **BPF_SOCK_OPS_RETRANS_CB_FLAG** (retransmission)
1561+ * * **BPF_SOCK_OPS_STATE_CB_FLAG** (TCP state change)
1562+ *
1563+ * Here are some examples of where one could call such eBPF
1564+ * program:
1565+ *
1566+ * * When RTO fires.
1567+ * * When a packet is retransmitted.
1568+ * * When the connection terminates.
1569+ * * When a packet is sent.
1570+ * * When a packet is received.
1571+ * Return
1572+ * Code **-EINVAL** if the socket is not a full TCP socket;
1573+ * otherwise, a positive number containing the bits that could not
1574+ * be set is returned (which comes down to 0 if all bits were set
1575+ * as required).
1576+ *
1577+ * int bpf_bind(struct bpf_sock_addr_kern *ctx, struct sockaddr *addr, int addr_len)
1578+ * Description
1579+ * Bind the socket associated to *ctx* to the address pointed by
1580+ * *addr*, of length *addr_len*. This allows for making outgoing
1581+ * connection from the desired IP address, which can be useful for
1582+ * example when all processes inside a cgroup should use one
1583+ * single IP address on a host that has multiple IP configured.
1584+ *
1585+ * This helper works for IPv4 and IPv6, TCP and UDP sockets. The
1586+ * domain (*addr*\ **->sa_family**) must be **AF_INET** (or
1587+ * **AF_INET6**). Looking for a free port to bind to can be
1588+ * expensive, therefore binding to port is not permitted by the
1589+ * helper: *addr*\ **->sin_port** (or **sin6_port**, respectively)
1590+ * must be set to zero.
1591+ * Return
1592+ * 0 on success, or a negative error in case of failure.
14131593 */
14141594 #define __BPF_FUNC_MAPPER(FN) \
14151595 FN(unspec), \