From 394bdd662b7facd32cfbb8ccd24cc0593f38ac0d Mon Sep 17 00:00:00 2001
From: Joe Subbiani <joe.subbiani@arm.com>
Date: Wed, 7 Jul 2021 15:16:56 +0100
Subject: [PATCH] Document common.h and remove changelog

Added documenttion comments to common.h and removed the changelog
as it is not really necessary for refactoring.

Also modified a comment in aria.c to be clearer

Signed-off-by: Joe Subbiani <joe.subbiani@arm.com>
---
 ChangeLog.d/issue4274.txt |  9 -------
 library/aria.c            |  3 ++-
 library/common.h          | 50 +++++++++++++++++++++++++++++++++++----
 3 files changed, 47 insertions(+), 15 deletions(-)
 delete mode 100644 ChangeLog.d/issue4274.txt

diff --git a/ChangeLog.d/issue4274.txt b/ChangeLog.d/issue4274.txt
deleted file mode 100644
index f0952f4307..0000000000
--- a/ChangeLog.d/issue4274.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-Changes
-   * Create 4 byte reading macros in library/common.h, used in files
-     within the same directory: MBEDTLS_BYTE_0... MBEDTLS_BYTE_3.
-   * Move the (PUT and GET) UINT32_ (BE and LE) macro functions into
-     library/common.h. Rename with the prefix MBEDTLS_ to satisfy
-     test/scripts/check-names.sh (e.g MBEDTLS_PUT_UINT32_LE).
-   * Move BYTES_TO_U32_LE macro function to library/common.h, also given
-     the prefix MBEDTLS_.
-     Fixes #4274.
diff --git a/library/aria.c b/library/aria.c
index a6319d3e29..f4aa64107a 100644
--- a/library/aria.c
+++ b/library/aria.c
@@ -385,7 +385,8 @@ static void aria_fe_xor( uint32_t r[4], const uint32_t p[4],
  * Big endian 128-bit rotation: r = a ^ (b <<< n), used only in key setup.
  *
  * We chose to store bytes into 32-bit words in little-endian format (see
- * GET/MBEDTLS_PUT_UINT32_LE) so we need to reverse bytes here.
+ * MBEDTLS_GET_UINT32_LE / MBEDTLS_PUT_UINT32_LE ) so we need to reverse
+ * bytes here.
  */
 static void aria_rot128( uint32_t r[4], const uint32_t a[4],
                          const uint32_t b[4], uint8_t n )
diff --git a/library/common.h b/library/common.h
index e85cbf28d0..5115465e88 100644
--- a/library/common.h
+++ b/library/common.h
@@ -68,15 +68,36 @@ extern void (*mbedtls_test_hook_test_fail)( const char * test, int line, const c
 
 /** Byte Reading Macros
  *
- * To tidy up code and save horizontal and vertical space, use byte
- * reading macros to cast
+ * Obtain the most significant byte of x using 0xff
+ * Using MBEDTLS_BYTE_a will shift a*8 bits
+ * to retrieve the next byte of information
  */
 #define MBEDTLS_BYTE_0( x ) ( (uint8_t) ( ( x ) & 0xff ) )
 #define MBEDTLS_BYTE_1( x ) ( (uint8_t) ( ( ( x ) >> 8  ) & 0xff ) )
 #define MBEDTLS_BYTE_2( x ) ( (uint8_t) ( ( ( x ) >> 16 ) & 0xff ) )
 #define MBEDTLS_BYTE_3( x ) ( (uint8_t) ( ( ( x ) >> 24 ) & 0xff ) )
 
-/*
+/**
+ * 32-bit integer manipulation macros
+ *
+ * \brief   Using GET-
+ *          From input data, take the most significant bytes
+ *          and concatonate them as you shift along
+ *          Using PUT-
+ *          Read from a 32 bit integer and store each byte
+ *          in memory, offset by a byte each, resulting in
+ *          each byte being adjacent in memory.
+ *
+ * \param   n   32 bit integer where data is accessed via
+ *              PUT or stored using GET
+ * \param   b   const unsigned char array of data to be
+ *              manipulated
+ * \param   i   offset in bytes, In the case of UINT32, i
+ *              would increment by 4 every use assuming
+ *              the data is being stored in the same location
+ */
+
+/**
  * 32-bit integer manipulation macros (big endian)
  */
 #ifndef MBEDTLS_GET_UINT32_BE
@@ -99,7 +120,7 @@ extern void (*mbedtls_test_hook_test_fail)( const char * test, int line, const c
     } while( 0 )
 #endif
 
-/*
+/**
  * 32-bit integer manipulation macros (little endian)
  */
 #ifndef MBEDTLS_GET_UINT32_LE
@@ -132,8 +153,27 @@ extern void (*mbedtls_test_hook_test_fail)( const char * test, int line, const c
       | (uint32_t) ( (uint32_t) (data)[( offset ) + 3] << 24 )  \
     )
 
+/**
+ * 16-bit integer manipulation macros
+ *
+ * \brief   Using GET-
+ *          From input data, take the most significant bytes
+ *          and concatonate them as you shift along
+ *          Using PUT-
+ *          Read from a 16 bit integer and store each byte
+ *          in memory, offset by a byte each, resulting in
+ *          each byte being adjacent in memory.
+ *
+ * \param   n   16 bit integer where data is accessed via
+ *              PUT or stored using GET
+ * \param   b   const unsigned char array of data to be
+ *              manipulated
+ * \param   i   offset in bytes, In the case of UINT16, i
+ *              would increment by 2 every use assuming
+ *              the data is being stored in the same location
+ */
 
-/*
+/**
  * 16-bit integer manipulation macros (little endian)
  */
 #ifndef MBEDTLS_GET_UINT16_LE