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
  8struct hte_chip;
  9struct hte_device;
 10struct 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 */
 21enum 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 */
 35enum 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 */
 48struct 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 */
 60struct 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 */
 74typedef 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 */
 85typedef 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 */
 97struct 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 */
113struct 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 */
136struct 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 */
163struct 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 */
183int devm_hte_register_chip(struct hte_chip *chip);
184int 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 */
188int hte_init_line_attr(struct hte_ts_desc *desc, u32 line_id,
189		       unsigned long edge_flags, const char *name,
190		       void *data);
191int hte_ts_get(struct device *dev, struct hte_ts_desc *desc, int index);
192int hte_ts_put(struct hte_ts_desc *desc);
193int hte_request_ts_ns(struct hte_ts_desc *desc, hte_ts_cb_t cb,
194		      hte_ts_sec_cb_t tcb, void *data);
195int 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);
197int of_hte_req_count(struct device *dev);
198int hte_enable_ts(struct hte_ts_desc *desc);
199int hte_disable_ts(struct hte_ts_desc *desc);
200int hte_get_clk_src_info(const struct hte_ts_desc *desc,
201			 struct hte_clk_info *ci);
202
203#else /* !CONFIG_HTE */
204static inline int devm_hte_register_chip(struct hte_chip *chip)
205{
206	return -EOPNOTSUPP;
207}
208
209static 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
216static 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
223static inline int hte_ts_get(struct device *dev, struct hte_ts_desc *desc,
224			     int index)
225{
226	return -EOPNOTSUPP;
227}
228
229static inline int hte_ts_put(struct hte_ts_desc *desc)
230{
231	return -EOPNOTSUPP;
232}
233
234static 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
240static 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
249static inline int of_hte_req_count(struct device *dev)
250{
251	return -EOPNOTSUPP;
252}
253
254static inline int hte_enable_ts(struct hte_ts_desc *desc)
255{
256	return -EOPNOTSUPP;
257}
258
259static inline int hte_disable_ts(struct hte_ts_desc *desc)
260{
261	return -EOPNOTSUPP;
262}
263
264static 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