libbpf: Add BTF permutation support for type reordering

Introduce btf__permute() API to allow in-place rearrangement of BTF types.
This function reorganizes BTF type order according to a provided array of
type IDs, updating all type references to maintain consistency.

The permutation process involves:
1. Shuffling types into new order based on the provided IDs array
2. Remapping all type ID references to point to new locations
3. Handling BTF extension data if provided via options

This is particularly useful for optimizing type locality after BTF
deduplication or for meeting specific layout requirements in specialized
use cases.

Cc: Eduard Zingerman <[email protected]>
Cc: Alexei Starovoitov <[email protected]>
Cc: Andrii Nakryiko <[email protected]>
Cc: Alan Maguire <[email protected]>
Cc: Song Liu <[email protected]>
Cc: Xiaoqin Zhang <[email protected]>
Signed-off-by: Donglin Peng <[email protected]>
Signed-off-by: Donglin Peng <[email protected]>
Acked-by: Eduard Zingerman <[email protected]>

Author: Donglin Peng

tools/lib/bpf/btf.c

@@ -5830,3 +5830,179 @@ int btf__relocate(struct btf *btf, const struct btf *base_btf)
 		btf->owns_base = false;
 	return libbpf_err(err);
 }
+
+struct btf_permute {
+	/* .BTF section to be permuted in-place */
+	struct btf *btf;
+	/* optional .BTF.ext info along the main BTF info */
+	struct btf_ext *btf_ext;
+	/* Array containing original type IDs (exclude VOID type ID 0)
+	 * in user-defined order
+	 */
+	__u32 *ids;
+	/* Array used to map from original type ID to a new permuted type
+	 * ID
+	 */
+	__u32 *ids_map;
+	/* Number of elements in ids array */
+	__u32 ids_sz;
+};
+
+static int btf_permute_shuffle_types(struct btf_permute *p);
+static int btf_permute_remap_types(struct btf_permute *p);
+static int btf_permute_remap_type_id(__u32 *type_id, void *ctx);
+
+int btf__permute(struct btf *btf, __u32 *ids, __u32 ids_sz, const struct btf_permute_opts *opts)
+{
+	struct btf_permute p;
+	int err = 0;
+	__u32 *ids_map = NULL;
+
+	if (!OPTS_VALID(opts, btf_permute_opts) || (ids_sz > btf->nr_types))
+		return libbpf_err(-EINVAL);
+
+	ids_map = calloc(ids_sz, sizeof(*ids_map));
+	if (!ids_map) {
+		err = -ENOMEM;
+		goto done;
+	}
+
+	p.btf = btf;
+	p.btf_ext = OPTS_GET(opts, btf_ext, NULL);
+	p.ids = ids;
+	p.ids_map = ids_map;
+	p.ids_sz = ids_sz;
+
+	if (btf_ensure_modifiable(btf)) {
+		err = -ENOMEM;
+		goto done;
+	}
+	err = btf_permute_shuffle_types(&p);
+	if (err < 0) {
+		goto done;
+	}
+	err = btf_permute_remap_types(&p);
+	if (err < 0) {
+		goto done;
+	}
+
+done:
+	free(ids_map);
+	return libbpf_err(err);
+}
+
+/* Shuffle BTF types.
+ *
+ * Rearranges types according to the order specified in p->ids array.
+ * The p->ids_map array stores the mapping from original type IDs to
+ * new shuffled IDs, which is used in the next phase to update type
+ * references.
+ */
+static int btf_permute_shuffle_types(struct btf_permute *p)
+{
+	struct btf *btf = p->btf;
+	const struct btf_type *t;
+	__u32 *new_offs = NULL, *ids_map;
+	void *nt, *new_types = NULL;
+	int i, id, len, err;
+
+	new_offs = calloc(p->ids_sz, sizeof(*new_offs));
+	new_types = calloc(btf->hdr->type_len, 1);
+	if (!new_offs || !new_types) {
+		err = -ENOMEM;
+		goto out_err;
+	}
+
+	nt = new_types;
+	for (i = 0; i < p->ids_sz; i++) {
+		id = p->ids[i];
+		/* type IDs from base_btf and the VOID type are not allowed */
+		if (id < btf->start_id) {
+			err = -EINVAL;
+			goto out_err;
+		}
+		/* must be a valid type ID */
+		t = btf__type_by_id(btf, id);
+		if (!t) {
+			err = -EINVAL;
+			goto out_err;
+		}
+		ids_map = &p->ids_map[id - btf->start_id];
+		/* duplicate type IDs are not allowed */
+		if (*ids_map) {
+			err = -EINVAL;
+			goto out_err;
+		}
+		len = btf_type_size(t);
+		memcpy(nt, t, len);
+		new_offs[i] = nt - new_types;
+		*ids_map = btf->start_id + i;
+		nt += len;
+	}
+
+	/* resize */
+	if (p->ids_sz < btf->nr_types) {
+		__u32 type_len = nt - new_types;
+		void *tmp_types;
+
+		tmp_types = realloc(new_types, type_len);
+		if (!tmp_types) {
+			err = -ENOMEM;
+			goto out_err;
+		}
+		new_types = tmp_types;
+		btf->nr_types = p->ids_sz;
+		btf->type_offs_cap = p->ids_sz;
+		btf->types_data_cap = type_len;
+		btf->hdr->type_len = type_len;
+		btf->hdr->str_off = type_len;
+		btf->raw_size = btf->hdr->hdr_len + btf->hdr->type_len + btf->hdr->str_len;
+	}
+	free(btf->types_data);
+	free(btf->type_offs);
+	btf->types_data = new_types;
+	btf->type_offs = new_offs;
+	return 0;
+
+out_err:
+	free(new_offs);
+	free(new_types);
+	return err;
+}
+
+/* Callback function to remap individual type ID references
+ *
+ * This callback is invoked by btf_remap_types() for each type ID reference
+ * found in the BTF data. It updates the reference to point to the new
+ * permuted type ID using ids_map array.
+ */
+static int btf_permute_remap_type_id(__u32 *type_id, void *ctx)
+{
+	struct btf_permute *p = ctx;
+	__u32 new_type_id = *type_id;
+
+	/* skip references that point into the base BTF */
+	if (new_type_id < p->btf->start_id)
+		return 0;
+
+	new_type_id = p->ids_map[*type_id - p->btf->start_id];
+	if (new_type_id > BTF_MAX_NR_TYPES)
+		return -EINVAL;
+
+	*type_id = new_type_id;
+	return 0;
+}
+
+/* Remap referenced type IDs into permuted type IDs.
+ *
+ * After BTF types are permuted, their final type IDs may differ from original
+ * ones. The map from original to a corresponding permuted type ID is stored
+ * in p->ids_map array and is populated during shuffle phase. During remapping
+ * phase we are rewriting all type IDs  referenced from any BTF type (e.g.,
+ * struct fields, func proto args, etc) to their final permuted type IDs.
+ */
+static int btf_permute_remap_types(struct btf_permute *p)
+{
+	return btf_remap_types(p->btf, p->btf_ext, btf_permute_remap_type_id, p);
+}
+

