Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/BUS_GET_PROPERTY.9
| Show All 19 Lines | |||||||||
| .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||||||||
| .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | ||||||||
| .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||||||||
| .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | ||||||||
| .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||||||||
| .\" | .\" | ||||||||
| .\" $FreeBSD$ | .\" $FreeBSD$ | ||||||||
| .\" | .\" | ||||||||
| .Dd August 19, 2021 | .Dd January 24, 2022 | ||||||||
bz: Please update before commit. | |||||||||
| .Dt BUS_GET_PROPERTY 9 | .Dt BUS_GET_PROPERTY 9 | ||||||||
| .Os | .Os | ||||||||
| .Sh NAME | .Sh NAME | ||||||||
| .Nm BUS_GET_PROPERTY | .Nm BUS_GET_PROPERTY | ||||||||
| .Nd get child's specific property | .Nd get child's specific property | ||||||||
| .Sh SYNOPSIS | .Sh SYNOPSIS | ||||||||
| .In sys/param.h | .In sys/param.h | ||||||||
| .In sys/bus.h | .In sys/bus.h | ||||||||
| .Ft ssize_t | .Ft ssize_t | ||||||||
| .Fn BUS_GET_PROPERTY "device_t dev" "device_t child" "const char *propname" \ | .Fn BUS_GET_PROPERTY "device_t dev" "device_t child" "const char *propname" \ | ||||||||
| "void *propvalue" "size_t size" | "void *propvalue" "size_t size" "device_property_type_t type" | ||||||||
Done Inline ActionsThere should be a description of the type argument in the man page. andrew: There should be a description of the `type` argument in the man page. | |||||||||
| .Sh DESCRIPTION | .Sh DESCRIPTION | ||||||||
| The | The | ||||||||
| .Fn BUS_GET_PROPERTY | .Fn BUS_GET_PROPERTY | ||||||||
| method | method | ||||||||
| is called from driver code which wants to access child's specific data stored | is called from driver code which wants to access a child's specific data stored | ||||||||
Done Inline Actions"a child's" maybe? pauamma_gundo.com: "a child's" maybe? | |||||||||
| on the bus. | on the bus. | ||||||||
| Property consits of its name and value. | A property has a name and an associated value. | ||||||||
Done Inline Actions
What I think you mean, reworded for clarity and slightly simpler language. pauamma_gundo.com: What I think you mean, reworded for clarity and slightly simpler language. | |||||||||
| Implementation shall copy to | Implementation shall copy to | ||||||||
| .Fa propvalue | .Fa propvalue | ||||||||
| at most | at most | ||||||||
| .Fa size | .Fa size | ||||||||
| bytes. | bytes. | ||||||||
| .Pp | |||||||||
| .Fn BUS_GET_PROPERTY | |||||||||
| supports different property types specified via the | |||||||||
| .Fa type | |||||||||
| argument. | |||||||||
| The | |||||||||
| .Fa size | |||||||||
| is guaranteed to be a multiple of the underlying property type. | |||||||||
Not Done Inline Actions"a multiple of"? Do you mean "larger than"? pauamma_gundo.com: "a multiple of"? Do you mean "larger than"? | |||||||||
Done Inline ActionsYes, multiple of is the right term. kd: Yes, multiple of is the right term.
For example for a uint32_t type(4 bytes) size = 4*n. | |||||||||
Not Done Inline ActionsI would add "size" somewhere for clarity, but this being the kernel, I don't know the audience well enough to insist on it. pauamma_gundo.com: I would add "size" somewhere for clarity, but this being the kernel, I don't know the audience… | |||||||||
| If a type is not supported, | |||||||||
| .Fn BUS_GET_PROPERTY | |||||||||
| returns -1. | |||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||
| .Sh NOTES | .Sh NOTES | ||||||||
| If | If | ||||||||
| .Fa propvalue | .Fa propvalue | ||||||||
| is NULL or | is NULL or | ||||||||
| .Fa size | .Fa size | ||||||||
| is zero, then implementation shall only return size of the property. | is zero, the implementation returns only the size of the property. | ||||||||
Done Inline Actions
Also, not sure what you mean by "implementation". Is that the macro/function code? pauamma_gundo.com: Also, not sure what you mean by "implementation". Is that the macro/function code? | |||||||||
Done Inline ActionsIt's something similar to polymorphism in c++. We have multiple implementations of BUS_GET_PROPERTY depending on which bus a device resides on. This man page is mostly meant to describe the API, rather then any particular one. kd: It's something similar to polymorphism in c++. We have multiple implementations of… | |||||||||
Not Done Inline ActionsIn that case, "shall" in the spots I suggested changing it is correct even if stilted, except the one that says "shall to", which should be "shall" instead. pauamma_gundo.com: In that case, "shall" in the spots I suggested changing it is correct even if stilted, except… | |||||||||
| .Sh RETURN VALUES | .Sh RETURN VALUES | ||||||||
| Property's size if successful, otherwise -1. | The property size if successful, otherwise -1. | ||||||||
Not Done Inline Actions
Since you're touching this page. pauamma_gundo.com: Since you're touching this page. | |||||||||
| .Sh SEE ALSO | .Sh SEE ALSO | ||||||||
| .Xr device 9 , | .Xr device 9 , | ||||||||
| .Xr device_get_property 9 | .Xr device_get_property 9 | ||||||||
| .Sh AUTHORS | .Sh AUTHORS | ||||||||
| This manual page was written by | This manual page was written by | ||||||||
| .An Bartlomiej Grzesik . | .An Bartlomiej Grzesik . | ||||||||
Please update before commit.