Documentation/power/regulator/machine.txt

   1 Regulator Machine Driver Interface
   2 ===================================
   3
   4 The regulator machine driver interface is intended for board/machine specific
   5 initialisation code to configure the regulator subsystem. Typical things that
   6 machine drivers would do are :-
   7
   8  1. Regulator -> Device mapping.
   9  2. Regulator supply configuration.
  10  3. Power Domain constraint setting.
  11
  12
  13
  14 1. Regulator -> device mapping
  15 ==============================
  16 Consider the following machine :-
  17
  18   Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
  19                |
  20                +-> [Consumer B @ 3.3V]
  21
  22 The drivers for consumers A & B must be mapped to the correct regulator in
  23 order to control their power supply. This mapping can be achieved in machine
  24 initialisation code by calling :-
  25
  26 int regulator_set_device_supply(const char *regulator, struct device *dev,
  27                                 const char *supply);
  28
  29 and is shown with the following code :-
  30
  31 regulator_set_device_supply("Regulator-1", devB, "Vcc");
  32 regulator_set_device_supply("Regulator-2", devA, "Vcc");
  33
  34 This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2
  35 to the 'Vcc' supply for Consumer A.
  36
  37
  38 2. Regulator supply configuration.
  39 ==================================
  40 Consider the following machine (again) :-
  41
  42   Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
  43                |
  44                +-> [Consumer B @ 3.3V]
  45
  46 Regulator-1 supplies power to Regulator-2. This relationship must be registered
  47 with the core so that Regulator-1 is also enabled when Consumer A enables it's
  48 supply (Regulator-2).
  49
  50 This relationship can be register with the core via :-
  51
  52 int regulator_set_supply(const char *regulator, const char *regulator_supply);
  53
  54 In this example we would use the following code :-
  55
  56 regulator_set_supply("Regulator-2", "Regulator-1");
  57
  58 Relationships can be queried by calling :-
  59
  60 const char *regulator_get_supply(const char *regulator);
  61
  62
  63 3. Power Domain constraint setting.
  64 ===================================
  65 Each power domain within a system has physical constraints on voltage and
  66 current. This must be defined in software so that the power domain is always
  67 operated within specifications.
  68
  69 Consider the following machine (again) :-
  70
  71   Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
  72                |
  73                +-> [Consumer B @ 3.3V]
  74
  75 This gives us two regulators and two power domains:
  76
  77                    Domain 1: Regulator-2, Consumer B.
  78                    Domain 2: Consumer A.
  79
  80 Constraints can be registered by calling :-
  81
  82 int regulator_set_platform_constraints(const char *regulator,
  83         struct regulation_constraints *constraints);
  84
  85 The example is defined as follows :-
  86
  87 struct regulation_constraints domain_1 = {
  88         .min_uV = 3300000,
  89         .max_uV = 3300000,
  90         .valid_modes_mask = REGULATOR_MODE_NORMAL,
  91 };
  92
  93 struct regulation_constraints domain_2 = {
  94         .min_uV = 1800000,
  95         .max_uV = 2000000,
  96         .valid_ops_mask = REGULATOR_CHANGE_VOLTAGE,
  97         .valid_modes_mask = REGULATOR_MODE_NORMAL,
  98 };
  99
 100 regulator_set_platform_constraints("Regulator-1", &domain_1);
 101 regulator_set_platform_constraints("Regulator-2", &domain_2);