include/linux/hte.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002
0003 #ifndef __LINUX_HTE_H
0004 #define __LINUX_HTE_H
0005
0006 #include <linux/errno.h>
0007
0008 struct hte_chip;
0009 struct hte_device;
0010 struct of_phandle_args;
0011
0012 /**
0013  * enum hte_edge - HTE line edge flags.
0014  *
0015  * @HTE_EDGE_NO_SETUP: No edge setup. In this case consumer will setup edges,
0016  * for example during request irq call.
0017  * @HTE_RISING_EDGE_TS: Rising edge.
0018  * @HTE_FALLING_EDGE_TS: Falling edge.
0019  *
0020  */
0021 enum hte_edge {
0022     HTE_EDGE_NO_SETUP = 1U << 0,
0023     HTE_RISING_EDGE_TS = 1U << 1,
0024     HTE_FALLING_EDGE_TS = 1U << 2,
0025 };
0026
0027 /**
0028  * enum hte_return - HTE subsystem return values used during callback.
0029  *
0030  * @HTE_CB_HANDLED: The consumer handled the data.
0031  * @HTE_RUN_SECOND_CB: The consumer needs further processing, in that case
0032  * HTE subsystem calls secondary callback provided by the consumer where it
0033  * is allowed to sleep.
0034  */
0035 enum hte_return {
0036     HTE_CB_HANDLED,
0037     HTE_RUN_SECOND_CB,
0038 };
0039
0040 /**
0041  * struct hte_ts_data - HTE timestamp data.
0042  *
0043  * @tsc: Timestamp value.
0044  * @seq: Sequence counter of the timestamps.
0045  * @raw_level: Level of the line at the timestamp if provider supports it,
0046  * -1 otherwise.
0047  */
0048 struct hte_ts_data {
0049     u64 tsc;
0050     u64 seq;
0051     int raw_level;
0052 };
0053
0054 /**
0055  * struct hte_clk_info - Clock source info that HTE provider uses to timestamp.
0056  *
0057  * @hz: Supported clock rate in HZ, for example 1KHz clock = 1000.
0058  * @type: Supported clock type.
0059  */
0060 struct hte_clk_info {
0061     u64 hz;
0062     clockid_t type;
0063 };
0064
0065 /**
0066  * typedef hte_ts_cb_t - HTE timestamp data processing primary callback.
0067  *
0068  * The callback is used to push timestamp data to the client and it is
0069  * not allowed to sleep.
0070  *
0071  * @ts: HW timestamp data.
0072  * @data: Client supplied data.
0073  */
0074 typedef enum hte_return (*hte_ts_cb_t)(struct hte_ts_data *ts, void *data);
0075
0076 /**
0077  * typedef hte_ts_sec_cb_t - HTE timestamp data processing secondary callback.
0078  *
0079  * This is used when the client needs further processing where it is
0080  * allowed to sleep.
0081  *
0082  * @data: Client supplied data.
0083  *
0084  */
0085 typedef enum hte_return (*hte_ts_sec_cb_t)(void *data);
0086
0087 /**
0088  * struct hte_line_attr - Line attributes.
0089  *
0090  * @line_id: The logical ID understood by the consumers and providers.
0091  * @line_data: Line data related to line_id.
0092  * @edge_flags: Edge setup flags.
0093  * @name: Descriptive name of the entity that is being monitored for the
0094  * hardware timestamping. If null, HTE core will construct the name.
0095  *
0096  */
0097 struct hte_line_attr {
0098     u32 line_id;
0099     void *line_data;
0100     unsigned long edge_flags;
0101     const char *name;
0102 };
0103
0104 /**
0105  * struct hte_ts_desc - HTE timestamp descriptor.
0106  *
0107  * This structure is a communication token between consumers to subsystem
0108  * and subsystem to providers.
0109  *
0110  * @attr: The line attributes.
0111  * @hte_data: Subsystem's private data, set by HTE subsystem.
0112  */
0113 struct hte_ts_desc {
0114     struct hte_line_attr attr;
0115     void *hte_data;
0116 };
0117
0118 /**
0119  * struct hte_ops - HTE operations set by providers.
0120  *
0121  * @request: Hook for requesting a HTE timestamp. Returns 0 on success,
0122  * non-zero for failures.
0123  * @release: Hook for releasing a HTE timestamp. Returns 0 on success,
0124  * non-zero for failures.
0125  * @enable: Hook to enable the specified timestamp. Returns 0 on success,
0126  * non-zero for failures.
0127  * @disable: Hook to disable specified timestamp. Returns 0 on success,
0128  * non-zero for failures.
0129  * @get_clk_src_info: Hook to get the clock information the provider uses
0130  * to timestamp. Returns 0 for success and negative error code for failure. On
0131  * success HTE subsystem fills up provided struct hte_clk_info.
0132  *
0133  * xlated_id parameter is used to communicate between HTE subsystem and the
0134  * providers and is translated by the provider.
0135  */
0136 struct hte_ops {
0137     int (*request)(struct hte_chip *chip, struct hte_ts_desc *desc,
0138                u32 xlated_id);
0139     int (*release)(struct hte_chip *chip, struct hte_ts_desc *desc,
0140                u32 xlated_id);
0141     int (*enable)(struct hte_chip *chip, u32 xlated_id);
0142     int (*disable)(struct hte_chip *chip, u32 xlated_id);
0143     int (*get_clk_src_info)(struct hte_chip *chip,
0144                 struct hte_clk_info *ci);
0145 };
0146
0147 /**
0148  * struct hte_chip - Abstract HTE chip.
0149  *
0150  * @name: functional name of the HTE IP block.
0151  * @dev: device providing the HTE.
0152  * @ops: callbacks for this HTE.
0153  * @nlines: number of lines/signals supported by this chip.
0154  * @xlate_of: Callback which translates consumer supplied logical ids to
0155  * physical ids, return 0 for the success and negative for the failures.
0156  * It stores (between 0 to @nlines) in xlated_id parameter for the success.
0157  * @xlate_plat: Same as above but for the consumers with no DT node.
0158  * @match_from_linedata: Match HTE device using the line_data.
0159  * @of_hte_n_cells: Number of cells used to form the HTE specifier.
0160  * @gdev: HTE subsystem abstract device, internal to the HTE subsystem.
0161  * @data: chip specific private data.
0162  */
0163 struct hte_chip {
0164     const char *name;
0165     struct device *dev;
0166     const struct hte_ops *ops;
0167     u32 nlines;
0168     int (*xlate_of)(struct hte_chip *gc,
0169             const struct of_phandle_args *args,
0170             struct hte_ts_desc *desc, u32 *xlated_id);
0171     int (*xlate_plat)(struct hte_chip *gc, struct hte_ts_desc *desc,
0172              u32 *xlated_id);
0173     bool (*match_from_linedata)(const struct hte_chip *chip,
0174                     const struct hte_ts_desc *hdesc);
0175     u8 of_hte_n_cells;
0176
0177     struct hte_device *gdev;
0178     void *data;
0179 };
0180
0181 #if IS_ENABLED(CONFIG_HTE)
0182 /* HTE APIs for the providers */
0183 int devm_hte_register_chip(struct hte_chip *chip);
0184 int hte_push_ts_ns(const struct hte_chip *chip, u32 xlated_id,
0185            struct hte_ts_data *data);
0186
0187 /* HTE APIs for the consumers */
0188 int hte_init_line_attr(struct hte_ts_desc *desc, u32 line_id,
0189                unsigned long edge_flags, const char *name,
0190                void *data);
0191 int hte_ts_get(struct device *dev, struct hte_ts_desc *desc, int index);
0192 int hte_ts_put(struct hte_ts_desc *desc);
0193 int hte_request_ts_ns(struct hte_ts_desc *desc, hte_ts_cb_t cb,
0194               hte_ts_sec_cb_t tcb, void *data);
0195 int devm_hte_request_ts_ns(struct device *dev, struct hte_ts_desc *desc,
0196                hte_ts_cb_t cb, hte_ts_sec_cb_t tcb, void *data);
0197 int of_hte_req_count(struct device *dev);
0198 int hte_enable_ts(struct hte_ts_desc *desc);
0199 int hte_disable_ts(struct hte_ts_desc *desc);
0200 int hte_get_clk_src_info(const struct hte_ts_desc *desc,
0201              struct hte_clk_info *ci);
0202
0203 #else /* !CONFIG_HTE */
0204 static inline int devm_hte_register_chip(struct hte_chip *chip)
0205 {
0206     return -EOPNOTSUPP;
0207 }
0208
0209 static inline int hte_push_ts_ns(const struct hte_chip *chip,
0210                  u32 xlated_id,
0211                  const struct hte_ts_data *data)
0212 {
0213     return -EOPNOTSUPP;
0214 }
0215
0216 static inline int hte_init_line_attr(struct hte_ts_desc *desc, u32 line_id,
0217                      unsigned long edge_flags,
0218                      const char *name, void *data)
0219 {
0220     return -EOPNOTSUPP;
0221 }
0222
0223 static inline int hte_ts_get(struct device *dev, struct hte_ts_desc *desc,
0224                  int index)
0225 {
0226     return -EOPNOTSUPP;
0227 }
0228
0229 static inline int hte_ts_put(struct hte_ts_desc *desc)
0230 {
0231     return -EOPNOTSUPP;
0232 }
0233
0234 static inline int hte_request_ts_ns(struct hte_ts_desc *desc, hte_ts_cb_t cb,
0235                     hte_ts_sec_cb_t tcb, void *data)
0236 {
0237     return -EOPNOTSUPP;
0238 }
0239
0240 static inline int devm_hte_request_ts_ns(struct device *dev,
0241                      struct hte_ts_desc *desc,
0242                      hte_ts_cb_t cb,
0243                      hte_ts_sec_cb_t tcb,
0244                      void *data)
0245 {
0246     return -EOPNOTSUPP;
0247 }
0248
0249 static inline int of_hte_req_count(struct device *dev)
0250 {
0251     return -EOPNOTSUPP;
0252 }
0253
0254 static inline int hte_enable_ts(struct hte_ts_desc *desc)
0255 {
0256     return -EOPNOTSUPP;
0257 }
0258
0259 static inline int hte_disable_ts(struct hte_ts_desc *desc)
0260 {
0261     return -EOPNOTSUPP;
0262 }
0263
0264 static inline int hte_get_clk_src_info(const struct hte_ts_desc *desc,
0265                        struct hte_clk_info *ci)
0266 {
0267     return -EOPNOTSUPP;
0268 }
0269 #endif /* !CONFIG_HTE */
0270
0271 #endif