From 9f31c6306be73904b21f32154575c1eb71b4223b Mon Sep 17 00:00:00 2001 From: sBubshait Date: Sat, 15 Jun 2024 02:08:29 +0100 Subject: [PATCH] Update util files for documentation --- src/util/binary_util.c | 12 +++++++----- src/util/binary_util.h | 43 ++++++++++++++++++++++++++++++++++++++++++ src/util/fileio.c | 11 +++++++---- src/util/fileio.h | 19 ++++++++++++++++++- 4 files changed, 75 insertions(+), 10 deletions(-) diff --git a/src/util/binary_util.c b/src/util/binary_util.c index 78bf11d..68d8e38 100644 --- a/src/util/binary_util.c +++ b/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 #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; } diff --git a/src/util/binary_util.h b/src/util/binary_util.h index 2fc0439..2b9bc15 100644 --- a/src/util/binary_util.h +++ b/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 diff --git a/src/util/fileio.c b/src/util/fileio.c index 41df962..c427c09 100644 --- a/src/util/fileio.c +++ b/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 #include #include #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) { diff --git a/src/util/fileio.h b/src/util/fileio.h index 47aa858..fc36a23 100644 --- a/src/util/fileio.h +++ b/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 @@ -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