1 | // SPDX-License-Identifier: GPL-2.0 |
2 | /* |
3 | * System Trace Module (STM) infrastructure apis |
4 | * Copyright (C) 2014 Intel Corporation. |
5 | */ |
6 | |
7 | #ifndef _STM_H_ |
8 | #define _STM_H_ |
9 | |
10 | #include <linux/device.h> |
11 | |
12 | /** |
13 | * enum stp_packet_type - STP packets that an STM driver sends |
14 | */ |
15 | enum stp_packet_type { |
16 | STP_PACKET_DATA = 0, |
17 | STP_PACKET_FLAG, |
18 | STP_PACKET_USER, |
19 | STP_PACKET_MERR, |
20 | STP_PACKET_GERR, |
21 | STP_PACKET_TRIG, |
22 | STP_PACKET_XSYNC, |
23 | }; |
24 | |
25 | /** |
26 | * enum stp_packet_flags - STP packet modifiers |
27 | */ |
28 | enum stp_packet_flags { |
29 | STP_PACKET_MARKED = 0x1, |
30 | STP_PACKET_TIMESTAMPED = 0x2, |
31 | }; |
32 | |
33 | struct stp_policy; |
34 | |
35 | struct stm_device; |
36 | |
37 | /** |
38 | * struct stm_data - STM device description and callbacks |
39 | * @name: device name |
40 | * @stm: internal structure, only used by stm class code |
41 | * @sw_start: first STP master available to software |
42 | * @sw_end: last STP master available to software |
43 | * @sw_nchannels: number of STP channels per master |
44 | * @sw_mmiosz: size of one channel's IO space, for mmap, optional |
45 | * @hw_override: masters in the STP stream will not match the ones |
46 | * assigned by software, but are up to the STM hardware |
47 | * @packet: callback that sends an STP packet |
48 | * @mmio_addr: mmap callback, optional |
49 | * @link: called when a new stm_source gets linked to us, optional |
50 | * @unlink: likewise for unlinking, again optional |
51 | * @set_options: set device-specific options on a channel |
52 | * |
53 | * Fill out this structure before calling stm_register_device() to create |
54 | * an STM device and stm_unregister_device() to destroy it. It will also be |
55 | * passed back to @packet(), @mmio_addr(), @link(), @unlink() and @set_options() |
56 | * callbacks. |
57 | * |
58 | * Normally, an STM device will have a range of masters available to software |
59 | * and the rest being statically assigned to various hardware trace sources. |
60 | * The former is defined by the range [@sw_start..@sw_end] of the device |
61 | * description. That is, the lowest master that can be allocated to software |
62 | * writers is @sw_start and data from this writer will appear is @sw_start |
63 | * master in the STP stream. |
64 | * |
65 | * The @packet callback should adhere to the following rules: |
66 | * 1) it must return the number of bytes it consumed from the payload; |
67 | * 2) therefore, if it sent a packet that does not have payload (like FLAG), |
68 | * it must return zero; |
69 | * 3) if it does not support the requested packet type/flag combination, |
70 | * it must return -ENOTSUPP. |
71 | * |
72 | * The @unlink callback is called when there are no more active writers so |
73 | * that the master/channel can be quiesced. |
74 | */ |
75 | struct stm_data { |
76 | const char *name; |
77 | struct stm_device *stm; |
78 | unsigned int sw_start; |
79 | unsigned int sw_end; |
80 | unsigned int sw_nchannels; |
81 | unsigned int sw_mmiosz; |
82 | unsigned int hw_override; |
83 | ssize_t (*packet)(struct stm_data *, unsigned int, |
84 | unsigned int, unsigned int, |
85 | unsigned int, unsigned int, |
86 | const unsigned char *); |
87 | phys_addr_t (*mmio_addr)(struct stm_data *, unsigned int, |
88 | unsigned int, unsigned int); |
89 | int (*link)(struct stm_data *, unsigned int, |
90 | unsigned int); |
91 | void (*unlink)(struct stm_data *, unsigned int, |
92 | unsigned int); |
93 | long (*set_options)(struct stm_data *, unsigned int, |
94 | unsigned int, unsigned int, |
95 | unsigned long); |
96 | }; |
97 | |
98 | int stm_register_device(struct device *parent, struct stm_data *stm_data, |
99 | struct module *owner); |
100 | void stm_unregister_device(struct stm_data *stm_data); |
101 | |
102 | struct stm_source_device; |
103 | |
104 | /** |
105 | * struct stm_source_data - STM source device description and callbacks |
106 | * @name: device name, will be used for policy lookup |
107 | * @src: internal structure, only used by stm class code |
108 | * @nr_chans: number of channels to allocate |
109 | * @link: called when this source gets linked to an STM device |
110 | * @unlink: called when this source is about to get unlinked from its STM |
111 | * |
112 | * Fill in this structure before calling stm_source_register_device() to |
113 | * register a source device. Also pass it to unregister and write calls. |
114 | */ |
115 | struct stm_source_data { |
116 | const char *name; |
117 | struct stm_source_device *src; |
118 | unsigned int percpu; |
119 | unsigned int nr_chans; |
120 | int (*link)(struct stm_source_data *data); |
121 | void (*unlink)(struct stm_source_data *data); |
122 | }; |
123 | |
124 | int stm_source_register_device(struct device *parent, |
125 | struct stm_source_data *data); |
126 | void stm_source_unregister_device(struct stm_source_data *data); |
127 | |
128 | int notrace stm_source_write(struct stm_source_data *data, unsigned int chan, |
129 | const char *buf, size_t count); |
130 | |
131 | #endif /* _STM_H_ */ |
132 | |