Expound a little bit about the softc, where its size is found and a

caution against emulating legacy softc methods used in the tree.

1 files changed, 16 insertions, 2 deletions

diff --git a/share/man/man9/device_get_softc.9 b/share/man/man9/device_get_softc.9
index f180a49..74816d01 100644
--- a/share/man/man9/device_get_softc.9
+++ b/share/man/man9/device_get_softc.9
@@ -40,11 +40,25 @@
 .Ft void *
 .Fn device_get_softc "device_t dev"
 .Sh DESCRIPTION
-Return the driver-specific instance variables of a device.
+Return the driver-specific state of
+.Fa dev .
+The softc is automatically allocated the first time it is requested.
+The size of the allocation is determined by the device's
+.Ft driver_t
+information used to define the driver.
+The softc typically encaposlates the state of this instance of the
+device.
+.Pp
+Driver writers are discouraged from using their own softc management
+mechanisms.
+Driver writers should not copy such mechanisms found in drivers in the
+tree that predates this function.
 .Sh RETURN VALUES
 The pointer to the driver-specific instance variable is returned.
 .Sh SEE ALSO
-.Xr device 9
+.Xr driver 9 ,
+.Xr device 9 ,
+.Xr device_set_softc 9
 .Sh AUTHORS
 This man page was written by
 .An Doug Rabson .