Refine comments

Author: jserv

src/breakpoint.c

@@ -25,7 +25,7 @@ bool breakpoint_map_insert(breakpoint_map_t map, riscv_word_t addr)
     breakpoint_t bp = (breakpoint_t){.addr = addr, .orig_insn = 0};
     map_iter_t it;
     map_find(map, &it, &addr);
-    /* We don't expect to set breakpoint at duplicate address */
+    /* breakpoints are not expected to be set at duplicate addresses */
     if (!map_at_end(map, &it))
         return false;
 

src/cache.c

@@ -16,25 +16,27 @@
 #define GOLDEN_RATIO_32 0x61C88647
 #define HASH(val) \
     (((val) * (GOLDEN_RATIO_32)) >> (32 - (cache_size_bits))) & (cache_size - 1)
+
 /* THRESHOLD is set to identify hot spots. Once the frequency of use for a block
- * exceeds the THRESHOLD, the JIT compiler flow is triggered. */
+ * exceeds the THRESHOLD, the JIT compiler flow is triggered.
+ */
 #define THRESHOLD 1000
 
 static uint32_t cache_size, cache_size_bits;
 static struct mpool *cache_mp;
 
 #if RV32_HAS(ARC)
-/*
- * Adaptive Replacement Cache (ARC) improves the fundamental LRU strategy
- * by dividing the cache into two lists, T1 and T2. list T1 is for LRU
- * strategy and list T2 is for LFU strategy. Moreover, it keeps two ghost
- * lists, B1 and B2, with replaced entries from the LRU list going into B1
- * and the LFU list going into B2.
+/* The Adaptive Replacement Cache (ARC) improves the traditional LRU strategy
+ * by dividing the cache into two lists: T1 and T2. T1 follows the LRU
+ * strategy, while T2 follows the LFU strategy. Additionally, ARC maintains two
+ * ghost lists, B1 and B2, which store replaced entries from the LRU and LFU
+ * lists, respectively.
  *
- * Based on B1 and B2, ARC will modify the size of T1 and T2. When a cache
- * hit occurs in B1, it indicates that T1's capacity is too little, therefore
- * we increase T1's size while decreasing T2. But, if the cache hit occurs in
- * B2, we would increase the size of T2 and decrease the size of T1.
+ * Based on the contents of B1 and B2, ARC dynamically adjusts the sizes of T1
+ * and T2. If a cache hit occurs in B1, it indicates that the size of T1 is
+ * insufficient, leading to an increase in T1's size and a decrease in T2's
+ * size. Conversely, if a cache hit occurs in B2, T2's size is increased while
+ * T1's size is decreased.
  */
 typedef enum {
     LRU_list,
@@ -57,8 +59,7 @@ struct hlist_node {
 };
 
 #if RV32_HAS(ARC)
-/*
- * list maintains four cache lists T1, T2, B1, and B2.
+/* list maintains four cache lists T1, T2, B1, and B2.
  * ht_list maintains hashtable and improves the performance of cache searching.
  */
 typedef struct {
@@ -225,7 +226,6 @@ static inline void hlist_del_init(struct hlist_node *n)
          pos = hlist_entry_safe((pos)->member.next, type, member))
 #endif
 
-
 cache_t *cache_create(int size_bits)
 {
     cache_t *cache = malloc(sizeof(cache_t));
@@ -291,12 +291,12 @@ cache_t *cache_create(int size_bits)
 
 
 #if RV32_HAS(ARC)
-/* Rules of ARC
+/* Rules of ARC:
  * 1. size of LRU_list + size of LFU_list <= c
  * 2. size of LRU_list + size of LRU_ghost_list <= c
  * 3. size of LFU_list + size of LFU_ghost_list <= 2c
  * 4. size of LRU_list + size of LFU_list + size of LRU_ghost_list + size of
- * LFU_ghost_list <= 2c
+ *    LFU_ghost_list <= 2c
  */
 #define CACHE_ASSERT(cache)                                                 \
     assert(cache->list_size[LRU_list] + cache->list_size[LFU_list] <=       \
@@ -401,10 +401,11 @@ void *cache_get(cache_t *cache, uint32_t key)
     if (!entry || entry->key != key)
         return NULL;
 
-    /* Once the frequency of use for a specific block exceeds the predetermined
-     * THRESHOLD, we dispatch the block to the code generator for the purpose of
-     * generating C code. Subsequently, the generated C code is compiled into
-     * machine code by the target compiler. */
+    /* When the frequency of use for a specific block exceeds the predetermined
+     * THRESHOLD, the block is dispatched to the code generator to generate C
+     * code. The generated C code is then compiled into machine code by the
+     * target compiler.
+     */
     if (entry->frequency < THRESHOLD) {
         list_del_init(&entry->list);
         list_add(&entry->list, cache->lists[entry->frequency++]);
@@ -420,8 +421,8 @@ void *cache_put(cache_t *cache, uint32_t key, void *value)
 #if RV32_HAS(ARC)
     assert(cache->list_size[LRU_list] + cache->list_size[LRU_ghost_list] <=
            cache->capacity);
-    /* Before adding new element to cach, we should check the status
-     * of cache.
+    /* Before adding a new element to the cache, it is necessary to check the
+     * status of the cache.
      */
     if ((cache->list_size[LRU_list] + cache->list_size[LRU_ghost_list]) ==
         cache->capacity) {
@@ -539,4 +540,4 @@ void cache_free(cache_t *cache, void (*callback)(void *))
     free(cache->map->ht_list_head);
     free(cache->map);
     free(cache);
-}
+}

src/common.h

@@ -24,9 +24,9 @@
 #define __ALIGNED(x)
 #endif
 
-/* There is no tail-call optimization(TCO) in non-optimized builds. To work
- * around this, we attempts to use a compiler attribute called musttail that
- * forces the compiler to TCO even when optimizations aren't on.
+/* Non-optimized builds do not have tail-call optimization (TCO). To work
+ * around this, the compiler attribute 'musttail' is used, which forces TCO
+ * even without optimizations enabled.
  */
 #if defined(__has_attribute) && __has_attribute(musttail)
 #define MUST_TAIL __attribute__((musttail))
@@ -73,4 +73,4 @@
 #define container_of(ptr, type, member) \
     ((type *) ((char *) (ptr) - (offsetof(type, member))))
 #endif
-#endif
+#endif

src/decode.h

@@ -244,27 +244,28 @@ typedef struct rv_insn {
     /* instruction length */
     uint8_t insn_len;
 
-    /* According to tail-call optimization (TCO), if a C function ends with
-     * a function call to another function or itself and simply returns that
-     * function's result, the compiler can substitute a simple jump to the
-     * other function for the 'call' and 'return' instructions . The self
-     * -recursive function can therefore use the same function stack frame.
+    /* Tail-call optimization (TCO) allows a C function to replace a function
+     * call to another function or itself, followed by a simple return of the
+     * function's result, with a direct jump to the target function. This
+     * optimization enables the self-recursive function to reuse the same
+     * function stack frame.
      *
-     * Using member tailcall, we can tell whether an IR is the final IR in
-     * a basic block. Additionally, member 'impl' allows us to invoke next
-     * instruction emulation directly without computing the jumping address.
-     * In order to enable the compiler to perform TCO, we can use these two
-     * members to rewrite all instruction emulations into a self-recursive
-     * version.
+     * The @tailcall member indicates whether an intermediate representation
+     * (IR) is the final instruction in a basic block. The @impl member
+     * facilitates the direct invocation of the next instruction emulation
+     * without the need to compute the jump address. By utilizing these two
+     * members, all instruction emulations can be rewritten into a
+     * self-recursive version, enabling the compiler to leverage TCO.
      */
     bool tailcall;
     bool (*impl)(riscv_t *, const struct rv_insn *);
 
-    /* We employ two pointers, branch taken and branch untaken, to avoid the
-     * significant overhead resulting from aggressive memory copy. Instead of
-     * copying the entire IR array, these pointers respectively point to the
-     * first IR of the first basic block in the path of the taken and untaken
-     * branches, so we can jump to the specific IR array directly.
+    /* Two pointers, 'branch_taken' and 'branch_untaken', are employed to
+     * avoid the overhead associated with aggressive memory copying. Instead
+     * of copying the entire intermediate representation (IR) array, these
+     * pointers indicate the first IR of the first basic block in the path of
+     * the taken and untaken branches. This allows for direct jumping to the
+     * specific IR array without the need for additional copying.
      */
     struct rv_insn *branch_taken, *branch_untaken;
 } rv_insn_t;