Merge pull request #212 from riscv/org-param-app-by-ch

Organize params by chapter.

Author: james-ball-qualcomm

Makefile

@@ -40,9 +40,12 @@ CREATE_PARAMS_TOOL := $(TOOLS_DIR)/create_params.py
 CREATE_PARAMS_PYTHON := python3 $(CREATE_PARAMS_TOOL)
 CREATE_PARAM_ADOC_FILES_TOOL := $(TOOLS_DIR)/create_param_appendix.py
 CREATE_PARAM_ADOC_FILES_PYTHON := python3 $(CREATE_PARAM_ADOC_FILES_TOOL)
-PARAM_ADOC_TEST_SCRIPT := $(PARAMS_TESTS_DIR)/test_param_appendix.py
-PARAM_ADOC_TEST_PYTHON := python3 $(PARAM_ADOC_TEST_SCRIPT)
-PARAMS_ADOC_TEMPLATE := $(PARAMS_TESTS_DIR)/test-param-appendix-template.adoc
+PARAMS_ADOC_SOURCE := $(PARAMS_TESTS_DIR)/test-param-appendix.adoc
+PARAM_TABLE_SCHEMA_INPUT := $(TOOLS_DIR)/default_param_table.yaml
+PARAM_TABLE_VARIANT_FILES := \
+	$(PARAMS_TESTS_DIR)/test-param-table-full-default.yaml \
+	$(PARAMS_TESTS_DIR)/test-param-table-reordered.yaml \
+	$(PARAMS_TESTS_DIR)/test-param-table-minimal.yaml
 
 # Stuff for building test standards document in HTML to have links into it.
 DOCS = test-ch1 test-ch2
@@ -88,6 +91,8 @@ BUILT_PARAMS_HTML := $(BUILD_DIR)/$(PARAMS_HTML_OUTPUT_FNAME)
 BUILT_PARAM_ADOC_DIR := $(BUILD_DIR)/test-param-appendix-adoc-includes
 BUILT_PARAM_ADOC_STAMP := $(BUILD_DIR)/test-param-adoc.done
 BUILT_PARAMS_ADOC := $(BUILD_DIR)/test-param-appendix.adoc
+BUILT_PARAM_TABLE_VARIANTS_DIR := $(BUILD_DIR)/test-param-table-variants
+BUILT_PARAM_TABLE_VARIANTS_STAMP := $(BUILD_DIR)/test-param-table-variants.done
 
 # Combine separate fnames into lists.
 BUILT_TEST_HTML_FNAMES := $(BUILT_TEST_CH1_HTML_FNAME) $(BUILT_TEST_CH2_HTML_FNAME)
@@ -103,6 +108,7 @@ EXPECTED_PARAMS_JSON := $(PARAMS_EXPECTED_DIR)/$(PARAMS_JSON_OUTPUT_FNAME)
 EXPECTED_PARAMS_HTML := $(PARAMS_EXPECTED_DIR)/$(PARAMS_HTML_OUTPUT_FNAME)
 EXPECTED_PARAMS_ADOC := $(PARAMS_EXPECTED_DIR)/test-param-appendix.adoc
 EXPECTED_PARAM_ADOC_DIR := $(PARAMS_EXPECTED_DIR)/test-param-appendix-adoc-includes
+EXPECTED_PARAM_TABLE_VARIANTS_DIR := $(PARAMS_EXPECTED_DIR)/test-param-table-variants
 
 # Normative rule definition input YAML files.
 GOOD_NORM_RULE_DEF_FILES := $(NORM_RULE_DEF_DIR)/test-ch1.yaml $(NORM_RULE_DEF_DIR)/test-ch2.yaml
@@ -193,19 +199,20 @@ all: test
 test: build-tests compare-tests test-tag-changes test-adoc2html test-shared-utils test-text-to-html
 
 # Build tests
