Describe the role of tags and mapping objects as abstractions.
Describe static vs dynamic transaction types and give a brief overview
of the set of functions and object life cycles used for static vs
dynamic.
While here, fix a few other typos.
Details
Details
- Reviewers
cem imp - Group Reviewers
manpages - Commits
- rS337673: Add an overview section to bus_dma.9.
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
Comment Actions
Other than an inconsistency in how you're adding newlines after , I like it.
| share/man/man9/bus_dma.9 | ||
|---|---|---|
| 144 ↗ | (On Diff #46483) | why a newline here? |
| share/man/man9/bus_dma.9 | ||
|---|---|---|
| 140 ↗ | (On Diff #46483) | I'd suggest .Vt ( bus_dma_tag_t ) — when ascii can express the same output, it's one less macro for anyone editing or reading the raw doc to have to reference — and AFAICT they render the same. |
| 184 ↗ | (On Diff #46483) | Why not just use parentheses? |
| 229–232 ↗ | (On Diff #46483) | I think this can just use ASCII parens |
| 257 ↗ | (On Diff #46483) | memory region must be bound to the mapping object (or vice versa)? |
Comment Actions
I'm not a fan of the lines-terminating-at-commas style but it's not an issue.
Thanks for writing this.
| share/man/man9/bus_dma.9 | ||
|---|---|---|
| 144 ↗ | (On Diff #46483) | similar to the "start every sentence on a new line" rule, I was applying the same to clauses. It is probably debatable if "for example" is the same as a clause though. I have a newline after all the subordinate clauses though. I'll add manpages to the review who I missed earlier. |
| 148 ↗ | (On Diff #46483) | Did not here. |
| 153 ↗ | (On Diff #46483) | Did here. |
| 156 ↗ | (On Diff #46483) | Did here. |
| 230 ↗ | (On Diff #46483) | Did here |
| 234 ↗ | (On Diff #46483) | Did here |
Comment Actions
Hmm, I'll defer to the @wblock or the like on ASCII ()'s. In general I prefer to let the markup pick how it wants to render markup instead of doing the rendering directly (so prefer to use tags than not), but I do think there might be something different there for parentheses.
| share/man/man9/bus_dma.9 | ||
|---|---|---|
| 257 ↗ | (On Diff #46483) | Good catch, I'll fix. |
Comment Actions
- Use explicit parantheses as this does seem to be the prevailing style.
- Only use newlines after actual clauses as opposed to simple phrases.
Comment Actions
- Add an Example.
This might be a bit much (and it ended up being quite a bit long), but
it does give about the smallest example I could think of of using both
static and dynamic mappings in a single driver.
Comment Actions
Seems kind of long. It's unfortunate we don't really have an existing pattern for manual page examples.
One option that might be too "cute" would be to dump the code in sys/dev/helloworld, annotate in helloworld.4, and refer to that (with slightly more context than just bare .Xr) from this page.
The straightforward thing might be adding a bus_dma_example.9?
Comment Actions
I'll see if maybe there's a good place for the extended example in the developer handbook.