device: add device_get_property and device_has_property

Generialize bus specific property accessors. Those functions allow driver code
to access device specific information.

Currently there is only support for FDT and ACPI buses.

Reviewed by: manu, mw
Sponsored by: Semihalf
Differential revision: https://reviews.freebsd.org/D31597

3 files changed, 134 insertions, 0 deletions

diff --git a/share/man/man9/BUS_GET_PROPERTY.9 b/share/man/man9/BUS_GET_PROPERTY.9
new file mode 100644
index 000000000000..89edbd95b68c
--- /dev/null
+++ b/share/man/man9/BUS_GET_PROPERTY.9
@@ -0,0 +1,65 @@
+.\" -
+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
+.\"
+.\" Copyright (c) 2021 Semihalf
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd August 19, 2021
+.Dt BUS_GET_PROPERTY 9
+.Os
+.Sh NAME
+.Nm BUS_GET_PROPERTY
+.Nd get child's specific property
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/bus.h
+.Ft ssize_t
+.Fn BUS_GET_PROPERTY "device_t dev" "device_t child" "const char *propname" \
+    "void *propvalue" "size_t size"
+.Sh DESCRIPTION
+The
+.Fn BUS_GET_PROPERTY
+method
+is called from driver code which wants to access child's specific data stored
+on the bus.
+Property consits of its name and value.
+Implementation shall copy to
+.Fa propvalue
+at most
+.Fa size
+bytes.
+.Sh NOTES
+If
+.Fa propvalue
+is NULL or
+.Fa size
+is zero, then implementation shall only return size of the property.
+.Sh RETURN VALUES
+Property's size if successful, otherwise -1.
+.Sh SEE ALSO
+.Xr device 9 ,
+.Xr device_get_property 9
+.Sh AUTHORS
+This manual page was written by
+.An Bartlomiej Grzesik .
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 4764db983f8a..30632e0a6cb6 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -47,6 +47,7 @@ MAN=	accept_filter.9 \
 	bus_generic_read_ivar.9 \
 	bus_generic_shutdown.9 \
 	BUS_GET_CPUS.9 \
+	BUS_GET_PROPERTY.9 \
 	bus_get_resource.9 \
 	bus_map_resource.9 \
 	BUS_NEW_PASS.9 \
@@ -108,6 +109,7 @@ MAN=	accept_filter.9 \
 	device_get_ivars.9 \
 	device_get_name.9 \
 	device_get_parent.9 \
+	device_get_property.9 \
 	device_get_softc.9 \
 	device_get_state.9 \
 	device_get_sysctl.9 \
diff --git a/share/man/man9/device_get_property.9 b/share/man/man9/device_get_property.9
new file mode 100644
index 000000000000..1d9bd5058b1a
--- /dev/null
+++ b/share/man/man9/device_get_property.9
@@ -0,0 +1,67 @@
+.\" -
+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
+.\"
+.\" Copyright (c) 2021 Semihalf
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd August 19, 2021
+.Dt DEVICE_GET_PROPERTY 9
+.Os
+.Sh NAME
+.Nm device_get_property ,
+.Nm device_has_property
+.Nd access device specific data
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/bus.h
+.Ft ssize_t
+.Fn device_get_property "device_t dev" "const char *prop" "void *val" "size_t sz"
+.Ft bool
+.Fn device_has_property "device_t dev" "const char *prop"
+.Sh DESCRIPTION
+Access device specific data provided by the parent bus.
+Drivers can use these properties to obtain device capabilities and set
+necessary quirks.
+.Sh NOTES
+You can pass NULL as pointer to property's value when calling
+.Fn device_get_property
+to obtain its size.
+.Pp
+Currently this interface is implemented by
+.Xr simplebus 4
+and
+.Xr acpi 4 .
+.Sh RETURN VALUES
+.Fn device_get_property
+if successful returns property's size, otherwise returns -1.
+.Pp
+.Fn device_has_property
+returns true if given property was found.
+.Sh SEE ALSO
+.Xr acpi 4 ,
+.Xr simplebus 4 ,
+.Xr device 9
+.Sh AUTHORS
+This manual page was written by
+.An Bartlomiej Grzesik .