Documentation/hwmon/pmbus-core

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