LCOV - code coverage report
Current view: top level - include/linux - clk.h (source / functions) Hit Total Coverage
Test: Real Lines: 8 9 88.9 %
Date: 2020-10-17 15:46:16 Functions: 0 1 0.0 %
Legend: Neither, QEMU, Real, Both Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : /* SPDX-License-Identifier: GPL-2.0-only */
       2                 :            : /*
       3                 :            :  *  linux/include/linux/clk.h
       4                 :            :  *
       5                 :            :  *  Copyright (C) 2004 ARM Limited.
       6                 :            :  *  Written by Deep Blue Solutions Limited.
       7                 :            :  *  Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org>
       8                 :            :  */
       9                 :            : #ifndef __LINUX_CLK_H
      10                 :            : #define __LINUX_CLK_H
      11                 :            : 
      12                 :            : #include <linux/err.h>
      13                 :            : #include <linux/kernel.h>
      14                 :            : #include <linux/notifier.h>
      15                 :            : 
      16                 :            : struct device;
      17                 :            : struct clk;
      18                 :            : struct device_node;
      19                 :            : struct of_phandle_args;
      20                 :            : 
      21                 :            : /**
      22                 :            :  * DOC: clk notifier callback types
      23                 :            :  *
      24                 :            :  * PRE_RATE_CHANGE - called immediately before the clk rate is changed,
      25                 :            :  *     to indicate that the rate change will proceed.  Drivers must
      26                 :            :  *     immediately terminate any operations that will be affected by the
      27                 :            :  *     rate change.  Callbacks may either return NOTIFY_DONE, NOTIFY_OK,
      28                 :            :  *     NOTIFY_STOP or NOTIFY_BAD.
      29                 :            :  *
      30                 :            :  * ABORT_RATE_CHANGE: called if the rate change failed for some reason
      31                 :            :  *     after PRE_RATE_CHANGE.  In this case, all registered notifiers on
      32                 :            :  *     the clk will be called with ABORT_RATE_CHANGE. Callbacks must
      33                 :            :  *     always return NOTIFY_DONE or NOTIFY_OK.
      34                 :            :  *
      35                 :            :  * POST_RATE_CHANGE - called after the clk rate change has successfully
      36                 :            :  *     completed.  Callbacks must always return NOTIFY_DONE or NOTIFY_OK.
      37                 :            :  *
      38                 :            :  */
      39                 :            : #define PRE_RATE_CHANGE                 BIT(0)
      40                 :            : #define POST_RATE_CHANGE                BIT(1)
      41                 :            : #define ABORT_RATE_CHANGE               BIT(2)
      42                 :            : 
      43                 :            : /**
      44                 :            :  * struct clk_notifier - associate a clk with a notifier
      45                 :            :  * @clk: struct clk * to associate the notifier with
      46                 :            :  * @notifier_head: a blocking_notifier_head for this clk
      47                 :            :  * @node: linked list pointers
      48                 :            :  *
      49                 :            :  * A list of struct clk_notifier is maintained by the notifier code.
      50                 :            :  * An entry is created whenever code registers the first notifier on a
      51                 :            :  * particular @clk.  Future notifiers on that @clk are added to the
      52                 :            :  * @notifier_head.
      53                 :            :  */
      54                 :            : struct clk_notifier {
      55                 :            :         struct clk                      *clk;
      56                 :            :         struct srcu_notifier_head       notifier_head;
      57                 :            :         struct list_head                node;
      58                 :            : };
      59                 :            : 
      60                 :            : /**
      61                 :            :  * struct clk_notifier_data - rate data to pass to the notifier callback
      62                 :            :  * @clk: struct clk * being changed
      63                 :            :  * @old_rate: previous rate of this clk
      64                 :            :  * @new_rate: new rate of this clk
      65                 :            :  *
      66                 :            :  * For a pre-notifier, old_rate is the clk's rate before this rate
      67                 :            :  * change, and new_rate is what the rate will be in the future.  For a
      68                 :            :  * post-notifier, old_rate and new_rate are both set to the clk's
      69                 :            :  * current rate (this was done to optimize the implementation).
      70                 :            :  */
      71                 :            : struct clk_notifier_data {
      72                 :            :         struct clk              *clk;
      73                 :            :         unsigned long           old_rate;
      74                 :            :         unsigned long           new_rate;
      75                 :            : };
      76                 :            : 
      77                 :            : /**
      78                 :            :  * struct clk_bulk_data - Data used for bulk clk operations.
      79                 :            :  *
      80                 :            :  * @id: clock consumer ID
      81                 :            :  * @clk: struct clk * to store the associated clock
      82                 :            :  *
      83                 :            :  * The CLK APIs provide a series of clk_bulk_() API calls as
      84                 :            :  * a convenience to consumers which require multiple clks.  This
      85                 :            :  * structure is used to manage data for these calls.
      86                 :            :  */
      87                 :            : struct clk_bulk_data {
      88                 :            :         const char              *id;
      89                 :            :         struct clk              *clk;
      90                 :            : };
      91                 :            : 
      92                 :            : #ifdef CONFIG_COMMON_CLK
      93                 :            : 
      94                 :            : /**
      95                 :            :  * clk_notifier_register: register a clock rate-change notifier callback
      96                 :            :  * @clk: clock whose rate we are interested in
      97                 :            :  * @nb: notifier block with callback function pointer
      98                 :            :  *
      99                 :            :  * ProTip: debugging across notifier chains can be frustrating. Make sure that
     100                 :            :  * your notifier callback function prints a nice big warning in case of
     101                 :            :  * failure.
     102                 :            :  */
     103                 :            : int clk_notifier_register(struct clk *clk, struct notifier_block *nb);
     104                 :            : 
     105                 :            : /**
     106                 :            :  * clk_notifier_unregister: unregister a clock rate-change notifier callback
     107                 :            :  * @clk: clock whose rate we are no longer interested in
     108                 :            :  * @nb: notifier block which will be unregistered
     109                 :            :  */
     110                 :            : int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb);
     111                 :            : 
     112                 :            : /**
     113                 :            :  * clk_get_accuracy - obtain the clock accuracy in ppb (parts per billion)
     114                 :            :  *                    for a clock source.
     115                 :            :  * @clk: clock source
     116                 :            :  *
     117                 :            :  * This gets the clock source accuracy expressed in ppb.
     118                 :            :  * A perfect clock returns 0.
     119                 :            :  */
     120                 :            : long clk_get_accuracy(struct clk *clk);
     121                 :            : 
     122                 :            : /**
     123                 :            :  * clk_set_phase - adjust the phase shift of a clock signal
     124                 :            :  * @clk: clock signal source
     125                 :            :  * @degrees: number of degrees the signal is shifted
     126                 :            :  *
     127                 :            :  * Shifts the phase of a clock signal by the specified degrees. Returns 0 on
     128                 :            :  * success, -EERROR otherwise.
     129                 :            :  */
     130                 :            : int clk_set_phase(struct clk *clk, int degrees);
     131                 :            : 
     132                 :            : /**
     133                 :            :  * clk_get_phase - return the phase shift of a clock signal
     134                 :            :  * @clk: clock signal source
     135                 :            :  *
     136                 :            :  * Returns the phase shift of a clock node in degrees, otherwise returns
     137                 :            :  * -EERROR.
     138                 :            :  */
     139                 :            : int clk_get_phase(struct clk *clk);
     140                 :            : 
     141                 :            : /**
     142                 :            :  * clk_set_duty_cycle - adjust the duty cycle ratio of a clock signal
     143                 :            :  * @clk: clock signal source
     144                 :            :  * @num: numerator of the duty cycle ratio to be applied
     145                 :            :  * @den: denominator of the duty cycle ratio to be applied
     146                 :            :  *
     147                 :            :  * Adjust the duty cycle of a clock signal by the specified ratio. Returns 0 on
     148                 :            :  * success, -EERROR otherwise.
     149                 :            :  */
     150                 :            : int clk_set_duty_cycle(struct clk *clk, unsigned int num, unsigned int den);
     151                 :            : 
     152                 :            : /**
     153                 :            :  * clk_get_duty_cycle - return the duty cycle ratio of a clock signal
     154                 :            :  * @clk: clock signal source
     155                 :            :  * @scale: scaling factor to be applied to represent the ratio as an integer
     156                 :            :  *
     157                 :            :  * Returns the duty cycle ratio multiplied by the scale provided, otherwise
     158                 :            :  * returns -EERROR.
     159                 :            :  */
     160                 :            : int clk_get_scaled_duty_cycle(struct clk *clk, unsigned int scale);
     161                 :            : 
     162                 :            : /**
     163                 :            :  * clk_is_match - check if two clk's point to the same hardware clock
     164                 :            :  * @p: clk compared against q
     165                 :            :  * @q: clk compared against p
     166                 :            :  *
     167                 :            :  * Returns true if the two struct clk pointers both point to the same hardware
     168                 :            :  * clock node. Put differently, returns true if @p and @q
     169                 :            :  * share the same &struct clk_core object.
     170                 :            :  *
     171                 :            :  * Returns false otherwise. Note that two NULL clks are treated as matching.
     172                 :            :  */
     173                 :            : bool clk_is_match(const struct clk *p, const struct clk *q);
     174                 :            : 
     175                 :            : #else
     176                 :            : 
     177                 :            : static inline int clk_notifier_register(struct clk *clk,
     178                 :            :                                         struct notifier_block *nb)
     179                 :            : {
     180                 :            :         return -ENOTSUPP;
     181                 :            : }
     182                 :            : 
     183                 :            : static inline int clk_notifier_unregister(struct clk *clk,
     184                 :            :                                           struct notifier_block *nb)
     185                 :            : {
     186                 :            :         return -ENOTSUPP;
     187                 :            : }
     188                 :            : 
     189                 :            : static inline long clk_get_accuracy(struct clk *clk)
     190                 :            : {
     191                 :            :         return -ENOTSUPP;
     192                 :            : }
     193                 :            : 
     194                 :            : static inline long clk_set_phase(struct clk *clk, int phase)
     195                 :            : {
     196                 :            :         return -ENOTSUPP;
     197                 :            : }
     198                 :            : 
     199                 :            : static inline long clk_get_phase(struct clk *clk)
     200                 :            : {
     201                 :            :         return -ENOTSUPP;
     202                 :            : }
     203                 :            : 
     204                 :            : static inline int clk_set_duty_cycle(struct clk *clk, unsigned int num,
     205                 :            :                                      unsigned int den)
     206                 :            : {
     207                 :            :         return -ENOTSUPP;
     208                 :            : }
     209                 :            : 
     210                 :            : static inline unsigned int clk_get_scaled_duty_cycle(struct clk *clk,
     211                 :            :                                                      unsigned int scale)
     212                 :            : {
     213                 :            :         return 0;
     214                 :            : }
     215                 :            : 
     216                 :            : static inline bool clk_is_match(const struct clk *p, const struct clk *q)
     217                 :            : {
     218                 :            :         return p == q;
     219                 :            : }
     220                 :            : 
     221                 :            : #endif
     222                 :            : 
     223                 :            : /**
     224                 :            :  * clk_prepare - prepare a clock source
     225                 :            :  * @clk: clock source
     226                 :            :  *
     227                 :            :  * This prepares the clock source for use.
     228                 :            :  *
     229                 :            :  * Must not be called from within atomic context.
     230                 :            :  */
     231                 :            : #ifdef CONFIG_HAVE_CLK_PREPARE
     232                 :            : int clk_prepare(struct clk *clk);
     233                 :            : int __must_check clk_bulk_prepare(int num_clks,
     234                 :            :                                   const struct clk_bulk_data *clks);
     235                 :            : #else
     236                 :            : static inline int clk_prepare(struct clk *clk)
     237                 :            : {
     238                 :            :         might_sleep();
     239                 :            :         return 0;
     240                 :            : }
     241                 :            : 
     242                 :            : static inline int __must_check
     243                 :            : clk_bulk_prepare(int num_clks, const struct clk_bulk_data *clks)
     244                 :            : {
     245                 :            :         might_sleep();
     246                 :            :         return 0;
     247                 :            : }
     248                 :            : #endif
     249                 :            : 
     250                 :            : /**
     251                 :            :  * clk_unprepare - undo preparation of a clock source
     252                 :            :  * @clk: clock source
     253                 :            :  *
     254                 :            :  * This undoes a previously prepared clock.  The caller must balance
     255                 :            :  * the number of prepare and unprepare calls.
     256                 :            :  *
     257                 :            :  * Must not be called from within atomic context.
     258                 :            :  */
     259                 :            : #ifdef CONFIG_HAVE_CLK_PREPARE
     260                 :            : void clk_unprepare(struct clk *clk);
     261                 :            : void clk_bulk_unprepare(int num_clks, const struct clk_bulk_data *clks);
     262                 :            : #else
     263                 :            : static inline void clk_unprepare(struct clk *clk)
     264                 :            : {
     265                 :            :         might_sleep();
     266                 :            : }
     267                 :            : static inline void clk_bulk_unprepare(int num_clks,
     268                 :            :                                       const struct clk_bulk_data *clks)
     269                 :            : {
     270                 :            :         might_sleep();
     271                 :            : }
     272                 :            : #endif
     273                 :            : 
     274                 :            : #ifdef CONFIG_HAVE_CLK
     275                 :            : /**
     276                 :            :  * clk_get - lookup and obtain a reference to a clock producer.
     277                 :            :  * @dev: device for clock "consumer"
     278                 :            :  * @id: clock consumer ID
     279                 :            :  *
     280                 :            :  * Returns a struct clk corresponding to the clock producer, or
     281                 :            :  * valid IS_ERR() condition containing errno.  The implementation
     282                 :            :  * uses @dev and @id to determine the clock consumer, and thereby
     283                 :            :  * the clock producer.  (IOW, @id may be identical strings, but
     284                 :            :  * clk_get may return different clock producers depending on @dev.)
     285                 :            :  *
     286                 :            :  * Drivers must assume that the clock source is not enabled.
     287                 :            :  *
     288                 :            :  * clk_get should not be called from within interrupt context.
     289                 :            :  */
     290                 :            : struct clk *clk_get(struct device *dev, const char *id);
     291                 :            : 
     292                 :            : /**
     293                 :            :  * clk_bulk_get - lookup and obtain a number of references to clock producer.
     294                 :            :  * @dev: device for clock "consumer"
     295                 :            :  * @num_clks: the number of clk_bulk_data
     296                 :            :  * @clks: the clk_bulk_data table of consumer
     297                 :            :  *
     298                 :            :  * This helper function allows drivers to get several clk consumers in one
     299                 :            :  * operation. If any of the clk cannot be acquired then any clks
     300                 :            :  * that were obtained will be freed before returning to the caller.
     301                 :            :  *
     302                 :            :  * Returns 0 if all clocks specified in clk_bulk_data table are obtained
     303                 :            :  * successfully, or valid IS_ERR() condition containing errno.
     304                 :            :  * The implementation uses @dev and @clk_bulk_data.id to determine the
     305                 :            :  * clock consumer, and thereby the clock producer.
     306                 :            :  * The clock returned is stored in each @clk_bulk_data.clk field.
     307                 :            :  *
     308                 :            :  * Drivers must assume that the clock source is not enabled.
     309                 :            :  *
     310                 :            :  * clk_bulk_get should not be called from within interrupt context.
     311                 :            :  */
     312                 :            : int __must_check clk_bulk_get(struct device *dev, int num_clks,
     313                 :            :                               struct clk_bulk_data *clks);
     314                 :            : /**
     315                 :            :  * clk_bulk_get_all - lookup and obtain all available references to clock
     316                 :            :  *                    producer.
     317                 :            :  * @dev: device for clock "consumer"
     318                 :            :  * @clks: pointer to the clk_bulk_data table of consumer
     319                 :            :  *
     320                 :            :  * This helper function allows drivers to get all clk consumers in one
     321                 :            :  * operation. If any of the clk cannot be acquired then any clks
     322                 :            :  * that were obtained will be freed before returning to the caller.
     323                 :            :  *
     324                 :            :  * Returns a positive value for the number of clocks obtained while the
     325                 :            :  * clock references are stored in the clk_bulk_data table in @clks field.
     326                 :            :  * Returns 0 if there're none and a negative value if something failed.
     327                 :            :  *
     328                 :            :  * Drivers must assume that the clock source is not enabled.
     329                 :            :  *
     330                 :            :  * clk_bulk_get should not be called from within interrupt context.
     331                 :            :  */
     332                 :            : int __must_check clk_bulk_get_all(struct device *dev,
     333                 :            :                                   struct clk_bulk_data **clks);
     334                 :            : 
     335                 :            : /**
     336                 :            :  * clk_bulk_get_optional - lookup and obtain a number of references to clock producer
     337                 :            :  * @dev: device for clock "consumer"
     338                 :            :  * @num_clks: the number of clk_bulk_data
     339                 :            :  * @clks: the clk_bulk_data table of consumer
     340                 :            :  *
     341                 :            :  * Behaves the same as clk_bulk_get() except where there is no clock producer.
     342                 :            :  * In this case, instead of returning -ENOENT, the function returns 0 and
     343                 :            :  * NULL for a clk for which a clock producer could not be determined.
     344                 :            :  */
     345                 :            : int __must_check clk_bulk_get_optional(struct device *dev, int num_clks,
     346                 :            :                                        struct clk_bulk_data *clks);
     347                 :            : /**
     348                 :            :  * devm_clk_bulk_get - managed get multiple clk consumers
     349                 :            :  * @dev: device for clock "consumer"
     350                 :            :  * @num_clks: the number of clk_bulk_data
     351                 :            :  * @clks: the clk_bulk_data table of consumer
     352                 :            :  *
     353                 :            :  * Return 0 on success, an errno on failure.
     354                 :            :  *
     355                 :            :  * This helper function allows drivers to get several clk
     356                 :            :  * consumers in one operation with management, the clks will
     357                 :            :  * automatically be freed when the device is unbound.
     358                 :            :  */
     359                 :            : int __must_check devm_clk_bulk_get(struct device *dev, int num_clks,
     360                 :            :                                    struct clk_bulk_data *clks);
     361                 :            : /**
     362                 :            :  * devm_clk_bulk_get_optional - managed get multiple optional consumer clocks
     363                 :            :  * @dev: device for clock "consumer"
     364                 :            :  * @num_clks: the number of clk_bulk_data
     365                 :            :  * @clks: pointer to the clk_bulk_data table of consumer
     366                 :            :  *
     367                 :            :  * Behaves the same as devm_clk_bulk_get() except where there is no clock
     368                 :            :  * producer.  In this case, instead of returning -ENOENT, the function returns
     369                 :            :  * NULL for given clk. It is assumed all clocks in clk_bulk_data are optional.
     370                 :            :  *
     371                 :            :  * Returns 0 if all clocks specified in clk_bulk_data table are obtained
     372                 :            :  * successfully or for any clk there was no clk provider available, otherwise
     373                 :            :  * returns valid IS_ERR() condition containing errno.
     374                 :            :  * The implementation uses @dev and @clk_bulk_data.id to determine the
     375                 :            :  * clock consumer, and thereby the clock producer.
     376                 :            :  * The clock returned is stored in each @clk_bulk_data.clk field.
     377                 :            :  *
     378                 :            :  * Drivers must assume that the clock source is not enabled.
     379                 :            :  *
     380                 :            :  * clk_bulk_get should not be called from within interrupt context.
     381                 :            :  */
     382                 :            : int __must_check devm_clk_bulk_get_optional(struct device *dev, int num_clks,
     383                 :            :                                             struct clk_bulk_data *clks);
     384                 :            : /**
     385                 :            :  * devm_clk_bulk_get_all - managed get multiple clk consumers
     386                 :            :  * @dev: device for clock "consumer"
     387                 :            :  * @clks: pointer to the clk_bulk_data table of consumer
     388                 :            :  *
     389                 :            :  * Returns a positive value for the number of clocks obtained while the
     390                 :            :  * clock references are stored in the clk_bulk_data table in @clks field.
     391                 :            :  * Returns 0 if there're none and a negative value if something failed.
     392                 :            :  *
     393                 :            :  * This helper function allows drivers to get several clk
     394                 :            :  * consumers in one operation with management, the clks will
     395                 :            :  * automatically be freed when the device is unbound.
     396                 :            :  */
     397                 :            : 
     398                 :            : int __must_check devm_clk_bulk_get_all(struct device *dev,
     399                 :            :                                        struct clk_bulk_data **clks);
     400                 :            : 
     401                 :            : /**
     402                 :            :  * devm_clk_get - lookup and obtain a managed reference to a clock producer.
     403                 :            :  * @dev: device for clock "consumer"
     404                 :            :  * @id: clock consumer ID
     405                 :            :  *
     406                 :            :  * Returns a struct clk corresponding to the clock producer, or
     407                 :            :  * valid IS_ERR() condition containing errno.  The implementation
     408                 :            :  * uses @dev and @id to determine the clock consumer, and thereby
     409                 :            :  * the clock producer.  (IOW, @id may be identical strings, but
     410                 :            :  * clk_get may return different clock producers depending on @dev.)
     411                 :            :  *
     412                 :            :  * Drivers must assume that the clock source is not enabled.
     413                 :            :  *
     414                 :            :  * devm_clk_get should not be called from within interrupt context.
     415                 :            :  *
     416                 :            :  * The clock will automatically be freed when the device is unbound
     417                 :            :  * from the bus.
     418                 :            :  */
     419                 :            : struct clk *devm_clk_get(struct device *dev, const char *id);
     420                 :            : 
     421                 :            : /**
     422                 :            :  * devm_clk_get_optional - lookup and obtain a managed reference to an optional
     423                 :            :  *                         clock producer.
     424                 :            :  * @dev: device for clock "consumer"
     425                 :            :  * @id: clock consumer ID
     426                 :            :  *
     427                 :            :  * Behaves the same as devm_clk_get() except where there is no clock producer.
     428                 :            :  * In this case, instead of returning -ENOENT, the function returns NULL.
     429                 :            :  */
     430                 :            : struct clk *devm_clk_get_optional(struct device *dev, const char *id);
     431                 :            : 
     432                 :            : /**
     433                 :            :  * devm_get_clk_from_child - lookup and obtain a managed reference to a
     434                 :            :  *                           clock producer from child node.
     435                 :            :  * @dev: device for clock "consumer"
     436                 :            :  * @np: pointer to clock consumer node
     437                 :            :  * @con_id: clock consumer ID
     438                 :            :  *
     439                 :            :  * This function parses the clocks, and uses them to look up the
     440                 :            :  * struct clk from the registered list of clock providers by using
     441                 :            :  * @np and @con_id
     442                 :            :  *
     443                 :            :  * The clock will automatically be freed when the device is unbound
     444                 :            :  * from the bus.
     445                 :            :  */
     446                 :            : struct clk *devm_get_clk_from_child(struct device *dev,
     447                 :            :                                     struct device_node *np, const char *con_id);
     448                 :            : /**
     449                 :            :  * clk_rate_exclusive_get - get exclusivity over the rate control of a
     450                 :            :  *                          producer
     451                 :            :  * @clk: clock source
     452                 :            :  *
     453                 :            :  * This function allows drivers to get exclusive control over the rate of a
     454                 :            :  * provider. It prevents any other consumer to execute, even indirectly,
     455                 :            :  * opereation which could alter the rate of the provider or cause glitches
     456                 :            :  *
     457                 :            :  * If exlusivity is claimed more than once on clock, even by the same driver,
     458                 :            :  * the rate effectively gets locked as exclusivity can't be preempted.
     459                 :            :  *
     460                 :            :  * Must not be called from within atomic context.
     461                 :            :  *
     462                 :            :  * Returns success (0) or negative errno.
     463                 :            :  */
     464                 :            : int clk_rate_exclusive_get(struct clk *clk);
     465                 :            : 
     466                 :            : /**
     467                 :            :  * clk_rate_exclusive_put - release exclusivity over the rate control of a
     468                 :            :  *                          producer
     469                 :            :  * @clk: clock source
     470                 :            :  *
     471                 :            :  * This function allows drivers to release the exclusivity it previously got
     472                 :            :  * from clk_rate_exclusive_get()
     473                 :            :  *
     474                 :            :  * The caller must balance the number of clk_rate_exclusive_get() and
     475                 :            :  * clk_rate_exclusive_put() calls.
     476                 :            :  *
     477                 :            :  * Must not be called from within atomic context.
     478                 :            :  */
     479                 :            : void clk_rate_exclusive_put(struct clk *clk);
     480                 :            : 
     481                 :            : /**
     482                 :            :  * clk_enable - inform the system when the clock source should be running.
     483                 :            :  * @clk: clock source
     484                 :            :  *
     485                 :            :  * If the clock can not be enabled/disabled, this should return success.
     486                 :            :  *
     487                 :            :  * May be called from atomic contexts.
     488                 :            :  *
     489                 :            :  * Returns success (0) or negative errno.
     490                 :            :  */
     491                 :            : int clk_enable(struct clk *clk);
     492                 :            : 
     493                 :            : /**
     494                 :            :  * clk_bulk_enable - inform the system when the set of clks should be running.
     495                 :            :  * @num_clks: the number of clk_bulk_data
     496                 :            :  * @clks: the clk_bulk_data table of consumer
     497                 :            :  *
     498                 :            :  * May be called from atomic contexts.
     499                 :            :  *
     500                 :            :  * Returns success (0) or negative errno.
     501                 :            :  */
     502                 :            : int __must_check clk_bulk_enable(int num_clks,
     503                 :            :                                  const struct clk_bulk_data *clks);
     504                 :            : 
     505                 :            : /**
     506                 :            :  * clk_disable - inform the system when the clock source is no longer required.
     507                 :            :  * @clk: clock source
     508                 :            :  *
     509                 :            :  * Inform the system that a clock source is no longer required by
     510                 :            :  * a driver and may be shut down.
     511                 :            :  *
     512                 :            :  * May be called from atomic contexts.
     513                 :            :  *
     514                 :            :  * Implementation detail: if the clock source is shared between
     515                 :            :  * multiple drivers, clk_enable() calls must be balanced by the
     516                 :            :  * same number of clk_disable() calls for the clock source to be
     517                 :            :  * disabled.
     518                 :            :  */
     519                 :            : void clk_disable(struct clk *clk);
     520                 :            : 
     521                 :            : /**
     522                 :            :  * clk_bulk_disable - inform the system when the set of clks is no
     523                 :            :  *                    longer required.
     524                 :            :  * @num_clks: the number of clk_bulk_data
     525                 :            :  * @clks: the clk_bulk_data table of consumer
     526                 :            :  *
     527                 :            :  * Inform the system that a set of clks is no longer required by
     528                 :            :  * a driver and may be shut down.
     529                 :            :  *
     530                 :            :  * May be called from atomic contexts.
     531                 :            :  *
     532                 :            :  * Implementation detail: if the set of clks is shared between
     533                 :            :  * multiple drivers, clk_bulk_enable() calls must be balanced by the
     534                 :            :  * same number of clk_bulk_disable() calls for the clock source to be
     535                 :            :  * disabled.
     536                 :            :  */
     537                 :            : void clk_bulk_disable(int num_clks, const struct clk_bulk_data *clks);
     538                 :            : 
     539                 :            : /**
     540                 :            :  * clk_get_rate - obtain the current clock rate (in Hz) for a clock source.
     541                 :            :  *                This is only valid once the clock source has been enabled.
     542                 :            :  * @clk: clock source
     543                 :            :  */
     544                 :            : unsigned long clk_get_rate(struct clk *clk);
     545                 :            : 
     546                 :            : /**
     547                 :            :  * clk_put      - "free" the clock source
     548                 :            :  * @clk: clock source
     549                 :            :  *
     550                 :            :  * Note: drivers must ensure that all clk_enable calls made on this
     551                 :            :  * clock source are balanced by clk_disable calls prior to calling
     552                 :            :  * this function.
     553                 :            :  *
     554                 :            :  * clk_put should not be called from within interrupt context.
     555                 :            :  */
     556                 :            : void clk_put(struct clk *clk);
     557                 :            : 
     558                 :            : /**
     559                 :            :  * clk_bulk_put - "free" the clock source
     560                 :            :  * @num_clks: the number of clk_bulk_data
     561                 :            :  * @clks: the clk_bulk_data table of consumer
     562                 :            :  *
     563                 :            :  * Note: drivers must ensure that all clk_bulk_enable calls made on this
     564                 :            :  * clock source are balanced by clk_bulk_disable calls prior to calling
     565                 :            :  * this function.
     566                 :            :  *
     567                 :            :  * clk_bulk_put should not be called from within interrupt context.
     568                 :            :  */
     569                 :            : void clk_bulk_put(int num_clks, struct clk_bulk_data *clks);
     570                 :            : 
     571                 :            : /**
     572                 :            :  * clk_bulk_put_all - "free" all the clock source
     573                 :            :  * @num_clks: the number of clk_bulk_data
     574                 :            :  * @clks: the clk_bulk_data table of consumer
     575                 :            :  *
     576                 :            :  * Note: drivers must ensure that all clk_bulk_enable calls made on this
     577                 :            :  * clock source are balanced by clk_bulk_disable calls prior to calling
     578                 :            :  * this function.
     579                 :            :  *
     580                 :            :  * clk_bulk_put_all should not be called from within interrupt context.
     581                 :            :  */
     582                 :            : void clk_bulk_put_all(int num_clks, struct clk_bulk_data *clks);
     583                 :            : 
     584                 :            : /**
     585                 :            :  * devm_clk_put - "free" a managed clock source
     586                 :            :  * @dev: device used to acquire the clock
     587                 :            :  * @clk: clock source acquired with devm_clk_get()
     588                 :            :  *
     589                 :            :  * Note: drivers must ensure that all clk_enable calls made on this
     590                 :            :  * clock source are balanced by clk_disable calls prior to calling
     591                 :            :  * this function.
     592                 :            :  *
     593                 :            :  * clk_put should not be called from within interrupt context.
     594                 :            :  */
     595                 :            : void devm_clk_put(struct device *dev, struct clk *clk);
     596                 :            : 
     597                 :            : /*
     598                 :            :  * The remaining APIs are optional for machine class support.
     599                 :            :  */
     600                 :            : 
     601                 :            : 
     602                 :            : /**
     603                 :            :  * clk_round_rate - adjust a rate to the exact rate a clock can provide
     604                 :            :  * @clk: clock source
     605                 :            :  * @rate: desired clock rate in Hz
     606                 :            :  *
     607                 :            :  * This answers the question "if I were to pass @rate to clk_set_rate(),
     608                 :            :  * what clock rate would I end up with?" without changing the hardware
     609                 :            :  * in any way.  In other words:
     610                 :            :  *
     611                 :            :  *   rate = clk_round_rate(clk, r);
     612                 :            :  *
     613                 :            :  * and:
     614                 :            :  *
     615                 :            :  *   clk_set_rate(clk, r);
     616                 :            :  *   rate = clk_get_rate(clk);
     617                 :            :  *
     618                 :            :  * are equivalent except the former does not modify the clock hardware
     619                 :            :  * in any way.
     620                 :            :  *
     621                 :            :  * Returns rounded clock rate in Hz, or negative errno.
     622                 :            :  */
     623                 :            : long clk_round_rate(struct clk *clk, unsigned long rate);
     624                 :            : 
     625                 :            : /**
     626                 :            :  * clk_set_rate - set the clock rate for a clock source
     627                 :            :  * @clk: clock source
     628                 :            :  * @rate: desired clock rate in Hz
     629                 :            :  *
     630                 :            :  * Returns success (0) or negative errno.
     631                 :            :  */
     632                 :            : int clk_set_rate(struct clk *clk, unsigned long rate);
     633                 :            : 
     634                 :            : /**
     635                 :            :  * clk_set_rate_exclusive- set the clock rate and claim exclusivity over
     636                 :            :  *                         clock source
     637                 :            :  * @clk: clock source
     638                 :            :  * @rate: desired clock rate in Hz
     639                 :            :  *
     640                 :            :  * This helper function allows drivers to atomically set the rate of a producer
     641                 :            :  * and claim exclusivity over the rate control of the producer.
     642                 :            :  *
     643                 :            :  * It is essentially a combination of clk_set_rate() and
     644                 :            :  * clk_rate_exclusite_get(). Caller must balance this call with a call to
     645                 :            :  * clk_rate_exclusive_put()
     646                 :            :  *
     647                 :            :  * Returns success (0) or negative errno.
     648                 :            :  */
     649                 :            : int clk_set_rate_exclusive(struct clk *clk, unsigned long rate);
     650                 :            : 
     651                 :            : /**
     652                 :            :  * clk_has_parent - check if a clock is a possible parent for another
     653                 :            :  * @clk: clock source
     654                 :            :  * @parent: parent clock source
     655                 :            :  *
     656                 :            :  * This function can be used in drivers that need to check that a clock can be
     657                 :            :  * the parent of another without actually changing the parent.
     658                 :            :  *
     659                 :            :  * Returns true if @parent is a possible parent for @clk, false otherwise.
     660                 :            :  */
     661                 :            : bool clk_has_parent(struct clk *clk, struct clk *parent);
     662                 :            : 
     663                 :            : /**
     664                 :            :  * clk_set_rate_range - set a rate range for a clock source
     665                 :            :  * @clk: clock source
     666                 :            :  * @min: desired minimum clock rate in Hz, inclusive
     667                 :            :  * @max: desired maximum clock rate in Hz, inclusive
     668                 :            :  *
     669                 :            :  * Returns success (0) or negative errno.
     670                 :            :  */
     671                 :            : int clk_set_rate_range(struct clk *clk, unsigned long min, unsigned long max);
     672                 :            : 
     673                 :            : /**
     674                 :            :  * clk_set_min_rate - set a minimum clock rate for a clock source
     675                 :            :  * @clk: clock source
     676                 :            :  * @rate: desired minimum clock rate in Hz, inclusive
     677                 :            :  *
     678                 :            :  * Returns success (0) or negative errno.
     679                 :            :  */
     680                 :            : int clk_set_min_rate(struct clk *clk, unsigned long rate);
     681                 :            : 
     682                 :            : /**
     683                 :            :  * clk_set_max_rate - set a maximum clock rate for a clock source
     684                 :            :  * @clk: clock source
     685                 :            :  * @rate: desired maximum clock rate in Hz, inclusive
     686                 :            :  *
     687                 :            :  * Returns success (0) or negative errno.
     688                 :            :  */
     689                 :            : int clk_set_max_rate(struct clk *clk, unsigned long rate);
     690                 :            : 
     691                 :            : /**
     692                 :            :  * clk_set_parent - set the parent clock source for this clock
     693                 :            :  * @clk: clock source
     694                 :            :  * @parent: parent clock source
     695                 :            :  *
     696                 :            :  * Returns success (0) or negative errno.
     697                 :            :  */
     698                 :            : int clk_set_parent(struct clk *clk, struct clk *parent);
     699                 :            : 
     700                 :            : /**
     701                 :            :  * clk_get_parent - get the parent clock source for this clock
     702                 :            :  * @clk: clock source
     703                 :            :  *
     704                 :            :  * Returns struct clk corresponding to parent clock source, or
     705                 :            :  * valid IS_ERR() condition containing errno.
     706                 :            :  */
     707                 :            : struct clk *clk_get_parent(struct clk *clk);
     708                 :            : 
     709                 :            : /**
     710                 :            :  * clk_get_sys - get a clock based upon the device name
     711                 :            :  * @dev_id: device name
     712                 :            :  * @con_id: connection ID
     713                 :            :  *
     714                 :            :  * Returns a struct clk corresponding to the clock producer, or
     715                 :            :  * valid IS_ERR() condition containing errno.  The implementation
     716                 :            :  * uses @dev_id and @con_id to determine the clock consumer, and
     717                 :            :  * thereby the clock producer. In contrast to clk_get() this function
     718                 :            :  * takes the device name instead of the device itself for identification.
     719                 :            :  *
     720                 :            :  * Drivers must assume that the clock source is not enabled.
     721                 :            :  *
     722                 :            :  * clk_get_sys should not be called from within interrupt context.
     723                 :            :  */
     724                 :            : struct clk *clk_get_sys(const char *dev_id, const char *con_id);
     725                 :            : 
     726                 :            : /**
     727                 :            :  * clk_save_context - save clock context for poweroff
     728                 :            :  *
     729                 :            :  * Saves the context of the clock register for powerstates in which the
     730                 :            :  * contents of the registers will be lost. Occurs deep within the suspend
     731                 :            :  * code so locking is not necessary.
     732                 :            :  */
     733                 :            : int clk_save_context(void);
     734                 :            : 
     735                 :            : /**
     736                 :            :  * clk_restore_context - restore clock context after poweroff
     737                 :            :  *
     738                 :            :  * This occurs with all clocks enabled. Occurs deep within the resume code
     739                 :            :  * so locking is not necessary.
     740                 :            :  */
     741                 :            : void clk_restore_context(void);
     742                 :            : 
     743                 :            : #else /* !CONFIG_HAVE_CLK */
     744                 :            : 
     745                 :            : static inline struct clk *clk_get(struct device *dev, const char *id)
     746                 :            : {
     747                 :            :         return NULL;
     748                 :            : }
     749                 :            : 
     750                 :            : static inline int __must_check clk_bulk_get(struct device *dev, int num_clks,
     751                 :            :                                             struct clk_bulk_data *clks)
     752                 :            : {
     753                 :            :         return 0;
     754                 :            : }
     755                 :            : 
     756                 :            : static inline int __must_check clk_bulk_get_optional(struct device *dev,
     757                 :            :                                 int num_clks, struct clk_bulk_data *clks)
     758                 :            : {
     759                 :            :         return 0;
     760                 :            : }
     761                 :            : 
     762                 :            : static inline int __must_check clk_bulk_get_all(struct device *dev,
     763                 :            :                                          struct clk_bulk_data **clks)
     764                 :            : {
     765                 :            :         return 0;
     766                 :            : }
     767                 :            : 
     768                 :            : static inline struct clk *devm_clk_get(struct device *dev, const char *id)
     769                 :            : {
     770                 :            :         return NULL;
     771                 :            : }
     772                 :            : 
     773                 :            : static inline struct clk *devm_clk_get_optional(struct device *dev,
     774                 :            :                                                 const char *id)
     775                 :            : {
     776                 :            :         return NULL;
     777                 :            : }
     778                 :            : 
     779                 :            : static inline int __must_check devm_clk_bulk_get(struct device *dev, int num_clks,
     780                 :            :                                                  struct clk_bulk_data *clks)
     781                 :            : {
     782                 :            :         return 0;
     783                 :            : }
     784                 :            : 
     785                 :            : static inline int __must_check devm_clk_bulk_get_optional(struct device *dev,
     786                 :            :                                 int num_clks, struct clk_bulk_data *clks)
     787                 :            : {
     788                 :            :         return 0;
     789                 :            : }
     790                 :            : 
     791                 :            : static inline int __must_check devm_clk_bulk_get_all(struct device *dev,
     792                 :            :                                                      struct clk_bulk_data **clks)
     793                 :            : {
     794                 :            : 
     795                 :            :         return 0;
     796                 :            : }
     797                 :            : 
     798                 :            : static inline struct clk *devm_get_clk_from_child(struct device *dev,
     799                 :            :                                 struct device_node *np, const char *con_id)
     800                 :            : {
     801                 :            :         return NULL;
     802                 :            : }
     803                 :            : 
     804                 :            : static inline void clk_put(struct clk *clk) {}
     805                 :            : 
     806                 :            : static inline void clk_bulk_put(int num_clks, struct clk_bulk_data *clks) {}
     807                 :            : 
     808                 :            : static inline void clk_bulk_put_all(int num_clks, struct clk_bulk_data *clks) {}
     809                 :            : 
     810                 :            : static inline void devm_clk_put(struct device *dev, struct clk *clk) {}
     811                 :            : 
     812                 :            : 
     813                 :            : static inline int clk_rate_exclusive_get(struct clk *clk)
     814                 :            : {
     815                 :            :         return 0;
     816                 :            : }
     817                 :            : 
     818                 :            : static inline void clk_rate_exclusive_put(struct clk *clk) {}
     819                 :            : 
     820                 :            : static inline int clk_enable(struct clk *clk)
     821                 :            : {
     822                 :            :         return 0;
     823                 :            : }
     824                 :            : 
     825                 :            : static inline int __must_check clk_bulk_enable(int num_clks,
     826                 :            :                                                const struct clk_bulk_data *clks)
     827                 :            : {
     828                 :            :         return 0;
     829                 :            : }
     830                 :            : 
     831                 :            : static inline void clk_disable(struct clk *clk) {}
     832                 :            : 
     833                 :            : 
     834                 :            : static inline void clk_bulk_disable(int num_clks,
     835                 :            :                                     const struct clk_bulk_data *clks) {}
     836                 :            : 
     837                 :            : static inline unsigned long clk_get_rate(struct clk *clk)
     838                 :            : {
     839                 :            :         return 0;
     840                 :            : }
     841                 :            : 
     842                 :            : static inline int clk_set_rate(struct clk *clk, unsigned long rate)
     843                 :            : {
     844                 :            :         return 0;
     845                 :            : }
     846                 :            : 
     847                 :            : static inline int clk_set_rate_exclusive(struct clk *clk, unsigned long rate)
     848                 :            : {
     849                 :            :         return 0;
     850                 :            : }
     851                 :            : 
     852                 :            : static inline long clk_round_rate(struct clk *clk, unsigned long rate)
     853                 :            : {
     854                 :            :         return 0;
     855                 :            : }
     856                 :            : 
     857                 :            : static inline bool clk_has_parent(struct clk *clk, struct clk *parent)
     858                 :            : {
     859                 :            :         return true;
     860                 :            : }
     861                 :            : 
     862                 :            : static inline int clk_set_rate_range(struct clk *clk, unsigned long min,
     863                 :            :                                      unsigned long max)
     864                 :            : {
     865                 :            :         return 0;
     866                 :            : }
     867                 :            : 
     868                 :            : static inline int clk_set_min_rate(struct clk *clk, unsigned long rate)
     869                 :            : {
     870                 :            :         return 0;
     871                 :            : }
     872                 :            : 
     873                 :            : static inline int clk_set_max_rate(struct clk *clk, unsigned long rate)
     874                 :            : {
     875                 :            :         return 0;
     876                 :            : }
     877                 :            : 
     878                 :            : static inline int clk_set_parent(struct clk *clk, struct clk *parent)
     879                 :            : {
     880                 :            :         return 0;
     881                 :            : }
     882                 :            : 
     883                 :            : static inline struct clk *clk_get_parent(struct clk *clk)
     884                 :            : {
     885                 :            :         return NULL;
     886                 :            : }
     887                 :            : 
     888                 :            : static inline struct clk *clk_get_sys(const char *dev_id, const char *con_id)
     889                 :            : {
     890                 :            :         return NULL;
     891                 :            : }
     892                 :            : 
     893                 :            : static inline int clk_save_context(void)
     894                 :            : {
     895                 :            :         return 0;
     896                 :            : }
     897                 :            : 
     898                 :            : static inline void clk_restore_context(void) {}
     899                 :            : 
     900                 :            : #endif
     901                 :            : 
     902                 :            : /* clk_prepare_enable helps cases using clk_enable in non-atomic context. */
     903                 :          3 : static inline int clk_prepare_enable(struct clk *clk)
     904                 :            : {
     905                 :            :         int ret;
     906                 :            : 
     907                 :          3 :         ret = clk_prepare(clk);
     908                 :          3 :         if (ret)
     909                 :            :                 return ret;
     910                 :          3 :         ret = clk_enable(clk);
     911                 :          3 :         if (ret)
     912                 :          0 :                 clk_unprepare(clk);
     913                 :            : 
     914                 :          3 :         return ret;
     915                 :            : }
     916                 :            : 
     917                 :            : /* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */
     918                 :            : static inline void clk_disable_unprepare(struct clk *clk)
     919                 :            : {
     920                 :          3 :         clk_disable(clk);
     921                 :          3 :         clk_unprepare(clk);
     922                 :            : }
     923                 :            : 
     924                 :            : static inline int __must_check
     925                 :            : clk_bulk_prepare_enable(int num_clks, const struct clk_bulk_data *clks)
     926                 :            : {
     927                 :            :         int ret;
     928                 :            : 
     929                 :            :         ret = clk_bulk_prepare(num_clks, clks);
     930                 :            :         if (ret)
     931                 :            :                 return ret;
     932                 :            :         ret = clk_bulk_enable(num_clks, clks);
     933                 :            :         if (ret)
     934                 :            :                 clk_bulk_unprepare(num_clks, clks);
     935                 :            : 
     936                 :            :         return ret;
     937                 :            : }
     938                 :            : 
     939                 :            : static inline void clk_bulk_disable_unprepare(int num_clks,
     940                 :            :                                               const struct clk_bulk_data *clks)
     941                 :            : {
     942                 :            :         clk_bulk_disable(num_clks, clks);
     943                 :            :         clk_bulk_unprepare(num_clks, clks);
     944                 :            : }
     945                 :            : 
     946                 :            : /**
     947                 :            :  * clk_get_optional - lookup and obtain a reference to an optional clock
     948                 :            :  *                    producer.
     949                 :            :  * @dev: device for clock "consumer"
     950                 :            :  * @id: clock consumer ID
     951                 :            :  *
     952                 :            :  * Behaves the same as clk_get() except where there is no clock producer. In
     953                 :            :  * this case, instead of returning -ENOENT, the function returns NULL.
     954                 :            :  */
     955                 :            : static inline struct clk *clk_get_optional(struct device *dev, const char *id)
     956                 :            : {
     957                 :            :         struct clk *clk = clk_get(dev, id);
     958                 :            : 
     959                 :            :         if (clk == ERR_PTR(-ENOENT))
     960                 :            :                 return NULL;
     961                 :            : 
     962                 :            :         return clk;
     963                 :            : }
     964                 :            : 
     965                 :            : #if defined(CONFIG_OF) && defined(CONFIG_COMMON_CLK)
     966                 :            : struct clk *of_clk_get(struct device_node *np, int index);
     967                 :            : struct clk *of_clk_get_by_name(struct device_node *np, const char *name);
     968                 :            : struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec);
     969                 :            : #else
     970                 :            : static inline struct clk *of_clk_get(struct device_node *np, int index)
     971                 :            : {
     972                 :            :         return ERR_PTR(-ENOENT);
     973                 :            : }
     974                 :            : static inline struct clk *of_clk_get_by_name(struct device_node *np,
     975                 :            :                                              const char *name)
     976                 :            : {
     977                 :            :         return ERR_PTR(-ENOENT);
     978                 :            : }
     979                 :            : static inline struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec)
     980                 :            : {
     981                 :            :         return ERR_PTR(-ENOENT);
     982                 :            : }
     983                 :            : #endif
     984                 :            : 
     985                 :            : #endif
    

Generated by: LCOV version 1.14