| Message ID | 20250116213214.5695-1-iii@linux.ibm.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [v2,1/2] tcg: Document tb_lookup() and tcg_tb_lookup() | expand |
On 1/16/25 13:31, Ilya Leoshkevich wrote: > These similarly named functions serve different purposes; add > docstrings to highlight them. > > Suggested-by: Alex Bennée <alex.bennee@linaro.org> > Signed-off-by: Ilya Leoshkevich <iii@linux.ibm.com> > --- > accel/tcg/cpu-exec.c | 15 ++++++++++++++- > include/tcg/tcg.h | 41 +++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 55 insertions(+), 1 deletion(-) Reviewed-by: Richard Henderson <richard.henderson@linaro.org> r~ > > diff --git a/accel/tcg/cpu-exec.c b/accel/tcg/cpu-exec.c > index d48b82a9325..8b773d88478 100644 > --- a/accel/tcg/cpu-exec.c > +++ b/accel/tcg/cpu-exec.c > @@ -249,7 +249,20 @@ static TranslationBlock *tb_htable_lookup(CPUState *cpu, vaddr pc, > return qht_lookup_custom(&tb_ctx.htable, &desc, h, tb_lookup_cmp); > } > > -/* Might cause an exception, so have a longjmp destination ready */ > +/** > + * tb_lookup: > + * @cpu: CPU that will execute the returned translation block > + * @pc: guest PC > + * @cs_base: arch-specific value associated with translation block > + * @flags: arch-specific translation block flags > + * @cflags: CF_* flags > + * > + * Look up a translation block inside the QHT using @pc, @cs_base, @flags and > + * @cflags. Uses @cpu's tb_jmp_cache. Might cause an exception, so have a > + * longjmp destination ready. > + * > + * Returns: an existing translation block or NULL. > + */ > static inline TranslationBlock *tb_lookup(CPUState *cpu, vaddr pc, > uint64_t cs_base, uint32_t flags, > uint32_t cflags) > diff --git a/include/tcg/tcg.h b/include/tcg/tcg.h > index a77ed12b9dc..057df6c4599 100644 > --- a/include/tcg/tcg.h > +++ b/include/tcg/tcg.h > @@ -746,10 +746,51 @@ void tcg_region_reset_all(void); > size_t tcg_code_size(void); > size_t tcg_code_capacity(void); > > +/** > + * tcg_tb_insert: > + * @tb: translation block to insert > + * > + * Insert @tb into the region trees. > + */ > void tcg_tb_insert(TranslationBlock *tb); > + > +/** > + * tcg_tb_remove: > + * @tb: translation block to remove > + * > + * Remove @tb from the region trees. > + */ > void tcg_tb_remove(TranslationBlock *tb); > + > +/** > + * tcg_tb_lookup: > + * @tc_ptr: host PC to look up > + * > + * Look up a translation block inside the region trees by @tc_ptr. This is > + * useful for exception handling, but must not be used for the purposes of > + * executing the returned translation block. See struct tb_tc for more > + * information. > + * > + * Returns: a translation block previously inserted into the region trees, > + * such that @tc_ptr points anywhere inside the code generated for it, or > + * NULL. > + */ > TranslationBlock *tcg_tb_lookup(uintptr_t tc_ptr); > + > +/** > + * tcg_tb_foreach: > + * @func: callback > + * @user_data: opaque value to pass to @callback > + * > + * Call @func for each translation block inserted into the region trees. > + */ > void tcg_tb_foreach(GTraverseFunc func, gpointer user_data); > + > +/** > + * tcg_nb_tbs: > + * > + * Returns: the number of translation blocks inserted into the region trees. > + */ > size_t tcg_nb_tbs(void); > > /* user-mode: Called with mmap_lock held. */
diff --git a/accel/tcg/cpu-exec.c b/accel/tcg/cpu-exec.c index d48b82a9325..8b773d88478 100644 --- a/accel/tcg/cpu-exec.c +++ b/accel/tcg/cpu-exec.c @@ -249,7 +249,20 @@ static TranslationBlock *tb_htable_lookup(CPUState *cpu, vaddr pc, return qht_lookup_custom(&tb_ctx.htable, &desc, h, tb_lookup_cmp); } -/* Might cause an exception, so have a longjmp destination ready */ +/** + * tb_lookup: + * @cpu: CPU that will execute the returned translation block + * @pc: guest PC + * @cs_base: arch-specific value associated with translation block + * @flags: arch-specific translation block flags + * @cflags: CF_* flags + * + * Look up a translation block inside the QHT using @pc, @cs_base, @flags and + * @cflags. Uses @cpu's tb_jmp_cache. Might cause an exception, so have a + * longjmp destination ready. + * + * Returns: an existing translation block or NULL. + */ static inline TranslationBlock *tb_lookup(CPUState *cpu, vaddr pc, uint64_t cs_base, uint32_t flags, uint32_t cflags) diff --git a/include/tcg/tcg.h b/include/tcg/tcg.h index a77ed12b9dc..057df6c4599 100644 --- a/include/tcg/tcg.h +++ b/include/tcg/tcg.h @@ -746,10 +746,51 @@ void tcg_region_reset_all(void); size_t tcg_code_size(void); size_t tcg_code_capacity(void); +/** + * tcg_tb_insert: + * @tb: translation block to insert + * + * Insert @tb into the region trees. + */ void tcg_tb_insert(TranslationBlock *tb); + +/** + * tcg_tb_remove: + * @tb: translation block to remove + * + * Remove @tb from the region trees. + */ void tcg_tb_remove(TranslationBlock *tb); + +/** + * tcg_tb_lookup: + * @tc_ptr: host PC to look up + * + * Look up a translation block inside the region trees by @tc_ptr. This is + * useful for exception handling, but must not be used for the purposes of + * executing the returned translation block. See struct tb_tc for more + * information. + * + * Returns: a translation block previously inserted into the region trees, + * such that @tc_ptr points anywhere inside the code generated for it, or + * NULL. + */ TranslationBlock *tcg_tb_lookup(uintptr_t tc_ptr); + +/** + * tcg_tb_foreach: + * @func: callback + * @user_data: opaque value to pass to @callback + * + * Call @func for each translation block inserted into the region trees. + */ void tcg_tb_foreach(GTraverseFunc func, gpointer user_data); + +/** + * tcg_nb_tbs: + * + * Returns: the number of translation blocks inserted into the region trees. + */ size_t tcg_nb_tbs(void); /* user-mode: Called with mmap_lock held. */
These similarly named functions serve different purposes; add docstrings to highlight them. Suggested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Ilya Leoshkevich <iii@linux.ibm.com> --- accel/tcg/cpu-exec.c | 15 ++++++++++++++- include/tcg/tcg.h | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 1 deletion(-)