1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
2 | /* |
3 | * soundbus generic definitions |
4 | * |
5 | * Copyright 2006 Johannes Berg <johannes@sipsolutions.net> |
6 | */ |
7 | #ifndef __SOUNDBUS_H |
8 | #define __SOUNDBUS_H |
9 | |
10 | #include <linux/platform_device.h> |
11 | #include <sound/pcm.h> |
12 | #include <linux/list.h> |
13 | |
14 | |
15 | /* When switching from master to slave or the other way around, |
16 | * you don't want to have the codec chip acting as clock source |
17 | * while the bus still is. |
18 | * More importantly, while switch from slave to master, you need |
19 | * to turn off the chip's master function first, but then there's |
20 | * no clock for a while and other chips might reset, so we notify |
21 | * their drivers after having switched. |
22 | * The constants here are codec-point of view, so when we switch |
23 | * the soundbus to master we tell the codec we're going to switch |
24 | * and give it CLOCK_SWITCH_PREPARE_SLAVE! |
25 | */ |
26 | enum clock_switch { |
27 | CLOCK_SWITCH_PREPARE_SLAVE, |
28 | CLOCK_SWITCH_PREPARE_MASTER, |
29 | CLOCK_SWITCH_SLAVE, |
30 | CLOCK_SWITCH_MASTER, |
31 | CLOCK_SWITCH_NOTIFY, |
32 | }; |
33 | |
34 | /* information on a transfer the codec can take */ |
35 | struct transfer_info { |
36 | u64 formats; /* SNDRV_PCM_FMTBIT_* */ |
37 | unsigned int rates; /* SNDRV_PCM_RATE_* */ |
38 | /* flags */ |
39 | u32 transfer_in:1, /* input = 1, output = 0 */ |
40 | must_be_clock_source:1; |
41 | /* for codecs to distinguish among their TIs */ |
42 | int tag; |
43 | }; |
44 | |
45 | struct codec_info_item { |
46 | struct codec_info *codec; |
47 | void *codec_data; |
48 | struct soundbus_dev *sdev; |
49 | /* internal, to be used by the soundbus provider */ |
50 | struct list_head list; |
51 | }; |
52 | |
53 | /* for prepare, where the codecs need to know |
54 | * what we're going to drive the bus with */ |
55 | struct bus_info { |
56 | /* see below */ |
57 | int sysclock_factor; |
58 | int bus_factor; |
59 | }; |
60 | |
61 | /* information on the codec itself, plus function pointers */ |
62 | struct codec_info { |
63 | /* the module this lives in */ |
64 | struct module *owner; |
65 | |
66 | /* supported transfer possibilities, array terminated by |
67 | * formats or rates being 0. */ |
68 | struct transfer_info *transfers; |
69 | |
70 | /* Master clock speed factor |
71 | * to be used (master clock speed = sysclock_factor * sampling freq) |
72 | * Unused if the soundbus provider has no such notion. |
73 | */ |
74 | int sysclock_factor; |
75 | |
76 | /* Bus factor, bus clock speed = bus_factor * sampling freq) |
77 | * Unused if the soundbus provider has no such notion. |
78 | */ |
79 | int bus_factor; |
80 | |
81 | /* operations */ |
82 | /* clock switching, see above */ |
83 | int (*switch_clock)(struct codec_info_item *cii, |
84 | enum clock_switch clock); |
85 | |
86 | /* called for each transfer_info when the user |
87 | * opens the pcm device to determine what the |
88 | * hardware can support at this point in time. |
89 | * That can depend on other user-switchable controls. |
90 | * Return 1 if usable, 0 if not. |
91 | * out points to another instance of a transfer_info |
92 | * which is initialised to the values in *ti, and |
93 | * it's format and rate values can be modified by |
94 | * the callback if it is necessary to further restrict |
95 | * the formats that can be used at the moment, for |
96 | * example when one codec has multiple logical codec |
97 | * info structs for multiple inputs. |
98 | */ |
99 | int (*usable)(struct codec_info_item *cii, |
100 | struct transfer_info *ti, |
101 | struct transfer_info *out); |
102 | |
103 | /* called when pcm stream is opened, probably not implemented |
104 | * most of the time since it isn't too useful */ |
105 | int (*open)(struct codec_info_item *cii, |
106 | struct snd_pcm_substream *substream); |
107 | |
108 | /* called when the pcm stream is closed, at this point |
109 | * the user choices can all be unlocked (see below) */ |
110 | int (*close)(struct codec_info_item *cii, |
111 | struct snd_pcm_substream *substream); |
112 | |
113 | /* if the codec must forbid some user choices because |
114 | * they are not valid with the substream/transfer info, |
115 | * it must do so here. Example: no digital output for |
116 | * incompatible framerate, say 8KHz, on Onyx. |
117 | * If the selected stuff in the substream is NOT |
118 | * compatible, you have to reject this call! */ |
119 | int (*prepare)(struct codec_info_item *cii, |
120 | struct bus_info *bi, |
121 | struct snd_pcm_substream *substream); |
122 | |
123 | /* start() is called before data is pushed to the codec. |
124 | * Note that start() must be atomic! */ |
125 | int (*start)(struct codec_info_item *cii, |
126 | struct snd_pcm_substream *substream); |
127 | |
128 | /* stop() is called after data is no longer pushed to the codec. |
129 | * Note that stop() must be atomic! */ |
130 | int (*stop)(struct codec_info_item *cii, |
131 | struct snd_pcm_substream *substream); |
132 | |
133 | int (*suspend)(struct codec_info_item *cii, pm_message_t state); |
134 | int (*resume)(struct codec_info_item *cii); |
135 | }; |
136 | |
137 | /* information on a soundbus device */ |
138 | struct soundbus_dev { |
139 | /* the bus it belongs to */ |
140 | struct list_head onbuslist; |
141 | |
142 | /* the of device it represents */ |
143 | struct platform_device ofdev; |
144 | |
145 | /* what modules go by */ |
146 | char modalias[32]; |
147 | |
148 | /* These fields must be before attach_codec can be called. |
149 | * They should be set by the owner of the alsa card object |
150 | * that is needed, and whoever sets them must make sure |
151 | * that they are unique within that alsa card object. */ |
152 | char *pcmname; |
153 | int pcmid; |
154 | |
155 | /* this is assigned by the soundbus provider in attach_codec */ |
156 | struct snd_pcm *pcm; |
157 | |
158 | /* operations */ |
159 | /* attach a codec to this soundbus, give the alsa |
160 | * card object the PCMs for this soundbus should be in. |
161 | * The 'data' pointer must be unique, it is used as the |
162 | * key for detach_codec(). */ |
163 | int (*attach_codec)(struct soundbus_dev *dev, struct snd_card *card, |
164 | struct codec_info *ci, void *data); |
165 | void (*detach_codec)(struct soundbus_dev *dev, void *data); |
166 | /* TODO: suspend/resume */ |
167 | |
168 | /* private for the soundbus provider */ |
169 | struct list_head codec_list; |
170 | u32 have_out:1, have_in:1; |
171 | }; |
172 | #define to_soundbus_device(d) container_of(d, struct soundbus_dev, ofdev.dev) |
173 | #define of_to_soundbus_device(d) container_of(d, struct soundbus_dev, ofdev) |
174 | |
175 | extern int soundbus_add_one(struct soundbus_dev *dev); |
176 | extern void soundbus_remove_one(struct soundbus_dev *dev); |
177 | |
178 | extern struct soundbus_dev *soundbus_dev_get(struct soundbus_dev *dev); |
179 | extern void soundbus_dev_put(struct soundbus_dev *dev); |
180 | |
181 | struct soundbus_driver { |
182 | char *name; |
183 | struct module *owner; |
184 | |
185 | /* we don't implement any matching at all */ |
186 | |
187 | int (*probe)(struct soundbus_dev* dev); |
188 | void (*remove)(struct soundbus_dev *dev); |
189 | |
190 | int (*shutdown)(struct soundbus_dev* dev); |
191 | |
192 | struct device_driver driver; |
193 | }; |
194 | #define to_soundbus_driver(drv) container_of(drv,struct soundbus_driver, driver) |
195 | |
196 | extern int soundbus_register_driver(struct soundbus_driver *drv); |
197 | extern void soundbus_unregister_driver(struct soundbus_driver *drv); |
198 | |
199 | extern struct attribute *soundbus_dev_attrs[]; |
200 | |
201 | #endif /* __SOUNDBUS_H */ |
202 | |