-.PHONY: build-tests build-test-tags build-test-norm-rules-json build-test-norm-rules-html build-test-tags-without-rules build-test-params-json build-test-params-html build-test-param-adoc
-build-tests: build-test-tags build-test-norm-rules-json build-test-norm-rules-html build-test-tags-without-rules build-test-params-json build-test-params-html build-test-param-adoc
+.PHONY: build-tests build-test-tags build-test-norm-rules-json build-test-norm-rules-html build-test-tags-without-rules build-test-params-json build-test-params-html build-test-param-adoc build-test-param-table-variants
+build-tests: build-test-tags build-test-norm-rules-json build-test-norm-rules-html build-test-tags-without-rules build-test-params-json build-test-params-html build-test-param-adoc build-test-param-table-variants
 build-test-tags: $(BUILT_TEST_NORM_TAGS_FNAMES) $(BUILT_DUPLICATE_NORM_TAGS_FNAME)
 build-test-norm-rules-json: $(BUILT_NORM_RULES_JSON)
 build-test-norm-rules-html: $(BUILT_NORM_RULES_HTML)
 build-test-tags-without-rules: $(BUILT_NORM_RULES_TAGS_NO_RULES)
 build-test-params-json: $(BUILT_PARAMS_JSON)
 build-test-params-html: $(BUILT_PARAMS_HTML)
 build-test-param-adoc: $(BUILT_PARAM_ADOC_STAMP)
+build-test-param-table-variants: $(BUILT_PARAM_TABLE_VARIANTS_STAMP)
 
 # Compare tests against expected
 .PHONY: compare-tests
-compare-tests: compare-test-tags compare-test-norm-rules-json compare-test-norm-rules-html compare-test-params-json compare-test-params-html compare-test-params-adoc compare-test-param-adoc-files
+compare-tests: compare-test-tags compare-test-norm-rules-json compare-test-norm-rules-html compare-test-params-json compare-test-params-html compare-test-params-adoc compare-test-param-adoc-files compare-test-param-table-variants
 
 .PHONY: compare-test-tags
 compare-test-tags: compare-test-ch1-tags compare-test-ch2-tags
