[Docs] Added OR messages glossary

[luarss]

Goal is to add OR error codes/warning codes to OR docs.

Todo

• Add in permalink to where you may find each
• How to add more value to the messages?

@vvbandeira @dralabeing @vijayank88

[luarss]

@vvbandeira Can I check if its okay to repeat the same code if they are different types?

e.g. DFT 0004

Error: https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/dft/src/clock_domain/ClockDomain.cpp#L52

Warning: https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/dft/src/cells/ScanCellFactory.cpp#L137

[maliberty]

No they should not repeat. Each message should be unique regardless of type

[vvbandeira]

Would it be too much of an inconvenience to do this in Python instead of shell? Then we could tightly integrate with the existing find_messages.py and avoid depending on temporary files.

[luarss]

@vvbandeira Yes, that's possible but i'm not sure if find_messages.py is being used by other parts of the codebase right now

[vvbandeira]

It is being used by CMake here. But you do not need to modify it I think, maybe you can just import it as a module.

[luarss]

@vvbandeira Added a prototype for getMessages.py. Its hacky but at least we generate one less temporary file

[dralabeing]

Goal is to add OR error codes/warning codes to OR docs.

Todo

• Add in permalink to where you may find each
• How to add more value to the messages?

@vvbandeira @dralabeing @vijayank88

permalink is very useful. We had also discussed making them actionable. What is the current plan for that?

[luarss]

@dralabeing We can do the following:

• Advice for some warnings/errors <- I am not an expert in EDA, so will need help in this
• Categorise nicely; i.e. create different sections & tables for different tools

Feel free to suggest more

[vvbandeira]

Marking it as a draft for now as we need to discuss a little more on the goals here.

---

@dralabeing I don't think making changes to the messages is in the scope of this PR or the work @luarss is doing.
The goal of this PR is to provide a way to grab the messages from the tools and add them to the docs automatically, we will define how tool developers should annotate their code to include in the docs, for example.

---

@luarss individual tables for each tool would indeed be nice, or you could just append them as a new section in the tool's README as a new section. Or we could have it as a separate file for each tool and add them in the toc as a subitem for each tool.

[dralabeing]

Marking it as a draft for now as we need to discuss a little more on the goals here.

@dralabeing I don't think making changes to the messages is in the scope of this PR or the work @luarss is doing. The goal of this PR is to provide a way to grab the messages from the tools and add them to the docs automatically, we will define how tool developers should annotate their code to include in the docs, for example.

@luarss individual tables for each tool would indeed be nice, or you could just append them as a new section in the tool's README as a new section. Or we could have it as a separate file for each tool and add them in the toc as a subitem for each tool.

Sounds good. It could be both right? table+ tool README. This would give the user multiple ways to track messages. However, open to suggestions however in terms of best ways to organize this.

[luarss]

@vvbandeira @dralabeing I have added a prototype for how a tool developer could potentially add additional user guidance in their respective repositories.

Key features

• createNewMsgs.sh: this will create "information" files in each tool dir (src/<tool>/doc/messages/xxxx.md) if it doesn't already exist
• getMessages.py: will look for these "information" file and place it the "Information" column. If no content, just put a "-"

Also, I realised a bug with the PR docs 1. We cannot see the file user/MessagesFinal.md right now because readthedocs does not actually do the compilation every time, it simply takes what is in the repo - parsed by conf.py. So we do have to include that file after all.

[luarss]

@vvbandeira Updated, now it looks like this

[vvbandeira]

This looks very good @luarss.
Let's replace the ant and cts placeholders with these two following messages from grt:

GRT 0118 GlobalRouter.cpp:331      Routing congestion too high. Check the congestion heatmap in the GUI.
GRT 0119 GlobalRouter.cpp:324      Routing congestion too high. Check the congestion heatmap in the GUI and load {} in the DRC viewer.

For these messages, we can point the user on how to open the GUI, reference a section in the Flow tutorial for example. We can also give suggestions such as trying to reduce the GPL density target.

[luarss]

Those aren't really placeholders. At least for some of them I think the deprecated keyword suggestion is useful to leave in?

Anyways, here's what I came up for GRT

[vvbandeira]

Those aren't really placeholders. At least for some of them I think the deprecated keyword suggestion is useful to leave in?

I think that these cts and ant are short enough to include in the message themselves. The main goal of the table and separated md files would be to add long descriptions with details, rich formatting and useful links that are "extra" and do not fit in the message context.

Anyways, here's what I came up for GRT

This looks great and is an example of the above. Here we can add the links to the GUI with the instructions. Later, other developers can add tips to users on which knobs to turn to avoid the error message.

---

FYI @maliberty, @vijayank88. We can start curating information that we often see in issues and discussions to add to the table. Congestion is a big one that I often see repeating in many places.

[luarss]

@vvbandeira Merge conflict is resolved, ready for review