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, struct pmbus_driver_info *info); 274 275Execute probe function. Similar to standard probe function for other drivers, 276with the pointer to struct pmbus_driver_info as additional argument. Calls 277identify function if supported. Must only be called from device probe 278function. 279 280:: 281 282 const struct pmbus_driver_info 283 *pmbus_get_driver_info(struct i2c_client *client); 284 285Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe(). 286 287 288PMBus driver platform data 289========================== 290 291PMBus platform data is defined in include/linux/pmbus.h. Platform data 292currently only provides a flag field with a single bit used:: 293 294 #define PMBUS_SKIP_STATUS_CHECK (1 << 0) 295 296 struct pmbus_platform_data { 297 u32 flags; /* Device specific flags */ 298 }; 299 300 301Flags 302----- 303 304PMBUS_SKIP_STATUS_CHECK 305 During register detection, skip checking the status register for 306 communication or command errors. 307 308Some PMBus chips respond with valid data when trying to read an unsupported 309register. For such chips, checking the status register is mandatory when 310trying to determine if a chip register exists or not. 311Other PMBus chips don't support the STATUS_CML register, or report 312communication errors for no explicable reason. For such chips, checking the 313status register must be disabled. 314 315Some i2c controllers do not support single-byte commands (write commands with 316no data, i2c_smbus_write_byte()). With such controllers, clearing the status 317register is impossible, and the PMBUS_SKIP_STATUS_CHECK flag must be set. 318