Add man pages for number of OF_* functions that are used
in OpenFirmware-compatible systems. Please note that
documentation in OF_getprop.9 does not match current
property management API but matches what it will be
once functional and style bugs are fixed. This diff
will not be committed until API is fixed I just want
to start editorial review as sson as possible.
Details
Details
- Reviewers
nwhitehorn - Group Reviewers
manpages - Commits
- rS332342: [man] Add documentation for OpenFirmware API
Diff Detail
Diff Detail
- Lint
Lint Passed - Unit
No Test Coverage - Build Status
Buildable 15359 Build 15413: arc lint + arc unit
Event Timeline
Comment Actions
There is a lot of redundancy in the "The function returns" sentences, which could be shortened by saying just "Returns" or rearranging some in a different order, like "Zero is returned..."
| share/man/man9/OF_child.9 | ||
|---|---|---|
| 49 | returns the phandle value of the first child of the | |
| 51 | Zero is returned if there are no child nodes. | |
| 54 | returns the phandle for the parent of the | |
| 55 | .Fa node . | |
| 56 | Zero is returned if | |
| 61 | returns the phandle value of the next sibling of the | |
| 63 | Zero is returned if there is no sibling node. | |
| share/man/man9/OF_device_from_xref.9 | ||
| 48 | When a device tree node references another node, the driver may | |
| 49 | need to get the device associated with the referenced node. "get the device" needs to be more specific. Get a device_t instance? | |
| 50 | For instance, an Ethernet driver accessing a PHY device. | |
| 51 | To make this possible, the kernel maintains a table that | |
| 55 | adds a map entry from the effective phandle | |
| 59 | If a mapping entry for | |
| 61 | already exists, it is replaced with the new one. | |
| 65 | returns a device_t instance associated with the effective phandle | |
| 70 | returns the effective phandle associated with the device | |
| 72 | If no such mapping exists, the function returns 0. | |
| share/man/man9/OF_finddevice.9 | ||
| 43 | returns the phandle for the node specified by the | |
| 45 | Returns -1 if the path cannot be found in the tree. | |
| 47 | The return value should only be checked with equality | |
| 48 | Make this more language-agnostic: operators (equal to, not equal to) and not relational comparison | |
| 49 | As above, and start new sentences on new lines. (less than, greater than). There is a discrepancy between the IEEE 1275 standard and | |
| 50 | the .Fx Ns 's internal representation of a phandle: IEEE 1275 | |
| 51 | requires the return value of this function to be -1 if the path | |
| 52 | Break sentence: is not found. But phandle_t is an unsigned type, so it cannot | |
| 53 | be relationally compared with -1 or 0, which I'm not sure if "relationally" is the right word. I can think of others like "accurately" or "properly", but they don't seem much better. | |
| share/man/man9/OF_getprop.9 | ||
| 80 | Device nodes can have associated properties. | |
| 81 | Properties consist of a name and a value. | |
| 83 | A value is an array of zero or more bytes that encode certain | |
| 87 | values or any combination of these types. | |
| 89 | Properties with a zero-byte length value usually represent boolean Is the length being a byte value relevant if it is zero? Could we just say Properties with a zero-length value usually represent boolean | |
| 93 | Possessive adds no value here: A byte array is encoded as a sequence of bytes and represents | |
| 96 | A text string is a sequence of n printable characters. It is | |
| 98 | characters represented as bytes plus a terminating null character. | |
| 108 | or 0 if the property exists but has no associated value. | |
| 109 | If .Fa propname does not exist, -1 is returned. | |
| 114 | copies a maximum of | |
| 122 | The function returns the actual size of the value or -1 if the | |
| 126 | copies a maximum of | |
| 130 | then converts cell values from big-endian to host byte order. | |
| 131 | The function returns the actual size of the value in bytes, or -1 | |
| 134 | Spelling, but also unclear. Will it still work if len is not a multiple of 4? If not, this should say "must". must be a multiple of 4. | |
| 139 | has a property specified by | |
| 141 | or zero if the property does not exist. | |
| 149 | If the property is found, the function copies a maximum of | |
| 154 | The function returns the actual size in bytes of the value, | |
| 155 | or -1 if the property does not exist. | |
| 163 | If the property is found, the function copies a maximum of | |
| 168 | then converts cell values from big-endian to host byte order. | |
| 169 | The function returns the actual size in bytes of the value, | |
| 170 | or -1 if the property does not exist. | |
| 173 | allocates memory large enough to hold the | |
| 179 | The function returns the actual size of the value and stores the | |
| 180 | address of the allocated memory in | |
| 182 | If the property has a zero-sized value, | |
| 185 | The function returns -1 if the property does not exist or | |
| 190 | Does "may sleep" mean I have permission to sleep while waiting for the memory allocation, or does it mean that the memory allocation might cause me to sleep? I suspect it's the second. So: The function might sleep when allocating memory. | |
| 193 | allocates enough memory to hold the | |
| 201 | The actual size of the value is returned and the | |
| 202 | address of allocated memory is stored in Note: many of the previous sections had this copy/paste "The function returns", which is redundant and can be shortened this way. | |
| 204 | If the property has a zero-length value, | |
| 206 | is set to NULL. | |
| 207 | The function returns -1 if the property does not exist or | |
| 212 | The function might sleep when allocating memory. | |
| 217 | Should this be that was allocated by | |
| 219 | or | |
| 223 | copies a maximum of | |
| 225 | Not clear. Maybe: .Fn OF_nextprop copies .Fa size bytes of the name of the property following .Fa propname | |
| 252 | If the property does not exist, the function tries to create | |
| share/man/man9/OF_node_from_xref.9 | ||
| 48 | For instance, a framebuffer controller may refer to a GPIO | |
| 50 | For such implementations, the phandle is used by the kernel to | |
| 51 | identify the node does not match the value of the cell property that | |
| 52 | This sentence is difficult to understand. | |
| 53 | Otherwise, the effective phandle is equal to the kernel phandle. | |
| 57 | returns the kernel phandle for the effective phandle | |
| 59 | If one cannot be found or the OpenFirmware implementation | |
| 61 | the input value. | |
| 64 | returns the effective phandle for the kernel phandle | |
| 66 | If one cannot be found or the OpenFirmware implementation | |
| 68 | the input value. | |
| share/man/man9/OF_package_to_path.9 | ||
| 45 | bytes of the fully qualified path to the device tree node | |
Comment Actions
Apply wblock@ edits and get rid of "The function returns"
in favor of just "Returns"
| share/man/man9/OF_finddevice.9 | ||
|---|---|---|
| 53 | By "relationally" I meant "using greater than, less than" as opposing to equality check. Maybe it can give you some hints on how to phrase this better. | |
| share/man/man9/OF_getprop.9 | ||
| 190 | It's the second. | |
| 225 | I don't think it's the right description. Function copies name to buf, if the name length is larger than size, it copies only size bytes. | |
| share/man/man9/OF_node_from_xref.9 | ||
| 52 | I added more details to the example to illustrate the concept of reference. | |