sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget,/translations/zh_CN/power/regulator/consumermodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/zh_TW/power/regulator/consumermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/it_IT/power/regulator/consumermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/ja_JP/power/regulator/consumermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/ko_KR/power/regulator/consumermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/sp_SP/power/regulator/consumermodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h#Regulator Consumer Driver Interfaceh]h#Regulator Consumer Driver Interface}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhF/var/lib/git/docbuild/linux/Documentation/power/regulator/consumer.rsthKubh paragraph)}(hThis text describes the regulator interface for consumer device drivers. Please see overview.txt for a description of the terms used in this text.h]hThis text describes the regulator interface for consumer device drivers. Please see overview.txt for a description of the terms used in this text.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h71. Consumer Regulator Access (static & dynamic drivers)h]h71. Consumer Regulator Access (static & dynamic drivers)}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh)}(hFA consumer driver can get access to its supply regulator by calling ::h]hCA consumer driver can get access to its supply regulator by calling}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh literal_block)}(h®ulator = regulator_get(dev, "Vcc");h]h®ulator = regulator_get(dev, "Vcc");}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhKhhhhubh)}(hXThe consumer passes in its struct device pointer and power supply ID. The core then finds the correct regulator by consulting a machine specific lookup table. If the lookup is successful then this call will return a pointer to the struct regulator that supplies this consumer.h]hXThe consumer passes in its struct device pointer and power supply ID. The core then finds the correct regulator by consulting a machine specific lookup table. If the lookup is successful then this call will return a pointer to the struct regulator that supplies this consumer.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h;To release the regulator the consumer driver should call ::h]h8To release the regulator the consumer driver should call}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hregulator_put(regulator);h]hregulator_put(regulator);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhhhhubh)}(hlConsumers can be supplied by more than one regulator e.g. codec consumer with analog and digital supplies ::h]hiConsumers can be supplied by more than one regulator e.g. codec consumer with analog and digital supplies}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hkdigital = regulator_get(dev, "Vcc"); /* digital core */ analog = regulator_get(dev, "Avdd"); /* analog */h]hkdigital = regulator_get(dev, "Vcc"); /* digital core */ analog = regulator_get(dev, "Avdd"); /* analog */}hj0sbah}(h]h ]h"]h$]h&]hhuh1hhhhKhhhhubh)}(hThe regulator access functions regulator_get() and regulator_put() will usually be called in your device drivers probe() and remove() respectively.h]hThe regulator access functions regulator_get() and regulator_put() will usually be called in your device drivers probe() and remove() respectively.}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]0consumer-regulator-access-static-dynamic-driversah ]h"]71. consumer regulator access (static & dynamic drivers)ah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(h?2. Regulator Output Enable & Disable (static & dynamic drivers)h]h?2. Regulator Output Enable & Disable (static & dynamic drivers)}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjThhhhhK$ubh)}(h3A consumer can enable its power supply by calling::h]h2A consumer can enable its power supply by calling:}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hjThhubh)}(h int regulator_enable(regulator);h]h int regulator_enable(regulator);}hjssbah}(h]h ]h"]h$]h&]hhuh1hhhhK)hjThhubhdefinition_list)}(hhh]hdefinition_list_item)}(hNOTE: The supply may already be enabled before regulator_enable() is called. This may happen if the consumer shares the regulator or the regulator has been previously enabled by bootloader or kernel board initialization code. h](hterm)}(hNOTE:h]hNOTE:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK.hjubh definition)}(hhh]h)}(hThe supply may already be enabled before regulator_enable() is called. This may happen if the consumer shares the regulator or the regulator has been previously enabled by bootloader or kernel board initialization code.h]hThe supply may already be enabled before regulator_enable() is called. This may happen if the consumer shares the regulator or the regulator has been previously enabled by bootloader or kernel board initialization code.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK,hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK.hjubah}(h]h ]h"]h$]h&]uh1jhjThhhhhNubh)}(h?A consumer can determine if a regulator is enabled by calling::h]h>A consumer can determine if a regulator is enabled by calling:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK0hjThhubh)}(h$int regulator_is_enabled(regulator);h]h$int regulator_is_enabled(regulator);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhK2hjThhubh)}(h6This will return > zero when the regulator is enabled.h]h6This will return > zero when the regulator is enabled.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK4hjThhubh)}(hDA consumer can disable its supply when no longer needed by calling::h]hCA consumer can disable its supply when no longer needed by calling:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK7hjThhubh)}(h!int regulator_disable(regulator);h]h!int regulator_disable(regulator);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhK9hjThhubj)}(hhh]j)}(hNOTE: This may not disable the supply if it's shared with other consumers. The regulator will only be disabled when the enabled reference count is zero. h](j)}(hNOTE:h]hNOTE:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK=hj ubj)}(hhh]h)}(hThis may not disable the supply if it's shared with other consumers. The regulator will only be disabled when the enabled reference count is zero.h]hThis may not disable the supply if it’s shared with other consumers. The regulator will only be disabled when the enabled reference count is zero.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5. Regulator Operating Mode Control & Status (dynamic drivers)h]h>5. Regulator Operating Mode Control & Status (dynamic drivers)}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+hhhhhKubh)}(hSome consumers can further save system power by changing the operating mode of their supply regulator to be more efficient when the consumers operating state changes. e.g. consumer driver is idle and subsequently draws less currenth]hSome consumers can further save system power by changing the operating mode of their supply regulator to be more efficient when the consumers operating state changes. e.g. consumer driver is idle and subsequently draws less current}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj+hhubh)}(h?Regulator operating mode can be changed indirectly or directly.h]h?Regulator operating mode can be changed indirectly or directly.}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj+hhubh)}(hhh](h)}(h Indirect operating mode control.h]h Indirect operating mode control.}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjXhhhhhKubh)}(h[Consumer drivers can request a change in their supply regulator operating mode by calling::h]hZConsumer drivers can request a change in their supply regulator operating mode by calling:}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjXhhubh)}(hAint regulator_set_load(struct regulator *regulator, int load_uA);h]hAint regulator_set_load(struct regulator *regulator, int load_uA);}hjwsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjXhhubh)}(hThis will cause the core to recalculate the total load on the regulator (based on all its consumers) and change operating mode (if necessary and permitted) to best match the current operating load.h]hThis will cause the core to recalculate the total load on the regulator (based on all its consumers) and change operating mode (if necessary and permitted) to best match the current operating load.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjXhhubh)}(hThe load_uA value can be determined from the consumer's datasheet. e.g. most datasheets have tables showing the maximum current consumed in certain situations.h]hThe load_uA value can be determined from the consumer’s datasheet. e.g. most datasheets have tables showing the maximum current consumed in certain situations.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjXhhubh)}(hMost consumers will use indirect operating mode control since they have no knowledge of the regulator or whether the regulator is shared with other consumers.h]hMost consumers will use indirect operating mode control since they have no knowledge of the regulator or whether the regulator is shared with other consumers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjXhhubeh}(h]indirect-operating-mode-controlah ]h"] indirect operating mode control.ah$]h&]uh1hhj+hhhhhKubh)}(hhh](h)}(hDirect operating mode control.h]hDirect operating mode control.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hBespoke or tightly coupled drivers may want to directly control regulator operating mode depending on their operating point. This can be achieved by calling::h]hBespoke or tightly coupled drivers may want to directly control regulator operating mode depending on their operating point. This can be achieved by calling:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hint regulator_set_mode(struct regulator *regulator, unsigned int mode); unsigned int regulator_get_mode(struct regulator *regulator);h]hint regulator_set_mode(struct regulator *regulator, unsigned int mode); unsigned int regulator_get_mode(struct regulator *regulator);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(hDirect mode will only be used by consumers that *know* about the regulator and are not sharing the regulator with other consumers.h](h0Direct mode will only be used by consumers that }(hjhhhNhNubhemphasis)}(h*know*h]hknow}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhL about the regulator and are not sharing the regulator with other consumers.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]direct-operating-mode-controlah ]h"]direct operating mode control.ah$]h&]uh1hhj+hhhhhKubeh}(h]7regulator-operating-mode-control-status-dynamic-driversah ]h"]>5. regulator operating mode control & status (dynamic drivers)ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h6. Regulator Eventsh]h6. Regulator Events}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hRegulators can notify consumers of external events. Events could be received by consumers under regulator stress or failure conditions.h]hRegulators can notify consumers of external events. Events could be received by consumers under regulator stress or failure conditions.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h@Consumers can register interest in regulator events by calling::h]h?Consumers can register interest in regulator events by calling:}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hxint regulator_register_notifier(struct regulator *regulator, struct notifier_block *nb);h]hxint regulator_register_notifier(struct regulator *regulator, struct notifier_block *nb);}hjCsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(h.Consumers can unregister interest by calling::h]h-Consumers can unregister interest by calling:}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h|int regulator_unregister_notifier(struct regulator *regulator, struct notifier_block *nb);h]h|int regulator_unregister_notifier(struct regulator *regulator, struct notifier_block *nb);}hj_sbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(hYRegulators use the kernel notifier framework to send event to their interested consumers.h]hYRegulators use the kernel notifier framework to send event to their interested consumers.}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]regulator-eventsah ]h"]6. regulator eventsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h#7. Regulator Direct Register Accessh]h#7. Regulator Direct Register Access}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hSome kinds of power management hardware or firmware are designed such that they need to do low-level hardware access to regulators, with no involvement from the kernel. Examples of such devices are:h]hSome kinds of power management hardware or firmware are designed such that they need to do low-level hardware access to regulators, with no involvement from the kernel. Examples of such devices are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh bullet_list)}(hhh](h list_item)}(hclocksource with a voltage-controlled oscillator and control logic to change the supply voltage over I2C to achieve a desired output clock rateh]h)}(hclocksource with a voltage-controlled oscillator and control logic to change the supply voltage over I2C to achieve a desired output clock rateh]hclocksource with a voltage-controlled oscillator and control logic to change the supply voltage over I2C to achieve a desired output clock rate}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hthermal management firmware that can issue an arbitrary I2C transaction to perform system poweroff during overtemperature conditions h]h)}(hthermal management firmware that can issue an arbitrary I2C transaction to perform system poweroff during overtemperature conditionsh]hthermal management firmware that can issue an arbitrary I2C transaction to perform system poweroff during overtemperature conditions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKhjhhubh)}(hTo set up such a device/firmware, various parameters like I2C address of the regulator, addresses of various regulator registers etc. need to be configured to it. The regulator framework provides the following helpers for querying these details.h]hTo set up such a device/firmware, various parameters like I2C address of the regulator, addresses of various regulator registers etc. need to be configured to it. The regulator framework provides the following helpers for querying these details.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hBus-specific details, like I2C addresses or transfer rates are handled by the regmap framework. To get the regulator's regmap (if supported), use::h]hBus-specific details, like I2C addresses or transfer rates are handled by the regmap framework. To get the regulator’s regmap (if supported), use:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hAstruct regmap *regulator_get_regmap(struct regulator *regulator);h]hAstruct regmap *regulator_get_regmap(struct regulator *regulator);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(hgTo obtain the hardware register offset and bitmask for the regulator's voltage selector register, use::h]hhTo obtain the hardware register offset and bitmask for the regulator’s voltage selector register, use:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hint regulator_get_hardware_vsel_register(struct regulator *regulator, unsigned *vsel_reg, unsigned *vsel_mask);h]hint regulator_get_hardware_vsel_register(struct regulator *regulator, unsigned *vsel_reg, unsigned *vsel_mask);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(hTo convert a regulator framework voltage selector code (used by regulator_list_voltage) to a hardware-specific voltage selector that can be directly written to the voltage selector register, use::h]hTo convert a regulator framework voltage selector code (used by regulator_list_voltage) to a hardware-specific voltage selector that can be directly written to the voltage selector register, use:}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hrint regulator_list_hardware_vsel(struct regulator *regulator, unsigned selector);h]hrint regulator_list_hardware_vsel(struct regulator *regulator, unsigned selector);}hj5sbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(hTo access the hardware for enabling/disabling the regulator, consumers must use regulator_get_exclusive(), as it can't work if there's more than one consumer. To enable/disable regulator use::h]hTo access the hardware for enabling/disabling the regulator, consumers must use regulator_get_exclusive(), as it can’t work if there’s more than one consumer. To enable/disable regulator use:}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hHint regulator_hardware_enable(struct regulator *regulator, bool enable);h]hHint regulator_hardware_enable(struct regulator *regulator, bool enable);}hjQsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubeh}(h] regulator-direct-register-accessah ]h"]#7. regulator direct register accessah$]h&]uh1hhhhhhhhKubeh}(h]#regulator-consumer-driver-interfaceah ]h"]#regulator consumer driver interfaceah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jljijQjNjjjKjHj(j%jjjjj jjj}jdjau nametypes}(jljQjjKj(jjj jjduh}(jihjNhjjTjHjj%jNjj+jjXjjj}jjaju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.