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 15268 Build 15327: 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 | ||
|---|---|---|
| 48 | returns the phandle value of the first child of the | |
| 50 | Zero is returned if there are no child nodes. | |
| 53 | returns the phandle for the parent of the | |
| 54 | .Fa node . | |
| 55 | Zero is returned if | |
| 60 | returns the phandle value of the next sibling of the | |
| 62 | Zero is returned if there is no sibling node. | |
| share/man/man9/OF_device_from_xref.9 | ||
| 47 | When a device tree node references another node, the driver may | |
| 48 | need to get the device associated with the referenced node. "get the device" needs to be more specific. Get a device_t instance? | |
| 49 | For instance, an Ethernet driver accessing a PHY device. | |
| 50 | To make this possible, the kernel maintains a table that | |
| 54 | adds a map entry from the effective phandle | |
| 58 | If a mapping entry for | |
| 60 | already exists, it is replaced with the new one. | |
| 64 | returns a device_t instance associated with the effective phandle | |
| 69 | returns the effective phandle associated with the device | |
| 71 | If no such mapping exists, the function returns 0. | |
| share/man/man9/OF_finddevice.9 | ||
| 42 | returns the phandle for the node specified by the | |
| 44 | Returns -1 if the path cannot be found in the tree. | |
| 46 | The return value should only be checked with equality | |
| 47 | Make this more language-agnostic: operators (equal to, not equal to) and not relational comparison | |
| 48 | As above, and start new sentences on new lines. (less than, greater than). There is a discrepancy between the IEEE 1275 standard and | |
| 49 | the .Fx Ns 's internal representation of a phandle: IEEE 1275 | |
| 50 | requires the return value of this function to be -1 if the path | |
| 51 | Break sentence: is not found. But phandle_t is an unsigned type, so it cannot | |
| 52 | 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 | ||
| 79 | Device nodes can have associated properties. | |
| 80 | Properties consist of a name and a value. | |
| 82 | A value is an array of zero or more bytes that encode certain | |
| 86 | values or any combination of these types. | |
| 88 | 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 | |
| 92 | Possessive adds no value here: A byte array is encoded as a sequence of bytes and represents | |
| 95 | A text string is a sequence of n printable characters. It is | |
| 97 | characters represented as bytes plus a terminating null character. | |
| 107 | or 0 if the property exists but has no associated value. | |
| 108 | If .Fa propname does not exist, -1 is returned. | |
| 113 | copies a maximum of | |
| 121 | The function returns the actual size of the value or -1 if the | |
| 125 | copies a maximum of | |
| 129 | then converts cell values from big-endian to host byte order. | |
| 130 | The function returns the actual size of the value in bytes, or -1 | |
| 133 | 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. | |
| 138 | has a property specified by | |
| 140 | or zero if the property does not exist. | |
| 148 | If the property is found, the function copies a maximum of | |
| 153 | The function returns the actual size in bytes of the value, | |
| 154 | or -1 if the property does not exist. | |
| 162 | If the property is found, the function copies a maximum of | |
| 167 | then converts cell values from big-endian to host byte order. | |
| 168 | The function returns the actual size in bytes of the value, | |
| 169 | or -1 if the property does not exist. | |
| 172 | allocates memory large enough to hold the | |
| 178 | The function returns the actual size of the value and stores the | |
| 179 | address of the allocated memory in | |
| 181 | If the property has a zero-sized value, | |
| 184 | The function returns -1 if the property does not exist or | |
| 189 | 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. | |
| 192 | allocates enough memory to hold the | |
| 200 | The actual size of the value is returned and the | |
| 201 | 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. | |
| 203 | If the property has a zero-length value, | |
| 205 | is set to NULL. | |
| 206 | The function returns -1 if the property does not exist or | |
| 211 | The function might sleep when allocating memory. | |
| 216 | Should this be that was allocated by | |
| 218 | or | |
| 222 | copies a maximum of | |
| 224 | Not clear. Maybe: .Fn OF_nextprop copies .Fa size bytes of the name of the property following .Fa propname | |
| 251 | If the property does not exist, the function tries to create | |
| share/man/man9/OF_node_from_xref.9 | ||
| 47 | For instance, a framebuffer controller may refer to a GPIO | |
| 49 | For such implementations, the phandle is used by the kernel to | |
| 50 | identify the node does not match the value of the cell property that | |
| 51 | This sentence is difficult to understand. | |
| 52 | Otherwise, the effective phandle is equal to the kernel phandle. | |
| 56 | returns the kernel phandle for the effective phandle | |
| 58 | If one cannot be found or the OpenFirmware implementation | |
| 60 | the input value. | |
| 63 | returns the effective phandle for the kernel phandle | |
| 65 | If one cannot be found or the OpenFirmware implementation | |
| 67 | the input value. | |
| share/man/man9/OF_package_to_path.9 | ||
| 44 | 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 | ||
|---|---|---|
| 52 | 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 | ||
| 189 | It's the second. | |
| 224 | 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 | ||
| 51 | I added more details to the example to illustrate the concept of reference. | |