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_UCLASS_H 9#define _CLK_UCLASS_H 10 11/* See clk.h for background documentation. */ 12 13#include <clk.h> 14 15struct ofnode_phandle_args; 16 17/** 18 * struct clk_ops - The functions that a clock driver must implement. 19 * @of_xlate: Translate a client's device-tree (OF) clock specifier. 20 * @request: Request a translated clock. 21 * @round_rate: Adjust a rate to the exact rate a clock can provide. 22 * @get_rate: Get current clock rate. 23 * @set_rate: Set current clock rate. 24 * @set_parent: Set current clock parent 25 * @enable: Enable a clock. 26 * @disable: Disable a clock. 27 * @dump: Print clock information. 28 * 29 * The individual methods are described more fully below. 30 */ 31struct clk_ops { 32 int (*of_xlate)(struct clk *clock, 33 struct ofnode_phandle_args *args); 34 int (*request)(struct clk *clock); 35 ulong (*round_rate)(struct clk *clk, ulong rate); 36 ulong (*get_rate)(struct clk *clk); 37 ulong (*set_rate)(struct clk *clk, ulong rate); 38 int (*set_parent)(struct clk *clk, struct clk *parent); 39 int (*enable)(struct clk *clk); 40 int (*disable)(struct clk *clk); 41#if IS_ENABLED(CONFIG_CMD_CLK) 42 void (*dump)(struct udevice *dev); 43#endif 44}; 45 46#if 0 /* For documentation only */ 47/** 48 * of_xlate() - Translate a client's device-tree (OF) clock specifier. 49 * @clock: The clock struct to hold the translation result. 50 * @args: The clock specifier values from device tree. 51 * 52 * The clock core calls this function as the first step in implementing 53 * a client's clk_get_by_*() call. 54 * 55 * If this function pointer is set to NULL, the clock core will use a 56 * default implementation, which assumes #clock-cells = <1>, and that 57 * the DT cell contains a simple integer clock ID. 58 * 59 * This function should be a simple translation of @args into @clock->id and 60 * (optionally) @clock->data. All other processing, allocation, or error 61 * checking should take place in request(). 62 * 63 * At present, the clock API solely supports device-tree. If this 64 * changes, other xxx_xlate() functions may be added to support those 65 * other mechanisms. 66 * 67 * Return: 68 * * 0 on success 69 * * -%EINVAL if @args does not have the correct format. For example, it could 70 * have too many/few arguments. 71 * * -%ENOENT if @args has the correct format but cannot be translated. This can 72 * happen if translation involves a table lookup and @args is not present. 73 */ 74int of_xlate(struct clk *clock, struct ofnode_phandle_args *args); 75 76/** 77 * request() - Request a translated clock. 78 * @clock: The clock struct to request; this has been filled in by 79 * a previoux xxx_xlate() function call, or by the caller 80 * of clk_request(). 81 * 82 * The clock core calls this function as the second step in 83 * implementing a client's clk_get_by_*() call, following a successful 84 * xxx_xlate() call, or as the only step in implementing a client's 85 * clk_request() call. 86 * 87 * This is the right place to do bounds checking (rejecting invalid or 88 * unimplemented clocks), allocate resources, or perform other setup not done 89 * during driver probe(). Most clock drivers should allocate resources in their 90 * probe() function, but it is possible to lazily initialize something here. 91 * 92 * Return: 93 * * 0 on success 94 * * -%ENOENT, if there is no clock corresponding to @clock->id and 95 * @clock->data. 96 */ 97int request(struct clk *clock); 98 99/** 100 * round_rate() - Adjust a rate to the exact rate a clock can provide. 101 * @clk: The clock to query. 102 * @rate: Desired clock rate in Hz. 103 * 104 * This function returns a new rate which can be provided to set_rate(). This 105 * new rate should be the closest rate to @rate which can be set without 106 * rounding. The following pseudo-code should hold:: 107 * 108 * for all rate in range(ULONG_MAX): 109 * rounded = round_rate(clk, rate) 110 * new_rate = set_rate(clk, rate) 111 * assert(IS_ERR_VALUE(new_rate) || new_rate == rounded) 112 * 113 * Return: 114 * * The rounded rate in Hz on success 115 * * A negative error value from another API (such as clk_get_rate()). This 116 * function must not return an error for any other reason. 117 */ 118ulong round_rate(struct clk *clk, ulong rate); 119 120/** 121 * get_rate() - Get current clock rate. 122 * @clk: The clock to query. 123 * 124 * This returns the current rate of a clock. If the clock is disabled, it 125 * returns the rate at which the clock would run if it was enabled. The 126 * following pseudo-code should hold:: 127 * 128 * disable(clk) 129 * rate = get_rate(clk) 130 * enable(clk) 131 * assert(get_rate(clk) == rate) 132 * 133 * Return: 134 * * The rate of @clk 135 * * -%ENOSYS if this function is not implemented for @clk 136 * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing 137 * this check in request(). 138 * * Another negative error value (such as %EIO or %ECOMM) if the rate could 139 * not be determined due to a bus error. 140 */ 141ulong get_rate(struct clk *clk); 142 143/** 144 * set_rate() - Set current clock rate. 145 * @clk: The clock to manipulate. 146 * @rate: New clock rate in Hz. 147 * 148 * Set the rate of @clk to @rate. The actual rate may be rounded. However, 149 * excessive rounding should be avoided. It is left to the driver author's 150 * discretion when this function should attempt to round and when it should 151 * return an error. For example, a dividing clock might use the following 152 * pseudo-logic when implemening this function:: 153 * 154 * divisor = parent_rate / rate 155 * if divisor < min || divisor > max: 156 * return -EINVAL 157 * 158 * If there is any concern about rounding, prefer to let consumers make the 159 * decision by calling round_rate(). 160 * 161 * Return: 162 * * The new rate on success 163 * * -%ENOSYS if this function is not implemented for @clk 164 * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing 165 * this check in request(). 166 * * -%EINVAL if @rate is not valid for @clk. 167 * * Another negative error value (such as %EIO or %ECOMM) if the rate could 168 * not be set due to a bus error. 169 */ 170ulong set_rate(struct clk *clk, ulong rate); 171 172/** 173 * set_parent() - Set current clock parent 174 * @clk: The clock to manipulate. 175 * @parent: New clock parent. 176 * 177 * Set the current parent of @clk to @parent. The rate of the clock may be 178 * modified by this call. If @clk was enabled before this function, it should 179 * remain enabled after this function, although it may be temporarily disabled 180 * if necessary. 181 * 182 * Return: 183 * * 0 on success 184 * * -%ENOSYS if this function is not implemented for @clk 185 * * -%ENOENT if @clk->id or @parent->id is invalid. Prefer using an assert 186 * instead, and doing this check in request(). 187 * * -%EINVAL if @parent is not a valid parent for @clk. 188 * * Another negative error value (such as %EIO or %ECOMM) if the parent could 189 * not be set due to a bus error. 190 */ 191int set_parent(struct clk *clk, struct clk *parent); 192 193/** 194 * enable() - Enable a clock. 195 * @clk: The clock to manipulate. 196 * 197 * Enable (un-gate) the clock. This function should not modify the rate of the 198 * clock (see get_rate() for details). 199 * 200 * Return: 201 * * 0 on success 202 * * -%ENOSYS if this function is not implemented for @clk 203 * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing 204 * this check in request(). 205 * * Another negative error value (such as %EIO or %ECOMM) if the clock could 206 * not be enabled due to a bus error. 207 */ 208int enable(struct clk *clk); 209 210/** 211 * disable() - Disable a clock. 212 * @clk: The clock to manipulate. 213 * 214 * Disable (gate) the clock. This function should not modify the rate of the 215 * clock (see get_rate() for details). 216 * 217 * * 0 on success 218 * * -%ENOSYS if this function is not implemented for @clk 219 * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing 220 * this check in request(). 221 * * Another negative error value (such as %EIO or %ECOMM) if the clock could 222 * not be disabled due to a bus error. 223 */ 224int disable(struct clk *clk); 225 226/** 227 * dump() - Print clock information. 228 * @dev: The clock device to dump. 229 * 230 * If present, this function is called by "clk dump" command for each 231 * bound device. 232 */ 233void dump(struct udevice *dev); 234#endif 235 236#endif 237