Give kldunload a -f(orce) argument.

Add a MOD_QUIESCE event for modules.  This should return error (EBUSY)
of the module is in use.

MOD_UNLOAD should now only fail if it is impossible (as opposed to
inconvenient) to unload the module.  Valid reasons are memory references
into the module which cannot be tracked down and eliminated.

When kldunloading, we abandon if MOD_UNLOAD fails, and if -force is
not given, MOD_QUIESCE failing will also prevent the unload.

For backwards compatibility, we treat EOPNOTSUPP from MOD_QUIESCE as
success.

Document that modules should return EOPNOTSUPP for unknown events.

1 files changed, 19 insertions, 1 deletions

diff --git a/share/man/man9/module.9 b/share/man/man9/module.9
index 6dc14b2..39b95a4 100644
--- a/share/man/man9/module.9
+++ b/share/man/man9/module.9
@@ -47,19 +47,37 @@ The
 .Xr DECLARE_MODULE 9
 macro
 registers the module with the system.
+.Pp
 When the module is loaded, the event handler function is called with
 the
 .Fa what
 argument set to
 .Dv MOD_LOAD .
-On unload,
+.Pp
+On unload it is first called with
+.Fa what
+set to MOD_QUIESCE .
+If the unload was not forced, a non-zero return will prevent the
+unload from happening.
+.Pp
+If the unload continues
 .Fa what
 is set to
 .Dv MOD_UNLOAD .
+If the module returns non-zero to this, the unload will not happen.
+.Pp
+The difference between MOD_QUIESCE and MOD_UNLOAD is that the module
+should fail MOD_QUIESCE if it is currently in use, whereas MOD_UNLOAD
+should only fail if it is impossible to unload the module, for instance
+because there are memory references to the module which cannot be revoked.
+.Pp
 When the system is shutting down,
 .Fa what
 contains the value of
 .Dv MOD_SHUTDOWN .
+.Pp
+The module should return EOPNOTSUPP for unrecognized values of
+.Fa what .
 .Sh EXAMPLES
 .Bd -literal
 #include <sys/param.h>