From 531d0001b1d2502b1aeed414c08d0ce9de7fb39f Mon Sep 17 00:00:00 2001
From: Adrian Stanea <Adrian.Stanea@analog.com>
Date: Tue, 6 Aug 2024 10:20:24 +0300
Subject: [PATCH] tests/iio_diff: add documentation and usage instructions

Signed-off-by: Adrian Stanea <Adrian.Stanea@analog.com>
---
 tests/README.md          |  6 +++++-
 tests/iio_diff/README.md | 45 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 tests/iio_diff/README.md

diff --git a/tests/README.md b/tests/README.md
index 84643122..efb50c83 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -30,4 +30,8 @@ To repeat a test, add the @repeat(times) decorator before the test to be repeate
  
  Ex: <br>
 ```    @repeat(50)``` <br>
-```    def test_2_calibration(self):```
\ No newline at end of file
+```    def test_2_calibration(self):```
+
+### iio_diff
+
+The directory contains utilities for storing iio state in xml format: ```xml_generator.py```, as well as an utility used to compare common, new and missing attributes: ```iio_diff.py```.
\ No newline at end of file
diff --git a/tests/iio_diff/README.md b/tests/iio_diff/README.md
new file mode 100644
index 00000000..b390951d
--- /dev/null
+++ b/tests/iio_diff/README.md
@@ -0,0 +1,45 @@
+# iio-diff
+
+## Prerequisites
+
+Before running the scripts in this project, make sure that the Python bindings for libiio **(pylibiio)** are properly installed on your system. For installation instructions and additional information refer to the [official wiki page](https://wiki.analog.com/resources/tools-software/linux-software/pyadi-iio)
+
+## XML generation: `xml_generator.py`
+
+The xml_generator.py script generates an XML representation of the current libiio context.
+
+
+- Stores the current libiio context in XML format.
+- By default, the resulting XML file is stored in a `./results` directory relative to the path where xml_generator.py is located. The directory is created if it does not exist.
+
+Usage example:
+```bash
+python3 xml_generator.py \
+    --uri ip:192.168.2.1 \
+    --filename v0_XX.xml
+```
+
+## Compare iio state: `iio_diff.py`
+
+The `iio_diff.py` script compares a reference context with a target context using XML files. It identifies and highlights the differences between the two contexts:
+
+- **Common Attributes**: Attributes present in both the reference and target contexts.
+New Attributes: Attributes added in the target context but not present in the reference context.
+- **Missing Attributes**: Attributes present in the reference context but missing in the target context.
+- **Note**: The reference context can be compared against a target context loaded from an XML file or by providing a URI to a connected board.
+
+The `iio_diff.py` script is designed to compare a reference context and a target context using XML files.
+
+
+Usage:
+```bash
+# Target context created from a URI
+python3 iio_diff.py \
+        --reference_file ./results/v0_32.xml \
+        --uri ip:192.168.2.2    
+
+# Target context created from an XML file
+python3 iio_diff.py \
+        --reference_file ./results/v0_32.xml \
+        --target_file  ./results/v0_31.xml
+```
\ No newline at end of file