On 08/08/16 07:38, Ian Sutton wrote: > On Sun, Aug 07, 2016 at 10:50:49PM -0600, Theo de Raadt wrote: >> Your diff also contained: >> >> -.Fn config_detach "struct device *dev" "int flags" >> +.Fn config_detach "struct device *dev" > > Argh! I had initially given config_deactivate() a flags parameter, > realized it lacked one in the code, and must have also accidently > removed it from _detach() accidently. Patch below removes this error. > Page also uploaded for convenience: > > http://ce.gl/config_attach.9.txt > >> I think you are reading NetBSD? > > I have not used nor even tried any other BSDs.
I'm not sure this function should be documented. Instead you could see where it can be removed or replaced by config_deactivate_children(9). This function also has the advantage of simplifying drivers since they no longer need to keep an extra reference for their child. That's the function that need to be documented and IMHO I'd start a new manual because it's not straightforward. config_deactivate(9) is misleading on OpenBSD because as you've seen it no longer match its original design. Hopefully we should be able to make it private. > Index: 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 > --- config_attach.9 5 Dec 2014 16:55:53 -0000 1.3 > +++ config_attach.9 8 Aug 2016 05:31:34 -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 > @@ -46,6 +47,8 @@ > .Fn config_detach "struct device *dev" "int flags" > .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 >
