lowRISC / lowRISC/ibex

[tracking] Use Verible's verilog_format for code formatting

Open
#687 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Component:Tool-and-Build Type:Enhancement
Dominant language
SystemVerilog
Stars
2.1k
Forks
810
Avg merge
5d 23h
Merged PRs (30d)
9

Description

Verible's verilog_format is a automatic code formatter. We want to be able to run it on our code base, ultimately in "enforcing" mode, requiring all submissions to be formatted with this tool. This is the same approach we take with clang-format and C/C++ files. This issue is to track the progress towards that.

Ibex TODO:
- [x] Add Verible format support to edalize: https://github.com/olofk/edalize/pull/120
- [x] Add a fusesoc target to our core files: #686
- [x] Add Verible format in non-enforcing mode to CI: #686
- [ ] Document how to use it
- [ ] Clean up existing code once the auto-formatted style matches our expectations.
- [ ] Switch to enforcing mode.

Bugs crashing the formatter:
- [ ] "Some token partitions failed to complete within the search limit" https://github.com/google/verible/issues/346
- [ ] "Formatted output is lexically different from the input" (Mismatched token enums.): https://github.com/google/verible/issues/347

Wrong style produced by the formatter according to the [lowRISC style guide](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md):
- [ ] Use two space indents for port and parameter lists: https://github.com/google/verible/issues/40
- [ ] Indentation of initializer lists: https://github.com/google/verible/issues/352
- [ ] Comment in assign statement breaks indentation: https://github.com/google/verible/issues/353

Verible formatter style/readability issues and optional issues:
- [ ] https://github.com/google/verible/issues/228. Workaround for one specific case proposed in https://github.com/lowRISC/ibex/pull/693 to remove the blocking status of this, given that a full solution on the Verible side will take longer.
- [ ] Continue comments in port lists: https://github.com/google/verible/issues/349
- [ ] Line up comments in port lists: https://github.com/google/verible/issues/350
- [ ] Closing parenthesis on its own line: https://github.com/google/verible/issues/351
- [ ] Align assignment expressions: https://github.com/google/verible/issues/357
- [ ] Align variable declarations: https://github.com/google/verible/issues/358
- [ ] Keep condition and `?` together in ternaries: https://github.com/google/verible/issues/359
- [ ] Align nested ternaries: https://github.com/google/verible/issues/360
- [ ] Avoid whitespace in bit-selection: https://github.com/google/verible/issues/361

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

Start with the unchecked items in this tracking issue, reviewing the existing fusesoc and CI work in #686 and the workaround discussed in pull request #693. Check the linked Verible formatter issues and the lowRISC VerilogCodingStyle guide before changing formatting. Done means the documented formatter workflow, cleaned-up code, and enforcing CI mode match the agreed style and no listed blocker remains.

Written by the indexing model from the issue text.

Assessment

Domain
ci-cd, documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.