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