1/* SPDX-License-Identifier: GPL-2.0+ */ 2/* 3 * Copyright (c) 2015 Google, Inc 4 * Written by Simon Glass <sjg@chromium.org> 5 * Copyright (c) 2016, NVIDIA CORPORATION. 6 */ 7 8#ifndef _CLK_H_ 9#define _CLK_H_ 10 11#include <dm/ofnode.h> 12#include <linux/err.h> 13#include <linux/errno.h> 14#include <linux/types.h> 15 16/** 17 * DOC: Overview 18 * 19 * A clock is a hardware signal that oscillates autonomously at a specific 20 * frequency and duty cycle. Most hardware modules require one or more clock 21 * signal to drive their operation. Clock signals are typically generated 22 * externally to the HW module consuming them, by an entity this API calls a 23 * clock provider. This API provides a standard means for drivers to enable and 24 * disable clocks, and to set the rate at which they oscillate. 25 * 26 * A driver that implements UCLASS_CLK is a clock provider. A provider will 27 * often implement multiple separate clocks, since the hardware it manages 28 * often has this capability. clk-uclass.h describes the interface which 29 * clock providers must implement. 30 * 31 * Clock consumers/clients are the HW modules driven by the clock signals. This 32 * header file describes the API used by drivers for those HW modules. 33 */ 34 35struct udevice; 36 37/** 38 * struct clk - A handle to (allowing control of) a single clock. 39 * @dev: The device which implements the clock signal. 40 * @rate: The clock rate (in HZ). 41 * @flags: Flags used across common clock structure (e.g. %CLK_) 42 * Clock IP blocks specific flags (i.e. mux, div, gate, etc) are defined 43 * in struct's for those devices (e.g. &struct clk_mux). 44 * @enable_count: The number of times this clock has been enabled. 45 * @id: The clock signal ID within the provider. 46 * @data: An optional data field for scenarios where a single integer ID is not 47 * sufficient. If used, it can be populated through an .of_xlate op and 48 * processed during the various clock ops. 49 * 50 * Clients provide storage for clock handles. The content of the structure is 51 * managed solely by the clock API and clock drivers. A clock struct is 52 * initialized by "get"ing the clock struct. The clock struct is passed to all 53 * other clock APIs to identify which clock signal to operate upon. 54 * 55 * Should additional information to identify and configure any clock signal 56 * for any provider be required in the future, the struct could be expanded to 57 * either (a) add more fields to allow clock providers to store additional 58 * information, or (b) replace the id field with an opaque pointer, which the 59 * provider would dynamically allocated during its .of_xlate op, and process 60 * during is .request op. This may require the addition of an extra op to clean 61 * up the allocation. 62 */ 63struct clk { 64 struct udevice *dev; 65 long long rate; /* in HZ */ 66 u32 flags; 67 int enable_count; 68 /* 69 * Written by of_xlate. In the future, we might add more fields here. 70 */ 71 unsigned long id; 72 unsigned long data; 73}; 74 75/** 76 * struct clk_bulk - A handle to (allowing control of) a bulk of clocks. 77 * @clks: An array of clock handles. 78 * @count: The number of clock handles in the clks array. 79 * 80 * Clients provide storage for the clock bulk. The content of the structure is 81 * managed solely by the clock API. A clock bulk struct is 82 * initialized by "get"ing the clock bulk struct. 83 * The clock bulk struct is passed to all other bulk clock APIs to apply 84 * the API to all the clock in the bulk struct. 85 */ 86struct clk_bulk { 87 struct clk *clks; 88 unsigned int count; 89}; 90 91struct phandle_1_arg; 92 93#if CONFIG_IS_ENABLED(OF_CONTROL) && CONFIG_IS_ENABLED(CLK) 94/** 95 * clk_get_by_phandle() - Get a clock by its phandle information (of-platadata) 96 * @dev: Device containing the phandle 97 * @cells: Phandle info 98 * @clk: A pointer to a clock struct to initialise 99 * 100 * This function is used when of-platdata is enabled. 101 * 102 * This looks up a clock using the phandle info. With dtoc, each phandle in the 103 * 'clocks' property is transformed into an idx representing the device. 104 * For example:: 105 * 106 * clocks = <&dpll_mpu_ck 23>; 107 * 108 * might result in:: 109 * 110 * .clocks = {1, {23}},}, 111 * 112 * indicating that the clock is udevice idx 1 in dt-plat.c with an argument of 113 * 23. This function can return a valid clock given the above information. In 114 * this example it would return a clock containing the 'dpll_mpu_ck' device and 115 * the clock ID 23. 116 * 117 * Return: 0 if OK, or a negative error code. 118 */ 119int clk_get_by_phandle(struct udevice *dev, const struct phandle_1_arg *cells, 120 struct clk *clk); 121 122/** 123 * clk_get_by_index() - Get/request a clock by integer index. 124 * @dev: The client device. 125 * @index: The index of the clock to request, within the client's list of 126 * clocks. 127 * @clk: A pointer to a clock struct to initialize. 128 * 129 * This looks up and requests a clock. The index is relative to the client 130 * device; each device is assumed to have n clocks associated with it somehow, 131 * and this function finds and requests one of them. The mapping of client 132 * device clock indices to provider clocks may be via device-tree properties, 133 * board-provided mapping tables, or some other mechanism. 134 * 135 * Return: 0 if OK, or a negative error code. 136 */ 137int clk_get_by_index(struct udevice *dev, int index, struct clk *clk); 138 139/** 140 * clk_get_by_index_nodev() - Get/request a clock by integer index without a 141 * device. 142 * @node: The client ofnode. 143 * @index: The index of the clock to request, within the client's list of 144 * clocks. 145 * @clk: A pointer to a clock struct to initialize. 146 * 147 * Return: 0 if OK, or a negative error code. 148 */ 149int clk_get_by_index_nodev(ofnode node, int index, struct clk *clk); 150 151/** 152 * clk_get_bulk() - Get/request all clocks of a device. 153 * @dev: The client device. 154 * @bulk: A pointer to a clock bulk struct to initialize. 155 * 156 * This looks up and requests all clocks of the client device; each device is 157 * assumed to have n clocks associated with it somehow, and this function finds 158 * and requests all of them in a separate structure. The mapping of client 159 * device clock indices to provider clocks may be via device-tree properties, 160 * board-provided mapping tables, or some other mechanism. 161 * 162 * Return: 0 if OK, or a negative error code. 163 */ 164int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk); 165 166/** 167 * clk_get_by_name() - Get/request a clock by name. 168 * @dev: The client device. 169 * @name: The name of the clock to request, within the client's list of 170 * clocks, or NULL to request the first clock in the list. 171 * @clk: A pointer to a clock struct to initialize. 172 * 173 * This looks up and requests a clock. The name is relative to the client 174 * device; each device is assumed to have n clocks associated with it somehow, 175 * and this function finds and requests one of them. The mapping of client 176 * device clock names to provider clocks may be via device-tree properties, 177 * board-provided mapping tables, or some other mechanism. 178 * 179 * Return: 0 if OK, or a negative error code. 180 */ 181int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk); 182 183/** 184 * clk_get_by_name_nodev - Get/request a clock by name without a device. 185 * @node: The client ofnode. 186 * @name: The name of the clock to request, within the client's list of 187 * clocks, or NULL to request the first clock in the list. 188 * @clk: A pointer to a clock struct to initialize. 189 * 190 * Return: 0 if OK, or a negative error code. 191 */ 192int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk); 193 194/** 195 * devm_clk_get() - lookup and obtain a managed reference to a clock producer. 196 * @dev: device for clock "consumer" 197 * @id: clock consumer ID 198 * 199 * The implementation uses @dev and @id to determine the clock consumer, and 200 * thereby the clock producer. (IOW, @id may be identical strings, but clk_get 201 * may return different clock producers depending on @dev.) 202 * 203 * Drivers must assume that the clock source is not enabled. 204 * 205 * The clock will automatically be freed when the device is unbound 206 * from the bus. 207 * 208 * Return: 209 * a struct clk corresponding to the clock producer, or 210 * valid IS_ERR() condition containing errno 211 */ 212struct clk *devm_clk_get(struct udevice *dev, const char *id); 213 214/** 215 * devm_clk_get_optional() - lookup and obtain a managed reference to an 216 * optional clock producer. 217 * @dev: device for clock "consumer" 218 * @id: clock consumer ID 219 * 220 * Behaves the same as devm_clk_get() except where there is no clock producer. 221 * In this case, instead of returning -%ENOENT, the function returns NULL. 222 */ 223static inline struct clk *devm_clk_get_optional(struct udevice *dev, 224 const char *id) 225{ 226 int ret; 227 struct clk *clk = devm_clk_get(dev, id); 228 229 ret = PTR_ERR(clk); 230 if (ret == -ENODATA || ret == -ENOENT) 231 return NULL; 232 233 return clk; 234} 235 236/** 237 * clk_release_all() - Disable (turn off)/Free an array of previously 238 * requested clocks. 239 * @clk: A clock struct array that was previously successfully 240 * requested by clk_request/get_by_*(). 241 * @count: Number of clock contained in the array 242 * 243 * For each clock contained in the clock array, this function will check if 244 * clock has been previously requested and then will disable and free it. 245 * 246 * Return: zero on success, or -ve error code. 247 */ 248int clk_release_all(struct clk *clk, unsigned int count); 249 250#else 251 252static inline int clk_get_by_phandle(struct udevice *dev, const 253 struct phandle_1_arg *cells, 254 struct clk *clk) 255{ 256 return -ENOSYS; 257} 258 259static inline int clk_get_by_index(struct udevice *dev, int index, 260 struct clk *clk) 261{ 262 return -ENOSYS; 263} 264 265static inline int clk_get_by_index_nodev(ofnode node, int index, 266 struct clk *clk) 267{ 268 return -ENOSYS; 269} 270 271static inline int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk) 272{ 273 return -ENOSYS; 274} 275 276static inline int clk_get_by_name(struct udevice *dev, const char *name, 277 struct clk *clk) 278{ 279 return -ENOSYS; 280} 281 282static inline struct clk *devm_clk_get(struct udevice *dev, const char *id) 283{ 284 return ERR_PTR(-ENOSYS); 285} 286 287static inline struct clk *devm_clk_get_optional(struct udevice *dev, 288 const char *id) 289{ 290 return ERR_PTR(-ENOSYS); 291} 292 293static inline int 294clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk) 295{ 296 return -ENOSYS; 297} 298 299static inline int clk_release_all(struct clk *clk, unsigned int count) 300{ 301 return -ENOSYS; 302} 303#endif 304 305/** 306 * clk_get_by_name_optional() - Get/request a optional clock by name. 307 * @dev: The client device. 308 * @name: The name of the clock to request, within the client's list of 309 * clocks. 310 * @clk: A pointer to a clock struct to initialize. 311 * 312 * Behaves the same as clk_get_by_name(), except when there is no clock 313 * provider. In the latter case, return 0. 314 * 315 * Return: 0 if OK, or a negative error code. 316 */ 317static inline int clk_get_by_name_optional(struct udevice *dev, 318 const char *name, struct clk *clk) 319{ 320 int ret; 321 322 ret = clk_get_by_name(dev, name, clk); 323 if (ret == -ENODATA || ret == -ENOENT) 324 return 0; 325 326 return ret; 327} 328 329/** 330 * clk_get_by_name_nodev_optional - Get/request an optinonal clock by name 331 * without a device. 332 * @node: The client ofnode. 333 * @name: The name of the clock to request, within the client's list of 334 * clocks. 335 * @clk: A pointer to a clock struct to initialize. 336 * 337 * Behaves the same as clk_get_by_name_nodev() except where there is 338 * no clock producer, in this case, skip the error number -%ENODATA, and 339 * the function returns 0. 340 */ 341static inline int clk_get_by_name_nodev_optional(ofnode node, const char *name, 342 struct clk *clk) 343{ 344 int ret; 345 346 ret = clk_get_by_name_nodev(node, name, clk); 347 if (ret == -ENODATA || ret == -ENOENT) 348 return 0; 349 350 return ret; 351} 352 353/** 354 * enum clk_defaults_stage - What stage clk_set_defaults() is called at 355 * @CLK_DEFAULTS_PRE: Called before probe. Setting of defaults for clocks owned 356 * by this clock driver will be defered until after probing. 357 * @CLK_DEFAULTS_POST: Called after probe. Only defaults for clocks owned by 358 * this clock driver will be set. 359 * @CLK_DEFAULTS_POST_FORCE: Called after probe, and always set defaults, even 360 * before relocation. Usually, defaults are not set 361 * pre-relocation to avoid setting them twice (when 362 * the device is probed again post-relocation). This 363 * may incur a performance cost as device tree 364 * properties must be parsed for a second time. 365 * However, when not using SPL, pre-relocation may be 366 * the only time we can set defaults for some clocks 367 * (such as those used for the RAM we will relocate 368 * into). 369 */ 370enum clk_defaults_stage { 371 CLK_DEFAULTS_PRE = 0, 372 CLK_DEFAULTS_POST = 1, 373 CLK_DEFAULTS_POST_FORCE, 374}; 375 376#if CONFIG_IS_ENABLED(OF_REAL) && CONFIG_IS_ENABLED(CLK) 377/** 378 * clk_set_defaults - Process ``assigned-{clocks/clock-parents/clock-rates}`` 379 * properties to configure clocks 380 * @dev: A device to process (the ofnode associated with this device 381 * will be processed). 382 * @stage: The stage of the probing process this function is called during. 383 * 384 * Return: zero on success, or -ve error code. 385 */ 386int clk_set_defaults(struct udevice *dev, enum clk_defaults_stage stage); 387#else 388static inline int clk_set_defaults(struct udevice *dev, int stage) 389{ 390 return 0; 391} 392#endif 393 394/** 395 * clk_release_bulk() - Disable (turn off)/Free an array of previously 396 * requested clocks in a clock bulk struct. 397 * @bulk: A clock bulk struct that was previously successfully 398 * requested by clk_get_bulk(). 399 * 400 * For each clock contained in the clock bulk struct, this function will check 401 * if clock has been previously requested and then will disable and free it. 402 * 403 * Return: zero on success, or -ve error code. 404 */ 405static inline int clk_release_bulk(struct clk_bulk *bulk) 406{ 407 return clk_release_all(bulk->clks, bulk->count); 408} 409 410#if CONFIG_IS_ENABLED(CLK) 411/** 412 * clk_request() - Request a clock by provider-specific ID. 413 * @dev: The clock provider device. 414 * @clk: A pointer to a clock struct to initialize. The caller must 415 * have already initialized any field in this struct which the 416 * clock provider uses to identify the clock. 417 * 418 * This requests a clock using a provider-specific ID. Generally, this function 419 * should not be used, since clk_get_by_index/name() provide an interface that 420 * better separates clients from intimate knowledge of clock providers. 421 * However, this function may be useful in core SoC-specific code. 422 * 423 * Return: 0 if OK, or a negative error code. 424 */ 425int clk_request(struct udevice *dev, struct clk *clk); 426 427/** 428 * clk_get_rate() - Get current clock rate. 429 * @clk: A clock struct that was previously successfully requested by 430 * clk_request/get_by_*(). 431 * 432 * Return: clock rate in Hz on success, 0 for invalid clock, or -ve error code 433 * for other errors. 434 */ 435ulong clk_get_rate(struct clk *clk); 436 437/** 438 * clk_get_parent() - Get current clock's parent. 439 * @clk: A clock struct that was previously successfully requested by 440 * clk_request/get_by_*(). 441 * 442 * Return: pointer to parent's struct clk, or error code passed as pointer 443 */ 444struct clk *clk_get_parent(struct clk *clk); 445 446/** 447 * clk_get_parent_rate() - Get parent of current clock rate. 448 * @clk: A clock struct that was previously successfully requested by 449 * clk_request/get_by_*(). 450 * 451 * Return: clock rate in Hz, or -ve error code. 452 */ 453ulong clk_get_parent_rate(struct clk *clk); 454 455/** 456 * clk_round_rate() - Adjust a rate to the exact rate a clock can provide 457 * @clk: A clock struct that was previously successfully requested by 458 * clk_request/get_by_*(). 459 * @rate: desired clock rate in Hz. 460 * 461 * This answers the question "if I were to pass @rate to clk_set_rate(), 462 * what clock rate would I end up with?" without changing the hardware 463 * in any way. In other words:: 464 * 465 * rate = clk_round_rate(clk, r); 466 * 467 * and:: 468 * 469 * rate = clk_set_rate(clk, r); 470 * 471 * are equivalent except the former does not modify the clock hardware 472 * in any way. 473 * 474 * Return: rounded rate in Hz, or -ve error code. 475 */ 476ulong clk_round_rate(struct clk *clk, ulong rate); 477 478/** 479 * clk_set_rate() - Set current clock rate. 480 * @clk: A clock struct that was previously successfully requested by 481 * clk_request/get_by_*(). 482 * @rate: New clock rate in Hz. 483 * 484 * Return: new rate, or -ve error code. 485 */ 486ulong clk_set_rate(struct clk *clk, ulong rate); 487 488/** 489 * clk_set_parent() - Set current clock parent. 490 * @clk: A clock struct that was previously successfully requested by 491 * clk_request/get_by_*(). 492 * @parent: A clock struct that was previously successfully requested by 493 * clk_request/get_by_*(). 494 * 495 * Return: new rate, or -ve error code. 496 */ 497int clk_set_parent(struct clk *clk, struct clk *parent); 498 499/** 500 * clk_enable() - Enable (turn on) a clock. 501 * @clk: A clock struct that was previously successfully requested by 502 * clk_request/get_by_*(). 503 * 504 * Return: zero on success, or -ve error code. 505 */ 506int clk_enable(struct clk *clk); 507 508/** 509 * clk_enable_bulk() - Enable (turn on) all clocks in a clock bulk struct. 510 * @bulk: A clock bulk struct that was previously successfully requested 511 * by clk_get_bulk(). 512 * 513 * Return: zero on success, or -ve error code. 514 */ 515int clk_enable_bulk(struct clk_bulk *bulk); 516 517/** 518 * clk_disable() - Disable (turn off) a clock. 519 * @clk: A clock struct that was previously successfully requested by 520 * clk_request/get_by_*(). 521 * 522 * Return: zero on success, or -ve error code. 523 */ 524int clk_disable(struct clk *clk); 525 526/** 527 * clk_disable_bulk() - Disable (turn off) all clocks in a clock bulk struct. 528 * @bulk: A clock bulk struct that was previously successfully requested 529 * by clk_get_bulk(). 530 * 531 * Return: zero on success, or -ve error code. 532 */ 533int clk_disable_bulk(struct clk_bulk *bulk); 534 535/** 536 * clk_is_match - check if two clk's point to the same hardware clock 537 * @p: clk compared against q 538 * @q: clk compared against p 539 * 540 * Return: 541 * %true if the two struct clk pointers both point to the same hardware clock 542 * node, and %false otherwise. Note that two %NULL clks are treated as matching. 543 */ 544bool clk_is_match(const struct clk *p, const struct clk *q); 545 546/** 547 * clk_get_by_id() - Get the clock by its ID 548 * @id: The clock ID to search for 549 * @clkp: A pointer to clock struct that has been found among added clocks 550 * to UCLASS_CLK 551 * 552 * Return: zero on success, or -ENOENT on error 553 */ 554int clk_get_by_id(ulong id, struct clk **clkp); 555 556/** 557 * clk_dev_binded() - Check whether the clk has a device binded 558 * @clk: A pointer to the clk 559 * 560 * Return: true on binded, or false on no 561 */ 562bool clk_dev_binded(struct clk *clk); 563 564#else /* CONFIG_IS_ENABLED(CLK) */ 565 566static inline int clk_request(struct udevice *dev, struct clk *clk) 567{ 568 return -ENOSYS; 569} 570 571static inline ulong clk_get_rate(struct clk *clk) 572{ 573 return -ENOSYS; 574} 575 576static inline struct clk *clk_get_parent(struct clk *clk) 577{ 578 return ERR_PTR(-ENOSYS); 579} 580 581static inline ulong clk_get_parent_rate(struct clk *clk) 582{ 583 return -ENOSYS; 584} 585 586static inline ulong clk_round_rate(struct clk *clk, ulong rate) 587{ 588 return -ENOSYS; 589} 590 591static inline ulong clk_set_rate(struct clk *clk, ulong rate) 592{ 593 return -ENOSYS; 594} 595 596static inline int clk_set_parent(struct clk *clk, struct clk *parent) 597{ 598 return -ENOSYS; 599} 600 601static inline int clk_enable(struct clk *clk) 602{ 603 return 0; 604} 605 606static inline int clk_enable_bulk(struct clk_bulk *bulk) 607{ 608 return 0; 609} 610 611static inline int clk_disable(struct clk *clk) 612{ 613 return 0; 614} 615 616static inline int clk_disable_bulk(struct clk_bulk *bulk) 617{ 618 return 0; 619} 620 621static inline bool clk_is_match(const struct clk *p, const struct clk *q) 622{ 623 return false; 624} 625 626static inline int clk_get_by_id(ulong id, struct clk **clkp) 627{ 628 return -ENOSYS; 629} 630 631static inline bool clk_dev_binded(struct clk *clk) 632{ 633 return false; 634} 635#endif /* CONFIG_IS_ENABLED(CLK) */ 636 637/** 638 * clk_valid() - check if clk is valid 639 * @clk: the clock to check 640 * 641 * Return: true if valid, or false 642 */ 643static inline bool clk_valid(struct clk *clk) 644{ 645 return clk && !!clk->dev; 646} 647 648#endif 649 650#define clk_prepare_enable(clk) clk_enable(clk) 651#define clk_disable_unprepare(clk) clk_disable(clk) 652