include/linux/hte.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2
   3 #ifndef __LINUX_HTE_H
   4 #define __LINUX_HTE_H
   5
   6 #include <linux/errno.h>
   7
   8 struct hte_chip;
   9 struct hte_device;
  10 struct of_phandle_args;
  11
  12 /**
  13  * enum hte_edge - HTE line edge flags.
  14  *
  15  * @HTE_EDGE_NO_SETUP: No edge setup. In this case consumer will setup edges,
  16  * for example during request irq call.
  17  * @HTE_RISING_EDGE_TS: Rising edge.
  18  * @HTE_FALLING_EDGE_TS: Falling edge.
  19  *
  20  */
  21 enum hte_edge {
  22         HTE_EDGE_NO_SETUP = 1U << 0,
  23         HTE_RISING_EDGE_TS = 1U << 1,
  24         HTE_FALLING_EDGE_TS = 1U << 2,
  25 };
  26
  27 /**
  28  * enum hte_return - HTE subsystem return values used during callback.
  29  *
  30  * @HTE_CB_HANDLED: The consumer handled the data.
  31  * @HTE_RUN_SECOND_CB: The consumer needs further processing, in that case
  32  * HTE subsystem calls secondary callback provided by the consumer where it
  33  * is allowed to sleep.
  34  */
  35 enum hte_return {
  36         HTE_CB_HANDLED,
  37         HTE_RUN_SECOND_CB,
  38 };
  39
  40 /**
  41  * struct hte_ts_data - HTE timestamp data.
  42  *
  43  * @tsc: Timestamp value.
  44  * @seq: Sequence counter of the timestamps.
  45  * @raw_level: Level of the line at the timestamp if provider supports it,
  46  * -1 otherwise.
  47  */
  48 struct hte_ts_data {
  49         u64 tsc;
  50         u64 seq;
  51         int raw_level;
  52 };
  53
  54 /**
  55  * struct hte_clk_info - Clock source info that HTE provider uses to timestamp.
  56  *
  57  * @hz: Supported clock rate in HZ, for example 1KHz clock = 1000.
  58  * @type: Supported clock type.
  59  */
  60 struct hte_clk_info {
  61         u64 hz;
  62         clockid_t type;
  63 };
  64
  65 /**
  66  * typedef hte_ts_cb_t - HTE timestamp data processing primary callback.
  67  *
  68  * The callback is used to push timestamp data to the client and it is
  69  * not allowed to sleep.
  70  *
  71  * @ts: HW timestamp data.
  72  * @data: Client supplied data.
  73  */
  74 typedef enum hte_return (*hte_ts_cb_t)(struct hte_ts_data *ts, void *data);
  75
  76 /**
  77  * typedef hte_ts_sec_cb_t - HTE timestamp data processing secondary callback.
  78  *
  79  * This is used when the client needs further processing where it is
  80  * allowed to sleep.
  81  *
  82  * @data: Client supplied data.
  83  *
  84  */
  85 typedef enum hte_return (*hte_ts_sec_cb_t)(void *data);
  86
  87 /**
  88  * struct hte_line_attr - Line attributes.
  89  *
  90  * @line_id: The logical ID understood by the consumers and providers.
  91  * @line_data: Line data related to line_id.
  92  * @edge_flags: Edge setup flags.
  93  * @name: Descriptive name of the entity that is being monitored for the
  94  * hardware timestamping. If null, HTE core will construct the name.
  95  *
  96  */
  97 struct hte_line_attr {
  98         u32 line_id;
  99         void *line_data;
 100         unsigned long edge_flags;
 101         const char *name;
 102 };
 103
 104 /**
 105  * struct hte_ts_desc - HTE timestamp descriptor.
 106  *
 107  * This structure is a communication token between consumers to subsystem
 108  * and subsystem to providers.
 109  *
 110  * @attr: The line attributes.
 111  * @hte_data: Subsystem's private data, set by HTE subsystem.
 112  */
 113 struct hte_ts_desc {
 114         struct hte_line_attr attr;
 115         void *hte_data;
 116 };
 117
 118 /**
 119  * struct hte_ops - HTE operations set by providers.
 120  *
 121  * @request: Hook for requesting a HTE timestamp. Returns 0 on success,
 122  * non-zero for failures.
 123  * @release: Hook for releasing a HTE timestamp. Returns 0 on success,
 124  * non-zero for failures.
 125  * @enable: Hook to enable the specified timestamp. Returns 0 on success,
 126  * non-zero for failures.
 127  * @disable: Hook to disable specified timestamp. Returns 0 on success,
 128  * non-zero for failures.
 129  * @get_clk_src_info: Hook to get the clock information the provider uses
 130  * to timestamp. Returns 0 for success and negative error code for failure. On
 131  * success HTE subsystem fills up provided struct hte_clk_info.
 132  *
 133  * xlated_id parameter is used to communicate between HTE subsystem and the
 134  * providers and is translated by the provider.
 135  */
 136 struct hte_ops {
 137         int (*request)(struct hte_chip *chip, struct hte_ts_desc *desc,
 138                        u32 xlated_id);
 139         int (*release)(struct hte_chip *chip, struct hte_ts_desc *desc,
 140                        u32 xlated_id);
 141         int (*enable)(struct hte_chip *chip, u32 xlated_id);
 142         int (*disable)(struct hte_chip *chip, u32 xlated_id);
 143         int (*get_clk_src_info)(struct hte_chip *chip,
 144                                 struct hte_clk_info *ci);
 145 };
 146
 147 /**
 148  * struct hte_chip - Abstract HTE chip.
 149  *
 150  * @name: functional name of the HTE IP block.
 151  * @dev: device providing the HTE.
 152  * @ops: callbacks for this HTE.
 153  * @nlines: number of lines/signals supported by this chip.
 154  * @xlate_of: Callback which translates consumer supplied logical ids to
 155  * physical ids, return 0 for the success and negative for the failures.
 156  * It stores (between 0 to @nlines) in xlated_id parameter for the success.
 157  * @xlate_plat: Same as above but for the consumers with no DT node.
 158  * @match_from_linedata: Match HTE device using the line_data.
 159  * @of_hte_n_cells: Number of cells used to form the HTE specifier.
 160  * @gdev: HTE subsystem abstract device, internal to the HTE subsystem.
 161  * @data: chip specific private data.
 162  */
 163 struct hte_chip {
 164         const char *name;
 165         struct device *dev;
 166         const struct hte_ops *ops;
 167         u32 nlines;
 168         int (*xlate_of)(struct hte_chip *gc,
 169                         const struct of_phandle_args *args,
 170                         struct hte_ts_desc *desc, u32 *xlated_id);
 171         int (*xlate_plat)(struct hte_chip *gc, struct hte_ts_desc *desc,
 172                          u32 *xlated_id);
 173         bool (*match_from_linedata)(const struct hte_chip *chip,
 174                                     const struct hte_ts_desc *hdesc);
 175         u8 of_hte_n_cells;
 176
 177         struct hte_device *gdev;
 178         void *data;
 179 };
 180
 181 #if IS_ENABLED(CONFIG_HTE)
 182 /* HTE APIs for the providers */
 183 int devm_hte_register_chip(struct hte_chip *chip);
 184 int hte_push_ts_ns(const struct hte_chip *chip, u32 xlated_id,
 185                    struct hte_ts_data *data);
 186
 187 /* HTE APIs for the consumers */
 188 int hte_init_line_attr(struct hte_ts_desc *desc, u32 line_id,
 189                        unsigned long edge_flags, const char *name,
 190                        void *data);
 191 int hte_ts_get(struct device *dev, struct hte_ts_desc *desc, int index);
 192 int hte_ts_put(struct hte_ts_desc *desc);
 193 int hte_request_ts_ns(struct hte_ts_desc *desc, hte_ts_cb_t cb,
 194                       hte_ts_sec_cb_t tcb, void *data);
 195 int devm_hte_request_ts_ns(struct device *dev, struct hte_ts_desc *desc,
 196                            hte_ts_cb_t cb, hte_ts_sec_cb_t tcb, void *data);
 197 int of_hte_req_count(struct device *dev);
 198 int hte_enable_ts(struct hte_ts_desc *desc);
 199 int hte_disable_ts(struct hte_ts_desc *desc);
 200 int hte_get_clk_src_info(const struct hte_ts_desc *desc,
 201                          struct hte_clk_info *ci);
 202
 203 #else /* !CONFIG_HTE */
 204 static inline int devm_hte_register_chip(struct hte_chip *chip)
 205 {
 206         return -EOPNOTSUPP;
 207 }
 208
 209 static inline int hte_push_ts_ns(const struct hte_chip *chip,
 210                                  u32 xlated_id,
 211                                  const struct hte_ts_data *data)
 212 {
 213         return -EOPNOTSUPP;
 214 }
 215
 216 static inline int hte_init_line_attr(struct hte_ts_desc *desc, u32 line_id,
 217                                      unsigned long edge_flags,
 218                                      const char *name, void *data)
 219 {
 220         return -EOPNOTSUPP;
 221 }
 222
 223 static inline int hte_ts_get(struct device *dev, struct hte_ts_desc *desc,
 224                              int index)
 225 {
 226         return -EOPNOTSUPP;
 227 }
 228
 229 static inline int hte_ts_put(struct hte_ts_desc *desc)
 230 {
 231         return -EOPNOTSUPP;
 232 }
 233
 234 static inline int hte_request_ts_ns(struct hte_ts_desc *desc, hte_ts_cb_t cb,
 235                                     hte_ts_sec_cb_t tcb, void *data)
 236 {
 237         return -EOPNOTSUPP;
 238 }
 239
 240 static inline int devm_hte_request_ts_ns(struct device *dev,
 241                                          struct hte_ts_desc *desc,
 242                                          hte_ts_cb_t cb,
 243                                          hte_ts_sec_cb_t tcb,
 244                                          void *data)
 245 {
 246         return -EOPNOTSUPP;
 247 }
 248
 249 static inline int of_hte_req_count(struct device *dev)
 250 {
 251         return -EOPNOTSUPP;
 252 }
 253
 254 static inline int hte_enable_ts(struct hte_ts_desc *desc)
 255 {
 256         return -EOPNOTSUPP;
 257 }
 258
 259 static inline int hte_disable_ts(struct hte_ts_desc *desc)
 260 {
 261         return -EOPNOTSUPP;
 262 }
 263
 264 static inline int hte_get_clk_src_info(const struct hte_ts_desc *desc,
 265                                        struct hte_clk_info *ci)
 266 {
 267         return -EOPNOTSUPP;
 268 }
 269 #endif /* !CONFIG_HTE */
 270
 271 #endif