1.\" Copyright (c) 2021 Emmanuel Vadot <manu@freebsd.org> 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 13.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 14.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 15.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 16.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 17.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 18.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 19.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 20.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 21.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 22.\" 23.Dd June 14, 2021 24.Dt REGULATOR 9 25.Os 26.Sh NAME 27.Nm regulator , 28.Nm regulator_get_by_name , 29.Nm regulator_get_by_id , 30.Nm regulator_release , 31.Nm regulator_get_name , 32.Nm regulator_enable , 33.Nm regulator_disable , 34.Nm regulator_stop , 35.Nm regulator_status , 36.Nm regulator_get_voltage , 37.Nm regulator_set_voltage , 38.Nm regulator_check_voltage , 39.Nm regulator_get_by_ofw_property 40.Nd regulator methods 41.Sh SYNOPSIS 42.Cd "options EXT_RESOURCES" 43.Cd "device regulator" 44.In "dev/extres/regulator/regulator.h" 45.Ft int 46.Fn regulator_get_by_name "device_t cdev" "const char *name" "regulator_t *regulator" 47.Ft int 48.Fn regulator_get_by_id "device_t cdev" "device_t pdev" "intptr_t id" "regulator_t *regulator" 49.Ft int 50.Fn regulator_release "regulator_t regulator" 51.Ft int 52.Fn regulator_get_name "regulator_t regulator" 53.Ft int 54.Fn regulator_enable "regulator_t reg" 55.Ft int 56.Fn regulator_disable "regulator_t reg" 57.Ft int 58.Fn regulator_stop "regulator_t reg" 59.Ft int 60.Fn regulator_status "regulator_t reg" "int *status" 61.Ft int 62.Fn regulator_get_voltage "regulator_t reg" "int *uvolt" 63.Ft int 64.Fn regulator_set_voltage "regulator_t reg" "int min_uvolt" "int max_uvolt" 65.Ft int 66.Fn regulator_check_voltage "regulator_t reg" "int uvolt" 67.Ft int 68.Fn regulator_get_by_ofw_property "device_t dev" "phandle_t node" "char *name" "regulator_t *reg" 69.Sh DESCRIPTION 70The regulator framework allow drivers to enable, disable and change regulator voltage. 71.Sh RETURN VALUES 72All functions returns 0 on success or 73.Er ENODEV 74if the regulator or one of its parent was not found. 75.Sh INTERFACE 76.Bl -tag -width indent 77.It Fn regulator_get_by_name "device_t cdev" "const char *name" "regulator_t *regulator" 78Resolve a regulator based on its name. 79All regulators names are unique. 80This will also increment the refcount on the regulator. 81.It Fn regulator_get_by_id "device_t cdev" "device_t pdev" "intptr_t id" "regulator_t *regulator" 82Resolve a regulator based on its id. 83All regulators ids are unique. 84This will also increment the refcount on the regulator. 85.It Fn regulator_get_by_ofw_property "device_t dev" "phandle_t node" "char *name" "regulator_t *reg" 86Resolve a regulator based on the fdt property named name. 87If node is 0 then the function will get the ofw node itself. 88This will also increment the refcount on the regulator. 89Returns 0 on success or 90.Er ENOENT 91if the ofw property does not exists. 92.It Fn regulator_release "regulator_t regulator" 93This disables the regulator, decrements the refcount on it and frees the regulator variable passed. 94.It Fn regulator_get_name "regulator_t regulator" 95Returns the name of the regulator. 96All regulator names are unique. 97.It Fn regulator_enable "regulator_t reg" 98Enable the regulator. 99If the regulator supports a voltage range, the one configured in the hardware will be the output voltage. 100If the regulator was already enabled by another driver this simply increments the enable counter. 101.It Fn regulator_disable "regulator_t reg" 102Disable the regulator. 103If the regulator was also enabled by another driver this simply decrements the enable counter. 104If the regulator was not previously enabled we will kassert. 105.It Fn regulator_stop "regulator_t reg" 106Disable the regulator in hardware. 107This ensures the regulator is disabled even if it was enabled by bootloader. 108This should not be called on regulator that has previously been enabled by a driver. 109Returns 0 on success or 110.Er EBUSY 111if another consumer enabled it. 112.It Fn regulator_status "regulator_t reg" "int *status" 113Get the hardware status of the regulator. 114status will contain a bit mask with 115thoses possible value : 116.Bl -tag -width indent 117.It REGULATOR_STATUS_ENABLED 118The regulator is enabled. 119.It REGULATOR_STATUS_OVERCURRENT 120The hardware reports that too much current is being drawn. 121.El 122.It Fn regulator_get_voltage "regulator_t reg" "int *uvolt" 123Get the current voltage set for the regulator in microvolts. 124.It Fn regulator_set_voltage "regulator_t reg" "int min_uvolt" "int max_uvolt" 125Change the voltage for the regulator. 126If a range is acceptable by the hardware or driver different values can be provided as min and max. 127Returns 0 on success or 128.Er ERANGE 129if the regulator doesn't support this voltage range. 130.It Fn regulator_check_voltage "regulator_t reg" "int uvolt" 131Checks if the regulator support the given voltage. 132Returns 0 on success or 133.Er ERANGE 134if the regulator doesn't support this voltage range. 135.El 136.Sh HISTORY 137The 138.Nm regulator 139framework first appear in 140.Fx 12.0 . 141The 142.Nm regulator 143framework was written by 144.An Michal Meloun Aq Mt mmel@FreeBSD.org . 145The 146.Nm regulator 147manual page was written by 148.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . 149