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 PEC Support
125 ===========
126
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
130 the I2C device. This attribute can be used to control PEC support in the
131 communication with the PMBus chip.
132
133 API functions
134 =============
135
136 Functions provided by chip driver
137 ---------------------------------
138
139 All functions return the command return value (read) or zero (write) if
140 successful. A return value of -ENODATA indicates that there is no manufacturer
141 specific command, but that a standard PMBus command may exist. Any other
142 negative return value indicates that the commands does not exist for this
143 chip, and that no attempt should be made to read or write the standard
144 command.
145
146 As mentioned above, an exception to this rule applies to virtual commands,
147 which *must* be handled in driver specific code. See "Virtual PMBus Commands"
148 above for more details.
149
150 Command execution in the core PMBus driver code is as follows::
151
152 if (chip_access_function) {
153 status = chip_access_function();
154 if (status != -ENODATA)
155 return status;
156 }
157 if (command >= PMBUS_VIRT_BASE) /* For word commands/registers only */
158 return -EINVAL;
159 return generic_access();
160
161 Chip drivers may provide pointers to the following functions in struct
162 pmbus_driver_info. All functions are optional.
163
164 ::
165
166 int (*read_byte_data)(struct i2c_client *client, int page, int reg);
167
168 Read byte from page <page>, register <reg>.
169 <page> may be -1, which means "current page".
170
171
172 ::
173
174 int (*read_word_data)(struct i2c_client *client, int page, int phase,
175 int reg);
176
177 Read word from page <page>, phase <phase>, register <reg>. If the chip does not
178 support multiple phases, the phase parameter can be ignored. If the chip
179 supports multiple phases, a phase value of 0xff indicates all phases.
180
181 ::
182
183 int (*write_word_data)(struct i2c_client *client, int page, int reg,
184 u16 word);
185
186 Write word to page <page>, register <reg>.
187
188 ::
189
190 int (*write_byte)(struct i2c_client *client, int page, u8 value);
191
192 Write byte to page <page>, register <reg>.
193 <page> may be -1, which means "current page".
194
195 ::
196
197 int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info);
198
199 Determine supported PMBus functionality. This function is only necessary
200 if a chip driver supports multiple chips, and the chip functionality is not
201 pre-determined. It is currently only used by the generic pmbus driver
202 (pmbus.c).
203
204 Functions exported by core driver
205 ---------------------------------
206
207 Chip drivers are expected to use the following functions to read or write
208 PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C
209 commands are used, the chip driver code must not directly modify the current
210 page, since the selected page is cached in the core driver and the core driver
211 will assume that it is selected. Using pmbus_set_page() to select a new page
212 is mandatory.
213
214 ::
215
216 int pmbus_set_page(struct i2c_client *client, u8 page, u8 phase);
217
218 Set PMBus page register to <page> and <phase> for subsequent commands.
219 If the chip does not support multiple phases, the phase parameter is
220 ignored. Otherwise, a phase value of 0xff selects all phases.
221
222 ::
223
224 int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 phase,
225 u8 reg);
226
227 Read word data from <page>, <phase>, <reg>. Similar to
228 i2c_smbus_read_word_data(), but selects page and phase first. If the chip does
229 not support multiple phases, the phase parameter is ignored. Otherwise, a phase
230 value of 0xff selects all phases.
231
232 ::
233
234 int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg,
235 u16 word);
236
237 Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but
238 selects page first.
239
240 ::
241
242 int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg);
243
244 Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but
245 selects page first. <page> may be -1, which means "current page".
246
247 ::
248
249 int pmbus_write_byte(struct i2c_client *client, int page, u8 value);
250
251 Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but
252 selects page first. <page> may be -1, which means "current page".
253
254 ::
255
256 void pmbus_clear_faults(struct i2c_client *client);
257
258 Execute PMBus "Clear Fault" command on all chip pages.
259 This function calls the device specific write_byte function if defined.
260 Therefore, it must _not_ be called from that function.
261
262 ::
263
264 bool pmbus_check_byte_register(struct i2c_client *client, int page, int reg);
265
266 Check if byte 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 bool pmbus_check_word_register(struct i2c_client *client, int page, int reg);
274
275 Check if word register exists. Return true if the register exists, false
276 otherwise.
277 This function calls the device specific write_byte function if defined to
278 obtain the chip status. Therefore, it must _not_ be called from that function.
279
280 ::
281
282 int pmbus_do_probe(struct i2c_client *client, struct pmbus_driver_info *info);
283
284 Execute probe function. Similar to standard probe function for other drivers,
285 with the pointer to struct pmbus_driver_info as additional argument. Calls
286 identify function if supported. Must only be called from device probe
287 function.
288
289 ::
290
291 const struct pmbus_driver_info
292 *pmbus_get_driver_info(struct i2c_client *client);
293
294 Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe().
295
296
297 PMBus driver platform data
298 ==========================
299
300 PMBus platform data is defined in include/linux/pmbus.h. Platform data
301 currently provides a flags field with four bits used::
302
303 #define PMBUS_SKIP_STATUS_CHECK BIT(0)
304
305 #define PMBUS_WRITE_PROTECTED BIT(1)
306
307 #define PMBUS_NO_CAPABILITY BIT(2)
308
309 #define PMBUS_READ_STATUS_AFTER_FAILED_CHECK BIT(3)
310
311 struct pmbus_platform_data {
312 u32 flags; /* Device specific flags */
313
314 /* regulator support */
315 int num_regulators;
316 struct regulator_init_data *reg_init_data;
317 };
318
319
320 Flags
321 -----
322
323 PMBUS_SKIP_STATUS_CHECK
324
325 During register detection, skip checking the status register for
326 communication or command errors.
327
328 Some PMBus chips respond with valid data when trying to read an unsupported
329 register. For such chips, checking the status register is mandatory when
330 trying to determine if a chip register exists or not.
331 Other PMBus chips don't support the STATUS_CML register, or report
332 communication errors for no explicable reason. For such chips, checking the
333 status register must be disabled.
334
335 Some i2c controllers do not support single-byte commands (write commands with
336 no data, i2c_smbus_write_byte()). With such controllers, clearing the status
337 register is impossible, and the PMBUS_SKIP_STATUS_CHECK flag must be set.
338
339 PMBUS_WRITE_PROTECTED
340
341 Set if the chip is write protected and write protection is not determined
342 by the standard WRITE_PROTECT command.
343
344 PMBUS_NO_CAPABILITY
345
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
348 driver doesn't use CAPABILITY to determine its behavior.
349
350 PMBUS_READ_STATUS_AFTER_FAILED_CHECK
351
352 Read the STATUS register after each failed register check.
353
354 Some PMBus chips end up in an undefined state when trying to read an
355 unsupported register. For such chips, it is necessary to reset the
356 chip pmbus controller to a known state after a failed register check.
357 This can be done by reading a known register. By setting this flag the
358 driver will try to read the STATUS register after each failed
359 register check. This read may fail, but it will put the chip into a
360 known state.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.