Documentation/hwmon/pmbus-core.rst

   1 ==================================
   2 PMBus core driver and internal API
   3 ==================================
   4
   5 Introduction
   6 ============
   7
   8 [from pmbus.org] The Power Management Bus (PMBus) is an open standard
   9 power-management protocol with a fully defined command language that facilitates
  10 communication with power converters and other devices in a power system. The
  11 protocol is implemented over the industry-standard SMBus serial interface and
  12 enables programming, control, and real-time monitoring of compliant power
  13 conversion products. This flexible and highly versatile standard allows for
  14 communication between devices based on both analog and digital technologies, and
  15 provides true interoperability which will reduce design complexity and shorten
  16 time to market for power system designers. Pioneered by leading power supply and
  17 semiconductor companies, this open power system standard is maintained and
  18 promoted by the PMBus Implementers Forum (PMBus-IF), comprising 30+ adopters
  19 with the objective to provide support to, and facilitate adoption among, users.
  20
  21 Unfortunately, while PMBus commands are standardized, there are no mandatory
  22 commands, and manufacturers can add as many non-standard commands as they like.
  23 Also, different PMBUs devices act differently if non-supported commands are
  24 executed. Some devices return an error, some devices return 0xff or 0xffff and
  25 set a status error flag, and some devices may simply hang up.
  26
  27 Despite all those difficulties, a generic PMBus device driver is still useful
  28 and supported since kernel version 2.6.39. However, it was necessary to support
  29 device specific extensions in addition to the core PMBus driver, since it is
  30 simply unknown what new device specific functionality PMBus device developers
  31 come up with next.
  32
  33 To make device specific extensions as scalable as possible, and to avoid having
  34 to modify the core PMBus driver repeatedly for new devices, the PMBus driver was
  35 split into core, generic, and device specific code. The core code (in
  36 pmbus_core.c) provides generic functionality. The generic code (in pmbus.c)
  37 provides support for generic PMBus devices. Device specific code is responsible
  38 for device specific initialization and, if needed, maps device specific
  39 functionality into generic functionality. This is to some degree comparable
  40 to PCI code, where generic code is augmented as needed with quirks for all kinds
  41 of devices.
  42
  43 PMBus device capabilities auto-detection
  44 ========================================
  45
  46 For generic PMBus devices, code in pmbus.c attempts to auto-detect all supported
  47 PMBus commands. Auto-detection is somewhat limited, since there are simply too
  48 many variables to consider. For example, it is almost impossible to autodetect
  49 which PMBus commands are paged and which commands are replicated across all
  50 pages (see the PMBus specification for details on multi-page PMBus devices).
  51
  52 For this reason, it often makes sense to provide a device specific driver if not
  53 all commands can be auto-detected. The data structures in this driver can be
  54 used to inform the core driver about functionality supported by individual
  55 chips.
  56
  57 Some commands are always auto-detected. This applies to all limit commands
  58 (lcrit, min, max, and crit attributes) as well as associated alarm attributes.
  59 Limits and alarm attributes are auto-detected because there are simply too many
  60 possible combinations to provide a manual configuration interface.
  61
  62 PMBus internal API
  63 ==================
  64
  65 The API between core and device specific PMBus code is defined in
  66 drivers/hwmon/pmbus/pmbus.h. In addition to the internal API, pmbus.h defines
  67 standard PMBus commands and virtual PMBus commands.
  68
  69 Standard PMBus commands
  70 -----------------------
  71
  72 Standard PMBus commands (commands values 0x00 to 0xff) are defined in the PMBUs
  73 specification.
  74
  75 Virtual PMBus commands
  76 ----------------------
  77
  78 Virtual PMBus commands are provided to enable support for non-standard
  79 functionality which has been implemented by several chip vendors and is thus
  80 desirable to support.
  81
  82 Virtual PMBus commands start with command value 0x100 and can thus easily be
  83 distinguished from standard PMBus commands (which can not have values larger
  84 than 0xff). Support for virtual PMBus commands is device specific and thus has
  85 to be implemented in device specific code.
  86
  87 Virtual commands are named PMBUS_VIRT_xxx and start with PMBUS_VIRT_BASE. All
  88 virtual commands are word sized.
  89
  90 There are currently two types of virtual commands.
  91
  92 - READ commands are read-only; writes are either ignored or return an error.
  93 - RESET commands are read/write. Reading reset registers returns zero
  94   (used for detection), writing any value causes the associated history to be
  95   reset.
  96
  97 Virtual commands have to be handled in device specific driver code. Chip driver
  98 code returns non-negative values if a virtual command is supported, or a
  99 negative error code if not. The chip driver may return -ENODATA or any other
 100 Linux error code in this case, though an error code other than -ENODATA is
 101 handled more efficiently and thus preferred. Either case, the calling PMBus
 102 core code will abort if the chip driver returns an error code when reading
 103 or writing virtual registers (in other words, the PMBus core code will never
 104 send a virtual command to a chip).
 105
 106 PMBus driver information
 107 ------------------------
 108
 109 PMBus driver information, defined in struct pmbus_driver_info, is the main means
 110 for device specific drivers to pass information to the core PMBus driver.
 111 Specifically, it provides the following information.
 112
 113 - For devices supporting its data in Direct Data Format, it provides coefficients
 114   for converting register values into normalized data. This data is usually
 115   provided by chip manufacturers in device datasheets.
 116 - Supported chip functionality can be provided to the core driver. This may be
 117   necessary for chips which react badly if non-supported commands are executed,
 118   and/or to speed up device detection and initialization.
 119 - Several function entry points are provided to support overriding and/or
 120   augmenting generic command execution. This functionality can be used to map
 121   non-standard PMBus commands to standard commands, or to augment standard
 122   command return values with device specific information.
 123
 124 API functions
 125 =============
 126
 127 Functions provided by chip driver
 128 ---------------------------------
 129
 130 All functions return the command return value (read) or zero (write) if
 131 successful. A return value of -ENODATA indicates that there is no manufacturer
 132 specific command, but that a standard PMBus command may exist. Any other
 133 negative return value indicates that the commands does not exist for this
 134 chip, and that no attempt should be made to read or write the standard
 135 command.
 136
 137 As mentioned above, an exception to this rule applies to virtual commands,
 138 which *must* be handled in driver specific code. See "Virtual PMBus Commands"
 139 above for more details.
 140
 141 Command execution in the core PMBus driver code is as follows::
 142
 143         if (chip_access_function) {
 144                 status = chip_access_function();
 145                 if (status != -ENODATA)
 146                         return status;
 147         }
 148         if (command >= PMBUS_VIRT_BASE) /* For word commands/registers only */
 149                 return -EINVAL;
 150         return generic_access();
 151
 152 Chip drivers may provide pointers to the following functions in struct
 153 pmbus_driver_info. All functions are optional.
 154
 155 ::
 156
 157   int (*read_byte_data)(struct i2c_client *client, int page, int reg);
 158
 159 Read byte from page <page>, register <reg>.
 160 <page> may be -1, which means "current page".
 161
 162
 163 ::
 164
 165   int (*read_word_data)(struct i2c_client *client, int page, int phase,
 166                         int reg);
 167
 168 Read word from page <page>, phase <pase>, register <reg>. If the chip does not
 169 support multiple phases, the phase parameter can be ignored. If the chip
 170 supports multiple phases, a phase value of 0xff indicates all phases.
 171
 172 ::
 173
 174   int (*write_word_data)(struct i2c_client *client, int page, int reg,
 175                          u16 word);
 176
 177 Write word to page <page>, register <reg>.
 178
 179 ::
 180
 181   int (*write_byte)(struct i2c_client *client, int page, u8 value);
 182
 183 Write byte to page <page>, register <reg>.
 184 <page> may be -1, which means "current page".
 185
 186 ::
 187
 188   int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info);
 189
 190 Determine supported PMBus functionality. This function is only necessary
 191 if a chip driver supports multiple chips, and the chip functionality is not
 192 pre-determined. It is currently only used by the generic pmbus driver
 193 (pmbus.c).
 194
 195 Functions exported by core driver
 196 ---------------------------------
 197
 198 Chip drivers are expected to use the following functions to read or write
 199 PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C
 200 commands are used, the chip driver code must not directly modify the current
 201 page, since the selected page is cached in the core driver and the core driver
 202 will assume that it is selected. Using pmbus_set_page() to select a new page
 203 is mandatory.
 204
 205 ::
 206
 207   int pmbus_set_page(struct i2c_client *client, u8 page, u8 phase);
 208
 209 Set PMBus page register to <page> and <phase> for subsequent commands.
 210 If the chip does not support multiple phases, the phase parameter is
 211 ignored. Otherwise, a phase value of 0xff selects all phases.
 212
 213 ::
 214
 215   int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 phase,
 216                            u8 reg);
 217
 218 Read word data from <page>, <phase>, <reg>. Similar to
 219 i2c_smbus_read_word_data(), but selects page and phase first. If the chip does
 220 not support multiple phases, the phase parameter is ignored. Otherwise, a phase
 221 value of 0xff selects all phases.
 222
 223 ::
 224
 225   int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg,
 226                             u16 word);
 227
 228 Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but
 229 selects page first.
 230
 231 ::
 232
 233   int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg);
 234
 235 Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but
 236 selects page first. <page> may be -1, which means "current page".
 237
 238 ::
 239
 240   int pmbus_write_byte(struct i2c_client *client, int page, u8 value);
 241
 242 Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but
 243 selects page first. <page> may be -1, which means "current page".
 244
 245 ::
 246
 247   void pmbus_clear_faults(struct i2c_client *client);
 248
 249 Execute PMBus "Clear Fault" command on all chip pages.
 250 This function calls the device specific write_byte function if defined.
 251 Therefore, it must _not_ be called from that function.
 252
 253 ::
 254
 255   bool pmbus_check_byte_register(struct i2c_client *client, int page, int reg);
 256
 257 Check if byte register exists. Return true if the register exists, false
 258 otherwise.
 259 This function calls the device specific write_byte function if defined to
 260 obtain the chip status. Therefore, it must _not_ be called from that function.
 261
 262 ::
 263
 264   bool pmbus_check_word_register(struct i2c_client *client, int page, int reg);
 265
 266 Check if word register exists. Return true if the register exists, false
 267 otherwise.
 268 This function calls the device specific write_byte function if defined to
 269 obtain the chip status. Therefore, it must _not_ be called from that function.
 270
 271 ::
 272
 273   int pmbus_do_probe(struct i2c_client *client, struct pmbus_driver_info *info);
 274
 275 Execute probe function. Similar to standard probe function for other drivers,
 276 with the pointer to struct pmbus_driver_info as additional argument. Calls
 277 identify function if supported. Must only be called from device probe
 278 function.
 279
 280 ::
 281
 282   const struct pmbus_driver_info
 283         *pmbus_get_driver_info(struct i2c_client *client);
 284
 285 Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe().
 286
 287
 288 PMBus driver platform data
 289 ==========================
 290
 291 PMBus platform data is defined in include/linux/pmbus.h. Platform data
 292 currently only provides a flag field with a single bit used::
 293
 294         #define PMBUS_SKIP_STATUS_CHECK (1 << 0)
 295
 296         struct pmbus_platform_data {
 297                 u32 flags;              /* Device specific flags */
 298         };
 299
 300
 301 Flags
 302 -----
 303
 304 PMBUS_SKIP_STATUS_CHECK
 305         During register detection, skip checking the status register for
 306         communication or command errors.
 307
 308 Some PMBus chips respond with valid data when trying to read an unsupported
 309 register. For such chips, checking the status register is mandatory when
 310 trying to determine if a chip register exists or not.
 311 Other PMBus chips don't support the STATUS_CML register, or report
 312 communication errors for no explicable reason. For such chips, checking the
 313 status register must be disabled.
 314
 315 Some i2c controllers do not support single-byte commands (write commands with
 316 no data, i2c_smbus_write_byte()). With such controllers, clearing the status
 317 register is impossible, and the PMBUS_SKIP_STATUS_CHECK flag must be set.