Update util files for documentation

src/util/binary_util.c

@@ -1,4 +1,10 @@
-/** Binary Util */
+/** @file binary_util.c
+ *  @brief Implementation of utility functions for binary manipulation.
+ *
+ *  @author Saleh Bubshait
+ *  @author Themis Demetriades
+ */
+
 #include <assert.h>
 #include "binary_util.h"
 
@@ -20,11 +26,9 @@ dword truncateValue(dword value, a64inst_regType regType) {
         return value;
     } else {
         return (word)value;
-        //return value & (dword)(((dword)1 << WORD_BITS) - 1);
     }
 }
 
-// Sign extend a given value to a 64-bit signed integer given the number of bits
 int64_t signExtend(dword value, unsigned int n) {
     if (n == 0 || n >= 64) {
         // If n_bits is 0 or greater than or equal to 64, return the value as is
@@ -46,12 +50,10 @@ int64_t signExtend(dword value, unsigned int n) {
     }
 }
 
-// Returns the position of the MSB of the given register type
 dword getMSBPos(a64inst_regType regType) {
     return (regType ? DWORD_BITS : WORD_BITS) - 1;
 }
 
-// Returns the MSB of the given value assuming it's of the size stored in the given register type
 uint8_t getMSB(dword value, a64inst_regType regType) {
     return (value >> getMSBPos(regType)) & 1u; 
 }

src/util/binary_util.h

@@ -1,19 +1,62 @@
+/** @file binary_util.h
+ *  @brief Utility functions for binary manipulation.
+ *
+ *  @author Saleh Bubshait
+ *  @author Themis Demetriades
+ */
 #ifndef __BINARY_UTIL__
 #define __BINARY_UTIL__
 
 #include "../global.h"
 #include "../a64instruction/a64instruction_global.h"
 
+/** @brief Extracts the bits between the given indices from a word as an 
+ *  unsigned integer, uint32_t (word).
+ *
+ *  @param wrd The input word (uint32_t) to extract bits from.
+ *  @param lsb The index of the least significant bit to extract.
+ *  @param msb The index of the most significant bit to extract.
+ *  @return The extracted bits as a word.
+ */
 word getBits(word wrd, uint8_t lsb, uint8_t msb);
 
+/** @brief Returns the maximum of two given two double words (uint64_t).
+ *
+ *  @param a The first double word.
+ *  @param b The second double word.
+ *  @return The maximum of the two given double words.
+ */
 dword max(dword a, dword b);
 
+/** @brief Truncates a given value to the size of the given register type.
+ *
+ *  @param value The value to truncate.
+ *  @param regType The register type to truncate the value to.
+ *  @return The truncated value.
+ */
 dword truncateValue(dword value, a64inst_regType regType);
 
+/** @brief Sign extend a n-bit given value to a signed integer.
+ *
+ *  @param value The value to sign extend.
+ *  @param n The number of bits of the signed value. E.g., 16 for simm16.
+ */
 int64_t signExtend(dword value, unsigned int n);
 
+/** @brief Returns the position of the most significant bit of the given register type.
+ *
+ *  @param regType The register type to get the most significant bit position of.
+ *  @return The position of the most significant bit. This is either 31 or 63.
+ */
 dword getMSBPos(a64inst_regType regType);
 
+/** @brief Returns the most significant bit of the given value assuming it's of
+ *  the size stored in the given register type.
+ *
+ *  @param value The value to get the most significant bit of.
+ *  @param regType The register type to get the most significant bit of.
+ *  @return The most significant bit of the given value.
+ */
 uint8_t getMSB(dword value, a64inst_regType regType);
 
 #endif

src/util/fileio.c

@@ -1,13 +1,16 @@
+/** @file fileio.c
+ *  @brief Implementation of file input/output functions.
+ *
+ *  @author Saleh Bubshait
+ *  @author Themis Demetriades
+ */
+
 #include <assert.h>
 #include <stdio.h>
 #include <string.h>
 #include "fileio.h"
 #include "../global.h"
 
-/* Loads a binary file located at filePath to memory, taking up a block of exactly memorySize bytes,
-   and returns the starting address of the data. If memorySize is insufficient to store the entire file,
-   an appropriate error is reported. Excess memory is set to 0 bit values. */
-
 byte *fileio_loadBin(const char *filePath, size_t memorySize) {
     FILE *file = fopen(filePath, "rb");
     if (file == NULL) {

src/util/fileio.h

@@ -1,3 +1,10 @@
+/** @file fileio.h
+ *  @brief File input/output functions, used in both the emulator and assembler.
+ *
+ *  @author Saleh Bubshait
+ *  @author Themis Demetriades
+ */
+
 #ifndef __FILEIO__
 #define __FILEIO__
 #include <stdlib.h>
@@ -5,5 +12,15 @@
 
 #define EXIT_FAILURE 1
 
-extern byte *fileio_loadBin(const char *filePath, size_t memorySize);
+/** @brief Loads a binary file located at filePath to memory, taking up a block 
+ *  of exactly memorySize bytes.
+ *  If memorySize is insufficient to store the entire file, an appropriate error
+ *  is reported. Excess memory is set to 0 bit values.
+ *
+ *  @param filePath The path to the binary file to load.
+ *  @param memorySize The size of the memory block to allocate.
+ *  @return The starting address of the data loaded from the file.
+ */
+byte *fileio_loadBin(const char *filePath, size_t memorySize);
+
 #endif