361 lines · plain
1==================================2PMBus core driver and internal API3==================================4 5Introduction6============7 8[from pmbus.org] The Power Management Bus (PMBus) is an open standard9power-management protocol with a fully defined command language that facilitates10communication with power converters and other devices in a power system. The11protocol is implemented over the industry-standard SMBus serial interface and12enables programming, control, and real-time monitoring of compliant power13conversion products. This flexible and highly versatile standard allows for14communication between devices based on both analog and digital technologies, and15provides true interoperability which will reduce design complexity and shorten16time to market for power system designers. Pioneered by leading power supply and17semiconductor companies, this open power system standard is maintained and18promoted by the PMBus Implementers Forum (PMBus-IF), comprising 30+ adopters19with the objective to provide support to, and facilitate adoption among, users.20 21Unfortunately, while PMBus commands are standardized, there are no mandatory22commands, and manufacturers can add as many non-standard commands as they like.23Also, different PMBUs devices act differently if non-supported commands are24executed. Some devices return an error, some devices return 0xff or 0xffff and25set a status error flag, and some devices may simply hang up.26 27Despite all those difficulties, a generic PMBus device driver is still useful28and supported since kernel version 2.6.39. However, it was necessary to support29device specific extensions in addition to the core PMBus driver, since it is30simply unknown what new device specific functionality PMBus device developers31come up with next.32 33To make device specific extensions as scalable as possible, and to avoid having34to modify the core PMBus driver repeatedly for new devices, the PMBus driver was35split into core, generic, and device specific code. The core code (in36pmbus_core.c) provides generic functionality. The generic code (in pmbus.c)37provides support for generic PMBus devices. Device specific code is responsible38for device specific initialization and, if needed, maps device specific39functionality into generic functionality. This is to some degree comparable40to PCI code, where generic code is augmented as needed with quirks for all kinds41of devices.42 43PMBus device capabilities auto-detection44========================================45 46For generic PMBus devices, code in pmbus.c attempts to auto-detect all supported47PMBus commands. Auto-detection is somewhat limited, since there are simply too48many variables to consider. For example, it is almost impossible to autodetect49which PMBus commands are paged and which commands are replicated across all50pages (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 not53all commands can be auto-detected. The data structures in this driver can be54used to inform the core driver about functionality supported by individual55chips.56 57Some commands are always auto-detected. This applies to all limit commands58(lcrit, min, max, and crit attributes) as well as associated alarm attributes.59Limits and alarm attributes are auto-detected because there are simply too many60possible combinations to provide a manual configuration interface.61 62PMBus internal API63==================64 65The API between core and device specific PMBus code is defined in66drivers/hwmon/pmbus/pmbus.h. In addition to the internal API, pmbus.h defines67standard PMBus commands and virtual PMBus commands.68 69Standard PMBus commands70-----------------------71 72Standard PMBus commands (commands values 0x00 to 0xff) are defined in the PMBUs73specification.74 75Virtual PMBus commands76----------------------77 78Virtual PMBus commands are provided to enable support for non-standard79functionality which has been implemented by several chip vendors and is thus80desirable to support.81 82Virtual PMBus commands start with command value 0x100 and can thus easily be83distinguished from standard PMBus commands (which can not have values larger84than 0xff). Support for virtual PMBus commands is device specific and thus has85to be implemented in device specific code.86 87Virtual commands are named PMBUS_VIRT_xxx and start with PMBUS_VIRT_BASE. All88virtual 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 zero94 (used for detection), writing any value causes the associated history to be95 reset.96 97Virtual commands have to be handled in device specific driver code. Chip driver98code returns non-negative values if a virtual command is supported, or a99negative error code if not. The chip driver may return -ENODATA or any other100Linux error code in this case, though an error code other than -ENODATA is101handled more efficiently and thus preferred. Either case, the calling PMBus102core code will abort if the chip driver returns an error code when reading103or writing virtual registers (in other words, the PMBus core code will never104send a virtual command to a chip).105 106PMBus driver information107------------------------108 109PMBus driver information, defined in struct pmbus_driver_info, is the main means110for 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 coefficients114 for converting register values into normalized data. This data is usually115 provided by chip manufacturers in device datasheets.116- Supported chip functionality can be provided to the core driver. This may be117 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/or120 augmenting generic command execution. This functionality can be used to map121 non-standard PMBus commands to standard commands, or to augment standard122 command return values with device specific information.123 124PEC Support125===========126 127Many PMBus devices support SMBus PEC (Packet Error Checking). If supported128by both the I2C adapter and by the PMBus chip, it is by default enabled.129If PEC is supported, the PMBus core driver adds an attribute named 'pec' to130the I2C device. This attribute can be used to control PEC support in the131communication with the PMBus chip.132 133API functions134=============135 136Functions provided by chip driver137---------------------------------138 139All functions return the command return value (read) or zero (write) if140successful. A return value of -ENODATA indicates that there is no manufacturer141specific command, but that a standard PMBus command may exist. Any other142negative return value indicates that the commands does not exist for this143chip, and that no attempt should be made to read or write the standard144command.145 146As mentioned above, an exception to this rule applies to virtual commands,147which *must* be handled in driver specific code. See "Virtual PMBus Commands"148above for more details.149 150Command execution in the core PMBus driver code is as follows::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 161Chip drivers may provide pointers to the following functions in struct162pmbus_driver_info. All functions are optional.163 164::165 166 int (*read_byte_data)(struct i2c_client *client, int page, int reg);167 168Read byte from page <page>, register <reg>.169<page> may be -1, which means "current page".170 171 172::173 174 int (*read_word_data)(struct i2c_client *client, int page, int phase,175 int reg);176 177Read word from page <page>, phase <phase>, register <reg>. If the chip does not178support multiple phases, the phase parameter can be ignored. If the chip179supports multiple phases, a phase value of 0xff indicates all phases.180 181::182 183 int (*write_word_data)(struct i2c_client *client, int page, int reg,184 u16 word);185 186Write word to page <page>, register <reg>.187 188::189 190 int (*write_byte)(struct i2c_client *client, int page, u8 value);191 192Write byte to page <page>, register <reg>.193<page> may be -1, which means "current page".194 195::196 197 int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info);198 199Determine supported PMBus functionality. This function is only necessary200if a chip driver supports multiple chips, and the chip functionality is not201pre-determined. It is currently only used by the generic pmbus driver202(pmbus.c).203 204Functions exported by core driver205---------------------------------206 207Chip drivers are expected to use the following functions to read or write208PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C209commands are used, the chip driver code must not directly modify the current210page, since the selected page is cached in the core driver and the core driver211will assume that it is selected. Using pmbus_set_page() to select a new page212is mandatory.213 214::215 216 int pmbus_set_page(struct i2c_client *client, u8 page, u8 phase);217 218Set PMBus page register to <page> and <phase> for subsequent commands.219If the chip does not support multiple phases, the phase parameter is220ignored. Otherwise, a phase value of 0xff selects all phases.221 222::223 224 int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 phase,225 u8 reg);226 227Read word data from <page>, <phase>, <reg>. Similar to228i2c_smbus_read_word_data(), but selects page and phase first. If the chip does229not support multiple phases, the phase parameter is ignored. Otherwise, a phase230value of 0xff selects all phases.231 232::233 234 int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg,235 u16 word);236 237Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but238selects page first.239 240::241 242 int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg);243 244Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but245selects page first. <page> may be -1, which means "current page".246 247::248 249 int pmbus_write_byte(struct i2c_client *client, int page, u8 value);250 251Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but252selects page first. <page> may be -1, which means "current page".253 254::255 256 void pmbus_clear_faults(struct i2c_client *client);257 258Execute PMBus "Clear Fault" command on all chip pages.259This function calls the device specific write_byte function if defined.260Therefore, it must _not_ be called from that function.261 262::263 264 bool pmbus_check_byte_register(struct i2c_client *client, int page, int reg);265 266Check if byte register exists. Return true if the register exists, false267otherwise.268This function calls the device specific write_byte function if defined to269obtain the chip status. Therefore, it must _not_ be called from that function.270 271::272 273 bool pmbus_check_word_register(struct i2c_client *client, int page, int reg);274 275Check if word register exists. Return true if the register exists, false276otherwise.277This function calls the device specific write_byte function if defined to278obtain the chip status. Therefore, it must _not_ be called from that function.279 280::281 282 int pmbus_do_probe(struct i2c_client *client, struct pmbus_driver_info *info);283 284Execute probe function. Similar to standard probe function for other drivers,285with the pointer to struct pmbus_driver_info as additional argument. Calls286identify function if supported. Must only be called from device probe287function.288 289::290 291 const struct pmbus_driver_info292 *pmbus_get_driver_info(struct i2c_client *client);293 294Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe().295 296 297PMBus driver platform data298==========================299 300PMBus platform data is defined in include/linux/pmbus.h. Platform data301currently provides a flags field with four bits used::302 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)310 311 struct pmbus_platform_data {312 u32 flags; /* Device specific flags */313 314 /* regulator support */315 int num_regulators;316 struct regulator_init_data *reg_init_data;317 };318 319 320Flags321-----322 323PMBUS_SKIP_STATUS_CHECK324 325During register detection, skip checking the status register for326communication or command errors.327 328Some PMBus chips respond with valid data when trying to read an unsupported329register. For such chips, checking the status register is mandatory when330trying to determine if a chip register exists or not.331Other PMBus chips don't support the STATUS_CML register, or report332communication errors for no explicable reason. For such chips, checking the333status register must be disabled.334 335Some i2c controllers do not support single-byte commands (write commands with336no data, i2c_smbus_write_byte()). With such controllers, clearing the status337register is impossible, and the PMBUS_SKIP_STATUS_CHECK flag must be set.338 339PMBUS_WRITE_PROTECTED340 341Set if the chip is write protected and write protection is not determined342by the standard WRITE_PROTECT command.343 344PMBUS_NO_CAPABILITY345 346Some PMBus chips don't respond with valid data when reading the CAPABILITY347register. For such chips, this flag should be set so that the PMBus core348driver doesn't use CAPABILITY to determine its behavior.349 350PMBUS_READ_STATUS_AFTER_FAILED_CHECK351 352Read the STATUS register after each failed register check.353 354Some PMBus chips end up in an undefined state when trying to read an355unsupported register. For such chips, it is necessary to reset the356chip pmbus controller to a known state after a failed register check.357This can be done by reading a known register. By setting this flag the358driver will try to read the STATUS register after each failed359register check. This read may fail, but it will put the chip into a360known state.361