Add /*<type>*/ comments everywhere (#2986)

Adds /*<type>*/ comments and a linter check from rz-bindgen to enforce
their existence and consistency

Also includes the following fixes made when adding the annotations:
* removed unused intern_table arguments in pyc_dis.c, pyc_dis.h, asm_pyc.c
* removed unused classes argument from place_nodes in agraph.c
* removed unused recurse and recurse_bb functions in canalysis.c
* removed unused vars field from RzPrint struct
* removed unused RzAnalysisType* structs from rz_analysis.h
* removed unused list field from RzEgg struct
* fixed bug in bp_plugin.c where duplication-checking logic iterates over the wrong list
* removed unused q_regs field from RzDebug struct
* removed unused backtrace field from RzDebugPlugin struct
* removed unused classes_list field from RzBinNXOObj struct
* removed unused methods_list and classes_list fields from RzBinZimgObj struct

.github/workflows/linter.yml

@@ -15,6 +15,7 @@ jobs:
     outputs:
       yaml: ${{ steps.filter.outputs.yaml }}
       clang-format: ${{ steps.filter.outputs.clang-format }}
+      bindgen-linter: ${{ steps.filter.outputs.bindgen-linter }}
       prettier: ${{ steps.filter.outputs.prettier }}
       python: ${{ steps.filter.outputs.python }}
     steps:
@@ -27,6 +28,11 @@ jobs:
             - '**.yml'
             - '**.yaml'
             - '.github/workflows/linter.yml'
+          bindgen-linter:
+            - '**.c'
+            - '**.h'
+            - '**.inc'
+            - '.github/workflows/linter.yml'
           clang-format:
             - '**.c'
             - '**.h'
@@ -59,6 +65,37 @@ jobs:
           ./librz/core/cmd_descs/cmd_descs_generate.py --output-dir /tmp ./librz/core/cmd_descs/*.yaml
           diff /tmp/cmd_descs.c ./librz/core/cmd_descs/cmd_descs.c && diff /tmp/cmd_descs.h ./librz/core/cmd_descs/cmd_descs.h
 
+  bindgen-linter:
+    needs: changes
+    runs-on: ubuntu-22.04
+    if: ${{ needs.changes.outputs.bindgen-linter == 'true' }}
+    steps:
+      - name: Checkout rizin
+        uses: actions/checkout@v3
+        with:
+          path: rizin
+      - name: Checkout rz-bindgen
+        uses: actions/checkout@v3
+        with:
+          repository: rizinorg/rz-bindgen
+          path: rz-bindgen
+      - name: Install dependencies
+        run: |
+          sudo pip install meson ninja
+          sudo apt update
+          sudo apt install libclang-14-dev
+      - name: Build rizin
+        working-directory: rizin
+        run: |
+          meson setup build
+          ninja -C build
+      - name: Run rz-bindgen linter
+        run: |
+          python3 rz-bindgen/src/lint.py \
+                  --clang-path "/usr/lib/llvm-14/lib" \
+                  --clang-args "-resource-dir=$(clang -print-resource-dir) " \
+                  --rizin-path rizin
+
   clang-format:
     needs: changes
     runs-on: ubuntu-20.04

binrz/rz-test/load.c

@@ -102,7 +102,7 @@ static char *read_string_val(char **nextline, const char *val, ut64 *linenum) {
 	return strdup(val);
 }
 
-RZ_API RzPVector *rz_test_load_cmd_test_file(const char *file) {
+RZ_API RzPVector /*<RzCmdTest *>*/ *rz_test_load_cmd_test_file(const char *file) {
 	char *contents = rz_file_slurp(file, NULL);
 	if (!contents) {
 		eprintf("Failed to open file \"%s\"\n", file);
@@ -310,7 +310,7 @@ static bool parse_asm_path(const char *path, RzStrConstPool *strpool, const char
 	return true;
 }
 
-RZ_API RzPVector *rz_test_load_asm_test_file(RzStrConstPool *strpool, const char *file) {
+RZ_API RzPVector /*<RzAsmTest *>*/ *rz_test_load_asm_test_file(RzStrConstPool *strpool, const char *file) {
 	const char *arch;
 	const char *cpu;
 	int bits;
@@ -479,7 +479,7 @@ RZ_API void rz_test_json_test_free(RzJsonTest *test) {
 	free(test);
 }
 
-RZ_API RzPVector *rz_test_load_json_test_file(const char *file) {
+RZ_API RzPVector /*<RzJsonTest *>*/ *rz_test_load_json_test_file(const char *file) {
 	char *contents = rz_file_slurp(file, NULL);
 	if (!contents) {
 		eprintf("Failed to open file \"%s\"\n", file);

binrz/rz-test/run.c

@@ -110,7 +110,7 @@ static char *convert_win_cmds(const char *cmds) {
 }
 #endif
 
-static RzSubprocessOutput *run_rz_test(RzTestRunConfig *config, ut64 timeout_ms, const char *cmds, RzList *files, RzList *extra_args, bool load_plugins, RzTestCmdRunner runner, void *user) {
+static RzSubprocessOutput *run_rz_test(RzTestRunConfig *config, ut64 timeout_ms, const char *cmds, RzList /*<char *>*/ *files, RzList /*<char *>*/ *extra_args, bool load_plugins, RzTestCmdRunner runner, void *user) {
 	RzPVector args;
 	rz_pvector_init(&args, NULL);
 	rz_pvector_push(&args, "-escr.utf8=0");

binrz/rz-test/rz-test.c

@@ -42,22 +42,22 @@ typedef struct rz_test_state_t {
 	RzThreadCond *cond; // signaled from workers to main thread to update status
 	RzThreadLock *lock; // protects everything below
 	HtPP *path_left; // char * (path to test file) => RzTestFileCounts *
-	RzPVector completed_paths;
+	RzPVector /*<char *>*/ completed_paths;
 	ut64 ok_count;
 	ut64 xx_count;
 	ut64 br_count;
 	ut64 fx_count;
-	RzPVector queue;
-	RzPVector results;
+	RzPVector /*<RzTest *>*/ queue;
+	RzPVector /*<RzTestResultInfo *>*/ results;
 } RzTestState;
 
 static void *worker_th(RzTestState *state);
 static void print_state(RzTestState *state, ut64 prev_completed);
 static void print_log(RzTestState *state, ut64 prev_completed, ut64 prev_paths_completed);
 static void interact(RzTestState *state);
-static bool interact_fix(RzTestResultInfo *result, RzPVector *fixup_results);
-static void interact_break(RzTestResultInfo *result, RzPVector *fixup_results);
-static void interact_commands(RzTestResultInfo *result, RzPVector *fixup_results);
+static bool interact_fix(RzTestResultInfo *result, RzPVector /*<RzTestResultInfo *>*/ *fixup_results);
+static void interact_break(RzTestResultInfo *result, RzPVector /*<RzTestResultInfo *>*/ *fixup_results);
+static void interact_commands(RzTestResultInfo *result, RzPVector /*<RzTestResultInfo *>*/ *fixup_results);
 
 static int help(bool verbose) {
 	printf("Usage: rz-test [-qvVnL] [-j threads] [test file/dir | @test-type]\n");
@@ -1075,7 +1075,7 @@ static char *replace_lines(const char *src, size_t from, size_t to, const char *
 }
 
 // After editing a test, fix the line numbers previously saved for all the other tests
-static void fixup_tests(RzPVector *results, const char *edited_file, ut64 start_line, st64 delta) {
+static void fixup_tests(RzPVector /*<RzTestResultInfo *>*/ *results, const char *edited_file, ut64 start_line, st64 delta) {
 	void **it;
 	rz_pvector_foreach (results, it) {
 		RzTestResultInfo *result = *it;
@@ -1133,7 +1133,7 @@ static void save_test_file_for_fix(const char *path, const char *newc) {
 	}
 }
 
-static char *replace_cmd_kv(const char *path, const char *content, size_t line_begin, size_t line_end, const char *key, const char *value, RzPVector *fixup_results) {
+static char *replace_cmd_kv(const char *path, const char *content, size_t line_begin, size_t line_end, const char *key, const char *value, RzPVector /*<RzTestResultInfo *>*/ *fixup_results) {
 	char *kv = format_cmd_kv(key, value);
 	if (!kv) {
 		return NULL;
@@ -1153,7 +1153,7 @@ static char *replace_cmd_kv(const char *path, const char *content, size_t line_b
 	return newc;
 }
 
-static void replace_cmd_kv_file(const char *path, ut64 line_begin, ut64 line_end, const char *key, const char *value, RzPVector *fixup_results) {
+static void replace_cmd_kv_file(const char *path, ut64 line_begin, ut64 line_end, const char *key, const char *value, RzPVector /*<RzTestResultInfo *>*/ *fixup_results) {
 	char *content = read_test_file_for_fix(path);
 	if (!content) {
 		return;
@@ -1167,7 +1167,7 @@ static void replace_cmd_kv_file(const char *path, ut64 line_begin, ut64 line_end
 	free(newc);
 }
 
-static bool interact_fix_cmd(RzTestResultInfo *result, RzPVector *fixup_results) {
+static bool interact_fix_cmd(RzTestResultInfo *result, RzPVector /*<RzTestResultInfo *>*/ *fixup_results) {
 	assert(result->test->type == RZ_TEST_TYPE_CMD);
 	if (result->run_failed || result->proc_out->ret != 0) {
 		return false;
@@ -1279,7 +1279,7 @@ static bool interact_fix_asm(RzTestResultInfo *result) {
 	return true;
 }
 
-static bool interact_fix(RzTestResultInfo *result, RzPVector *fixup_results) {
+static bool interact_fix(RzTestResultInfo *result, RzPVector /*<RzTestResultInfo *>*/ *fixup_results) {
 	switch (result->test->type) {
 	case RZ_TEST_TYPE_CMD:
 		return interact_fix_cmd(result, fixup_results);
@@ -1290,7 +1290,7 @@ static bool interact_fix(RzTestResultInfo *result, RzPVector *fixup_results) {
 	}
 }
 
-static void interact_break_cmd(RzTestResultInfo *result, RzPVector *fixup_results) {
+static void interact_break_cmd(RzTestResultInfo *result, RzPVector /*<RzTestResultInfo *>*/ *fixup_results) {
 	assert(result->test->type == RZ_TEST_TYPE_CMD);
 	RzCmdTest *test = result->test->cmd_test;
 	ut64 line_begin;
@@ -1311,7 +1311,7 @@ static void interact_break_asm(RzTestResultInfo *result) {
 		test->mode | RZ_ASM_TEST_MODE_BROKEN, test->disasm, test->bytes, test->bytes_size, test->offset, test->il);
 }
 
-static void interact_break(RzTestResultInfo *result, RzPVector *fixup_results) {
+static void interact_break(RzTestResultInfo *result, RzPVector /*<RzTestResultInfo *>*/ *fixup_results) {
 	switch (result->test->type) {
 	case RZ_TEST_TYPE_CMD:
 		interact_break_cmd(result, fixup_results);
@@ -1324,7 +1324,7 @@ static void interact_break(RzTestResultInfo *result, RzPVector *fixup_results) {
 	}
 }
 
-static void interact_commands(RzTestResultInfo *result, RzPVector *fixup_results) {
+static void interact_commands(RzTestResultInfo *result, RzPVector /*<RzTestResultInfo *>*/ *fixup_results) {
 	assert(result->test->type == RZ_TEST_TYPE_CMD);
 	RzCmdTest *test = result->test->cmd_test;
 	if (!test->cmds.value) {

binrz/rz-test/rz_test.h

@@ -135,7 +135,7 @@ typedef struct rz_test_test_t {
 } RzTest;
 
 typedef struct rz_test_test_database_t {
-	RzPVector tests;
+	RzPVector /*<RzTest *>*/ tests;
 	RzStrConstPool strpool;
 } RzTestDatabase;
 
@@ -179,15 +179,15 @@ typedef struct rz_test_test_result_info_t {
 
 RZ_API RzCmdTest *rz_test_cmd_test_new(void);
 RZ_API void rz_test_cmd_test_free(RzCmdTest *test);
-RZ_API RzPVector *rz_test_load_cmd_test_file(const char *file);
+RZ_API RzPVector /*<RzCmdTest *>*/ *rz_test_load_cmd_test_file(const char *file);
 
 RZ_API RzAsmTest *rz_test_asm_test_new(void);
 RZ_API void rz_test_asm_test_free(RzAsmTest *test);
-RZ_API RzPVector *rz_test_load_asm_test_file(RzStrConstPool *strpool, const char *file);
+RZ_API RzPVector /*<RzAsmTest *>*/ *rz_test_load_asm_test_file(RzStrConstPool *strpool, const char *file);
 
 RZ_API RzJsonTest *rz_test_json_test_new(void);
 RZ_API void rz_test_json_test_free(RzJsonTest *test);
-RZ_API RzPVector *rz_test_load_json_test_file(const char *file);
+RZ_API RzPVector /*<RzJsonTest *>*/ *rz_test_load_json_test_file(const char *file);
 
 RZ_API RzTestDatabase *rz_test_test_database_new(void);
 RZ_API void rz_test_test_database_free(RzTestDatabase *db);

librz/analysis/block.c

@@ -408,7 +408,7 @@ RZ_API bool rz_analysis_block_successor_addrs_foreach(RzAnalysisBlock *block, Rz
 
 typedef struct rz_analysis_block_recurse_context_t {
 	RzAnalysis *analysis;
-	RzPVector /*<RzAnalysisBlock>*/ to_visit;
+	RzPVector /*<RzAnalysisBlock *>*/ to_visit;
 	HtUP *visited;
 } RzAnalysisBlockRecurseContext;
 
@@ -486,7 +486,7 @@ RZ_API bool rz_analysis_block_recurse_followthrough(RzAnalysisBlock *block, RzAn
 
 typedef struct {
 	RzAnalysisBlock *bb;
-	RzListIter *switch_it;
+	RzListIter /*<RzAnalysisCaseOp *>*/ *switch_it;
 } RecurseDepthFirstCtx;
 
 RZ_API bool rz_analysis_block_recurse_depth_first(RzAnalysisBlock *block, RzAnalysisBlockCb cb, RZ_NULLABLE RzAnalysisBlockCb on_exit, void *user) {
@@ -601,8 +601,8 @@ typedef struct {
 	RzAnalysis *analysis;
 	RzAnalysisBlock *cur_parent;
 	ut64 dst;
-	RzPVector /*<RzAnalysisBlock>*/ *next_visit; // accumulate block of the next level in the tree
-	HtUP /*<RzAnalysisBlock>*/ *visited; // maps addrs to their previous block (or NULL for entry)
+	RzPVector /*<RzAnalysisBlock *>*/ *next_visit; // accumulate block of the next level in the tree
+	HtUP /*<RzAnalysisBlock *>*/ *visited; // maps addrs to their previous block (or NULL for entry)
 } PathContext;
 
 static bool shortest_path_successor_cb(ut64 addr, void *user) {

librz/analysis/dwarf_process.c

@@ -994,7 +994,7 @@ static const char *get_dwarf_reg_name(RZ_NONNULL char *arch, int reg_num, Variab
 	return "unsupported_reg";
 }
 
-static RzBinDwarfLocRange *find_largest_loc_range(RzList *loc_list) {
+static RzBinDwarfLocRange *find_largest_loc_range(RzList /*<RzBinDwarfLocRange *>*/ *loc_list) {
 	RzBinDwarfLocRange *largest = NULL;
 	ut64 max_range_size = 0;
 	RzListIter *iter;

librz/analysis/fcn.c

@@ -556,7 +556,7 @@ static inline void set_bb_branches(RZ_OUT RzAnalysisBlock *bb, const ut64 jump,
  * \param tasks The task list to append the new task items to.
  * \return RzAnalysisBBEndCause Cause a basic block ended.
  */
-static RzAnalysisBBEndCause run_basic_block_analysis(RzAnalysisTaskItem *item, RzVector *tasks) {
+static RzAnalysisBBEndCause run_basic_block_analysis(RzAnalysisTaskItem *item, RzVector /*<RzAnalysisTaskItem>*/ *tasks) {
 	rz_return_val_if_fail(item && tasks, RZ_ANALYSIS_RET_ERROR);
 	RzAnalysis *analysis = item->fcn->analysis;
 	RzAnalysisFunction *fcn = item->fcn;
@@ -2334,7 +2334,7 @@ static void clear_bb_vars(RzAnalysisFunction *fcn, RzAnalysisBlock *bb, ut64 fro
 	}
 }
 
-static void update_analysis(RzAnalysis *analysis, RzList *fcns, HtUP *reachable) {
+static void update_analysis(RzAnalysis *analysis, RzList /*<RzAnalysisFunction *>*/ *fcns, HtUP *reachable) {
 	RzListIter *it, *it2, *tmp;
 	RzAnalysisFunction *fcn;
 	bool old_jmpmid = analysis->opt.jmpmid;
@@ -2378,7 +2378,7 @@ static void update_analysis(RzAnalysis *analysis, RzList *fcns, HtUP *reachable)
 	analysis->opt.jmpmid = old_jmpmid;
 }
 
-static void calc_reachable_and_remove_block(RzList *fcns, RzAnalysisFunction *fcn, RzAnalysisBlock *bb, HtUP *reachable) {
+static void calc_reachable_and_remove_block(RzList /*<RzAnalysisFunction *>*/ *fcns, RzAnalysisFunction *fcn, RzAnalysisBlock *bb, HtUP *reachable) {
 	clear_bb_vars(fcn, bb, bb->addr, bb->addr + bb->size);
 	if (!rz_list_contains(fcns, fcn)) {
 		rz_list_append(fcns, fcn);

librz/analysis/meta.c

@@ -50,7 +50,7 @@ typedef struct {
 	RzAnalysisMetaType type;
 	const RzSpace *space;
 
-	RzPVector /*RzIntervalNode*/ *result;
+	RzPVector /*<RzIntervalNode *>*/ *result;
 } CollectCtx;
 
 static bool collect_nodes_cb(RzIntervalNode *node, void *user) {
@@ -61,7 +61,7 @@ static bool collect_nodes_cb(RzIntervalNode *node, void *user) {
 	return true;
 }
 
-static RzPVector *collect_nodes_at(RzAnalysis *analysis, RzAnalysisMetaType type, RZ_NULLABLE const RzSpace *space, ut64 addr) {
+static RzPVector /*<RzIntervalNode *>*/ *collect_nodes_at(RzAnalysis *analysis, RzAnalysisMetaType type, RZ_NULLABLE const RzSpace *space, ut64 addr) {
 	CollectCtx ctx = {
 		.type = type,
 		.space = space,
@@ -74,7 +74,7 @@ static RzPVector *collect_nodes_at(RzAnalysis *analysis, RzAnalysisMetaType type
 	return ctx.result;
 }
 
-static RzPVector *collect_nodes_in(RzAnalysis *analysis, RzAnalysisMetaType type, RZ_NULLABLE const RzSpace *space, ut64 addr) {
+static RzPVector /*<RzIntervalNode *>*/ *collect_nodes_in(RzAnalysis *analysis, RzAnalysisMetaType type, RZ_NULLABLE const RzSpace *space, ut64 addr) {
 	CollectCtx ctx = {
 		.type = type,
 		.space = space,
@@ -87,7 +87,7 @@ static RzPVector *collect_nodes_in(RzAnalysis *analysis, RzAnalysisMetaType type
 	return ctx.result;
 }
 
-static RzPVector *collect_nodes_intersect(RzAnalysis *analysis, RzAnalysisMetaType type, RZ_NULLABLE const RzSpace *space, ut64 start, ut64 end) {
+static RzPVector /*<RzIntervalNode *>*/ *collect_nodes_intersect(RzAnalysis *analysis, RzAnalysisMetaType type, RZ_NULLABLE const RzSpace *space, ut64 start, ut64 end) {
 	CollectCtx ctx = {
 		.type = type,
 		.space = space,

librz/analysis/p/analysis_arm_cs.c

@@ -2349,7 +2349,7 @@ static ut8 *analysis_mask(RzAnalysis *analysis, int size, const ut8 *data, ut64
 	return ret;
 }
 
-static RzList *analysis_preludes(RzAnalysis *analysis) {
+static RzList /*<RzSearchKeyword *>*/ *analysis_preludes(RzAnalysis *analysis) {
 #define KW(d, ds, m, ms) rz_list_append(l, rz_search_keyword_new((const ut8 *)d, ds, (const ut8 *)m, ms, NULL))
 	RzList *l = rz_list_newf((RzListFree)rz_search_keyword_free);
 	switch (analysis->bits) {

librz/analysis/p/analysis_mips_cs.c

@@ -1215,7 +1215,7 @@ static int archinfo(RzAnalysis *a, RzAnalysisInfoType query) {
 	}
 }
 
-static RzList *analysis_preludes(RzAnalysis *analysis) {
+static RzList /*<RzSearchKeyword *>*/ *analysis_preludes(RzAnalysis *analysis) {
 #define KW(d, ds, m, ms) rz_list_append(l, rz_search_keyword_new((const ut8 *)d, ds, (const ut8 *)m, ms, NULL))
 	RzList *l = rz_list_newf((RzListFree)rz_search_keyword_free);
 	KW("\x27\xbd\x00", 3, NULL, 0);

librz/analysis/p/analysis_ppc_cs.c

@@ -1633,7 +1633,7 @@ static int archinfo(RzAnalysis *a, RzAnalysisInfoType query) {
 	}
 }
 
-static RzList *analysis_preludes(RzAnalysis *analysis) {
+static RzList /*<RzSearchKeyword *>*/ *analysis_preludes(RzAnalysis *analysis) {
 #define KW(d, ds, m, ms) rz_list_append(l, rz_search_keyword_new((const ut8 *)d, ds, (const ut8 *)m, ms, NULL))
 	RzList *l = rz_list_newf((RzListFree)rz_search_keyword_free);
 	KW("\x7c\x08\x02\xa6", 4, NULL, 0);

librz/analysis/p/analysis_pyc.c

@@ -39,7 +39,7 @@ static char *get_reg_profile(RzAnalysis *analysis) {
 	);
 }
 
-static RzList *get_pyc_code_obj(RzAnalysis *analysis) {
+static RzList /*<RzList<void *> *>*/ *get_pyc_code_obj(RzAnalysis *analysis) {
 	RzBin *b = analysis->binb.bin;
 	RzBinPlugin *plugin = b->cur && b->cur->o ? b->cur->o->plugin : NULL;
 	bool is_pyc = (plugin && strcmp(plugin->name, "pyc") == 0);

librz/analysis/p/analysis_v850.c

@@ -555,7 +555,7 @@ static char *get_reg_profile(RzAnalysis *analysis) {
 	return strdup(p);
 }
 
-static RzList *analysis_preludes(RzAnalysis *analysis) {
+static RzList /*<RzSearchKeyword *>*/ *analysis_preludes(RzAnalysis *analysis) {
 #define KW(d, ds, m, ms) rz_list_append(l, rz_search_keyword_new((const ut8 *)d, ds, (const ut8 *)m, ms, NULL))
 	RzList *l = rz_list_newf((RzListFree)rz_search_keyword_free);
 	KW("\x80\x07", 2, "\xf0\xff", 2);

librz/analysis/p/analysis_x86_cs.c

@@ -3705,7 +3705,7 @@ static int archinfo(RzAnalysis *a, RzAnalysisInfoType query) {
 	}
 }
 
-static RzList *analysis_preludes(RzAnalysis *analysis) {
+static RzList /*<RzSearchKeyword *>*/ *analysis_preludes(RzAnalysis *analysis) {
 #define KW(d, ds, m, ms) rz_list_append(l, rz_search_keyword_new((const ut8 *)d, ds, (const ut8 *)m, ms, NULL))
 	RzList *l = rz_list_newf((RzListFree)rz_search_keyword_free);
 	switch (analysis->bits) {

librz/analysis/reflines.c

@@ -36,7 +36,7 @@ static ReflineEnd *refline_end_new(ut64 val, bool is_from, RzAnalysisRefline *re
 	return re;
 }
 
-static bool add_refline(RzList *list, RzList *sten, ut64 addr, ut64 to, int *idx) {
+static bool add_refline(RzList /*<RzAnalysisRefline *>*/ *list, RzList /*<ReflineEnd *>*/ *sten, ut64 addr, ut64 to, int *idx) {
 	ReflineEnd *re1, *re2;
 	RzAnalysisRefline *item = RZ_NEW0(RzAnalysisRefline);
 	if (!item) {