1 /* 2 * Copyright (c) 2015 Google, Inc 3 * Written by Simon Glass <sjg@chromium.org> 4 * Copyright (c) 2016, NVIDIA CORPORATION. 5 * 6 * SPDX-License-Identifier: GPL-2.0+ 7 */ 8 9 #ifndef _CLK_H_ 10 #define _CLK_H_ 11 12 #include <linux/types.h> 13 14 /** 15 * A clock is a hardware signal that oscillates autonomously at a specific 16 * frequency and duty cycle. Most hardware modules require one or more clock 17 * signal to drive their operation. Clock signals are typically generated 18 * externally to the HW module consuming them, by an entity this API calls a 19 * clock provider. This API provides a standard means for drivers to enable and 20 * disable clocks, and to set the rate at which they oscillate. 21 * 22 * A driver that implements UCLASS_CLOCK is a clock provider. A provider will 23 * often implement multiple separate clocks, since the hardware it manages 24 * often has this capability. clock_uclass.h describes the interface which 25 * clock providers must implement. 26 * 27 * Clock consumers/clients are the HW modules driven by the clock signals. This 28 * header file describes the API used by drivers for those HW modules. 29 */ 30 31 struct udevice; 32 33 /** 34 * struct clk - A handle to (allowing control of) a single clock. 35 * 36 * Clients provide storage for clock handles. The content of the structure is 37 * managed solely by the clock API and clock drivers. A clock struct is 38 * initialized by "get"ing the clock struct. The clock struct is passed to all 39 * other clock APIs to identify which clock signal to operate upon. 40 * 41 * @dev: The device which implements the clock signal. 42 * @id: The clock signal ID within the provider. 43 * 44 * Currently, the clock API assumes that a single integer ID is enough to 45 * identify and configure any clock signal for any clock provider. If this 46 * assumption becomes invalid in the future, the struct could be expanded to 47 * either (a) add more fields to allow clock providers to store additional 48 * information, or (b) replace the id field with an opaque pointer, which the 49 * provider would dynamically allocated during its .of_xlate op, and process 50 * during is .request op. This may require the addition of an extra op to clean 51 * up the allocation. 52 */ 53 struct clk { 54 struct udevice *dev; 55 /* 56 * Written by of_xlate. We assume a single id is enough for now. In the 57 * future, we might add more fields here. 58 */ 59 unsigned long id; 60 }; 61 62 #if CONFIG_IS_ENABLED(OF_CONTROL) 63 struct phandle_2_cell; 64 int clk_get_by_index_platdata(struct udevice *dev, int index, 65 struct phandle_2_cell *cells, struct clk *clk); 66 67 /** 68 * clock_get_by_index - Get/request a clock by integer index. 69 * 70 * This looks up and requests a clock. The index is relative to the client 71 * device; each device is assumed to have n clocks associated with it somehow, 72 * and this function finds and requests one of them. The mapping of client 73 * device clock indices to provider clocks may be via device-tree properties, 74 * board-provided mapping tables, or some other mechanism. 75 * 76 * @dev: The client device. 77 * @index: The index of the clock to request, within the client's list of 78 * clocks. 79 * @clock A pointer to a clock struct to initialize. 80 * @return 0 if OK, or a negative error code. 81 */ 82 int clk_get_by_index(struct udevice *dev, int index, struct clk *clk); 83 84 /** 85 * clock_get_by_name - Get/request a clock by name. 86 * 87 * This looks up and requests a clock. The name is relative to the client 88 * device; each device is assumed to have n clocks associated with it somehow, 89 * and this function finds and requests one of them. The mapping of client 90 * device clock names to provider clocks may be via device-tree properties, 91 * board-provided mapping tables, or some other mechanism. 92 * 93 * @dev: The client device. 94 * @name: The name of the clock to request, within the client's list of 95 * clocks. 96 * @clock: A pointer to a clock struct to initialize. 97 * @return 0 if OK, or a negative error code. 98 */ 99 int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk); 100 #else 101 static inline int clk_get_by_index(struct udevice *dev, int index, 102 struct clk *clk) 103 { 104 return -ENOSYS; 105 } 106 107 static int clk_get_by_name(struct udevice *dev, const char *name, 108 struct clk *clk) 109 { 110 return -ENOSYS; 111 } 112 #endif 113 114 /** 115 * clk_request - Request a clock by provider-specific ID. 116 * 117 * This requests a clock using a provider-specific ID. Generally, this function 118 * should not be used, since clk_get_by_index/name() provide an interface that 119 * better separates clients from intimate knowledge of clock providers. 120 * However, this function may be useful in core SoC-specific code. 121 * 122 * @dev: The clock provider device. 123 * @clock: A pointer to a clock struct to initialize. The caller must 124 * have already initialized any field in this struct which the 125 * clock provider uses to identify the clock. 126 * @return 0 if OK, or a negative error code. 127 */ 128 int clk_request(struct udevice *dev, struct clk *clk); 129 130 /** 131 * clock_free - Free a previously requested clock. 132 * 133 * @clock: A clock struct that was previously successfully requested by 134 * clk_request/get_by_*(). 135 * @return 0 if OK, or a negative error code. 136 */ 137 int clk_free(struct clk *clk); 138 139 /** 140 * clk_get_rate() - Get current clock rate. 141 * 142 * @clk: A clock struct that was previously successfully requested by 143 * clk_request/get_by_*(). 144 * @return clock rate in Hz, or -ve error code. 145 */ 146 ulong clk_get_rate(struct clk *clk); 147 148 /** 149 * clk_set_rate() - Set current clock rate. 150 * 151 * @clk: A clock struct that was previously successfully requested by 152 * clk_request/get_by_*(). 153 * @rate: New clock rate in Hz. 154 * @return new rate, or -ve error code. 155 */ 156 ulong clk_set_rate(struct clk *clk, ulong rate); 157 158 /** 159 * clk_enable() - Enable (turn on) a clock. 160 * 161 * @clk: A clock struct that was previously successfully requested by 162 * clk_request/get_by_*(). 163 * @return zero on success, or -ve error code. 164 */ 165 int clk_enable(struct clk *clk); 166 167 /** 168 * clk_disable() - Disable (turn off) a clock. 169 * 170 * @clk: A clock struct that was previously successfully requested by 171 * clk_request/get_by_*(). 172 * @return zero on success, or -ve error code. 173 */ 174 int clk_disable(struct clk *clk); 175 176 int soc_clk_dump(void); 177 178 #endif 179