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 "device regulator" 43.In "dev/extres/regulator/regulator.h" 44.Ft int 45.Fn regulator_get_by_name "device_t cdev" "const char *name" "regulator_t *regulator" 46.Ft int 47.Fn regulator_get_by_id "device_t cdev" "device_t pdev" "intptr_t id" "regulator_t *regulator" 48.Ft int 49.Fn regulator_release "regulator_t regulator" 50.Ft int 51.Fn regulator_get_name "regulator_t regulator" 52.Ft int 53.Fn regulator_enable "regulator_t reg" 54.Ft int 55.Fn regulator_disable "regulator_t reg" 56.Ft int 57.Fn regulator_stop "regulator_t reg" 58.Ft int 59.Fn regulator_status "regulator_t reg" "int *status" 60.Ft int 61.Fn regulator_get_voltage "regulator_t reg" "int *uvolt" 62.Ft int 63.Fn regulator_set_voltage "regulator_t reg" "int min_uvolt" "int max_uvolt" 64.Ft int 65.Fn regulator_check_voltage "regulator_t reg" "int uvolt" 66.Ft int 67.Fn regulator_get_by_ofw_property "device_t dev" "phandle_t node" "char *name" "regulator_t *reg" 68.Sh DESCRIPTION 69The regulator framework allow drivers to enable, disable and change regulator voltage. 70.Sh RETURN VALUES 71All functions returns 0 on success or 72.Er ENODEV 73if the regulator or one of its parent was not found. 74.Sh INTERFACE 75.Bl -tag -width indent 76.It Fn regulator_get_by_name "device_t cdev" "const char *name" "regulator_t *regulator" 77Resolve a regulator based on its name. 78All regulators names are unique. 79This will also increment the refcount on the regulator. 80.It Fn regulator_get_by_id "device_t cdev" "device_t pdev" "intptr_t id" "regulator_t *regulator" 81Resolve a regulator based on its id. 82All regulators ids are unique. 83This will also increment the refcount on the regulator. 84.It Fn regulator_get_by_ofw_property "device_t dev" "phandle_t node" "char *name" "regulator_t *reg" 85Resolve a regulator based on the fdt property named name. 86If node is 0 then the function will get the ofw node itself. 87This will also increment the refcount on the regulator. 88Returns 0 on success or 89.Er ENOENT 90if the ofw property does not exists. 91.It Fn regulator_release "regulator_t regulator" 92This disables the regulator, decrements the refcount on it and frees the regulator variable passed. 93.It Fn regulator_get_name "regulator_t regulator" 94Returns the name of the regulator. 95All regulator names are unique. 96.It Fn regulator_enable "regulator_t reg" 97Enable the regulator. 98If the regulator supports a voltage range, the one configured in the hardware will be the output voltage. 99If the regulator was already enabled by another driver this simply increments the enable counter. 100.It Fn regulator_disable "regulator_t reg" 101Disable the regulator. 102If the regulator was also enabled by another driver this simply decrements the enable counter. 103If the regulator was not previously enabled we will kassert. 104.It Fn regulator_stop "regulator_t reg" 105Disable the regulator in hardware. 106This ensures the regulator is disabled even if it was enabled by bootloader. 107This should not be called on regulator that has previously been enabled by a driver. 108Returns 0 on success or 109.Er EBUSY 110if another consumer enabled it. 111.It Fn regulator_status "regulator_t reg" "int *status" 112Get the hardware status of the regulator. 113status will contain a bit mask with 114thoses possible value : 115.Bl -tag -width indent 116.It REGULATOR_STATUS_ENABLED 117The regulator is enabled. 118.It REGULATOR_STATUS_OVERCURRENT 119The hardware reports that too much current is being drawn. 120.El 121.It Fn regulator_get_voltage "regulator_t reg" "int *uvolt" 122Get the current voltage set for the regulator in microvolts. 123.It Fn regulator_set_voltage "regulator_t reg" "int min_uvolt" "int max_uvolt" 124Change the voltage for the regulator. 125If a range is acceptable by the hardware or driver different values can be provided as min and max. 126Returns 0 on success or 127.Er ERANGE 128if the regulator doesn't support this voltage range. 129.It Fn regulator_check_voltage "regulator_t reg" "int uvolt" 130Checks if the regulator support the given voltage. 131Returns 0 on success or 132.Er ERANGE 133if the regulator doesn't support this voltage range. 134.El 135.Sh HISTORY 136The 137.Nm regulator 138framework first appear in 139.Fx 12.0 . 140The 141.Nm regulator 142framework was written by 143.An Michal Meloun Aq Mt mmel@FreeBSD.org . 144The 145.Nm regulator 146manual page was written by 147.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . 148