Debian Codegraph @

src/shared/netif-naming-scheme.h

raw
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2 #pragma once
3
4 #include "shared-forward.h"
5
6 /* So here's the deal: net_id is supposed to be an exercise in providing stable names for network devices. However, we
7 * also want to keep updating the naming scheme used in future versions of net_id. These two goals of course are
8 * contradictory: on one hand we want things to not change and on the other hand we want them to improve. Our way out
9 * of this dilemma is to introduce the "naming scheme" concept: each time we improve the naming logic we define a new
10 * flag for it. Then, we keep a list of schemes, each identified by a name associated with the flags it implements. Via
11 * a kernel command line and environment variable we then allow the user to pick the scheme they want us to follow:
12 * installers could "freeze" the used scheme at the moment of installation this way.
13 *
14 * Developers: each time you tweak the naming logic here, define a new flag below, and condition the tweak with
15 * it. Each time we do a release we'll then add a new scheme entry and include all newly defined flags.
16 *
17 * Note that this is only half a solution to the problem though: not only udev/net_id gets updated all the time, the
18 * kernel gets too. And thus a kernel that previously didn't expose some sysfs attribute we look for might eventually
19 * do, and thus affect our naming scheme too. Thus, enforcing a naming scheme will make interfacing more stable across
20 * OS versions, but not fully stabilize them. */
21 typedef enum NamingSchemeFlags {
22 /* First, the individual features */
23 NAMING_SR_IOV_V = 1 << 0, /* Use "v" suffix for SR-IOV, see 609948c7043a */
24 NAMING_NPAR_ARI = 1 << 1, /* Use NPAR "ARI", see 6bc04997b6ea */
25 NAMING_INFINIBAND = 1 << 2, /* Use "ib" prefix for infiniband, see 938d30aa98df */
26 NAMING_ZERO_ACPI_INDEX = 1 << 3, /* Use zero acpi_index field, see d81186ef4f6a */
27 NAMING_ALLOW_RERENAMES = 1 << 4, /* Allow re-renaming of devices, see #9006 */
28 NAMING_STABLE_VIRTUAL_MACS = 1 << 5, /* Use device name to generate MAC, see 6d3646406560 */
29 NAMING_NETDEVSIM = 1 << 6, /* Generate names for netdevsim devices, see eaa9d507d855 */
30 NAMING_LABEL_NOPREFIX = 1 << 7, /* Don't prepend ID_NET_LABEL_ONBOARD with interface type prefix */
31 NAMING_NSPAWN_LONG_HASH = 1 << 8, /* Shorten nspawn interfaces by including 24bit hash, instead of simple truncation */
32 NAMING_BRIDGE_NO_SLOT = 1 << 9, /* Don't use PCI hotplug slot information if the corresponding device is a PCI bridge */
33 NAMING_SLOT_FUNCTION_ID = 1 << 10, /* Use function_id if present to identify PCI hotplug slots */
34 NAMING_16BIT_INDEX = 1 << 11, /* Allow full 16-bit for the onboard index */
35 NAMING_REPLACE_STRICTLY = 1 << 12, /* Use udev_replace_ifname() for NAME= rule */
36 NAMING_XEN_VIF = 1 << 13, /* Generate names for Xen netfront devices */
37 NAMING_BRIDGE_MULTIFUNCTION_SLOT = 1 << 14, /* Use PCI hotplug slot information associated with bridge, but only if PCI device is multifunction.
38 * This is disabled since v255, as it seems not to work at least for some setups. See issue #28929. */
39 NAMING_DEVICETREE_ALIASES = 1 << 15, /* Generate names from devicetree aliases of a netdev's parent's OF node */
40 NAMING_USB_HOST = 1 << 16, /* Generate names for usb host */
41 NAMING_SR_IOV_R = 1 << 17, /* Use "r" suffix for SR-IOV VF representors */
42 NAMING_FIRMWARE_NODE_SUN = 1 << 18, /* Use firmware_node/sun to get PCI slot number */
43 NAMING_DEVICETREE_PORT_ALIASES = 1 << 19, /* Include aliases of OF nodes of a netdev itself, not just its parent. See PR #33958. */
44 NAMING_USE_INTERFACE_PROPERTY = 1 << 20, /* Use INTERFACE udev property, rather than sysname, when no renaming is requested. */
45 NAMING_DEVICETREE_ALIASES_WLAN = 1 << 21, /* Generate names from devicetree aliases for WLAN devices */
46 NAMING_MCTP = 1 << 22, /* Use "mc" prefix for MCTP devices */
47 NAMING_SUBFUNC = 1 << 23, /* Generate names for auxiliary sub-function (SF) network
48 * devices (e.g. mlx5_core SFs), based on the parent PF's
49 * PCI path and the user-defined sfnum, with an "S" suffix. */
50
51 /* And now the masks that combine the features above */
52 NAMING_V238 = 0,
53 NAMING_V239 = NAMING_V238 | NAMING_SR_IOV_V | NAMING_NPAR_ARI,
54 NAMING_V240 = NAMING_V239 | NAMING_INFINIBAND | NAMING_ZERO_ACPI_INDEX | NAMING_ALLOW_RERENAMES,
55 NAMING_V241 = NAMING_V240 | NAMING_STABLE_VIRTUAL_MACS,
56 NAMING_V243 = NAMING_V241 | NAMING_NETDEVSIM | NAMING_LABEL_NOPREFIX,
57 NAMING_V245 = NAMING_V243 | NAMING_NSPAWN_LONG_HASH,
58 NAMING_V247 = NAMING_V245 | NAMING_BRIDGE_NO_SLOT,
59 NAMING_V249 = NAMING_V247 | NAMING_SLOT_FUNCTION_ID | NAMING_16BIT_INDEX | NAMING_REPLACE_STRICTLY,
60 NAMING_V250 = NAMING_V249 | NAMING_XEN_VIF,
61 NAMING_V251 = NAMING_V250 | NAMING_BRIDGE_MULTIFUNCTION_SLOT,
62 NAMING_V252 = NAMING_V251 | NAMING_DEVICETREE_ALIASES,
63 NAMING_V253 = NAMING_V252 | NAMING_USB_HOST,
64 NAMING_V254 = NAMING_V253 | NAMING_SR_IOV_R, /* Despite the name, "v254" is NOT the default scheme
65 * for systemd version 254. It was added in a follow-up
66 * patch later. NAMING_SR_IOV_R is enabled by default in
67 * systemd version 255, naming scheme "v255". */
68 NAMING_V255 = NAMING_V254 & ~NAMING_BRIDGE_MULTIFUNCTION_SLOT,
69 NAMING_V257 = NAMING_V255 | NAMING_FIRMWARE_NODE_SUN | NAMING_DEVICETREE_PORT_ALIASES,
70 NAMING_V258 = NAMING_V257 | NAMING_USE_INTERFACE_PROPERTY,
71 NAMING_V259 = NAMING_V258 | NAMING_DEVICETREE_ALIASES_WLAN,
72 NAMING_V260 = NAMING_V259 | NAMING_MCTP,
73 NAMING_V261 = NAMING_V260 | NAMING_SUBFUNC,
74
75 EXTRA_NET_NAMING_SCHEMES
76
77 _NAMING_SCHEME_FLAGS_INVALID = -EINVAL,
78 } NamingSchemeFlags;
79
80 typedef struct NamingScheme {
81 const char *name;
82 NamingSchemeFlags flags;
83 } NamingScheme;
84
85 const NamingScheme* naming_scheme_from_name(const char *name);
86 const NamingScheme* naming_scheme(void);
87
88 static inline bool naming_scheme_has(NamingSchemeFlags flags) {
89 return FLAGS_SET(naming_scheme()->flags, flags);
90 }
91
92 typedef enum NamePolicy {
93 NAMEPOLICY_KERNEL,
94 NAMEPOLICY_KEEP,
95 NAMEPOLICY_DATABASE,
96 NAMEPOLICY_ONBOARD,
97 NAMEPOLICY_SLOT,
98 NAMEPOLICY_PATH,
99 NAMEPOLICY_MAC,
100 _NAMEPOLICY_MAX,
101 _NAMEPOLICY_INVALID = -EINVAL,
102 } NamePolicy;
103
104 DECLARE_STRING_TABLE_LOOKUP(name_policy, NamePolicy);
105
106 DECLARE_STRING_TABLE_LOOKUP(alternative_names_policy, NamePolicy);
107
108 int device_get_sysattr_int_filtered(sd_device *device, const char *sysattr, int *ret_value);
109 int device_get_sysattr_unsigned_filtered(sd_device *device, const char *sysattr, unsigned *ret_value);
110 int device_get_sysattr_bool_filtered(sd_device *device, const char *sysattr);
111 int device_get_sysattr_safe_string_filtered(sd_device *device, const char *sysattr, const char **ret_value);