diff --git a/share/man/man9/nvmem.9 b/share/man/man9/nvmem.9 index 281bb93ba80b..9dd7368c874c 100644 --- a/share/man/man9/nvmem.9 +++ b/share/man/man9/nvmem.9 @@ -1,157 +1,156 @@ .\" Copyright (c) 2018 Emmanuel Vadot .\" .\" 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, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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 July 24, 2018 .Dt nvmem 9 .Os .Sh NAME .Nm nvmem .Nm nvmem_get_cell_len , .Nm nvmem_read_cell_by_name , .Nm nvmem_read_cell_by_idx , .Nm nvmem_write_cell_by_name , .Nm nvmem_write_cell_by_idx , .Sh SYNOPSIS -.Cd "options EXT_RESOURCES" .Cd "options FDT" .Cd "device nvmem" .In sys/extres/nvmem/nvmem.h .Ft int .Fn nvmem_get_cell_len "phandle_t node" "const char *name" .Ft int .Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" .Ft int .Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" .Ft int .Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" .Ft int .Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" .Sh DESCRIPTION On some embedded boards, the manufacturer stored some data on a NVMEM (Non-Volatile Memory), this is generally stored in some eeprom or fuses. .Pp The .Nm API consist of helpers functions for consumer and device methods for providers. .Sh FUNCTIONS .Bl -tag -width indent .It Fn nvmem_get_cell_len "phandle_t node" "const char *name" Get the size of the cell base on the reg property on the node. Return the size or ENOENT if the cell name wasn't found .It Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" Get the cell content based on the name. Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, EINVAL if the size isn't correct. .It Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" Get the cell content based on the id. Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, EINVAL if the size isn't correct. .It Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" Write the cell content based on the name. Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, EINVAL if the size isn't correct. .It Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" Write the cell content based on the id. Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, EINVAL if the size isn't correct. .El .Sh DEVICE METHODS .Bl -tag -width indent .It Fn nvmem_read "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" Provider device method to read a cell content. .It Fn nvmem_write "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" Provider device method to write a cell content. .El .Sh EXAMPLES Consider this DTS .Bd -literal /* Provider */ eeprom: eeprom@20000 { board_id: id@0 { reg = <0x0 0x4>; }; }; /* Consumer */ device@30000 { ... nvmem-cells = <&board_id> nvmem-cell-names = "boardid"; }; .Ed .Pp The device driver for eeprom@20000 needs to expose itself as a provider .Bd -literal #include "nvmem_if.h" int foo_nvmem_read(device_t dev, uint32_t offset, uint32_t size, uint8_t *buffer) { /* Read the data */ } int foo_attach(device_t dev) { phandle_t node; node = ofw_bus_get_node(dev); ... /* Registering the device so the consumers can find us */ OF_device_register_xref(OF_xref_from_node(node), dev); ... } static device_method_t foo_methods[] = { ... /* nvmem interface */ DEVMETHOD(nvmem_read, foo_nvmem_read), /* Terminate method list */ DEVMETHOD_END }; .Ed .Pp The consumer device driver for device@30000 can now read the nvmem data .Bd -literal int bar_attach(device_t dev) { phandle_t node; uint32_t boardid; ... node = ofw_bus_get_node(dev); nvmem_read_cell_by_name(node, "boardid", (void *)&boardid, sizeof(boardid)); ... } .Ed .Sh HISTORY The nvmem related function first appear in .Fx 12.0 . The nvmem interface and manual page was written by .An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/share/man/man9/regulator.9 b/share/man/man9/regulator.9 index d4450de6eef1..52e24c18afe8 100644 --- a/share/man/man9/regulator.9 +++ b/share/man/man9/regulator.9 @@ -1,148 +1,147 @@ .\" Copyright (c) 2021 Emmanuel Vadot .\" .\" 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, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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 June 14, 2021 .Dt REGULATOR 9 .Os .Sh NAME .Nm regulator , .Nm regulator_get_by_name , .Nm regulator_get_by_id , .Nm regulator_release , .Nm regulator_get_name , .Nm regulator_enable , .Nm regulator_disable , .Nm regulator_stop , .Nm regulator_status , .Nm regulator_get_voltage , .Nm regulator_set_voltage , .Nm regulator_check_voltage , .Nm regulator_get_by_ofw_property .Nd regulator methods .Sh SYNOPSIS -.Cd "options EXT_RESOURCES" .Cd "device regulator" .In "dev/extres/regulator/regulator.h" .Ft int .Fn regulator_get_by_name "device_t cdev" "const char *name" "regulator_t *regulator" .Ft int .Fn regulator_get_by_id "device_t cdev" "device_t pdev" "intptr_t id" "regulator_t *regulator" .Ft int .Fn regulator_release "regulator_t regulator" .Ft int .Fn regulator_get_name "regulator_t regulator" .Ft int .Fn regulator_enable "regulator_t reg" .Ft int .Fn regulator_disable "regulator_t reg" .Ft int .Fn regulator_stop "regulator_t reg" .Ft int .Fn regulator_status "regulator_t reg" "int *status" .Ft int .Fn regulator_get_voltage "regulator_t reg" "int *uvolt" .Ft int .Fn regulator_set_voltage "regulator_t reg" "int min_uvolt" "int max_uvolt" .Ft int .Fn regulator_check_voltage "regulator_t reg" "int uvolt" .Ft int .Fn regulator_get_by_ofw_property "device_t dev" "phandle_t node" "char *name" "regulator_t *reg" .Sh DESCRIPTION The regulator framework allow drivers to enable, disable and change regulator voltage. .Sh RETURN VALUES All functions returns 0 on success or .Er ENODEV if the regulator or one of its parent was not found. .Sh INTERFACE .Bl -tag -width indent .It Fn regulator_get_by_name "device_t cdev" "const char *name" "regulator_t *regulator" Resolve a regulator based on its name. All regulators names are unique. This will also increment the refcount on the regulator. .It Fn regulator_get_by_id "device_t cdev" "device_t pdev" "intptr_t id" "regulator_t *regulator" Resolve a regulator based on its id. All regulators ids are unique. This will also increment the refcount on the regulator. .It Fn regulator_get_by_ofw_property "device_t dev" "phandle_t node" "char *name" "regulator_t *reg" Resolve a regulator based on the fdt property named name. If node is 0 then the function will get the ofw node itself. This will also increment the refcount on the regulator. Returns 0 on success or .Er ENOENT if the ofw property does not exists. .It Fn regulator_release "regulator_t regulator" This disables the regulator, decrements the refcount on it and frees the regulator variable passed. .It Fn regulator_get_name "regulator_t regulator" Returns the name of the regulator. All regulator names are unique. .It Fn regulator_enable "regulator_t reg" Enable the regulator. If the regulator supports a voltage range, the one configured in the hardware will be the output voltage. If the regulator was already enabled by another driver this simply increments the enable counter. .It Fn regulator_disable "regulator_t reg" Disable the regulator. If the regulator was also enabled by another driver this simply decrements the enable counter. If the regulator was not previously enabled we will kassert. .It Fn regulator_stop "regulator_t reg" Disable the regulator in hardware. This ensures the regulator is disabled even if it was enabled by bootloader. This should not be called on regulator that has previously been enabled by a driver. Returns 0 on success or .Er EBUSY if another consumer enabled it. .It Fn regulator_status "regulator_t reg" "int *status" Get the hardware status of the regulator. status will contain a bit mask with thoses possible value : .Bl -tag -width indent .It REGULATOR_STATUS_ENABLED The regulator is enabled. .It REGULATOR_STATUS_OVERCURRENT The hardware reports that too much current is being drawn. .El .It Fn regulator_get_voltage "regulator_t reg" "int *uvolt" Get the current voltage set for the regulator in microvolts. .It Fn regulator_set_voltage "regulator_t reg" "int min_uvolt" "int max_uvolt" Change the voltage for the regulator. If a range is acceptable by the hardware or driver different values can be provided as min and max. Returns 0 on success or .Er ERANGE if the regulator doesn't support this voltage range. .It Fn regulator_check_voltage "regulator_t reg" "int uvolt" Checks if the regulator support the given voltage. Returns 0 on success or .Er ERANGE if the regulator doesn't support this voltage range. .El .Sh HISTORY The .Nm regulator framework first appear in .Fx 12.0 . The .Nm regulator framework was written by .An Michal Meloun Aq Mt mmel@FreeBSD.org . The .Nm regulator manual page was written by .An Emmanuel Vadot Aq Mt manu@FreeBSD.org .