[PATCH bpf-next v1 2/3] libbpf: Drop btf_dump details from the BTF docs

[Ihor Solodrai <ihor.solodrai@linux.dev>]

btf.rst describes the BTF format, but commit fbafb695c5d2 ("libbpf: Let
decl tags override how btf_dump renders type tags") and
commit 79dcfd3e36a7 ("libbpf, bpftool, resolve_btfids: Dump kflagged
BTF tags as is") added to it how btf_dump prints kflagged tags and decl
tags on type tags. The comments of btf__add_type_attr() and
btf__add_decl_attr() also prescribe what the string must contain,
though it is arbitrary text that depends on the use case.

Describe kflagged tags only as arbitrary annotations in both places.
Keep a short note on the type tag override in btf_dump.c, whose comment
pointed to btf.rst.

Suggested-by: Andrii Nakryiko <andrii@kernel.org>
Link: https://lore.kernel.org/bpf/CAEf4BzYqq-o8SRTWyO=J6gBnSkZa=QYuEiBNuBEVndVsVYcExg@mail.gmail.com/
Signed-off-by: Ihor Solodrai <ihor.solodrai@linux.dev>
---
 Documentation/bpf/btf.rst | 21 ++++-----------------
 tools/lib/bpf/btf.c       |  6 ++----
 tools/lib/bpf/btf_dump.c  |  2 +-
 3 files changed, 7 insertions(+), 22 deletions(-)

diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
index 99833048de60..b618812390e4 100644
--- a/Documentation/bpf/btf.rst
+++ b/Documentation/bpf/btf.rst
@@ -506,14 +506,9 @@ If ``info.kind_flag`` is 0, then this is a normal decl tag, and the
 ``name_off`` encodes btf_decl_tag attribute string.
 
 If ``info.kind_flag`` is 1, then the decl tag represents an arbitrary
-annotation. ``name_off`` encodes the complete annotation string, which
-``btf_dump`` prints unchanged at the declaration. For example, an attribute
-specifier is encoded as ``__attribute__((aligned(4)))``, including the
-wrapper. A macro can be encoded as its identifier, leaving its definition
-to the generated header or its user.
-
-``btf_dump`` also accepts decl tags that reference a ``type_tag``, as
-described under ``BTF_KIND_TYPE_TAG``.
+annotation. ``name_off`` encodes the complete annotation string. For
+example, an attribute specifier is encoded as
+``__attribute__((aligned(4)))``, including the wrapper.
 
 2.2.18 BTF_KIND_TYPE_TAG
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -544,15 +539,7 @@ string.
 
 If ``info.kind_flag`` is 1, then the type tag represents an arbitrary
 annotation. As with decl tags, ``name_off`` encodes the complete annotation
-string, which ``btf_dump`` prints unchanged. An attribute specifier must
-include its wrapper, for example ``__attribute__((address_space(1)))``.
-
-``btf_dump`` prints decl tags that reference a type tag, with
-``btf_decl_tag.component_idx`` of ``-1``, in place of that type tag. They
-are printed the same way as decl tags on declarations. This lets a split
-BTF built for a C dump change how the type tags of its base BTF are
-printed, without modifying the base. The kernel rejects decl tags that
-reference type tags.
+string, for example ``__attribute__((address_space(1)))``.
 
 2.2.19 BTF_KIND_ENUM64
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/tools/lib/bpf/btf.c b/tools/lib/bpf/btf.c
index 448ee6acf519..a4bf01403a43 100644
--- a/tools/lib/bpf/btf.c
+++ b/tools/lib/bpf/btf.c
@@ -3064,8 +3064,7 @@ int btf__add_type_tag(struct btf *btf, const char *value, int ref_type_id)
  * Append new BTF_KIND_TYPE_TAG type with:
  *   - *value*, non-empty/non-NULL tag value;
  *   - *ref_type_id* - referenced type ID, it might not exist yet;
- * The kind flag is set; btf_dump prints *value* unchanged.
- * Attribute specifiers must include the __attribute__((...)) wrapper.
+ * Set info->kflag to 1, indicating this tag is an arbitrary annotation
  * Returns:
  *   - >0, type ID of newly added BTF type;
  *   - <0, on error.
@@ -3400,8 +3399,7 @@ int btf__add_decl_tag(struct btf *btf, const char *value, int ref_type_id,
  *   - *ref_type_id* - referenced type ID, it might not exist yet;
  *   - *component_idx* - -1 for tagging reference type, otherwise struct/union
  *     member or function argument index;
- * The kind flag is set; btf_dump prints *value* unchanged.
- * Attribute specifiers must include the __attribute__((...)) wrapper.
+ * Set info->kflag to 1, indicating this tag is an arbitrary annotation
  * Returns:
  *   - >0, type ID of newly added BTF type;
  *   - <0, on error.
diff --git a/tools/lib/bpf/btf_dump.c b/tools/lib/bpf/btf_dump.c
index fcd97aa90589..023047214b17 100644
--- a/tools/lib/bpf/btf_dump.c
+++ b/tools/lib/bpf/btf_dump.c
@@ -1597,7 +1597,7 @@ static void btf_dump_emit_type_chain(struct btf_dump *d,
 			break;
 		case BTF_KIND_TYPE_TAG:
 			btf_dump_emit_mods(d, decls);
-			/* decl tags override the type tag, see btf.rst */
+			/* decl tags on the type tag are printed in its place */
 			if (btf_dump_emit_decl_tags(d, id, -1))
 				break;
 			name = btf_name_of(d, t->name_off);
-- 
2.56.0