Improve readmes

Author: suyashmahar

README.md

@@ -6,21 +6,23 @@ Heimdall is a benchmark suite to profile the heterogeneous memory systems, inclu
 
 ## Usage
 
+To install and use Heimdall, please follow these instructions. Currently, Heimdall is supported only on Ubuntu. Specifically, **2X.XX**. While it is possible to run the benchmarks on other platforms, that would require manually installing the dependencies.
+
 ### Install dependencies
 1. Clone the repo:  
       ```
       git clone 'https://github.com/awesome-cxl/heimdall.git' --recursive
       ```
 2. Install `uv` and `pre-commit`, e.g.:  
-      **pip**
+      <!-- **pip** -->
       ```
       pip install uv pre-commit
       ```
 
-      **MacOS**
+      <!-- **MacOS**
       ```
       brew install uv pre-commit
-      ```
+      ``` -->
 3. Activate the uv python environment and execute the heimdall command line.
       ```shell
       uv run heimdall --help

benchmark/basic_performance/README.md

@@ -1,103 +1,96 @@
 # Basic Performance
 
-## 1. Clone the code
+## 1. Configure the machine environment files
 
-```shell
-git clone --recurse-submodules git@github.com:awesome-cxl/heimdall.git
-```
-
-## 2. Make Environment files
-
-You need to define two env files:
-
-a. Make the user env file, ***`USER_PASSWORD` field is mandatory*** while other ones are optional
-
-```shell
-cd benchmark/basic_performance/env_files
-nano self_template.env
-mv self_template.env self.env
-```
+Heimdall needs two configuration files to understand the test environment:
 
-b. Make the machine's env file ***ALL fields are required in this file***
+1. Create the user configuration file, ***`USER_PASSWORD` field is mandatory*** while others are optional
+   ```shell
+   cd benchmark/basic_performance/env_files
+   nano self_template.env
+   mv self_template.env self.env
+   ```
 
-```shell
-cd benchmark/basic_performance/env_files
-nano machine_template.env
-mv machine_template.env {hostname}.env
-```
+2. Create the machine configuration file ***All fields are required in this file***
+   ```shell
+   cd benchmark/basic_performance/env_files
+   nano machine_template.env
+   mv machine_template.env $(hostname).env
+   ```
 
-if you don't know the hostname, you can use the following command to get it:
+## 2. [Recommended] Modify/create the test sciript
 
+Next, we will create tests script to configure the BW vs Latency and Cache Latency tests.
 
-```shell
-hostname
-```
-## 3. [Recommended] Modify/make the test sciript
+### Bandwidth vs Latency Test
 
-For bandwidth vs latency test
+Configure the bandwidth vs latency test script:
 
  ```bash
  cd benchmark/basic_performance/scripts/batch
- nano 100_{your test script}.yaml or reuse previous one 100_bw_vs_latency.yaml, etc..
+ nano 100_{your test script}.yaml # or reuse previous one 100_bw_vs_latency.yaml, etc..
  ```
- 1. Thread number & Thread number type configuration:
-    - 'thread_num_type':
+
+ **Fields**
+
+ 1. Thread number & Thread number type configuration:  
+    - `thread_num_type`:
       - `0`: user defined thread number, specify the thread number in `thread_num_array`
       - `1`: auto detect thread number, in this mode, thread number will be detected automatically and sweep the thread number from 1 to the detected thread number
-   - 'thread_num_array':
+    - `thread_num_array`:
       - Specify how many thread to use in the test
       - **Warning**: Don't overflow the number of cores in the machine
-      - Example: In this case, we change the thread number from 1 to 3 and conduct the test
+      - **Example**: In this case, we sweep the thread count between 1 and 3 and run the test
        ```yaml
        thread_num_array: [1, 2, 3]
        ```
  2. `pattern_iteration_array` configuration:
     - specify how many time iteration to run the random pointer chasing
  3. `thread_buffer_size` array_megabyte configuration:
     - specify the buffer size for each thread
- 4. numa_node_array configuration:
-    1. specify the numa node to use
- 5. core_socket_array configuration:
-    1. specify the core to use
+ 4. `numa_node_array` configuration:
+    - specify the numa node to use
+ 5. `core_socket_array` configuration:
+    - specify the core to use
  6. `loadstore_array` configuration:
     - `0`: load
     - `1`: store
 
-For cache analysis test
+### Cache Analysis Test
 
 ```bash
  cd benchmark/basic_performance/scripts/batch
- nano 200_{your test script}.yaml or reuse previous one 200_cache_heatmap.yaml
+ nano 200_{your test script}.yaml # or reuse 200_cache_heatmap.yaml
 ```
 
-## 4. Start the test
+## 3. Start the test
 
-For bandwidth vs latency test
+For the bandwidth vs latency test
 
 ```bash
-cd {top directory}
+cd ${HEIMDALL_ROOT}
 uv run heimdall bench build basic bw
 uv run heimdall bench run basic bw
 ```
 
-For cache analysis test
+For the cache analysis test
 
 ```bash
-cd {top directory}
+cd ${HEIMDALL_ROOT}
 uv run heimdall bench build basic cache
 uv run heimdall bench run basic cache
 ```
 
-## 5. Check the result
+## 4. Check the result
 
-For bandwidth vs latency test
+For the bandwidth vs latency test
 
 ```bash
-cd {top directory}/results/basic_performance/100
+cd ${HEIMDALL_ROOT}/results/basic_performance/100
 ```
 
-For cache analysis test
+For the cache analysis test
 
 ```bash
-cd {top directory}/results/basic_performance/200
+cd ${HEIMDALL_ROOT}/results/basic_performance/200
 ```

benchmark/lockfree_bench/README.md

@@ -2,23 +2,20 @@
 
 ## Usage
 
-Install dependencies:
-
-```shell
-USER_PASSWORD=password uv run heimdall bench install lockfree all
-```
-
-Build benchmark
-
-```shell
-USER_PASSWORD=password uv run heimdall bench build lockfree all
-```
-
-Run benchmark
-
-```shell
-USER_PASSWORD=password uv run heimdall bench run lockfree <machine_name>
-```
+1. Install dependencies:
+    ```shell
+    USER_PASSWORD=password uv run heimdall bench install lockfree all
+    ```
+
+2. Build benchmark
+    ```shell
+    USER_PASSWORD=password uv run heimdall bench build lockfree all
+    ```
+
+3. Run benchmark
+    ```shell
+    USER_PASSWORD=password uv run heimdall bench run lockfree <machine_name>
+    ```
 
 Before running the benchmark, please add configuration of the machine in `run_bench.py`. The configuration is stored in map `numa_configs`. The key is the `machine_name` in running command. Values' meaning is in the comment of the map.