tools/lib/bpf/btf.h

@@ -281,6 +281,37 @@ LIBBPF_API int btf__dedup(struct btf *btf, const struct btf_dedup_opts *opts);
  */
 LIBBPF_API int btf__relocate(struct btf *btf, const struct btf *base_btf);
 
+struct btf_permute_opts {
+	size_t sz;
+	/* optional .BTF.ext info along the main BTF info */
+	struct btf_ext *btf_ext;
+	size_t :0;
+};
+#define btf_permute_opts__last_field btf_ext
+
+/**
+ * @brief **btf__permute()** rearranges BTF types in-place according to specified mapping
+ * @param btf BTF object to permute
+ * @param ids Array containing original type IDs (exclude VOID type ID 0) in user-defined order.
+ * @param ids_sz Number of elements in @ids array
+ * @param opts Optional parameters for BTF extension data reference updates
+ * @return 0 on success, negative error code on failure
+ *
+ * **btf__permute()** performs an in-place permutation of BTF types, rearranging them according
+ * to the order specified in @ids array. If @ids_sz is smaller than the total number of types
+ * in @btf, the BTF will be truncated to contain only the types specified in @ids. After
+ * reordering, all type references within the BTF data and optional BTF extension are updated
+ * to maintain consistency. Subsequent btf__dedup may be required if the BTF is truncated during
+ * permutation.
+ *
+ * On error, negative error code is returned and errno is set appropriately.
+ * Common error codes include:
+ *   - -EINVAL: Invalid parameters or invalid ID mapping (e.g., duplicate IDs, out-of-range IDs)
+ *   - -ENOMEM: Memory allocation failure during permutation process
+ */
+LIBBPF_API int btf__permute(struct btf *btf, __u32 *ids, __u32 ids_sz,
+			    const struct btf_permute_opts *opts);
+
 struct btf_dump;
 
 struct btf_dump_opts {

tools/lib/bpf/libbpf.map

@@ -451,4 +451,5 @@ LIBBPF_1.7.0 {
 	global:
 		bpf_map__set_exclusive_program;
 		bpf_map__exclusive_program;
+		btf__permute;
 } LIBBPF_1.6.0;