From f606010a2f4db625c8c69749f64ee96c39b02337 Mon Sep 17 00:00:00 2001
From: andreas789 <39582861+andreas789@users.noreply.github.com>
Date: Tue, 18 Jun 2024 01:48:43 +0300
Subject: [PATCH] Update readme.md

---
 readme.md | 47 ++++++++++++++++++++++++++++-------------------
 1 file changed, 28 insertions(+), 19 deletions(-)

diff --git a/readme.md b/readme.md
index b204395..b52791e 100644
--- a/readme.md
+++ b/readme.md
@@ -1,29 +1,32 @@
 
+
 # Overview of the Smart Array Implementation
 
-The smart array implementation aims to reduce physical memory waste by sharing physical pages among multiple virtual pages, resolving conflicts during slot allocation, and ensuring efficient access to stored data.
+The smart array implementation aims to reduce physical memory waste by sharing physical pages among multiple virtual pages - while at the same time - resolving conflicts during slot allocation, and ensuring efficient access to stored data.
 
 # 1. Implementation Details
 
 ### Memory Management
 
-Memory management is handled using Linux's `mmap` system call to allocate physical pages and manage their lifecycle throughout runtime.
+Memory management is mainly handled using Linux's `mmap` system call to allocate physical pages and manage their lifecycle throughout runtime.
 
-As per project project requests the mmap has used the following flags.
+As per project requirements the mmap system call has used the following flags.
 
 ```cpp
 mmap(nullptr, PAGE_SIZE, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
 ```
-**`PROT_READ | PROT_WRITE`**: Implies that allocated memory region should be readable and writable. This  ensures that the allocated pages can be both read from and written to by the application.
+The reason why those flags were used is discussed below: 
+
+**`PROT_READ | PROT_WRITE`**: Allocated memory region should be readable and writable. This  ensures that the allocated pages can be both read from and written to by the application.
 
-**`MAP_PRIVATE | MAP_ANONYMOUS`**: 1st flag implies that the changes to the memory region are private to the calling application and not visible to other processes that may map to  the same region. 2nd flag implies that the memory region is not backed by any file - so called anonymus memory.
+**`MAP_PRIVATE | MAP_ANONYMOUS`**: 1st flag implies that the changes to the memory region are private to the calling application and not visible to other processes that may map to  the same region. 2nd flag implies that the memory region is not backed by any file - anonymus memory.
 
 **`-1`**: Implies that the kernel should choose the address at which to create the mapping.
 **`-0`**: Implies that the offset within the anonymous memory should be 0.
 
 ### Virtual and Physical Page Mapping
 
-Virtual pages are mapped to physical pages using a vector container (`vector<void*> virtualPages_`) to track mappings and ensure modern & efficient access and modification of data.
+Virtual pages are mapped to physical pages using a vector container (`vector<void*> virtualPages_`). Each member is used to track mappings.
 
 ### Conflict Resolution Strategy
 
@@ -47,15 +50,31 @@ struct ArrMetadata {
 };
 ```
 
+### Size Constraints (8B Slots)
+
+Each slot in the implementaion is designed to accommodate 8 bytes (8B) of data, with 2 bytes allocated for metadata and 6 bytes available for data storage.
+
+#### Metadata Storage
+- **Structure**: The `ArrMetadata` struct has:
+  - `uint16_t virtualPageId : 15` (15 bits for virtualPageId)
+  - `bool occupiedFlg` (1 bit for occupancy flag)
+- **Total Size**: 16 bits = 2 bytes
+
+#### Data Storage
+- **Slot Size**: Each slot accommodates 6 bytes of data.
+- **Alignment**: Ensures data slots are efficiently packed without fragmentation.
+
+This allocation strategy optimizes memory usage by dedicating 2 bytes to metadata per slot, leaving 6 bytes available for data storage.
+
 ### Error Handling
 
-Error handling mechanisms ensure graceful recovery from memory allocation failures (`mmap` failures) and address invalid access attempts with appropriate error messages.
+Error mechanisms do exists throughout the code and will raise exceptions/errors.
 
 ## 2. Organization & Class
 
 ### Description of Files, Classes and Key Components
 
-This project is organized using CMake.
+This project is built/organized using CMake.
 
 -   **Files**:
 	1.  **src/SmartArrayMemoryManager.cpp**: Implements the `MemoryManager` class with constructors and destructors.
@@ -93,17 +112,7 @@ The system supports scalability up to the initial number of virtual pages (`INIT
 
 ### Test Cases Overview
 
--   **Basic Functionality Tests**: Ensure proper allocation and access of slots.
--   **Conflict Resolution Tests**: Validate strategies for resolving conflicts during slot allocation.
--   **Edge Case Tests**: Test scenarios with maximum capacity, boundary conditions, and concurrent access.
-
-### Results and Observations
-
-Tests confirm the robustness and reliability of the smart array implementation, highlighting areas of improvement and additional testing needs.
-
-### Additional Tests for Robustness
-
-Recommendations for further testing to enhance robustness and validate performance under diverse conditions.
+-   The ``main.cpp`` file tests the basic functionality of the implemetation. Specifically tests for conflict resolution, memory management, and system robustness through a series of structured tests.
 
 ## 6. Conclusion