linux/Documentation/hwmon/pmbus-core
<<
"v2./op/spa32. /op/form2. /opa "v2./o href="../linux+v30" 7/Documenta.6.3/hwm.3/pmbus-core">"v2./opimg src="../.sta.6c/gfx/right.png" alt=">>">"vp/spa32."vpspa3 class="lxr_search">"v2."v2./opinput typ"v2./opinput typ"v2./opbutt> typSearch 2. /op/form2. p/spa32."vpspa3 class="lxr_prefs"2. /opa href="+prefs?return=Documenta.6.3/hwm.3/pmbus-core""v2./o onclick="return ajax_prefs();">"v2./oPrefs. /op/a>"vp/spa32.2./o op/div2.2./o opform ac.6.3="ajax+*" method="post" onsubmit="return false;">"vpinput typ"2./o op/form2."2./o opdiv class="headingbott>m">o o1p/a>PMBus core driver and internal API o o2p/a>================================== o o3p/a>"o o4p/a>Introduc.6.3"o o5p/a>============"o o6p/a>"o o7p/a>[from pmbus.org] The Power Management Bus (PMBus) is an open standard"o o8p/a>power-management protocol with a fully defined command language that facilita.es"o o9p/a>communica.6.3 with power converters and other devices in a power system. The"o > a>protocol is implemented over the industry-standard SMBus serial interface and"o 11p/a>enables programming, control, and real-time m.3itoring of compliant power"o 12p/a>convers6.3 produc.s. This flexible and highly versa.6le standard allows for"o 13p/a>communica.6.3 between devices based o3 both analog and digital technologies, and"o 14 a>provides true interoperability which will reduce design complexity and shorte3"o 15p/a>time to market for power system designers. P6.3eered by leading power supply and"o 16p/a>semiconduc.or companies, this open power system standard is maintained and"o 17 a>promoted by the PMBus Implementers Forum (PMBus-IF), comprising 30+ adv2.ers"o 18p/a>with the objective to provide support to, and facilita.e adv2.6.3 am.3g, users."o 19p/a>"o 2 a>Unfortuna.ely, while PMBus commands are standardized, there are no manda.ory"o 21p/a>commands, and manufacturers can add as many non-standard commands as they like."o 22p/a>Also, different PMBUs devices act differently if non-supported commands are"o 23p/a>executed. Some devices return an error, some devices return 0xff or 0xffff and"o 24p/a>set a sta.us error flag, and some devices may simply hang up."o 25p/a>"o 26p/a>Despi.e all those difficulties, a generic PMBus device driver is still useful"o 27 a>and supported since kernel vers6.3 10" 39. However, it was necessary to support"o 28p/a>device specific exte3s6.3s in addi.6.3 to the core PMBus driver, since it is"o 29p/a>simply unknow3 what new device specific func.6.3ality PMBus device developers"o 30p/a>come up with next."o 31p/a>"o 32p/a>To make device specific exte3s6.3s as scalable as possible, and to avoid having"o 33p/a>to modify the core PMBus driver repea.edly for new devices, the PMBus driver was"o 34p/a>split into core, generic, and device specific code. The core code (i3"o 35p/a>pmbus_core.c) provides generic func.6.3ality. The generic code (i3 pmbus.c)"o 36 a>provides support for generic PMBus devices. Device specific code is resp.3sible"o 37 a>for device specific i3itializa.6.3 and, if needed, maps device specific"o 38p/a>func.6.3ality into generic func.6.3ality. This is to some degree comparable"o 39p/a>to PCI code, where generic code is augmented as needed with quirks for all kinds"o 40p/a>of devices."o 41p/a>"o 42p/a>PMBus device capabilities auto-detec.6.3"o 43p/a>========================================"o 44p/a>"o 45p/a>For generic PMBus devices, code i3 pmbus.c attempts to auto-detec. all supported"o 46p/a>PMBus commands. Auto-detec.6.3 is somewhat limi.ed, since there are simply too"o 47 a>many variables to co3sider. For example, it is almost impossible to autodetec."o 48p/a>which PMBus commands are paged and which commands are replica.ed across all"o 49p/a>pages (see the PMBus specifica.6.3 for details o3 multi-page PMBus devices)."o 50p/a>"o 51p/a>For this reason, it ofte3 makes sense to provide a device specific driver if no."o 52p/a>all commands can be auto-detec.ed. The data structures in this driver can be"o 53p/a>used to inform the core driver about func.6.3ality supported by individual"o 54p/a>chips."o 55p/a>"o 56p/a>Some commands are always auto-detec.ed. This applies to all limi. commands"o 57 a>(lcrit, min, max, and crit attributes) as well as associa.ed alarm attributes."o 58p/a>Limi.s and alarm attributes are auto-detec.ed because there are simply too many"o 59p/a>possible combina.6.3s to provide a manual configura.6.3 interface."o 60p/a>"o 61p/a>PMBus internal API o 62p/a>================== o 63p/a>"o 64p/a>The API between core and device specific PMBus code is defined i3"o 65p/a>drivers/hwm.3/pmbus/pmbus.h. In addi.6.3 to the internal API, pmbus.h defines"o 66p/a>standard PMBus commands and virtual PMBus commands."o 67p/a>"o 68p/a>Standard PMBus commands"o 69p/a>-----------------------"o 70p/a>"o 71p/a>Standard PMBus commands (commands o 72p/a>specifica.6.3."o 73p/a>"o 74p/a>Virtual PMBus commands"o 75p/a>----------------------"o 76p/a>"o 77p/a>Virtual PMBus commands are provided to enable support for non-standard"o 78p/a>func.6.3ality which has been implemented by several chip vendors and is thus"o 79p/a>desirable to support."o 80p/a>"o 81p/a>Virtual PMBus commands start with command < 0x100 and can thus easily be"o 82p/a>distinguished from standard PMBus commands (which can no. have o 83p/a>than 0xff). Support for virtual PMBus commands is device specific and thus has"o 84p/a>to be implemented in device specific code."o 85p/a>"o 86p/a>Virtual commands are namo 87p/a>virtual commands are word sized."o 88p/a>"o 89p/a>There are currently two typo 90p/a>"o 91p/a>- READ commands are read-only; writes are either ignored or return an error."o 92p/a>- RESET commands are read/write. Reading reset registers returns zero"o 93p/a> (used for detec.6.3), writing any va < causes the associa.ed history to be"o 94p/a> reset."o 95p/a>"o 96p/a>Virtual commands have to be handled in device specific driver code. Chip driver"o 97p/a>code returns non-negative o 98p/a>negative error code if no.. The chip driver may return -ENODATA or any other"o 99p/a>Linux error code in this case, though an error code other than -ENODATA is"o100p/a>handled more efficiently and thus preferred. Either case, th< calling PMBus"o101p/a>core code will abort if the chip driver returns an error code when reading"o102p/a>or writing virtual registers (i3 other words, the PMBus core code will never"o103p/a>send a virtual command to a chip)."o104p/a>"o105p/a>PMBus driver informa.6.3"o106p/a>------------------------"o107p/a>"o108p/a>PMBus driver informa.6.3, defined i3 struct pmbus_driver_info, is the main means"o109 a>for device specific drivers to pass informa.6.3 to the core PMBus driver."o1> a>Specifically, it provides the following informa.6.3."o111p/a>"o112p/a>- For devices supporting its data in Direc. Data Forma., it provides coefficients"o113p/a> for converting register o114p/a> provided by chip manufacturers in device datasheets."o115p/a>- Supported chip func.6.3ality can be provided to the core driver. This may be"o116p/a> necessary for chips which reac. badly if non-supported commands are executed,"o117 a> and/or to speed up device detec.6.3 and initializa.6.3."o118p/a>- Several func.6.3 entry points are provided to support overriding and/or"o119p/a> augmenting generic command execut6.3. This func.6.3ality can be used to map"o12 a> non-standard PMBus commands to standard commands, or to augment standard"o121p/a> command return o122p/a>"o123p/a> API func.6.3s"o124p/a> -------------"o125p/a>"o126p/a> Func.6.3s provided by chip driver"o127p/a> ---------------------------------"o128p/a>"o129p/a> All func.6.3s return the command return < (read) or zero (write) if"o13 a> successful. A return < of -ENODATA indica.es that there is no manufacturer"o131p/a> specific command, but that a standard PMBus command may exist. Any other"o132p/a> negative return < indica.es that the commands does no. exist for this"o133p/a> chip, and that no attempt should be made to read or write the standard"o134p/a> command."o135p/a>"o136p/a> As mentioned above, an excep.6.3 to this rule applies to virtual commands,"o137p/a> which _must_ be handled in driver specific code. See "Virtual PMBus Commands""o138p/a> above for more details."o139p/a>"o14 a> Command execut6.3 i3 the core PMBus driver code is as follows."o141p/a>"o142p/a> if (chip_access_func.6.3) {"o143p/a> sta.us = chip_access_func.6.3();"o144p/a> if (sta.us != -ENODATA)"o145p/a> return sta.us;"o146p/a> }"o147p/a> if (command >= PMBUS_VIRT_BASE) /* For word commands/registers only */"o148p/a> return -EINVAL;"o149p/a> return generic_access();"o150p/a>"o151p/a> Chip drivers may provide pointers to the following func.6.3s i3 struct"o152p/a> pmbus_driver_info. All func.6.3s are v2.6.3al."o153p/a>"o154p/a> int (*read_byte_data)(struct i2c_client *client, int page, int reg);"o155p/a>"o156p/a> Read byte from page <page>, register <reg>."o157p/a> <page> may be -1, which means "current page"."o158p/a>"o159p/a> int (*read_word_data)(struct i2c_client *client, int page, int reg);"o160p/a>"o161p/a> Read word from page <page>, register <reg>."o162p/a>"o163p/a> int (*write_word_data)(struct i2c_client *client, int page, int reg,"o164p/a> u16 word);"o165p/a>"o166p/a> Write word to page <page>, register <reg>."o167p/a>"o168p/a> int (*write_byte)(struct i2c_client *client, int page, u8 <);"o169p/a>"o170p/a> Write byte to page <page>, register <reg>."o171p/a> <page> may be -1, which means "current page"."o172p/a>"o173p/a> int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info);"o174p/a>"o175p/a> Determine supported PMBus func.6.3ality. This func.6.3 is only necessary"o176p/a> if a chip driver supports multiple chips, and the chip func.6.3ality is not"o177p/a> pre-determined. It is currently only used by the generic pmbus driver"o178p/a> (pmbus.c)."o179p/a>"o180p/a> Func.6.3s exported by core driver"o181p/a> ---------------------------------"o182p/a>"o183p/a> Chip drivers are expec.ed to use the following func.6.3s to read or write"o184p/a> PMBus registers. Chip drivers may also use direc. I2C commands. If direc. I2C"o185p/a> commands are used, the chip driver code must no. direc.ly modify the current"o186p/a> page, since the selected page is cached i3 the core driver and the core driver"o187p/a> will assume that it is selected. Using pmbus_set_page() to select a new page"o188p/a> is manda.ory."o189p/a>"o190p/a> int pmbus_set_page(struct i2c_client *client, u8 page);"o191p/a>"o192p/a> Set PMBus page register to <page> for subsequent commands."o193p/a>"o194p/a> int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 reg);"o195p/a>"o196p/a> Read word data from <page>, <reg>. Similar to i2c_smbus_read_word_data(), but"o197p/a> selects page first."o198p/a>"o199p/a> int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg,"o200p/a> u16 word);"o201p/a>"o202p/a> Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but"o203p/a> selects page first."o204p/a>"o205p/a> int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg);"o206p/a>"o207p/a> Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but"o208p/a> selects page first. <page> may be -1, which means "current page"."o209p/a>"o210p/a> int pmbus_write_byte(struct i2c_client *client, int page, u8 <);"o211p/a>"o212p/a> Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but"o213p/a> selects page first. <page> may be -1, which means "current page"."o214p/a>"o215p/a> void pmbus_clear_faults(struct i2c_client *client);"o216p/a>"o217 a> Execute PMBus "Clear Fault" command .3 all chip pages."o218p/a> This func.6.3 calls the device specific write_byte func.6.3 if defined."o219p/a> a2ref0">o210p/is almo. di_nohandlethe m standaacilit3 if deref="Documenta.6.3/hwm.3/pmbus-core#L22" idoppL210" class="line" namo 22 a22o 221p/a2 commanbool_clear_fheckdata()er to < i2c_client *client, int page, int reg);"o 222p/a>"o 223p/a22 Chip drieckfineunc.6er to <for tsing he comteropchip der to <for ts,;">"vpef="Documenta.6.3/hwm.3/pmbus-core#L123" i2opL214" class="line" namo 224p/a2 ------o 225p/a225This func.6.3 calls the device specific write_byte func.6.3 if defined."o 226p/a2 Func.6ob andhip driver;"o210p/is almo. di_nohandlethe m standaacilit3 if deref="Documenta.6.3/hwm.3/pmbus-core#L22" idoppL217" class="line" namo 227p/a22o 228p/a228commanbool_clear_fheckdata()er to < i2c_client *client, int page, int reg);"o 229p/a22o23 a2 succesrieckfineata ter to <for tsing he comteropchip der to <for ts,;">"vpef="Documenta.6.3/hwm.3/pmbus-core#L123" i2opL131" c2ass="line" namo231p/a2 specifo232p/a2 negatiunc.6.3 calls the device specific write_byte func.6.3 if defined."o233p/a2 chip, ob andhip driver;"o210p/is almo. di_nohandlethe m standaacilit3 if deref="Documenta.6.3/hwm.3/pmbus-core#L22" idoopL134" c2ass="line" namo234p/a23o235p/a23 int pmbus_read_bdo_probct i2c_client *client, int paer. t i2c_client speci_us_*ihref="Documenta.6.3/hwm.3/pmbus-core#L117" i2opL136" c2ass="line" namo236p/a23 }"o237p/a23o238p/a2 above e PMBus probcit3 if derar to i2c_smrd PMBus probcit3 if deubseqdevices may aref="Documenta.6.3/hwm.3/pmbus-core#L117" i2opL2ore#L1ass="line" namo239p/a239will ass objectrs to tc_smrdmbus_driver_info *info)ocia3 to thal arg.6.3/. Che def="Documenta.6.3/hwm.3/pmbus-core#L117" i2opL140" c2ass="line" namo24 a2 Commanfy)(stru6.3 if defineted PMBus. M. dised bdlethe m standa specifprobcef="Documenta.6.3/hwm.3/pmbus-core#L117" i2opL131" c2ass="line" namo241p/a24 specift3 if deref="Documenta.6.3/hwm.3/pmbus-core#L22" idoopL142" c2ass="line" namo242p/a24o243p/a2 mbus_clear_do_removct i2c_client *client, int href="Documenta.6.3/hwm.3/pmbus-core#L174" i2opL144" c2ass="line" namo244p/a2"o245p/a2 e PMBus returns mr mor3 if derar to i2c_smrd PMBus returns mr mor3 if deref="Documenta.6.3/hwm.3/pmbus-core#L45" id2opL136" c2ass="line" namo246p/a24o247p/a2 er. t i2c_cldriver_info *infoef="Documenta.6.3/hwm.3/pmbus-core#L217" idopL138" c2ass="line" namo248p/a2 *drivergetr_info *infot i2c_client *client, int href="Documenta.6.3/hwm.3/pmbus-core#L174" i2opL2ore#L1ass="line" namo249p/a24o250p/a250Read bythe cors to tc_smrdmbus_driver_info *info)ocinforuse thread_bdo_probcthref="Documenta.6.3/hwm.3/pmbus-core#L179" i2opL151" c2ass="line" namo251p/a25o252p/a25o253p/a2"o254p/a2 int ===================="o255p/a2"o256p/a25MBus commanplathe coo &lfined i3"o257p/a2 <tly only used bes coeffia and fiel quirksa thegle balmthe ref="Documenta.6.3/hwm.3/pmbus-core#L179" i2opL138" c2ass="line" namo258p/a2"o259p/a2 int #d i3"<_VIRT_BSKIP_STATT_BCHECK (1age&gge&g 0ref="Documenta.6.3/hwm.3/pmbus-core#L145" i2opL160" c2ass="line" namo260p/a2"o261p/a2 Readrdmbus_driverplathe c), buhref="Documenta.6.3/hwm.3/pmbus-core#L143" i2opL162" c2ass="line" namo262p/a26 if (chu32 and s;hhhhhhhhhhhhhh/*e specific code iand s href="Documenta.6.3/hwm.3/pmbus-core#L148" i2opL163" c2ass="line" namo263p/a2 int }ref="Documenta.6.3/hwm.3/pmbus-core#L174" i2opL164" c2ass="line" namo264p/a26o265p/a2"o266p/a2 WritFnd sef="Documenta.6.3/hwm.3/pmbus-core#L166" i2opL147" c2ass="line" namo267p/a2"o268p/a26o269p/a2"o270p/a2"o271p/a2 <Durgister o272p/a2"o273p/a2"o274p/a2"o275p/a2 Deteers. Chiexamplsu no.and thfheckgistandard"tisters. Chiuda.ory."o276p/a2 if atrygista oined. It chip driverer to <for ts -stanhref="Documenta.6.3/hwm.3/pmbus-core#L204" idopL177" c2ass="line" namo277p/a2 pre-Oevicecommandhich don'trt overriandaSTATT_BCMLrer to &l,turn averref="Documenta.6.3/hwm.3/pmbus-core#L204" idopL168" c2ass="line" namo278p/a2 (pmbd .3un3 for de6ode hon-stan.ed d ac sup, it oexamplsu no.and thfheckgistandef="Documenta.6.3/hwm.3/pmbus-core#L204" idopL169" c2ass="line" namo279p/a2"o280p/a2"o281p/a2 ----ommanien er.trolly aldoirec.t overrithegle-unc.6ds (which cyte dds (whichuirkef="Documenta.6.3/hwm.3/pmbus-core#L81" id2opL162" c2ass="line" namo282p/a2"o283p/a2 Chipers. Chiuda.ible to authe chip fVIRT_BSKIP_STATT_BCHECK and o. dibc.a href="Documenta.6.3/hwm.3/pmbus-core#L95" id2opL184" c2ass="line" namo284p/a2 PMBu
ip dorigihal LXR softwed, generif="Documehttp://sourc10p/ge.net/projage /lxi">LXR d .3un3tyPMBu,rule aed tri6.3/hl ay ar de gef="Documemailto:lxi@lrror.no">lxi@lrror.noPMBu.
lxi.lrror.no"Redpill Lrrpro ASPMBu,res coefrNODALrror er. e ch/or"