power/regulator/machine.rst

0001 ==================================
0002 Regulator Machine Driver Interface
0003 ==================================
0004
0005 The regulator machine driver interface is intended for board/machine specific
0006 initialisation code to configure the regulator subsystem.
0007
0008 Consider the following machine::
0009
0010   Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
0011                |
0012                +-> [Consumer B @ 3.3V]
0013
0014 The drivers for consumers A & B must be mapped to the correct regulator in
0015 order to control their power supplies. This mapping can be achieved in machine
0016 initialisation code by creating a struct regulator_consumer_supply for
0017 each regulator::
0018
0019   struct regulator_consumer_supply {
0020         const char *dev_name;   /* consumer dev_name() */
0021         const char *supply;     /* consumer supply - e.g. "vcc" */
0022   };
0023
0024 e.g. for the machine above::
0025
0026   static struct regulator_consumer_supply regulator1_consumers[] = {
0027         REGULATOR_SUPPLY("Vcc", "consumer B"),
0028   };
0029
0030   static struct regulator_consumer_supply regulator2_consumers[] = {
0031         REGULATOR_SUPPLY("Vcc", "consumer A"),
0032   };
0033
0034 This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2
0035 to the 'Vcc' supply for Consumer A.
0036
0037 Constraints can now be registered by defining a struct regulator_init_data
0038 for each regulator power domain. This structure also maps the consumers
0039 to their supply regulators::
0040
0041   static struct regulator_init_data regulator1_data = {
0042         .constraints = {
0043                 .name = "Regulator-1",
0044                 .min_uV = 3300000,
0045                 .max_uV = 3300000,
0046                 .valid_modes_mask = REGULATOR_MODE_NORMAL,
0047         },
0048         .num_consumer_supplies = ARRAY_SIZE(regulator1_consumers),
0049         .consumer_supplies = regulator1_consumers,
0050   };
0051
0052 The name field should be set to something that is usefully descriptive
0053 for the board for configuration of supplies for other regulators and
0054 for use in logging and other diagnostic output.  Normally the name
0055 used for the supply rail in the schematic is a good choice.  If no
0056 name is provided then the subsystem will choose one.
0057
0058 Regulator-1 supplies power to Regulator-2. This relationship must be registered
0059 with the core so that Regulator-1 is also enabled when Consumer A enables its
0060 supply (Regulator-2). The supply regulator is set by the supply_regulator
0061 field below and co::
0062
0063   static struct regulator_init_data regulator2_data = {
0064         .supply_regulator = "Regulator-1",
0065         .constraints = {
0066                 .min_uV = 1800000,
0067                 .max_uV = 2000000,
0068                 .valid_ops_mask = REGULATOR_CHANGE_VOLTAGE,
0069                 .valid_modes_mask = REGULATOR_MODE_NORMAL,
0070         },
0071         .num_consumer_supplies = ARRAY_SIZE(regulator2_consumers),
0072         .consumer_supplies = regulator2_consumers,
0073   };
0074
0075 Finally the regulator devices must be registered in the usual manner::
0076
0077   static struct platform_device regulator_devices[] = {
0078         {
0079                 .name = "regulator",
0080                 .id = DCDC_1,
0081                 .dev = {
0082                         .platform_data = &regulator1_data,
0083                 },
0084         },
0085         {
0086                 .name = "regulator",
0087                 .id = DCDC_2,
0088                 .dev = {
0089                         .platform_data = &regulator2_data,
0090                 },
0091         },
0092   };
0093   /* register regulator 1 device */
0094   platform_device_register(&regulator_devices[0]);
0095
0096   /* register regulator 2 device */
0097   platform_device_register(&regulator_devices[1]);