Improve documentation in definitions.h

2 files changed, 34 insertions, 10 deletions

diff --git a/inc/definitions.h b/inc/definitions.h
index 4b01be9..877065e 100644
--- a/inc/definitions.h
+++ b/inc/definitions.h
@@ -2,25 +2,49 @@
 #define DEFINITIONS_H
 #include <cmath>
 
-/* The number of bits to specify a word in a line
+/**
+ * The number of bits to specify a word in a line
  */
 #define LINE_SPEC 2
+/**
+ * The total number of words in a line
+ */
 #define LINE_SIZE (int)pow(2, 2)
 
-/* The number of bits to specify a memory line
- * (/ (expt 2 15) 4)
+/**
+ * The number of bits to specify a memory line
+ * calculated as: (/ (expt 2 15) 4)
  */
 #define MEM_SPEC 13
+/**
+ * The total number of words in memory
+ */
 #define MEM_SIZE (int)pow(2, MEM_SPEC)
 
-/* The number of bits to specify a l1 cache line
+/**
+ * The number of bits to specify a l1 cache line
  */
 #define L1_CACHE_SPEC 5
+/**
+ * The total number of words in l1 cache
+ */
 #define L1_CACHE_SIZE (int)pow(2, L1_CACHE_SPEC)
 
-/* Parses some bits.
+/**
+ * Return the N least-significant bits from integer K using a bit mask
+ * @param the integer to be parsed
+ * @param the number of bits to be parsed
+ * @return the N least-significant bits from K
+ */
+#define GET_LS_BITS(k, n) ((k) & ((1 << (n)) - 1))
+/**
+ * Return the bits from integer K starting at N and ending at M using a bit
+ * mask
+ * @param the integer to be parsed
+ * @param the index of the starting bit to be parsed
+ * @param the index of the ending bit to be parsed
+ * @return a section of bits from K
  */
-#define LAST(k, n) ((k) & ((1 << (n)) - 1))
-#define MID(k, m, n) LAST((k) >> (m), ((n) - (m)))
+#define GET_MID_BITS(k, m, n) GET_LS_BITS((k) >> (m), ((n) - (m)))
 
 #endif /* DEFINITIONS_H_INCLUDED */
diff --git a/src/utils/utils.cc b/src/utils/utils.cc
index 52be177..dfeb2b3 100644
--- a/src/utils/utils.cc
+++ b/src/utils/utils.cc
@@ -4,8 +4,8 @@
 void get_bit_fields(int address, int *tag, int *index, int *offset)
 {
 	*tag =
-		MID(address, LINE_SPEC + L1_CACHE_SPEC,
+		GET_MID_BITS(address, LINE_SPEC + L1_CACHE_SPEC,
 			MEM_SPEC + LINE_SPEC + L1_CACHE_SPEC);
-	*index = MID(address, LINE_SPEC, L1_CACHE_SPEC + LINE_SPEC);
-	*offset = LAST(address, LINE_SPEC);
+	*index = GET_MID_BITS(address, LINE_SPEC, L1_CACHE_SPEC + LINE_SPEC);
+	*offset = GET_LS_BITS(address, LINE_SPEC);
 }