config_attach.9 seems to be the man page which best describes what
struct cfattach members do. The following patch adds a section
describing what the ca_activate function pointer within struct cfattach
does via a description of the corresponding config_deactivate function
as to follow config_attach.9's established model. The following
additions do not incur any mdoc(7) warnings or errors.
I couldn't ascertain whether config_deactivate is always called from
process context; if anyone can authoritatively determine it is, please
chime in here so I can make a note of it in the CONTEXT section.
Ian
Index: man9/config_attach.9
===================================================================
RCS file: /cvs/src/share/man/man9/config_attach.9,v
retrieving revision 1.3
diff -u -p -r1.3 config_attach.9
--- man9/config_attach.9 5 Dec 2014 16:55:53 -0000 1.3
+++ man9/config_attach.9 8 Aug 2016 04:13:27 -0000
@@ -34,7 +34,8 @@
.Sh NAME
.Nm config_attach ,
.Nm config_detach ,
-.Nm config_detach_children
+.Nm config_detach_children ,
+.Nm config_deactivate
.Nd attach and detach devices
.Sh SYNOPSIS
.In sys/param.h
@@ -43,9 +44,11 @@
.Fn config_attach "struct device *parent" "void *cf" "void *aux" \
"cfprint_t print"
.Ft "int"
-.Fn config_detach "struct device *dev" "int flags"
+.Fn config_detach "struct device *dev"
.Ft "int"
.Fn config_detach_children "struct device *parent" "int flags"
+.Ft "int"
+.Fn config_deactivate "struct device *dev"
.Sh DESCRIPTION
The
.Fn config_attach
@@ -71,6 +74,21 @@ contains detachment flags:
#define DETACH_FORCE 0x01 /* Force detachment; hardware gone */
#define DETACH_QUIET 0x02 /* Don't print a notice */
.Ed
+.Pp
+The
+.Fn config_deactivate
+function is called by the parent to change the child device's operational state
+by calling the driver's activate function with a
+.Fa flags
+argument describing the targeted operational state:
+.Bd -literal
+#define DVACT_DEACTIVATE 1 /* deactivate the device */
+#define DVACT_QUIESCE 2 /* warn the device about
suspend */
+#define DVACT_SUSPEND 3 /* suspend the device */
+#define DVACT_RESUME 4 /* resume the device */
+#define DVACT_WAKEUP 5 /* tell device to recover after
resume */
+#define DVACT_POWERDOWN 6 /* power device down */
+.Ed
.Sh CONTEXT
.Fn config_detach
is always called from process context, allowing
@@ -79,6 +97,8 @@ to be called while the device detaches i
which have a device open).
.Sh RETURN VALUES
.Fn config_detach
-returns zero if successful and an error code otherwise.
+and
+.Fn config_deactivate
+return zero if successful and an error code otherwise.
.Sh SEE ALSO
.Xr config_found 9
