Differential D27413 Diff 82975 share/man/man9/firmware.9

Changeset View

Standalone View

share/man/man9/firmware.9

	Show All 17 Lines
	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,			.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY			.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT			.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF			.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.			.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd March 14, 2019			.Dd January 27, 2021
	.Dt FIRMWARE 9			.Dt FIRMWARE 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm firmware_register ,			.Nm firmware_register ,
	.Nm firmware_unregister ,			.Nm firmware_unregister ,
	.Nm firmware_get ,			.Nm firmware_get ,
				.Nm firmware_get_flags ,
	.Nm firmware_put			.Nm firmware_put
	.Nd firmware image loading and management			.Nd firmware image loading and management
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/param.h			.In sys/param.h
	.In sys/systm.h			.In sys/systm.h
	.In sys/linker.h			.In sys/linker.h
	.In sys/firmware.h			.In sys/firmware.h
	.Bd -literal			.Bd -literal
	Show All 11 Lines
	.Fa "size_t datasize"			.Fa "size_t datasize"
	.Fa "unsigned int version"			.Fa "unsigned int version"
	.Fa "const struct firmware *parent"			.Fa "const struct firmware *parent"
	.Fc			.Fc
	.Ft int			.Ft int
	.Fn firmware_unregister "const char *imagename"			.Fn firmware_unregister "const char *imagename"
	.Ft "const struct firmware *"			.Ft "const struct firmware *"
	.Fn firmware_get "const char *imagename"			.Fn firmware_get "const char *imagename"
				.Ft "const struct firmware *"
				.Fn firmware_get_flags "const char *imagename" "uint32_t flags"
	.Ft void			.Ft void
	.Fn firmware_put "const struct firmware *fp" "int flags"			.Fn firmware_put "const struct firmware *fp" "int flags"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The			The
	.Nm firmware			.Nm firmware
	abstraction provides a convenient interface for loading			abstraction provides a convenient interface for loading
	.Nm firmware images			.Nm firmware images
	into the kernel, and for accessing such images from kernel components.			into the kernel, and for accessing such images from kernel components.
	Show All 24 Lines
	manually at runtime, or on demand by the firmware subsystem.			manually at runtime, or on demand by the firmware subsystem.
	.Pp			.Pp
	.Nm Clients			.Nm Clients
	of the firmware subsystem can request access to a given image			of the firmware subsystem can request access to a given image
	by calling the function			by calling the function
	.Fn firmware_get			.Fn firmware_get
	with the			with the
	.Nm imagename			.Nm imagename
	they want as an argument.			they want as an argument, or by calling
				.Fn firmware_get_flags
				with the
				.Nm imagename
				and
				.Nm flags
				they want as an arguments.
	If a matching image is not already registered,			If a matching image is not already registered,
	the firmware subsystem will try to load it using the			the firmware subsystem will try to load it using the
	mechanisms specified below (typically, a kernel module			mechanisms specified below (typically, a kernel module
	with			with
	.Nm			.Nm
	the same name			the same name
	as the image).			as the image).
	.Sh API DESCRIPTION			.Sh API DESCRIPTION
	Show All 20 Lines
	tries to unregister the firmware image			tries to unregister the firmware image
	.Nm imagename			.Nm imagename
	from the system.			from the system.
	The function is successful and returns 0			The function is successful and returns 0
	if there are no pending references to the image, otherwise			if there are no pending references to the image, otherwise
	it does not unregister the image and returns EBUSY.			it does not unregister the image and returns EBUSY.
	.Pp			.Pp
	.Fn firmware_get			.Fn firmware_get
	returns the requested firmware image.			and
				.Fn firmware_get_flags
				return the requested firmware image.
				The
				.Fa flags
				argument may be set to
				.Dv FIRMWARE_GET_NOWARN
				to indicate that errors on firmware load or registration should
				markjUnsubmitted Done Inline Actions s/registering/registration/ markj: s/registering/registration/
				only be logged in case of
				.Nm booverbose .
	If the image is not yet registered with the system,			If the image is not yet registered with the system,
	the function tries to load it.			the functions try to load it.
	This involves the linker subsystem and disk access, so			This involves the linker subsystem and disk access, so
	.Fn firmware_get			.Fn firmware_get
				or
				.Fn firmware_get_flags
	must not be called with any locks (except for			must not be called with any locks (except for
	.Va Giant ) .			.Va Giant ) .
	Note also that if the firmware image is loaded from a filesystem			Note also that if the firmware image is loaded from a filesystem
	it must already be mounted.			it must already be mounted.
	In particular this means that it may be necessary to defer requests			In particular this means that it may be necessary to defer requests
	from a driver attach method unless it is known the root filesystem is			from a driver attach method unless it is known the root filesystem is
	already mounted.			already mounted.
	.Pp			.Pp
	On success,			On success,
	.Fn firmware_get			.Fn firmware_get
	returns a pointer to the image description and increases the reference count			and
				.Fn firmware_get_flags
				return a pointer to the image description and increase the reference count
	for this image.			for this image.
	On failure, the function returns NULL.			On failure, the functions return NULL.
	.Pp			.Pp
	.Fn firmware_put			.Fn firmware_put
	drops a reference to a firmware image.			drops a reference to a firmware image.
	The			The
	.Fa flags			.Fa flags
	argument may be set to			argument may be set to
	.Dv FIRMWARE_UNLOAD			.Dv FIRMWARE_UNLOAD
	to indicate that			to indicate that
	Show All 15 Lines
	or manually loaded with			or manually loaded with
	.Xr kldload 8 .			.Xr kldload 8 .
	However, a system can implement additional mechanisms to bring			However, a system can implement additional mechanisms to bring
	these images in memory before calling			these images in memory before calling
	.Fn firmware_register .			.Fn firmware_register .
	.Pp			.Pp
	When			When
	.Fn firmware_get			.Fn firmware_get
				or
				.Fn firmware_get_flags
	does not find the requested image, it tries to load it using			does not find the requested image, it tries to load it using
	one of the available loading mechanisms.			one of the available loading mechanisms.
	At the moment, there is only one, namely			At the moment, there is only one, namely
	.Nm Loadable kernel modules :			.Nm Loadable kernel modules .
	.Pp			.Pp
	A firmware image named			A firmware image named
	.Nm foo			.Nm foo
	is looked up by trying to load the module named			is looked up by trying to load the module named
	.Nm foo.ko ,			.Nm foo.ko ,
	using the facilities described in			using the facilities described in
	.Xr kld 4 .			.Xr kld 4 .
	In particular, images are looked up in the directories specified			In particular, images are looked up in the directories specified
	by the sysctl variable			by the sysctl variable
	.Nm kern.module_path			.Nm kern.module_path
	which on most systems defaults to			which on most systems defaults to
	.Nm /boot/kernel;/boot/modules .			.Nm /boot/kernel;/boot/modules .
	.Pp			.Pp
	Note that in case a module contains multiple images,			Note that in case a module contains multiple images,
	the caller should first request a			the caller should first request a
	.Fn firmware_get			.Fn firmware_get
				or
				.Fn firmware_get_flags
	for the first image contained in the module, followed by requests			for the first image contained in the module, followed by requests
	for the other images.			for the other images.
	.Sh BUILDING FIRMWARE LOADABLE MODULES			.Sh BUILDING FIRMWARE LOADABLE MODULES
	A firmware module is built by embedding the			A firmware module is built by embedding the
	.Nm firmware image			.Nm firmware image
	into a suitable loadable kernel module that calls			into a suitable loadable kernel module that calls
	.Fn firmware_register			.Fn firmware_register
	on loading, and			on loading, and
	▲ Show 20 Lines • Show All 61 Lines • Show Last 20 Lines