From: Nick Alcock Date: Fri, 25 Apr 2025 20:54:28 +0000 (+0100) Subject: libctf: API change documentation (NOT FOR UPSTREAMING) X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=71e1cc6fbabb46d631a27e50f97fc746869cf250;p=thirdparty%2Fbinutils-gdb.git libctf: API change documentation (NOT FOR UPSTREAMING) These probably need to be turned into libctf/NEWS content once we decide (if we decide) that these changes are good. (I do hope we don't make too many changes because it'll be horribly disruptive, but I wouldn't be surprised to see a few...) --- diff --git a/libctf/api.org b/libctf/api.org new file mode 100644 index 00000000000..b4e8e57e39d --- /dev/null +++ b/libctf/api.org @@ -0,0 +1,148 @@ +* Additions + +** #defines and enums + +#define CTF_ADD_STRUCT_BITFIELDS 2 /* Struct/union field-level bitfields */ + +typedef enum ctf_btf_mode +{ + LIBCTF_BTM_BTF = 0, + LIBCTF_BTM_POSSIBLE = 1, + LIBCTF_BTM_ALWAYS = 2 +} ctf_btf_mode_t; + +** typedefs + +typedef struct ctf_membinfo + int ctm_bit_width; /* Width of member in bits: -1: not bitfield */ + +typedef enum ctf_sect_names + CTF_SECT_LABEL removed. + +** Function typedefs + +ctf_unsigned_enum_f +ctf_datasec_var_f +ctf_type_kind_f + +** Functions + +ctf_id_t ctf_add_enum64_encoded (ctf_dict_t *, uint32_t, const char *, + const ctf_encoding_t *); +ctf_id_t ctf_add_enum64 (ctf_dict_t *, uint32_t, const char *); +ctf_id_t ctf_add_btf_float (ctf_dict_t *, uint32_t, + const char *, const ctf_encoding_t *); +ctf_id_t ctf_add_function_linkage (ctf_dict_t *, uint32_t, + ctf_id_t, const char *, int linkage); +int ctf_add_member_bitfield (ctf_dict_t *, ctf_id_t souid, + const char *, ctf_id_t type, + unsigned long bit_offset, + int bit_width); +ctf_id_t ctf_add_section_variable (ctf_dict_t *, uint32_t, + const char *datasec, const char *name, + int linkage, ctf_id_t type, + size_t size, size_t offset); +ctf_id_t ctf_add_type_tag (ctf_dict_t *, uint32_t, ctf_id_t, const char *); +ctf_id_t ctf_add_decl_type_tag (ctf_dict_t *, uint32_t, ctf_id_t, const char *); +ctf_id_t ctf_add_decl_tag (ctf_dict_t *, uint32_t, ctf_id_t, const char *, + int component_idx); +int ctf_set_conflicting (ctf_dict_t *, ctf_id_t, const char *); + +int ctf_struct_bitfield (ctf_dict_t *, ctf_id_t); +int ctf_func_arg_names (ctf_dict_t *, unsigned long, uint32_t, const char **); +int ctf_func_type_arg_names (ctf_dict_t *, ctf_id_t, uint32_t, + const char **); +int ctf_type_linkage (ctf_dict_t *, ctf_id_t); +ctf_id_t ctf_lookup_by_kind (ctf_dict_t *, int kind, const char *); +int ctf_type_conflicting (ctf_dict_t *, ctf_id_t, const char **cuname); +int ctf_enum_unsigned_value (ctf_dict_t *, ctf_id_t, const char *, uint64_t *); +int ctf_enum_unsigned (ctf_dict_t *, ctf_id_t); +ctf_id_t ctf_datasec_var_offset (ctf_dict_t *fp, ctf_id_t datasec, + uint32_t offset); +ctf_id_t ctf_variable_datasec (ctf_dict_t *fp, ctf_id_t var); +ctf_id_t ctf_tag (ctf_dict_t *, ctf_id_t tag); +ctf_id_t ctf_decl_tag (ctf_dict_t *, ctf_id_t decl_tag, + int64_t *component_idx); +int ctf_type_kind_iter (ctf_dict_t *, int kind, ctf_type_kind_f *, void *); +ctf_id_t ctf_type_kind_next (ctf_dict_t *, ctf_next_t **, int kind); +int ctf_datasec_var_iter (ctf_dict_t *, ctf_id_t, ctf_datasec_var_f *, + void *); +ctf_id_t ctf_datasec_var_next (ctf_dict_t *, ctf_id_t, ctf_next_t **, + size_t *size, size_t *offset); +ctf_id_t ctf_tag_next (ctf_dict_t *, const char *tag, ctf_next_t **); +int ctf_link_output_is_btf (ctf_dict_t *); +ctf_type_t *ctf_type_data (ctf_dict_t *fp, ctf_id_t type, int prefix); +size_t ctf_sect_size (ctf_dict_t *, ctf_sect_names_t sect); + +* Changes + +* function typedefs + +ctf_visit_f, ctf_member_f, ctf_variable_f, ctf_type_f, ctf_type_all_f, gain a +ctf_dict_t arg + +ctf_member_f, ctf_visit_f gain int bit_width arg, and their offset arg becomes a +size_t + +ctf_enum_f val arg becomes int -> int64_t + +* Structs/unions + +ctf_membinfo.ctm_offset, ctf_arinfo.ctr_nelems, ctf_funcinfo.ctc_argc are all +size_t. + +* Functions + +ctf_add_function gains arg_names arg +ctf_add_variable gains linkage arg, returns ctf_id_t like other type-addition +functions (error return checking changes to == CTF_ERR) + +ctf_add_enumerator, ctf_enum_name ctf_enum_value int val -> int64 val +ctf_enum_iter return value int -> int64 +ctf_enum_next int * val -> int64 * val + +ctf_member_next gains bit_width arg +ctf_member_count returns ssize_t + +ctf_version gains btf_hdr_len, btf_mode args. + +ctf_link_write gains is_btf argument + +* Behaviour + +Symtypetab entries now point at types of kind CTF_K_FUNC_LINKAGE + +* Removals + +typedef struct ctf_lblinfo ... ctf_lblinfo_t +ctf_label_f + +ctf_label_topmost, ctf_label_info, ctf_label_iter, ctf_label_next (last never +implemented, prototype only) + +** Errors + +*** Additions (so far) + + _CTF_ITEM (ECTF_BADCOMPONENT, "Declaration tag component_idx is invalid.") \ + _CTF_ITEM (ECTF_NOTBITSOU, "Type is not a bitfield-capable struct or union.") \ + _CTF_ITEM (ECTF_DESCENDING, "Structure offsets may not descend.") \ + _CTF_ITEM (ECTF_LINKAGE, "Invalid linkage.") \ + _CTF_ITEM (ECTF_LINKKIND, "Only functions and variables have linkage.") \ + _CTF_ITEM (ECTF_NEVERTAG, "Cannot call this function with a tag kind.") \ + _CTF_ITEM (ECTF_NOTDATASEC, "This function requires a datasec.") \ + _CTF_ITEM (ECTF_NOTVAR, "This function requires a variable.") \ + _CTF_ITEM (ECTF_NOTDECLTAG, "This function requires a decl tag.") \ + _CTF_ITEM (ECTF_NOTTAG, "This function requires a type or decl tag.") + _CTF_ITEM (ECTF_KIND_PROHIBITED, "Writeout of suppressed kind attempted.") + _CTF_ITEM (ECTF_NOTBTF, "Cannot write out this dict as BTF.") \ + _CTF_ITEM (ECTF_NODATASEC, "Variable not found in datasec.") + _CTF_ITEM (ECTF_TOOLARGE, "Prefix required for correct representation.") + +A bit of reshuffling of the constants to put ECTF_NEXT_END at the top, for +easier use in breakpoint conditions. + +*** Removals (never generated) + +ECTF_NOLABEL +ECTF_NOLABELDATA