pmbus-core.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323
  1. ==================================
  2. PMBus core driver and internal API
  3. ==================================
  4. Introduction
  5. ============
  6. [from pmbus.org] The Power Management Bus (PMBus) is an open standard
  7. power-management protocol with a fully defined command language that facilitates
  8. communication with power converters and other devices in a power system. The
  9. protocol is implemented over the industry-standard SMBus serial interface and
  10. enables programming, control, and real-time monitoring of compliant power
  11. conversion products. This flexible and highly versatile standard allows for
  12. communication between devices based on both analog and digital technologies, and
  13. provides true interoperability which will reduce design complexity and shorten
  14. time to market for power system designers. Pioneered by leading power supply and
  15. semiconductor companies, this open power system standard is maintained and
  16. promoted by the PMBus Implementers Forum (PMBus-IF), comprising 30+ adopters
  17. with the objective to provide support to, and facilitate adoption among, users.
  18. Unfortunately, while PMBus commands are standardized, there are no mandatory
  19. commands, and manufacturers can add as many non-standard commands as they like.
  20. Also, different PMBUs devices act differently if non-supported commands are
  21. executed. Some devices return an error, some devices return 0xff or 0xffff and
  22. set a status error flag, and some devices may simply hang up.
  23. Despite all those difficulties, a generic PMBus device driver is still useful
  24. and supported since kernel version 2.6.39. However, it was necessary to support
  25. device specific extensions in addition to the core PMBus driver, since it is
  26. simply unknown what new device specific functionality PMBus device developers
  27. come up with next.
  28. To make device specific extensions as scalable as possible, and to avoid having
  29. to modify the core PMBus driver repeatedly for new devices, the PMBus driver was
  30. split into core, generic, and device specific code. The core code (in
  31. pmbus_core.c) provides generic functionality. The generic code (in pmbus.c)
  32. provides support for generic PMBus devices. Device specific code is responsible
  33. for device specific initialization and, if needed, maps device specific
  34. functionality into generic functionality. This is to some degree comparable
  35. to PCI code, where generic code is augmented as needed with quirks for all kinds
  36. of devices.
  37. PMBus device capabilities auto-detection
  38. ========================================
  39. For generic PMBus devices, code in pmbus.c attempts to auto-detect all supported
  40. PMBus commands. Auto-detection is somewhat limited, since there are simply too
  41. many variables to consider. For example, it is almost impossible to autodetect
  42. which PMBus commands are paged and which commands are replicated across all
  43. pages (see the PMBus specification for details on multi-page PMBus devices).
  44. For this reason, it often makes sense to provide a device specific driver if not
  45. all commands can be auto-detected. The data structures in this driver can be
  46. used to inform the core driver about functionality supported by individual
  47. chips.
  48. Some commands are always auto-detected. This applies to all limit commands
  49. (lcrit, min, max, and crit attributes) as well as associated alarm attributes.
  50. Limits and alarm attributes are auto-detected because there are simply too many
  51. possible combinations to provide a manual configuration interface.
  52. PMBus internal API
  53. ==================
  54. The API between core and device specific PMBus code is defined in
  55. drivers/hwmon/pmbus/pmbus.h. In addition to the internal API, pmbus.h defines
  56. standard PMBus commands and virtual PMBus commands.
  57. Standard PMBus commands
  58. -----------------------
  59. Standard PMBus commands (commands values 0x00 to 0xff) are defined in the PMBUs
  60. specification.
  61. Virtual PMBus commands
  62. ----------------------
  63. Virtual PMBus commands are provided to enable support for non-standard
  64. functionality which has been implemented by several chip vendors and is thus
  65. desirable to support.
  66. Virtual PMBus commands start with command value 0x100 and can thus easily be
  67. distinguished from standard PMBus commands (which can not have values larger
  68. than 0xff). Support for virtual PMBus commands is device specific and thus has
  69. to be implemented in device specific code.
  70. Virtual commands are named PMBUS_VIRT_xxx and start with PMBUS_VIRT_BASE. All
  71. virtual commands are word sized.
  72. There are currently two types of virtual commands.
  73. - READ commands are read-only; writes are either ignored or return an error.
  74. - RESET commands are read/write. Reading reset registers returns zero
  75. (used for detection), writing any value causes the associated history to be
  76. reset.
  77. Virtual commands have to be handled in device specific driver code. Chip driver
  78. code returns non-negative values if a virtual command is supported, or a
  79. negative error code if not. The chip driver may return -ENODATA or any other
  80. Linux error code in this case, though an error code other than -ENODATA is
  81. handled more efficiently and thus preferred. Either case, the calling PMBus
  82. core code will abort if the chip driver returns an error code when reading
  83. or writing virtual registers (in other words, the PMBus core code will never
  84. send a virtual command to a chip).
  85. PMBus driver information
  86. ------------------------
  87. PMBus driver information, defined in struct pmbus_driver_info, is the main means
  88. for device specific drivers to pass information to the core PMBus driver.
  89. Specifically, it provides the following information.
  90. - For devices supporting its data in Direct Data Format, it provides coefficients
  91. for converting register values into normalized data. This data is usually
  92. provided by chip manufacturers in device datasheets.
  93. - Supported chip functionality can be provided to the core driver. This may be
  94. necessary for chips which react badly if non-supported commands are executed,
  95. and/or to speed up device detection and initialization.
  96. - Several function entry points are provided to support overriding and/or
  97. augmenting generic command execution. This functionality can be used to map
  98. non-standard PMBus commands to standard commands, or to augment standard
  99. command return values with device specific information.
  100. API functions
  101. =============
  102. Functions provided by chip driver
  103. ---------------------------------
  104. All functions return the command return value (read) or zero (write) if
  105. successful. A return value of -ENODATA indicates that there is no manufacturer
  106. specific command, but that a standard PMBus command may exist. Any other
  107. negative return value indicates that the commands does not exist for this
  108. chip, and that no attempt should be made to read or write the standard
  109. command.
  110. As mentioned above, an exception to this rule applies to virtual commands,
  111. which *must* be handled in driver specific code. See "Virtual PMBus Commands"
  112. above for more details.
  113. Command execution in the core PMBus driver code is as follows::
  114. if (chip_access_function) {
  115. status = chip_access_function();
  116. if (status != -ENODATA)
  117. return status;
  118. }
  119. if (command >= PMBUS_VIRT_BASE) /* For word commands/registers only */
  120. return -EINVAL;
  121. return generic_access();
  122. Chip drivers may provide pointers to the following functions in struct
  123. pmbus_driver_info. All functions are optional.
  124. ::
  125. int (*read_byte_data)(struct i2c_client *client, int page, int reg);
  126. Read byte from page <page>, register <reg>.
  127. <page> may be -1, which means "current page".
  128. ::
  129. int (*read_word_data)(struct i2c_client *client, int page, int phase,
  130. int reg);
  131. Read word from page <page>, phase <pase>, register <reg>. If the chip does not
  132. support multiple phases, the phase parameter can be ignored. If the chip
  133. supports multiple phases, a phase value of 0xff indicates all phases.
  134. ::
  135. int (*write_word_data)(struct i2c_client *client, int page, int reg,
  136. u16 word);
  137. Write word to page <page>, register <reg>.
  138. ::
  139. int (*write_byte)(struct i2c_client *client, int page, u8 value);
  140. Write byte to page <page>, register <reg>.
  141. <page> may be -1, which means "current page".
  142. ::
  143. int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info);
  144. Determine supported PMBus functionality. This function is only necessary
  145. if a chip driver supports multiple chips, and the chip functionality is not
  146. pre-determined. It is currently only used by the generic pmbus driver
  147. (pmbus.c).
  148. Functions exported by core driver
  149. ---------------------------------
  150. Chip drivers are expected to use the following functions to read or write
  151. PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C
  152. commands are used, the chip driver code must not directly modify the current
  153. page, since the selected page is cached in the core driver and the core driver
  154. will assume that it is selected. Using pmbus_set_page() to select a new page
  155. is mandatory.
  156. ::
  157. int pmbus_set_page(struct i2c_client *client, u8 page, u8 phase);
  158. Set PMBus page register to <page> and <phase> for subsequent commands.
  159. If the chip does not support multiple phases, the phase parameter is
  160. ignored. Otherwise, a phase value of 0xff selects all phases.
  161. ::
  162. int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 phase,
  163. u8 reg);
  164. Read word data from <page>, <phase>, <reg>. Similar to
  165. i2c_smbus_read_word_data(), but selects page and phase first. If the chip does
  166. not support multiple phases, the phase parameter is ignored. Otherwise, a phase
  167. value of 0xff selects all phases.
  168. ::
  169. int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg,
  170. u16 word);
  171. Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but
  172. selects page first.
  173. ::
  174. int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg);
  175. Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but
  176. selects page first. <page> may be -1, which means "current page".
  177. ::
  178. int pmbus_write_byte(struct i2c_client *client, int page, u8 value);
  179. Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but
  180. selects page first. <page> may be -1, which means "current page".
  181. ::
  182. void pmbus_clear_faults(struct i2c_client *client);
  183. Execute PMBus "Clear Fault" command on all chip pages.
  184. This function calls the device specific write_byte function if defined.
  185. Therefore, it must _not_ be called from that function.
  186. ::
  187. bool pmbus_check_byte_register(struct i2c_client *client, int page, int reg);
  188. Check if byte register exists. Return true if the register exists, false
  189. otherwise.
  190. This function calls the device specific write_byte function if defined to
  191. obtain the chip status. Therefore, it must _not_ be called from that function.
  192. ::
  193. bool pmbus_check_word_register(struct i2c_client *client, int page, int reg);
  194. Check if word register exists. Return true if the register exists, false
  195. otherwise.
  196. This function calls the device specific write_byte function if defined to
  197. obtain the chip status. Therefore, it must _not_ be called from that function.
  198. ::
  199. int pmbus_do_probe(struct i2c_client *client, struct pmbus_driver_info *info);
  200. Execute probe function. Similar to standard probe function for other drivers,
  201. with the pointer to struct pmbus_driver_info as additional argument. Calls
  202. identify function if supported. Must only be called from device probe
  203. function.
  204. ::
  205. void pmbus_do_remove(struct i2c_client *client);
  206. Execute driver remove function. Similar to standard driver remove function.
  207. ::
  208. const struct pmbus_driver_info
  209. *pmbus_get_driver_info(struct i2c_client *client);
  210. Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe().
  211. PMBus driver platform data
  212. ==========================
  213. PMBus platform data is defined in include/linux/pmbus.h. Platform data
  214. currently only provides a flag field with a single bit used::
  215. #define PMBUS_SKIP_STATUS_CHECK (1 << 0)
  216. struct pmbus_platform_data {
  217. u32 flags; /* Device specific flags */
  218. };
  219. Flags
  220. -----
  221. PMBUS_SKIP_STATUS_CHECK
  222. During register detection, skip checking the status register for
  223. communication or command errors.
  224. Some PMBus chips respond with valid data when trying to read an unsupported
  225. register. For such chips, checking the status register is mandatory when
  226. trying to determine if a chip register exists or not.
  227. Other PMBus chips don't support the STATUS_CML register, or report
  228. communication errors for no explicable reason. For such chips, checking the
  229. status register must be disabled.
  230. Some i2c controllers do not support single-byte commands (write commands with
  231. no data, i2c_smbus_write_byte()). With such controllers, clearing the status
  232. register is impossible, and the PMBUS_SKIP_STATUS_CHECK flag must be set.