feat: Added FreeBSD man pages

1 files changed, 137 insertions, 0 deletions

diff --git a/static/freebsd/man9/config_intrhook.9 b/static/freebsd/man9/config_intrhook.9
new file mode 100644
index 00000000..4ab49130
--- /dev/null
+++ b/static/freebsd/man9/config_intrhook.9
@@ -0,0 +1,137 @@
+.\"
+.\" Copyright (C) 2006 M. Warner Losh <imp@FreeBSD.org>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer as
+.\"    the first lines of this file unmodified other than the possible
+.\"    addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (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 March 8, 2021
+.Dt CONFIG_INTRHOOK 9
+.Os
+.Sh NAME
+.Nm config_intrhook
+.Nd schedule a function to be run after interrupts have been enabled,
+but before root is mounted
+.Sh SYNOPSIS
+.In sys/kernel.h
+.Vt typedef void (*ich_func_t)(void *arg);
+.Ft int
+.Fn config_intrhook_establish "struct intr_config_hook *hook"
+.Ft void
+.Fn config_intrhook_disestablish "struct intr_config_hook *hook"
+.Ft int
+.Fn config_intrhook_drain "struct intr_config_hook *hook"
+.Ft void
+.Fn config_intrhook_oneshot "ich_func_t func" "void *arg"
+.Sh DESCRIPTION
+The
+.Fn config_intrhook_establish
+function schedules a function to be run after interrupts have been
+enabled, but before root is mounted.
+If the system has already passed this point in its initialization,
+the function is called immediately.
+.Pp
+The
+.Fn config_intrhook_disestablish
+function removes the entry from the hook queue.
+.Pp
+The
+.Fn config_intrhook_drain
+function removes the entry from the hook queue in a safe way.
+If the hook is not currently active it removes
+.Fa hook
+from the hook queue and returns
+.Vt ICHS_QUEUED .
+If the hook is active, it waits for the hook to complete before returning
+.Vt ICHS_RUNNING .
+If the hook has previously completed, it returns
+.Vt ICHS_DONE .
+Because a
+.Vt config_intrhook
+is undefined prior to
+.Fn config_intrhook_establish ,
+this function may only be called after that function has returned.
+.Pp
+The
+.Fn config_intrhook_oneshot
+function schedules a function to be run as described for
+.Fn config_intrhook_establish ;
+the entry is automatically removed from the hook queue
+after that function runs.
+This is appropriate when additional device configuration must be done
+after interrupts are enabled, but there is no need to stall the
+boot process after that.
+This function allocates memory using M_WAITOK; do not call this while
+holding any non-sleepable locks.
+.Pp
+Before root is mounted, all the previously established hooks are
+run.
+The boot process is then stalled until all handlers remove their hook
+from the hook queue with
+.Fn config_intrhook_disestablish .
+The boot process then proceeds to attempt to mount the root file
+system.
+Any driver that can potentially provide devices they wish to be
+mounted as root must use either this hook, or probe all these devices
+in the initial probe.
+Since interrupts are disabled during the probe process, many drivers
+need a method to probe for devices with interrupts enabled.
+.Pp
+The requests are made with the
+.Vt intr_config_hook
+structure.
+This structure is defined as follows:
+.Bd -literal
+struct intr_config_hook {
+	TAILQ_ENTRY(intr_config_hook) ich_links;/* Private */
+	ich_func_t	ich_func;		/* function to call */
+	void		*ich_arg;		/* Argument to call */
+};
+.Ed
+.Pp
+Storage for the
+.Vt intr_config_hook
+structure must be provided by the driver.
+It must be stable from just before the hook is established until
+after the hook is disestablished.
+.Pp
+Specifically, hooks are run at
+.Fn SI_SUB_INT_CONFIG_HOOKS ,
+which is immediately after the scheduler is started,
+and just before the root file system device is discovered.
+.Sh RETURN VALUES
+A zero return value means the hook was successfully added to the queue
+(with either deferred or immediate execution).
+A non-zero return value means the hook could not be added to the queue
+because it was already on the queue.
+.Sh SEE ALSO
+.Xr DEVICE_ATTACH 9
+.Sh HISTORY
+These functions were introduced in
+.Fx 3.0
+with the CAM subsystem, but are available for any driver to use.
+.Sh AUTHORS
+.An -nosplit
+The functions were written by
+.An Justin Gibbs Aq Mt gibbs@FreeBSD.org .
+This manual page was written by
+.An M. Warner Losh Aq Mt imp@FreeBSD.org .