About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hwmon / pmbus-core


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog