share/man/man9/regulator.9

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