lowRISC / lowRISC/opentitan

[doc] Hjson Usage and Style Guide says integers with commas aren't allowed. Clarify?

Open
#22,626 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
SystemVerilog
Stars
3.6k
Forks
1.1k
Avg merge
2d 22h
Merged PRs (30d)
141

Description

https://github.com/lowRISC/opentitan/blob/a5f70f43bdd063877d68dbe81ef38a9acccca9ae/doc/contributing/style_guides/hjson_usage_style.md?plain=1#L118-L121

This isn't true; `tag: 2, ...` in hjson will define the field `tag` as the numeric value `2` and continue parsing other fields (whereas `tag: "2"` will make it the string `"2"`, with a similar effect but with type string rather than numeric).
On the other hand, `tag: 0x2, ...` will be interpreted as an unquoted string and "consume" the rest of the line since `0x2` is not a valid number format recognized by JSON, so the note of caution would apply there.

```python
>>> hjson.loads('''{ name: "fred", tag: 2, desc: "fred has tag 2" }''')
OrderedDict([('name', 'fred'), ('tag', 2), ('desc', 'fred has tag 2')])
>>> hjson.loads('''{ name: "fred", tag: "2", desc: "fred has tag 2" }''')
OrderedDict([('name', 'fred'), ('tag', '2'), ('desc', 'fred has tag 2')])
```

Does OpenTitan require strings in all "scalar" fields in hjson files? The documentation (for example [util/reggen/README.md](https://github.com/lowRISC/opentitan/blob/a5f70f43bdd063877d68dbe81ef38a9acccca9ae/util/reggen/README.md#configuration-and-register-definition-file-format)) doesn't make this clear, and explicitly states that certain fields are of type "int" (but they seem to be hjson strings containing an integer).
If this is the case, maybe it should be clarified somewhere that hjson files in OpenTitan use strings only, and not hjson numeric/boolean values.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read doc/contributing/style_guides/hjson_usage_style.md around lines 118-121 and util/reggen/README.md under the configuration and register definition format section. Verify the documented scalar-value rules against the examples in the issue, then clarify the guidance so integer formatting and the expected types for OpenTitan Hjson fields are unambiguous.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.