feat(generators/markdown): add show_hardware_mode option

Author: esynr3z

schemas/corsair-build-schema.json

@@ -80,6 +80,12 @@
           "title": "Show Disclaimer",
           "type": "boolean"
         },
+        "show_hardware_mode": {
+          "default": false,
+          "description": "Enable showing hardware mode for each field.",
+          "title": "Show Hardware Mode",
+          "type": "boolean"
+        },
         "wavedrom": {
           "$ref": "#/$defs/corsair___generators__wavedrom__WaveDromGenerator__Config",
           "default": {

src/corsair/_generators/markdown.py

@@ -42,6 +42,9 @@ class Config(GeneratorConfig):
         show_disclaimer: bool = True
         """Enable generating disclaimer with version at the beginning of the file."""
 
+        show_hardware_mode: bool = False
+        """Enable showing hardware mode for each field."""
+
         wavedrom: WaveDromGenerator.Config = WaveDromGenerator.Config()
         """Configuration for the WaveDrom generator."""
 

src/corsair/_templates/regmap.md.j2

@@ -41,6 +41,21 @@ Generated by [Corsair](https://github.com/esynr3z/corsair) v{{ version }}.
 | WOSC | Write Only / Self Clear |
 {% endif %}
 
+{% if cfg.show_hardware_mode %}
+| Hardware mode | Description |
+| :--- | :--- |
+| i | Use input value from hardware to update the field |
+| o | Enable output value from the field to be accessed by hardware |
+| c | Add signal to clear the field (fill with all zeros) |
+| s | Add signal to set the field (fill with all ones) |
+| e | Add signal to enable the field to capture input value (used with i) |
+| l | Add signal to lock the field (to prevent any changes) |
+| a | Add signals to notify when bus access to the field is performed (at the same cycle) |
+| q | Add simple interface to external queue (LIFO, FIFO) |
+| f | Enable fixed mode (field is a constant) |
+| n | Not accessible by hardware |
+{% endif %}
+
 ## Register map summary
 
 **Base address:** {{ literal(regmap.base_address, regmap.address_width) }}
@@ -69,10 +84,10 @@ Generated by [Corsair](https://github.com/esynr3z/corsair) v{{ version }}.
 ![{{ reg.name.lower()}}]({{ cfg.image_dir }}/{{regmap.name.lower()}}_{{ reg.name.lower()}}.svg)
 
     {% endif %}
-| Name | Bits | Mode | Reset | Description |
-| :--- | :--- | :--- | :--- | :--- |
+| Name | Bits | Access {%- if cfg.show_hardware_mode %} | Hardware {%- endif %} | Reset | Description |
+| :--- | :--- | :--- {%- if cfg.show_hardware_mode %} | :--- {%- endif %} | :--- | :--- |
     {% for bf in reg.fields_with_reserved[::-1] %}
-| {{ "-" if bf.name.startswith("_reserved") else bf.name.upper() }} | {{ range(bf.msb, bf.lsb) }} | {{ bf.access.value.upper() }} | {{ "X" if bf.reset == None else literal(bf.reset, bf.width) }} | {{ bf.doc | replace('\n', '<br>')  }} |
+| {{ "-" if bf.name.startswith("_reserved") else bf.name.upper() }} | {{ range(bf.msb, bf.lsb) }} | {{ bf.access.value.upper() }} {%- if cfg.show_hardware_mode %} | {{ bf.hardware.value.lower() }} {%- endif %} | {{ "X" if bf.reset == None else literal(bf.reset, bf.width) }} | {{ bf.doc | replace('\n', '<br>')  }} |
     {% endfor %}
 
     {% for bf in reg.fields %}

tests/generators/test_markdown.py

@@ -279,6 +279,35 @@ def test_show_disclaimer_false(tmp_path: Path, simple_regmap: csr.Map) -> None:
     assert "Generated by [Corsair]" not in content
 
 
+def test_show_hardware_mode_true(tmp_path: Path, simple_regmap: csr.Map) -> None:
+    """Test that hardware mode conventions and column are present when show_hardware_mode is True."""
+    config = csr.MarkdownGenerator.Config(show_hardware_mode=True)
+    gen = csr.MarkdownGenerator(
+        label="test_md_gen_hw_mode_true", register_map=simple_regmap, config=config, output_dir=tmp_path
+    )
+    generated_files = list(gen())
+    output_file = generated_files[0]
+    content = output_file.read_text()
+    assert "## Conventions" in content  # Assuming conventions are shown by default or with hardware mode
+    assert "| Hardware mode | Description |" in content
+    assert "| Hardware |" in content  # Check for the column in the fields table
+
+
+def test_show_hardware_mode_false(tmp_path: Path, simple_regmap: csr.Map) -> None:
+    """Test that hardware mode conventions and column are absent when show_hardware_mode is False."""
+    config = csr.MarkdownGenerator.Config(show_hardware_mode=False)
+    gen = csr.MarkdownGenerator(
+        label="test_md_gen_hw_mode_false", register_map=simple_regmap, config=config, output_dir=tmp_path
+    )
+    generated_files = list(gen())
+    output_file = generated_files[0]
+    content = output_file.read_text()
+    # Assuming default of show_conventions=True, so "## Conventions" might still be there
+    # We specifically check for the *hardware mode* conventions table
+    assert "| Hardware mode | Description |" not in content
+    assert "| Hardware |" not in content  # Check for the column in the fields table
+
+
 def test_custom_template_and_extra_param(tmp_path: Path, simple_regmap: csr.Map, custom_template: Path) -> None:
     """Test generation with a custom template and extra config parameters."""
     template_file = custom_template