Documentation/hwmon/pmbus-core.rst

2 PMBus core driver and internal API
8 [from pmbus.org] The Power Management Bus (PMBus) is an open standard
18 promoted by the PMBus Implementers Forum (PMBus-IF), comprising 30+ adopters
21 Unfortunately, while PMBus commands are standardized, there are no mandatory
23 Also, different PMBUs devices act differently if non-supported commands are
27 Despite all those difficulties, a generic PMBus device driver is still useful
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
34 to modify the core PMBus driver repeatedly for new devices, the PMBus driver was
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
43 PMBus device capabilities auto-detection
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
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).
62 PMBus internal API
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.
69 Standard PMBus commands
72 Standard PMBus commands (commands values 0x00 to 0xff) are defined in the PMBUs
75 Virtual PMBus commands
78 Virtual PMBus commands are provided to enable support for non-standard
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
101 handled more efficiently and thus preferred. Either case, the calling PMBus
103 or writing virtual registers (in other words, the PMBus core code will never
106 PMBus driver information
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.
121   non-standard PMBus commands to standard commands, or to augment standard
127 Many PMBus devices support SMBus PEC (Packet Error Checking). If supported
128 by both the I2C adapter and by the PMBus chip, it is by default enabled.
129 If PEC is supported, the PMBus core driver adds an attribute named 'pec' to
131 communication with the PMBus chip.
141 specific command, but that a standard PMBus command may exist. Any other
147 which *must* be handled in driver specific code. See "Virtual PMBus Commands"
150 Command execution in the core PMBus driver code is as follows::
199 Determine supported PMBus functionality. This function is only necessary
201 pre-determined. It is currently only used by the generic pmbus driver
202 (pmbus.c).
208 PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C
218 Set PMBus page register to <page> and <phase> for subsequent commands.
258 Execute PMBus "Clear Fault" command on all chip pages.
297 PMBus driver platform data
300 PMBus platform data is defined in include/linux/pmbus.h. Platform data
328 Some PMBus chips respond with valid data when trying to read an unsupported
331 Other PMBus chips don't support the STATUS_CML register, or report
346 Some PMBus chips don't respond with valid data when reading the CAPABILITY
347 register. For such chips, this flag should be set so that the PMBus core
354 Some PMBus chips end up in an undefined state when trying to read an
356 chip pmbus controller to a known state after a failed register check.