diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2019-05-06 19:56:51 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2019-05-06 19:56:51 -0700 |
commit | 7aefd944f038c7469571adb37769cb6f3924ecfa (patch) | |
tree | f0a8dc23633b6bbbc4f0bff932f332e847fb6c1b /Documentation/hwmon/pmbus-core.rst | |
parent | Merge branch 'ras-core-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip (diff) | |
parent | hwmon: (lm75) Add support for TMP75B (diff) | |
download | linux-dev-7aefd944f038c7469571adb37769cb6f3924ecfa.tar.xz linux-dev-7aefd944f038c7469571adb37769cb6f3924ecfa.zip |
Merge tag 'hwmon-for-v5.2' of git://git.kernel.org/pub/scm/linux/kernel/git/groeck/linux-staging
Pull hwmon updates from Guenter Roeck:
- Add driver for Intersil ISL68137 PWM Controller
- Add driver for Lochnagar 2
- Add driver for Infineon IR38064 Voltage Regulator
- Add support for TMP75B to lm75 driver
- Convert documentation to ReST format
- Use request_muxed_region for Super-IO accesses in several drivers
- Add 'samples' attribute to ABI, and start using it
- Add support for custom sysfs attributes to pmbus drivers (used in
ISL68137 driver)
- Introduce HWMON_CHANNEL_INFO macro
- Automated changes:
- Use permission specific [SENSOR_][DEVICE_]ATTR variants
- Fix build warnings due to unused of_device_id structures
- Use HWMON_CHANNEL_INFO macro
- Various minor improvements and fixes
* tag 'hwmon-for-v5.2' of git://git.kernel.org/pub/scm/linux/kernel/git/groeck/linux-staging: (125 commits)
hwmon: (lm75) Add support for TMP75B
dt-bindings: hwmon: Add tmp75b to lm75.txt
hwmon: (s3c) Use dev_get_drvdata()
hwmon: (max6650) Drop call to thermal_cdev_update
docs: hwmon: remove the extension from .rst files
docs: hwmon: convert three docs to ReST format
hwmon: (max6650) add thermal cooling device capability
hwmon: (ina3221) Add voltage conversion time settings
hwmon: (ina3221) Do not read-back to cache reg_config
docs: hwmon: Add an index file and rename docs to *.rst
docs: hwmon: convert remaining files to ReST format
docs: hwmon: misc files: convert to ReST format
docs: hwmon: pmbus files: convert to ReST format
docs: hwmon: k8temp, w83793: convert to ReST format
docs: hwmon: da9052, da9055: convert to ReST format
docs: hwmon: wm831x, wm8350: convert to ReST format
docs: hwmon: dme1737, vt1211: convert to ReST format
docs: hwmon: ads1015: convert to ReST format
docs: hwmon: asc7621: convert to ReST format
docs: hwmon: ibmpowernv: convert to ReST format
...
Diffstat (limited to 'Documentation/hwmon/pmbus-core.rst')
-rw-r--r-- | Documentation/hwmon/pmbus-core.rst | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/Documentation/hwmon/pmbus-core.rst b/Documentation/hwmon/pmbus-core.rst new file mode 100644 index 000000000000..92515c446fe3 --- /dev/null +++ b/Documentation/hwmon/pmbus-core.rst @@ -0,0 +1,316 @@ +================================== +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. + +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 reg); + +Read word from page <page>, register <reg>. + +:: + + 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); + +Set PMBus page register to <page> for subsequent commands. + +:: + + int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 reg); + +Read word data from <page>, <reg>. Similar to i2c_smbus_read_word_data(), but +selects page first. + +:: + + 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, 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. Calls +identify function if supported. Must only be called from device probe +function. + +:: + + 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(). + + +PMBus driver platform data +========================== + +PMBus platform data is defined in include/linux/pmbus.h. Platform data +currently only provides a flag field with a single bit used:: + + #define PMBUS_SKIP_STATUS_CHECK (1 << 0) + + struct pmbus_platform_data { + u32 flags; /* Device specific flags */ + }; + + +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. |