au-ts
Create a documentation directory and updating the serial subsystem docs
This pull request aims to provide an example of a preferred style of documentation. Firstly, it adds a docs directory to the repo, which contains developer targeted documentation for using each sDDF subsystem. Secondly, it restricts the README.md documentation in the serial example to more specifically provide details of the example, leaving general subsystem informations for docs/serial.md.
Once a convention for such documentation is agreed upon, we should aim to update the remaining sDDF subsystems.
I'm halfway through on a block doc aswell, will put that into this PR when im closer to finishing
I'd like to discuss with others in the team the role of this documentation vs the design doc before reviewing. I don't have any strong opinions on whether we should have everything in one place or not, but I do want to understand what belongs in the design doc and what belongs in these more technical docs.
I haven't looked closely yet but one good addition would be listing exactly what drivers we have and any setup they need.
Right now we have stuff like this in the Makefile:
# NOTES
# Generates eth_driver.elf
# Expects System Description File to set eth_regs to the address of
# the registers
# Expects libsddf_util_debug.a to be in LIBS
Other than the last line about LIBS, we really should not be documenting things in the Makefiles themselves.
So for serial we should have something like:
We support the following drivers:
* PL0111
* etc
Each driver expects to have the `uart_base` variable patched in the System Description File (SDF) like so:
<map mr="uart" vaddr="0x5_000_000" perms="rw" cached="false" setvar_vaddr="uart_base" />
Before addressing any feedback I would suggest rebasing since there might be some conflicting changes in the serial example since the PR got made.
This PR has been updated with new sdfgen documentation. I have also included some of the extra docs I wrote about writing drivers as this seemed to go missing.
Only problem is the broken links to the sddf design document - I assume we want to include this in the sddf repo at some point.
Only problem is the broken links to the sddf design document - I assume we want to include this in the sddf repo at some point.
We do, I'll make a separate PR that adds it in before we merge this.
Also just noticed that I write about the signalling protocol in the driver docs - I am planning on writing a little more about it in the design doc soon, and will probably use that as a starting point. Once I've done that, I'll just link to the design doc from the devloping.md instead.