361 lines
14 KiB
ReStructuredText
361 lines
14 KiB
ReStructuredText
==================================
|
|
PMBus core driver and internal API
|
|
==================================
|
|
|
|
Introduction
|
|
============
|
|
|
|
[from pmbus.org] The Power Management Bus (PMBus) is an open standard
|
|
power-management protocol with a fully defined command language that facilitates
|
|
communication with power converters and other devices in a power system. The
|
|
protocol is implemented over the industry-standard SMBus serial interface and
|
|
enables programming, control, and real-time monitoring of compliant power
|
|
conversion products. This flexible and highly versatile standard allows for
|
|
communication between devices based on both analog and digital technologies, and
|
|
provides true interoperability which will reduce design complexity and shorten
|
|
time to market for power system designers. Pioneered by leading power supply and
|
|
semiconductor companies, this open power system standard is maintained and
|
|
promoted by the PMBus Implementers Forum (PMBus-IF), comprising 30+ adopters
|
|
with the objective to provide support to, and facilitate adoption among, users.
|
|
|
|
Unfortunately, while PMBus commands are standardized, there are no mandatory
|
|
commands, and manufacturers can add as many non-standard commands as they like.
|
|
Also, different PMBUs devices act differently if non-supported commands are
|
|
executed. Some devices return an error, some devices return 0xff or 0xffff and
|
|
set a status error flag, and some devices may simply hang up.
|
|
|
|
Despite all those difficulties, a generic PMBus device driver is still useful
|
|
and supported since kernel version 2.6.39. However, it was necessary to support
|
|
device specific extensions in addition to the core PMBus driver, since it is
|
|
simply unknown what new device specific functionality PMBus device developers
|
|
come up with next.
|
|
|
|
To make device specific extensions as scalable as possible, and to avoid having
|
|
to modify the core PMBus driver repeatedly for new devices, the PMBus driver was
|
|
split into core, generic, and device specific code. The core code (in
|
|
pmbus_core.c) provides generic functionality. The generic code (in pmbus.c)
|
|
provides support for generic PMBus devices. Device specific code is responsible
|
|
for device specific initialization and, if needed, maps device specific
|
|
functionality into generic functionality. This is to some degree comparable
|
|
to PCI code, where generic code is augmented as needed with quirks for all kinds
|
|
of devices.
|
|
|
|
PMBus device capabilities auto-detection
|
|
========================================
|
|
|
|
For generic PMBus devices, code in pmbus.c attempts to auto-detect all supported
|
|
PMBus commands. Auto-detection is somewhat limited, since there are simply too
|
|
many variables to consider. For example, it is almost impossible to autodetect
|
|
which PMBus commands are paged and which commands are replicated across all
|
|
pages (see the PMBus specification for details on multi-page PMBus devices).
|
|
|
|
For this reason, it often makes sense to provide a device specific driver if not
|
|
all commands can be auto-detected. The data structures in this driver can be
|
|
used to inform the core driver about functionality supported by individual
|
|
chips.
|
|
|
|
Some commands are always auto-detected. This applies to all limit commands
|
|
(lcrit, min, max, and crit attributes) as well as associated alarm attributes.
|
|
Limits and alarm attributes are auto-detected because there are simply too many
|
|
possible combinations to provide a manual configuration interface.
|
|
|
|
PMBus internal API
|
|
==================
|
|
|
|
The API between core and device specific PMBus code is defined in
|
|
drivers/hwmon/pmbus/pmbus.h. In addition to the internal API, pmbus.h defines
|
|
standard PMBus commands and virtual PMBus commands.
|
|
|
|
Standard PMBus commands
|
|
-----------------------
|
|
|
|
Standard PMBus commands (commands values 0x00 to 0xff) are defined in the PMBUs
|
|
specification.
|
|
|
|
Virtual PMBus commands
|
|
----------------------
|
|
|
|
Virtual PMBus commands are provided to enable support for non-standard
|
|
functionality which has been implemented by several chip vendors and is thus
|
|
desirable to support.
|
|
|
|
Virtual PMBus commands start with command value 0x100 and can thus easily be
|
|
distinguished from standard PMBus commands (which can not have values larger
|
|
than 0xff). Support for virtual PMBus commands is device specific and thus has
|
|
to be implemented in device specific code.
|
|
|
|
Virtual commands are named PMBUS_VIRT_xxx and start with PMBUS_VIRT_BASE. All
|
|
virtual commands are word sized.
|
|
|
|
There are currently two types of virtual commands.
|
|
|
|
- READ commands are read-only; writes are either ignored or return an error.
|
|
- RESET commands are read/write. Reading reset registers returns zero
|
|
(used for detection), writing any value causes the associated history to be
|
|
reset.
|
|
|
|
Virtual commands have to be handled in device specific driver code. Chip driver
|
|
code returns non-negative values if a virtual command is supported, or a
|
|
negative error code if not. The chip driver may return -ENODATA or any other
|
|
Linux error code in this case, though an error code other than -ENODATA is
|
|
handled more efficiently and thus preferred. Either case, the calling PMBus
|
|
core code will abort if the chip driver returns an error code when reading
|
|
or writing virtual registers (in other words, the PMBus core code will never
|
|
send a virtual command to a chip).
|
|
|
|
PMBus driver information
|
|
------------------------
|
|
|
|
PMBus driver information, defined in struct pmbus_driver_info, is the main means
|
|
for device specific drivers to pass information to the core PMBus driver.
|
|
Specifically, it provides the following information.
|
|
|
|
- For devices supporting its data in Direct Data Format, it provides coefficients
|
|
for converting register values into normalized data. This data is usually
|
|
provided by chip manufacturers in device datasheets.
|
|
- Supported chip functionality can be provided to the core driver. This may be
|
|
necessary for chips which react badly if non-supported commands are executed,
|
|
and/or to speed up device detection and initialization.
|
|
- Several function entry points are provided to support overriding and/or
|
|
augmenting generic command execution. This functionality can be used to map
|
|
non-standard PMBus commands to standard commands, or to augment standard
|
|
command return values with device specific information.
|
|
|
|
PEC Support
|
|
===========
|
|
|
|
Many PMBus devices support SMBus PEC (Packet Error Checking). If supported
|
|
by both the I2C adapter and by the PMBus chip, it is by default enabled.
|
|
If PEC is supported, the PMBus core driver adds an attribute named 'pec' to
|
|
the I2C device. This attribute can be used to control PEC support in the
|
|
communication with the PMBus chip.
|
|
|
|
API functions
|
|
=============
|
|
|
|
Functions provided by chip driver
|
|
---------------------------------
|
|
|
|
All functions return the command return value (read) or zero (write) if
|
|
successful. A return value of -ENODATA indicates that there is no manufacturer
|
|
specific command, but that a standard PMBus command may exist. Any other
|
|
negative return value indicates that the commands does not exist for this
|
|
chip, and that no attempt should be made to read or write the standard
|
|
command.
|
|
|
|
As mentioned above, an exception to this rule applies to virtual commands,
|
|
which *must* be handled in driver specific code. See "Virtual PMBus Commands"
|
|
above for more details.
|
|
|
|
Command execution in the core PMBus driver code is as follows::
|
|
|
|
if (chip_access_function) {
|
|
status = chip_access_function();
|
|
if (status != -ENODATA)
|
|
return status;
|
|
}
|
|
if (command >= PMBUS_VIRT_BASE) /* For word commands/registers only */
|
|
return -EINVAL;
|
|
return generic_access();
|
|
|
|
Chip drivers may provide pointers to the following functions in struct
|
|
pmbus_driver_info. All functions are optional.
|
|
|
|
::
|
|
|
|
int (*read_byte_data)(struct i2c_client *client, int page, int reg);
|
|
|
|
Read byte from page <page>, register <reg>.
|
|
<page> may be -1, which means "current page".
|
|
|
|
|
|
::
|
|
|
|
int (*read_word_data)(struct i2c_client *client, int page, int phase,
|
|
int reg);
|
|
|
|
Read word from page <page>, phase <phase>, register <reg>. If the chip does not
|
|
support multiple phases, the phase parameter can be ignored. If the chip
|
|
supports multiple phases, a phase value of 0xff indicates all phases.
|
|
|
|
::
|
|
|
|
int (*write_word_data)(struct i2c_client *client, int page, int reg,
|
|
u16 word);
|
|
|
|
Write word to page <page>, register <reg>.
|
|
|
|
::
|
|
|
|
int (*write_byte)(struct i2c_client *client, int page, u8 value);
|
|
|
|
Write byte to page <page>, register <reg>.
|
|
<page> may be -1, which means "current page".
|
|
|
|
::
|
|
|
|
int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info);
|
|
|
|
Determine supported PMBus functionality. This function is only necessary
|
|
if a chip driver supports multiple chips, and the chip functionality is not
|
|
pre-determined. It is currently only used by the generic pmbus driver
|
|
(pmbus.c).
|
|
|
|
Functions exported by core driver
|
|
---------------------------------
|
|
|
|
Chip drivers are expected to use the following functions to read or write
|
|
PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C
|
|
commands are used, the chip driver code must not directly modify the current
|
|
page, since the selected page is cached in the core driver and the core driver
|
|
will assume that it is selected. Using pmbus_set_page() to select a new page
|
|
is mandatory.
|
|
|
|
::
|
|
|
|
int pmbus_set_page(struct i2c_client *client, u8 page, u8 phase);
|
|
|
|
Set PMBus page register to <page> and <phase> for subsequent commands.
|
|
If the chip does not support multiple phases, the phase parameter is
|
|
ignored. Otherwise, a phase value of 0xff selects all phases.
|
|
|
|
::
|
|
|
|
int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 phase,
|
|
u8 reg);
|
|
|
|
Read word data from <page>, <phase>, <reg>. Similar to
|
|
i2c_smbus_read_word_data(), but selects page and phase first. If the chip does
|
|
not support multiple phases, the phase parameter is ignored. Otherwise, a phase
|
|
value of 0xff selects all phases.
|
|
|
|
::
|
|
|
|
int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg,
|
|
u16 word);
|
|
|
|
Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but
|
|
selects page first.
|
|
|
|
::
|
|
|
|
int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg);
|
|
|
|
Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but
|
|
selects page first. <page> may be -1, which means "current page".
|
|
|
|
::
|
|
|
|
int pmbus_write_byte(struct i2c_client *client, int page, u8 value);
|
|
|
|
Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but
|
|
selects page first. <page> may be -1, which means "current page".
|
|
|
|
::
|
|
|
|
void pmbus_clear_faults(struct i2c_client *client);
|
|
|
|
Execute PMBus "Clear Fault" command on all chip pages.
|
|
This function calls the device specific write_byte function if defined.
|
|
Therefore, it must _not_ be called from that function.
|
|
|
|
::
|
|
|
|
bool pmbus_check_byte_register(struct i2c_client *client, int page, int reg);
|
|
|
|
Check if byte register exists. Return true if the register exists, false
|
|
otherwise.
|
|
This function calls the device specific write_byte function if defined to
|
|
obtain the chip status. Therefore, it must _not_ be called from that function.
|
|
|
|
::
|
|
|
|
bool pmbus_check_word_register(struct i2c_client *client, int page, int reg);
|
|
|
|
Check if word register exists. Return true if the register exists, false
|
|
otherwise.
|
|
This function calls the device specific write_byte function if defined to
|
|
obtain the chip status. Therefore, it must _not_ be called from that function.
|
|
|
|
::
|
|
|
|
int pmbus_do_probe(struct i2c_client *client, struct pmbus_driver_info *info);
|
|
|
|
Execute probe function. Similar to standard probe function for other drivers,
|
|
with the pointer to struct pmbus_driver_info as additional argument. Calls
|
|
identify function if supported. Must only be called from device probe
|
|
function.
|
|
|
|
::
|
|
|
|
const struct pmbus_driver_info
|
|
*pmbus_get_driver_info(struct i2c_client *client);
|
|
|
|
Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe().
|
|
|
|
|
|
PMBus driver platform data
|
|
==========================
|
|
|
|
PMBus platform data is defined in include/linux/pmbus.h. Platform data
|
|
currently provides a flags field with four bits used::
|
|
|
|
#define PMBUS_SKIP_STATUS_CHECK BIT(0)
|
|
|
|
#define PMBUS_WRITE_PROTECTED BIT(1)
|
|
|
|
#define PMBUS_NO_CAPABILITY BIT(2)
|
|
|
|
#define PMBUS_READ_STATUS_AFTER_FAILED_CHECK BIT(3)
|
|
|
|
struct pmbus_platform_data {
|
|
u32 flags; /* Device specific flags */
|
|
|
|
/* regulator support */
|
|
int num_regulators;
|
|
struct regulator_init_data *reg_init_data;
|
|
};
|
|
|
|
|
|
Flags
|
|
-----
|
|
|
|
PMBUS_SKIP_STATUS_CHECK
|
|
|
|
During register detection, skip checking the status register for
|
|
communication or command errors.
|
|
|
|
Some PMBus chips respond with valid data when trying to read an unsupported
|
|
register. For such chips, checking the status register is mandatory when
|
|
trying to determine if a chip register exists or not.
|
|
Other PMBus chips don't support the STATUS_CML register, or report
|
|
communication errors for no explicable reason. For such chips, checking the
|
|
status register must be disabled.
|
|
|
|
Some i2c controllers do not support single-byte commands (write commands with
|
|
no data, i2c_smbus_write_byte()). With such controllers, clearing the status
|
|
register is impossible, and the PMBUS_SKIP_STATUS_CHECK flag must be set.
|
|
|
|
PMBUS_WRITE_PROTECTED
|
|
|
|
Set if the chip is write protected and write protection is not determined
|
|
by the standard WRITE_PROTECT command.
|
|
|
|
PMBUS_NO_CAPABILITY
|
|
|
|
Some PMBus chips don't respond with valid data when reading the CAPABILITY
|
|
register. For such chips, this flag should be set so that the PMBus core
|
|
driver doesn't use CAPABILITY to determine it's behavior.
|
|
|
|
PMBUS_READ_STATUS_AFTER_FAILED_CHECK
|
|
|
|
Read the STATUS register after each failed register check.
|
|
|
|
Some PMBus chips end up in an undefined state when trying to read an
|
|
unsupported register. For such chips, it is necessary to reset the
|
|
chip pmbus controller to a known state after a failed register check.
|
|
This can be done by reading a known register. By setting this flag the
|
|
driver will try to read the STATUS register after each failed
|
|
register check. This read may fail, but it will put the chip into a
|
|
known state.
|