e52368365d
config_intrhook_drain will remove the hook from the list as config_intrhook_disestablish does if the hook hasn't been called. If it has, config_intrhook_drain will wait for the hook to be disestablished in the normal course (or expedited, it's up to the driver to decide how and when to call config_intrhook_disestablish). This is intended for removable devices that use config_intrhook and might be attached early in boot, but that may be removed before the kernel can call the config_intrhook or before it ends. To prevent all races, the detach routine will need to call config_intrhook_train. Sponsored by: Netflix, Inc Reviewed by: jhb, mav, gde (in D29006 for man page) Differential Revision: https://reviews.freebsd.org/D29005
140 lines
5.0 KiB
Groff
140 lines
5.0 KiB
Groff
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.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 .
|