@@ -250,6 +257,11 @@ compare-test-param-adoc-files: $(EXPECTED_PARAM_ADOC_DIR) $(BUILT_PARAM_ADOC_DIR
 	@echo "CHECKING GENERATED PARAM ADOC FILES AGAINST EXPECTED"
 	diff -r $(EXPECTED_PARAM_ADOC_DIR) $(BUILT_PARAM_ADOC_DIR) && echo "diff PASSED" || (echo "diff FAILED"; exit 1)
 
+.PHONY: compare-test-param-table-variants
+compare-test-param-table-variants: $(EXPECTED_PARAM_TABLE_VARIANTS_DIR) $(BUILT_PARAM_TABLE_VARIANTS_DIR)
+	@echo "CHECKING PARAM TABLE VARIANT OUTPUTS AGAINST EXPECTED"
+	diff -r $(EXPECTED_PARAM_TABLE_VARIANTS_DIR) $(BUILT_PARAM_TABLE_VARIANTS_DIR) && echo "diff PASSED" || (echo "diff FAILED"; exit 1)
+
 # Test tag change detection
 .PHONY: test-tag-changes test-tag-changes-basic test-tag-changes-verbose test-tag-changes-no-changes test-tag-changes-additions-only test-tag-changes-whitespace-only test-tag-changes-formatting-only test-tag-changes-update
 test-tag-changes: test-tag-changes-basic test-tag-changes-verbose test-tag-changes-no-changes test-tag-changes-additions-only test-tag-changes-whitespace-only test-tag-changes-formatting-only test-tag-changes-update
@@ -318,7 +330,7 @@ test-tag-text-to-html-unit: $(TAG_TEXT_TO_HTML_UNIT_TEST_SCRIPT) $(TOOLS_DIR)/ta
 
 # Update expected files from built files
 .PHONY: update-expected
-update-expected: update-test-tags update-test-norm-rules-json update-test-norm-rules-html update-test-params-json update-test-params-html update-test-params-adoc update-test-param-adoc-files
+update-expected: update-test-tags update-test-norm-rules-json update-test-norm-rules-html update-test-params-json update-test-params-html update-test-params-adoc update-test-param-adoc-files update-test-param-table-variants
 
 .PHONY: update-test-tags
 update-test-tags: update-test-ch1-tags update-test-ch2-tags
@@ -357,8 +369,12 @@ update-test-params-adoc: $(BUILT_PARAMS_ADOC)
 .PHONY: update-test-param-adoc-files
 update-test-param-adoc-files: $(BUILT_PARAM_ADOC_DIR)
 	rm -rf $(EXPECTED_PARAM_ADOC_DIR)
-	mkdir -p $(EXPECTED_PARAM_ADOC_DIR)
-	cp -f $(BUILT_PARAM_ADOC_DIR)/*.adoc $(EXPECTED_PARAM_ADOC_DIR)
+	cp -r $(BUILT_PARAM_ADOC_DIR) $(EXPECTED_PARAM_ADOC_DIR)
+
+.PHONY: update-test-param-table-variants
+update-test-param-table-variants: $(BUILT_PARAM_TABLE_VARIANTS_DIR)
+	rm -rf $(EXPECTED_PARAM_TABLE_VARIANTS_DIR)
+	cp -r $(BUILT_PARAM_TABLE_VARIANTS_DIR) $(EXPECTED_PARAM_TABLE_VARIANTS_DIR)
 
 # Build normative tags with ch1 adoc input
 $(BUILT_TEST_CH1_NORM_TAGS_FNAME): $(NORM_RULE_TESTS_DIR)/$(TEST_CH1_INPUT_ADOC_FNAME) $(CONVERTERS_DIR)/$(TAGS_BACKEND)
@@ -401,16 +417,24 @@ $(BUILT_PARAMS_HTML): $(BUILT_NORM_RULES_JSON) $(PARAM_DEF_TEST_FILES) $(CREATE_
 	$(WORKDIR_TEARDOWN)
 
 # Build parameter AsciiDoc row fragments from generated params JSON.
-$(BUILT_PARAM_ADOC_STAMP): $(BUILD_DIR)/$(PARAMS_JSON_OUTPUT_FNAME) $(CREATE_PARAM_ADOC_FILES_TOOL) $(PARAM_ADOC_TEST_SCRIPT) $(PARAMS_ADOC_TEMPLATE)
+$(BUILT_PARAM_ADOC_STAMP): $(BUILD_DIR)/$(PARAMS_JSON_OUTPUT_FNAME) $(CREATE_PARAM_ADOC_FILES_TOOL) $(PARAMS_ADOC_SOURCE) $(PARAM_TABLE_SCHEMA_INPUT)
 	$(WORKDIR_SETUP)
 	cp -f $(BUILD_DIR)/$(PARAMS_JSON_OUTPUT_FNAME) $@.workdir/$(BUILD_DIR)
-	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_PARAM_ADOC_FILES_PYTHON) --input $(BUILD_DIR)/$(PARAMS_JSON_OUTPUT_FNAME) --output-dir $(BUILT_PARAM_ADOC_DIR) && touch $(BUILT_PARAM_ADOC_STAMP) $(DOCKER_QUOTE)
-	$(DOCKER_CMD) $(DOCKER_QUOTE) $(PARAM_ADOC_TEST_PYTHON) --template $(PARAMS_ADOC_TEMPLATE) --adoc-dir $(BUILT_PARAM_ADOC_DIR) --output $(BUILT_PARAMS_ADOC) $(DOCKER_QUOTE)
+	cp -f $(PARAMS_ADOC_SOURCE) $@.workdir/$(BUILT_PARAMS_ADOC)
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_PARAM_ADOC_FILES_PYTHON) --input $(BUILD_DIR)/$(PARAMS_JSON_OUTPUT_FNAME) --param-table $(PARAM_TABLE_SCHEMA_INPUT) --output-dir $(BUILT_PARAM_ADOC_DIR) && touch $(BUILT_PARAM_ADOC_STAMP) $(DOCKER_QUOTE)
 	rm -rf $(BUILT_PARAM_ADOC_DIR)
 	mv $@.workdir/$(BUILT_PARAM_ADOC_DIR) $(BUILT_PARAM_ADOC_DIR)
 	mv $@.workdir/$(BUILT_PARAMS_ADOC) $(BUILT_PARAMS_ADOC)
 	$(WORKDIR_TEARDOWN)
 
+$(BUILT_PARAM_TABLE_VARIANTS_STAMP): $(BUILD_DIR)/$(PARAMS_JSON_OUTPUT_FNAME) $(CREATE_PARAM_ADOC_FILES_TOOL) $(PARAM_TABLE_VARIANT_FILES)
+	$(WORKDIR_SETUP)
+	cp -f $(BUILD_DIR)/$(PARAMS_JSON_OUTPUT_FNAME) $@.workdir/$(BUILD_DIR)
+	$(DOCKER_CMD) $(DOCKER_QUOTE) set -e; rm -rf $(BUILT_PARAM_TABLE_VARIANTS_DIR); mkdir -p $(BUILT_PARAM_TABLE_VARIANTS_DIR); for f in $(PARAM_TABLE_VARIANT_FILES); do stem=$$(basename $$f .yaml); python3 $(CREATE_PARAM_ADOC_FILES_TOOL) --input $(BUILD_DIR)/$(PARAMS_JSON_OUTPUT_FNAME) --param-table $$f --output-dir $(BUILT_PARAM_TABLE_VARIANTS_DIR)/$$stem; done; touch $(BUILT_PARAM_TABLE_VARIANTS_STAMP) $(DOCKER_QUOTE)
+	rm -rf $(BUILT_PARAM_TABLE_VARIANTS_DIR)
+	mv $@.workdir/$(BUILT_PARAM_TABLE_VARIANTS_DIR) $(BUILT_PARAM_TABLE_VARIANTS_DIR)
+	$(WORKDIR_TEARDOWN)
+
 # Build normative rules with HTML output format
 $(BUILT_NORM_RULES_HTML): $(BUILT_TEST_NORM_TAGS_FNAMES) $(GOOD_NORM_RULE_DEF_FILES) $(BUILT_TEST_HTML_FNAMES)
 	$(WORKDIR_SETUP)

schemas/param-table-schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Schema for parameter table layout files",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional path/URI to this schema"
+    },
+    "columns": {
+      "type": "array",
+      "description": "Ordered list of parameter columns from left to right",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Display name of the column"
+          },
+          "column": {
+            "type": "string",
+            "description": "Canonical column identifier",
+            "enum": [
+              "PARAM_NAME_AND_NORM_RULE_MAPPING",
+              "TYPE",
+              "FEATURES",
+              "DEFINITION"
+            ]
+          },
+          "width_pct": {
+            "type": "number",
+            "exclusiveMinimum": 0,
+            "maximum": 100,
+            "description": "Percentage of total table width allocated to this column"
+          }
+        },
+        "required": ["name", "column", "width_pct"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["columns"],
+  "additionalProperties": false
+}

tests/params/expected/test-param-appendix-adoc-includes/all_params_a_to_z.adoc

@@ -0,0 +1,33 @@
+.Parameter Definitions (A-Z): 25 Parameters
+[cols="30%,10%,10%,50%"]
+|===
+
+| Parameter and Mapping to Normative Rules | Type | Feature(s) | Definition
+
+include::test-ch1/ALL_BASES.adoc[]
+include::test-ch2/ASIDLEN1.adoc[]
+include::test-ch2/ASIDLEN2.adoc[]
+include::test-ch2/BASE_RV32I.adoc[]
+include::test-ch2/BASE_RV32I_RV64I.adoc[]
+include::test-ch1/BIT.adoc[]
+include::test-ch1/BOOLEAN.adoc[]
+include::test-ch1/BYTE.adoc[]
+include::test-ch1/DWORD.adoc[]
+include::test-ch2/FOOBAR.adoc[]
+include::test-ch1/HWORD.adoc[]
+include::test-ch1/INT64.adoc[]
+include::test-ch1/LIST_INT.adoc[]
+include::test-ch1/LIST_STR.adoc[]
+include::test-ch2/MOCK_CSR_FIELD_Y.adoc[]
+include::test-ch2/MOCK_CSR_X.adoc[]
+include::test-ch2/MOCK_EXT_DEP_A_ON_B.adoc[]
+include::test-ch2/MOCK_INST_X.adoc[]
+include::test-ch2/NO_IMPL_DEF.adoc[]
+include::test-ch2/ROSE_COLORS.adoc[]
+include::test-ch1/UINT32.adoc[]
+include::test-ch1/UINT6.adoc[]
+include::test-ch1/UINT_1TO100.adoc[]
+include::test-ch1/WORD.adoc[]
+include::test-ch2/XLEN.adoc[]
+
+|===

tests/params/expected/test-param-appendix-adoc-includes/all_params_by_chapter.adoc

@@ -0,0 +1,19 @@
+.Chapter One Parameter Definitions: 13 Parameters
+[cols="30%,10%,10%,50%"]
+|===
+
+| Parameter and Mapping to Normative Rules | Type | Feature(s) | Definition
+
+include::test-ch1/all_params.adoc[]
+
+|===
+
+.Chapter Two Parameter Definitions: 12 Parameters
+[cols="30%,10%,10%,50%"]
+|===
+
+| Parameter and Mapping to Normative Rules | Type | Feature(s) | Definition
+
+include::test-ch2/all_params.adoc[]
+
+|===