include/linux/soc/ti/ti_sci_protocol.h

   1 /*
   2  * Texas Instruments System Control Interface Protocol
   3  *
   4  * Copyright (C) 2015-2016 Texas Instruments Incorporated - http://www.ti.com/
   5  *      Nishanth Menon
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License version 2 as
   9  * published by the Free Software Foundation.
  10  *
  11  * This program is distributed "as is" WITHOUT ANY WARRANTY of any
  12  * kind, whether express or implied; without even the implied warranty
  13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  */
  16
  17 #ifndef __TISCI_PROTOCOL_H
  18 #define __TISCI_PROTOCOL_H
  19
  20 /**
  21  * struct ti_sci_version_info - version information structure
  22  * @abi_major:  Major ABI version. Change here implies risk of backward
  23  *              compatibility break.
  24  * @abi_minor:  Minor ABI version. Change here implies new feature addition,
  25  *              or compatible change in ABI.
  26  * @firmware_revision:  Firmware revision (not usually used).
  27  * @firmware_description: Firmware description (not usually used).
  28  */
  29 struct ti_sci_version_info {
  30         u8 abi_major;
  31         u8 abi_minor;
  32         u16 firmware_revision;
  33         char firmware_description[32];
  34 };
  35
  36 struct ti_sci_handle;
  37
  38 /**
  39  * struct ti_sci_core_ops - SoC Core Operations
  40  * @reboot_device: Reboot the SoC
  41  *              Returns 0 for successful request(ideally should never return),
  42  *              else returns corresponding error value.
  43  */
  44 struct ti_sci_core_ops {
  45         int (*reboot_device)(const struct ti_sci_handle *handle);
  46 };
  47
  48 /**
  49  * struct ti_sci_dev_ops - Device control operations
  50  * @get_device: Command to request for device managed by TISCI
  51  *              Returns 0 for successful exclusive request, else returns
  52  *              corresponding error message.
  53  * @idle_device: Command to idle a device managed by TISCI
  54  *              Returns 0 for successful exclusive request, else returns
  55  *              corresponding error message.
  56  * @put_device: Command to release a device managed by TISCI
  57  *              Returns 0 for successful release, else returns corresponding
  58  *              error message.
  59  * @is_valid:   Check if the device ID is a valid ID.
  60  *              Returns 0 if the ID is valid, else returns corresponding error.
  61  * @get_context_loss_count: Command to retrieve context loss counter - this
  62  *              increments every time the device looses context. Overflow
  63  *              is possible.
  64  *              - count: pointer to u32 which will retrieve counter
  65  *              Returns 0 for successful information request and count has
  66  *              proper data, else returns corresponding error message.
  67  * @is_idle:    Reports back about device idle state
  68  *              - req_state: Returns requested idle state
  69  *              Returns 0 for successful information request and req_state and
  70  *              current_state has proper data, else returns corresponding error
  71  *              message.
  72  * @is_stop:    Reports back about device stop state
  73  *              - req_state: Returns requested stop state
  74  *              - current_state: Returns current stop state
  75  *              Returns 0 for successful information request and req_state and
  76  *              current_state has proper data, else returns corresponding error
  77  *              message.
  78  * @is_on:      Reports back about device ON(or active) state
  79  *              - req_state: Returns requested ON state
  80  *              - current_state: Returns current ON state
  81  *              Returns 0 for successful information request and req_state and
  82  *              current_state has proper data, else returns corresponding error
  83  *              message.
  84  * @is_transitioning: Reports back if the device is in the middle of transition
  85  *              of state.
  86  *              -current_state: Returns 'true' if currently transitioning.
  87  * @set_device_resets: Command to configure resets for device managed by TISCI.
  88  *              -reset_state: Device specific reset bit field
  89  *              Returns 0 for successful request, else returns
  90  *              corresponding error message.
  91  * @get_device_resets: Command to read state of resets for device managed
  92  *              by TISCI.
  93  *              -reset_state: pointer to u32 which will retrieve resets
  94  *              Returns 0 for successful request, else returns
  95  *              corresponding error message.
  96  *
  97  * NOTE: for all these functions, the following parameters are generic in
  98  * nature:
  99  * -handle:     Pointer to TISCI handle as retrieved by *ti_sci_get_handle
 100  * -id:         Device Identifier
 101  *
 102  * Request for the device - NOTE: the client MUST maintain integrity of
 103  * usage count by balancing get_device with put_device. No refcounting is
 104  * managed by driver for that purpose.
 105  */
 106 struct ti_sci_dev_ops {
 107         int (*get_device)(const struct ti_sci_handle *handle, u32 id);
 108         int (*idle_device)(const struct ti_sci_handle *handle, u32 id);
 109         int (*put_device)(const struct ti_sci_handle *handle, u32 id);
 110         int (*is_valid)(const struct ti_sci_handle *handle, u32 id);
 111         int (*get_context_loss_count)(const struct ti_sci_handle *handle,
 112                                       u32 id, u32 *count);
 113         int (*is_idle)(const struct ti_sci_handle *handle, u32 id,
 114                        bool *requested_state);
 115         int (*is_stop)(const struct ti_sci_handle *handle, u32 id,
 116                        bool *req_state, bool *current_state);
 117         int (*is_on)(const struct ti_sci_handle *handle, u32 id,
 118                      bool *req_state, bool *current_state);
 119         int (*is_transitioning)(const struct ti_sci_handle *handle, u32 id,
 120                                 bool *current_state);
 121         int (*set_device_resets)(const struct ti_sci_handle *handle, u32 id,
 122                                  u32 reset_state);
 123         int (*get_device_resets)(const struct ti_sci_handle *handle, u32 id,
 124                                  u32 *reset_state);
 125 };
 126
 127 /**
 128  * struct ti_sci_clk_ops - Clock control operations
 129  * @get_clock:  Request for activation of clock and manage by processor
 130  *              - needs_ssc: 'true' if Spread Spectrum clock is desired.
 131  *              - can_change_freq: 'true' if frequency change is desired.
 132  *              - enable_input_term: 'true' if input termination is desired.
 133  * @idle_clock: Request for Idling a clock managed by processor
 134  * @put_clock:  Release the clock to be auto managed by TISCI
 135  * @is_auto:    Is the clock being auto managed
 136  *              - req_state: state indicating if the clock is auto managed
 137  * @is_on:      Is the clock ON
 138  *              - req_state: if the clock is requested to be forced ON
 139  *              - current_state: if the clock is currently ON
 140  * @is_off:     Is the clock OFF
 141  *              - req_state: if the clock is requested to be forced OFF
 142  *              - current_state: if the clock is currently Gated
 143  * @set_parent: Set the clock source of a specific device clock
 144  *              - parent_id: Parent clock identifier to set.
 145  * @get_parent: Get the current clock source of a specific device clock
 146  *              - parent_id: Parent clock identifier which is the parent.
 147  * @get_num_parents: Get the number of parents of the current clock source
 148  *              - num_parents: returns the number of parent clocks.
 149  * @get_best_match_freq: Find a best matching frequency for a frequency
 150  *              range.
 151  *              - match_freq: Best matching frequency in Hz.
 152  * @set_freq:   Set the Clock frequency
 153  * @get_freq:   Get the Clock frequency
 154  *              - current_freq: Frequency in Hz that the clock is at.
 155  *
 156  * NOTE: for all these functions, the following parameters are generic in
 157  * nature:
 158  * -handle:     Pointer to TISCI handle as retrieved by *ti_sci_get_handle
 159  * -did:        Device identifier this request is for
 160  * -cid:        Clock identifier for the device for this request.
 161  *              Each device has it's own set of clock inputs. This indexes
 162  *              which clock input to modify.
 163  * -min_freq:   The minimum allowable frequency in Hz. This is the minimum
 164  *              allowable programmed frequency and does not account for clock
 165  *              tolerances and jitter.
 166  * -target_freq: The target clock frequency in Hz. A frequency will be
 167  *              processed as close to this target frequency as possible.
 168  * -max_freq:   The maximum allowable frequency in Hz. This is the maximum
 169  *              allowable programmed frequency and does not account for clock
 170  *              tolerances and jitter.
 171  *
 172  * Request for the clock - NOTE: the client MUST maintain integrity of
 173  * usage count by balancing get_clock with put_clock. No refcounting is
 174  * managed by driver for that purpose.
 175  */
 176 struct ti_sci_clk_ops {
 177         int (*get_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid,
 178                          bool needs_ssc, bool can_change_freq,
 179                          bool enable_input_term);
 180         int (*idle_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid);
 181         int (*put_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid);
 182         int (*is_auto)(const struct ti_sci_handle *handle, u32 did, u8 cid,
 183                        bool *req_state);
 184         int (*is_on)(const struct ti_sci_handle *handle, u32 did, u8 cid,
 185                      bool *req_state, bool *current_state);
 186         int (*is_off)(const struct ti_sci_handle *handle, u32 did, u8 cid,
 187                       bool *req_state, bool *current_state);
 188         int (*set_parent)(const struct ti_sci_handle *handle, u32 did, u8 cid,
 189                           u8 parent_id);
 190         int (*get_parent)(const struct ti_sci_handle *handle, u32 did, u8 cid,
 191                           u8 *parent_id);
 192         int (*get_num_parents)(const struct ti_sci_handle *handle, u32 did,
 193                                u8 cid, u8 *num_parents);
 194         int (*get_best_match_freq)(const struct ti_sci_handle *handle, u32 did,
 195                                    u8 cid, u64 min_freq, u64 target_freq,
 196                                    u64 max_freq, u64 *match_freq);
 197         int (*set_freq)(const struct ti_sci_handle *handle, u32 did, u8 cid,
 198                         u64 min_freq, u64 target_freq, u64 max_freq);
 199         int (*get_freq)(const struct ti_sci_handle *handle, u32 did, u8 cid,
 200                         u64 *current_freq);
 201 };
 202
 203 /**
 204  * struct ti_sci_ops - Function support for TI SCI
 205  * @dev_ops:    Device specific operations
 206  * @clk_ops:    Clock specific operations
 207  */
 208 struct ti_sci_ops {
 209         struct ti_sci_core_ops core_ops;
 210         struct ti_sci_dev_ops dev_ops;
 211         struct ti_sci_clk_ops clk_ops;
 212 };
 213
 214 /**
 215  * struct ti_sci_handle - Handle returned to TI SCI clients for usage.
 216  * @version:    structure containing version information
 217  * @ops:        operations that are made available to TI SCI clients
 218  */
 219 struct ti_sci_handle {
 220         struct ti_sci_version_info version;
 221         struct ti_sci_ops ops;
 222 };
 223
 224 #if IS_ENABLED(CONFIG_TI_SCI_PROTOCOL)
 225 const struct ti_sci_handle *ti_sci_get_handle(struct device *dev);
 226 int ti_sci_put_handle(const struct ti_sci_handle *handle);
 227 const struct ti_sci_handle *devm_ti_sci_get_handle(struct device *dev);
 228
 229 #else   /* CONFIG_TI_SCI_PROTOCOL */
 230
 231 static inline const struct ti_sci_handle *ti_sci_get_handle(struct device *dev)
 232 {
 233         return ERR_PTR(-EINVAL);
 234 }
 235
 236 static inline int ti_sci_put_handle(const struct ti_sci_handle *handle)
 237 {
 238         return -EINVAL;
 239 }
 240
 241 static inline
 242 const struct ti_sci_handle *devm_ti_sci_get_handle(struct device *dev)
 243 {
 244         return ERR_PTR(-EINVAL);
 245 }
 246
 247 #endif  /* CONFIG_TI_SCI_PROTOCOL */
 248
 249 #endif  /* __TISCI_PROTOCOL_H */