bus_generic_print_child.9: Document bus_print_domain

While here, cross-reference BUS_PRINT_CHILD (and fix a stale reference
to DEVICE_PRINT_CHILD which doesn't exist) and expand the text
describing the role of the helper functions.

Differential Revision:	https://reviews.freebsd.org/D48373

share/man/man9/Makefile

@@ -697,7 +697,8 @@ MLINKS+=bus_dma.9 busdma.9 \
 	bus_dma.9 bus_dmamem_free.9 \
 	bus_dma.9 bus_dma_tag_create.9 \
 	bus_dma.9 bus_dma_tag_destroy.9
-MLINKS+=bus_generic_print_child.9 bus_print_child_footer.9 \
+MLINKS+=bus_generic_print_child.9 bus_print_child_domain.9 \
+	bus_generic_print_child.9 bus_print_child_footer.9 \
 	bus_generic_print_child.9 bus_print_child_header.9
 MLINKS+=bus_generic_read_ivar.9 bus_generic_write_ivar.9
 MLINKS+=BUS_GET_CPUS.9 bus_get_cpus.9

share/man/man9/bus_generic_print_child.9

@@ -26,43 +26,88 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd January 16, 2025
+.Dd February 5, 2025
 .Dt BUS_GENERIC_PRINT_CHILD 9
 .Os
 .Sh NAME
 .Nm bus_generic_print_child ,
+.Nm bus_print_child_domain ,
 .Nm bus_print_child_footer ,
 .Nm bus_print_child_header
 .Nd generic implementation of
-.Dv DEVICE_PRINT_CHILD
-for buses
+.Xr BUS_PRINT_CHILD 9
 .Sh SYNOPSIS
 .In sys/param.h
 .In sys/bus.h
 .Ft int
 .Fn bus_generic_print_child "device_t dev" "device_t child"
 .Ft int
+.Fn bus_print_child_domain "device_t dev" "device_t child"
+.Ft int
 .Fn bus_print_child_footer "device_t dev" "device_t child"
 .Ft int
 .Fn bus_print_child_header "device_t dev" "device_t child"
 .Sh DESCRIPTION
-This implementation prints out the default device announcement message.
-Given device 'foo0' on bus 'bar0' where foo0 has the name "FooCard 1234" the
+.Fn bus_generic_print_child
+prints out the default device announcement message.
+Given device
+.Sq foo0
+on bus
+.Sq bar0
+where foo0 has the description
+.Dq FooCard 1234
+and is associated with the NUMA domain 1,
+the
 following would be printed:
+.Bd -literal -offset indent
+foo0: <FooCard 1234> numa-domain 1 on bar0
+.Ed
 .Pp
-foo0: <FooCard 1234> on bar0
-.Pp
-bus_generic_print_child itself calls two functions
-.Fn bus_print_child_header
+.Fn bus_generic_print_child
+calls the three helper functions
+.Fn bus_print_child_header ,
+.Fn bus_print_child_domain ,
 and
 .Fn bus_print_child_footer .
-The former prints "foo0: <FooCard 1234>" and the latter "on bar0".
-These routines should be used if possible in your own code if
+.Pp
+.Fn bus_print_child_header
+outputs the device name and unit followed by the device description
+in angle brackets
+.Po
+.Dq foo0: <FooCard 1234>
+.Pc .
+.Pp
+.Fn bus_print_child_domain
+outputs
+.Dq \& numa-domain
+followed by the domain number if
+.Fn bus_get_domain
+returns a valid domain for the device
+.Po
+.Dq  numa-domain 1
+.Pc .
+If
+.Fa dev
+is not associated witha valid domain,
+nothing is output.
+.Pp
+.Fn bus_print_child_footer
+outputs the string
+.Dq \& on
+followed by the parent device's name and unit
+.Po
+.Dq \& on bar0
+.Pc .
+.Pp
+These functions can be used to implement
+.Xr BUS_PRINT_CHILD 9
+in a bus driver if
 .Fn bus_generic_print_child
-does not completely suit your needs.
+is not sufficient.
 .Sh RETURN VALUES
 The number of characters output.
 .Sh SEE ALSO
+.Xr BUS_PRINT_CHILD 9 ,
 .Xr device 9
 .Sh AUTHORS
 This manual page was written by