Software for peripheral registers documentation - Page 1
Forum section: electronics / general

author: hcglitte
author_rank: Regular Contributor
timestamp: November 02, 2017, 09:23:10 pm
content: Hi,I was wondering if there exists some SW for documenting the bit fields in registers.It would be nice to have this available for documenting various registers for a communication protocol for instance.Then it could be exported to pdf or something and be rendered beautifully.It's tedious to use tables in MS word etc.Does something like this exist?

author: dgtl
author_rank: Regular Contributor
timestamp: November 03, 2017, 12:06:01 am
content: ARM based microcontrollers use SVD file (xml based) to describe registers; debuggers like Eclipse GDB plugin read the SVD and can then nicely present the register space in GUI. Perhaps there are some tools based on that? As a last resort, one can apply xslt transform to this xml file to format it to HTML. If this is better than msword tables, I'm not sure.I'm doing technical documentation for my projects in tex. The plain text files reside in version control alongside source code; they are transformed to pdf when building the project. Importing other files is used to keep the files short and structured. Works for me. A lot of automatic documentation generation systems ie doxygen generate their stuff in tex and then transform to pdf, btw. In case of library API, sometimes it makes sense to auto-generate that and then add the textual paragraphs on to that.

author: westfw
author_rank: Super Contributor
timestamp: November 03, 2017, 04:47:50 am
content: Atmel AVRs also produce their .h files from some sort of .XML file. There's at least one tool (in python) that generates .h files in other formats, from the Atmel XML. (um...https://spaces.microchip.com/gf/project/altheadergen/)Using XML to describe protocol packet formats as well is an interesting idea.I think the Ada folk (the language, not Adafruit!) have some tools for generating Ada data structure descriptions from C/C++ header flles; it might be useful as well...https://www.adacore.com/gems/gem-59?

author: andyturk
author_rank: Frequent Contributor
timestamp: November 03, 2017, 06:04:23 am
content: LaTeX is good for this, if you don't mind hard-core tools. Writing a document in LaTeX is a lot like programming. Thebytefieldmakes nice looking data structures. You can also use fancier tools likegraphviz.Here's a small (sanitized) example using bytefield and tables:

author: hcglitte
author_rank: Regular Contributor
timestamp: November 04, 2017, 09:07:04 am
content: It's been some time since I used LaTeX, but I will do a refresh. graphviz looks like a nice program for various things, will definitely use that for FSM etc! Thanks to all of you for your replies.

author: westfw
author_rank: Super Contributor
timestamp: November 05, 2017, 06:31:45 am
content: I may not have explained my XML-related comments well enough. I was figuring that a program capable of generating .h output from a .xml input is only a SMOP away from generating documentation in your choice of text-formatting "language." (LaTex sounds good for "real" documentation, but HTML or MDL would be possible as well.

author: nctnico
author_rank: Super Contributor
timestamp: November 05, 2017, 03:29:42 pm
content: I always use Word. It is a tedious job to do well (IOW: explaining what each bit does and how it all works together).

author: andyturk
author_rank: Frequent Contributor
timestamp: November 06, 2017, 03:45:08 am
content: Quote from: nctnico on November 05, 2017, 03:29:42 pmOh, ouch.

author: FrankBuss
author_rank: Unknown
timestamp: November 06, 2017, 04:25:17 am
content: If you have a SVD file, there are also Python scripts to process it:https://github.com/posborne/cmsis-svd