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.