Standard PMBus commands¶

Standard PMBus commands (commands values 0x00 to 0xff) are defined in the PMBUsspecification.

Virtual PMBus commands¶

Virtual PMBus commands are provided to enable support for non-standardfunctionality which has been implemented by several chip vendors and is thusdesirable to support.

Virtual PMBus commands start with command value 0x100 and can thus easily bedistinguished from standard PMBus commands (which can not have values largerthan 0xff). Support for virtual PMBus commands is device specific and thus hasto be implemented in device specific code.

Virtual commands are named PMBUS_VIRT_xxx and start with PMBUS_VIRT_BASE. Allvirtual 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 bereset.

Virtual commands have to be handled in device specific driver code. Chip drivercode returns non-negative values if a virtual command is supported, or anegative error code if not. The chip driver may return -ENODATA or any otherLinux error code in this case, though an error code other than -ENODATA ishandled more efficiently and thus preferred. Either case, the calling PMBuscore code will abort if the chip driver returns an error code when readingor writing virtual registers (in other words, the PMBus core code will neversend a virtual command to a chip).

PMBus driver information¶

PMBus driver information, defined in struct pmbus_driver_info, is the main meansfor 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 coefficientsfor converting register values into normalized data. This data is usuallyprovided by chip manufacturers in device datasheets.
• Supported chip functionality can be provided to the core driver. This may benecessary 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/oraugmenting generic command execution. This functionality can be used to mapnon-standard PMBus commands to standard commands, or to augment standardcommand return values with device specific information.

Functions provided by chip driver¶

All functions return the command return value (read) or zero (write) ifsuccessful. A return value of -ENODATA indicates that there is no manufacturerspecific command, but that a standard PMBus command may exist. Any othernegative return value indicates that the commands does not exist for thischip, and that no attempt should be made to read or write the standardcommand.

As mentioned above, an exception to this rule applies to virtual commands,whichmust 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 structpmbus_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 <pase>, register <reg>. If the chip does notsupport multiple phases, the phase parameter can be ignored. If the chipsupports 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 necessaryif a chip driver supports multiple chips, and the chip functionality is notpre-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 writePMBus registers. Chip drivers may also use direct I2C commands. If direct I2Ccommands are used, the chip driver code must not directly modify the currentpage, since the selected page is cached in the core driver and the core driverwill assume that it is selected. Using pmbus_set_page() to select a new pageis 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 isignored. 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 toi2c_smbus_read_word_data(), but selects page and phase first. If the chip doesnot support multiple phases, the phase parameter is ignored. Otherwise, a phasevalue 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 toi2c_smbus_write_word_data(), butselects page first.

int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg);

Read byte data from <page>, <reg>. Similar toi2c_smbus_read_byte_data(), butselects 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 toi2c_smbus_write_byte(), butselects 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, falseotherwise.This function calls the device specific write_byte function if defined toobtain 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, falseotherwise.This function calls the device specific write_byte function if defined toobtain the chip status. Therefore, it must _not_ be called from that function.

int pmbus_do_probe(struct i2c_client *client, const struct i2c_device_id *id,                   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. Callsidentify function if supported. Must only be called from device probefunction.

void pmbus_do_remove(struct i2c_client *client);

Execute driver remove function. Similar to standard driver remove 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().

Flags¶

PMBUS_SKIP_STATUS_CHECK

During register detection, skip checking the status register forcommunication or command errors.

Some PMBus chips respond with valid data when trying to read an unsupportedregister. For such chips, checking the status register is mandatory whentrying to determine if a chip register exists or not.Other PMBus chips don’t support the STATUS_CML register, or reportcommunication errors for no explicable reason. For such chips, checking thestatus register must be disabled.

Some i2c controllers do not support single-byte commands (write commands withno data,i2c_smbus_write_byte()). With such controllers, clearing the statusregister is impossible, and the PMBUS_SKIP_STATUS_CHECK flag must be set.