Commit | Line | Data |
---|---|---|
1f234ff1 | 1 | ================================== |
ced29d42 GR |
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 | ||
f30ce040 GR |
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 | ||
1f234ff1 MCC |
133 | API functions |
134 | ============= | |
ced29d42 | 135 | |
1f234ff1 MCC |
136 | Functions provided by chip driver |
137 | --------------------------------- | |
ced29d42 | 138 | |
1f234ff1 MCC |
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. | |
ced29d42 | 145 | |
1f234ff1 MCC |
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. | |
ced29d42 | 149 | |
1f234ff1 | 150 | Command execution in the core PMBus driver code is as follows:: |
ced29d42 GR |
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 | ||
1f234ff1 MCC |
161 | Chip drivers may provide pointers to the following functions in struct |
162 | pmbus_driver_info. All functions are optional. | |
163 | ||
164 | :: | |
ced29d42 GR |
165 | |
166 | int (*read_byte_data)(struct i2c_client *client, int page, int reg); | |
167 | ||
1f234ff1 MCC |
168 | Read byte from page <page>, register <reg>. |
169 | <page> may be -1, which means "current page". | |
170 | ||
171 | ||
172 | :: | |
ced29d42 | 173 | |
43f33b6e GR |
174 | int (*read_word_data)(struct i2c_client *client, int page, int phase, |
175 | int reg); | |
ced29d42 | 176 | |
12087a36 | 177 | Read word from page <page>, phase <phase>, register <reg>. If the chip does not |
43f33b6e GR |
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. | |
1f234ff1 MCC |
180 | |
181 | :: | |
ced29d42 GR |
182 | |
183 | int (*write_word_data)(struct i2c_client *client, int page, int reg, | |
1f234ff1 | 184 | u16 word); |
ced29d42 | 185 | |
1f234ff1 MCC |
186 | Write word to page <page>, register <reg>. |
187 | ||
188 | :: | |
ced29d42 GR |
189 | |
190 | int (*write_byte)(struct i2c_client *client, int page, u8 value); | |
191 | ||
1f234ff1 MCC |
192 | Write byte to page <page>, register <reg>. |
193 | <page> may be -1, which means "current page". | |
194 | ||
195 | :: | |
ced29d42 GR |
196 | |
197 | int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info); | |
198 | ||
1f234ff1 MCC |
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 | --------------------------------- | |
ced29d42 | 206 | |
1f234ff1 MCC |
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. | |
ced29d42 | 213 | |
1f234ff1 | 214 | :: |
ced29d42 | 215 | |
43f33b6e | 216 | int pmbus_set_page(struct i2c_client *client, u8 page, u8 phase); |
ced29d42 | 217 | |
43f33b6e GR |
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. | |
1f234ff1 MCC |
221 | |
222 | :: | |
ced29d42 | 223 | |
43f33b6e GR |
224 | int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 phase, |
225 | u8 reg); | |
ced29d42 | 226 | |
43f33b6e GR |
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. | |
1f234ff1 MCC |
231 | |
232 | :: | |
ced29d42 GR |
233 | |
234 | int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg, | |
235 | u16 word); | |
236 | ||
1f234ff1 MCC |
237 | Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but |
238 | selects page first. | |
239 | ||
240 | :: | |
ced29d42 GR |
241 | |
242 | int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg); | |
243 | ||
1f234ff1 MCC |
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 | :: | |
ced29d42 GR |
248 | |
249 | int pmbus_write_byte(struct i2c_client *client, int page, u8 value); | |
250 | ||
1f234ff1 MCC |
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 | :: | |
ced29d42 GR |
255 | |
256 | void pmbus_clear_faults(struct i2c_client *client); | |
257 | ||
1f234ff1 MCC |
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 | :: | |
ced29d42 GR |
263 | |
264 | bool pmbus_check_byte_register(struct i2c_client *client, int page, int reg); | |
265 | ||
1f234ff1 MCC |
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 | :: | |
ced29d42 GR |
272 | |
273 | bool pmbus_check_word_register(struct i2c_client *client, int page, int reg); | |
274 | ||
1f234ff1 MCC |
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 | :: | |
ced29d42 | 281 | |
dd431939 | 282 | int pmbus_do_probe(struct i2c_client *client, struct pmbus_driver_info *info); |
1f234ff1 MCC |
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. | |
ced29d42 | 288 | |
1f234ff1 | 289 | :: |
ced29d42 GR |
290 | |
291 | const struct pmbus_driver_info | |
292 | *pmbus_get_driver_info(struct i2c_client *client); | |
293 | ||
1f234ff1 | 294 | Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe(). |
ced29d42 GR |
295 | |
296 | ||
297 | PMBus driver platform data | |
298 | ========================== | |
299 | ||
4ba1bb12 | 300 | PMBus platform data is defined in include/linux/pmbus.h. Platform data |
b976760d | 301 | currently provides a flags field with four bits used:: |
ced29d42 | 302 | |
b976760d ER |
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) | |
ced29d42 | 310 | |
1f234ff1 MCC |
311 | struct pmbus_platform_data { |
312 | u32 flags; /* Device specific flags */ | |
b976760d ER |
313 | |
314 | /* regulator support */ | |
315 | int num_regulators; | |
316 | struct regulator_init_data *reg_init_data; | |
1f234ff1 | 317 | }; |
ced29d42 GR |
318 | |
319 | ||
320 | Flags | |
321 | ----- | |
322 | ||
323 | PMBUS_SKIP_STATUS_CHECK | |
b976760d ER |
324 | |
325 | During register detection, skip checking the status register for | |
326 | communication or command errors. | |
ced29d42 GR |
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. | |
b976760d ER |
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 it's 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. |