1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 /*
3 * Universal MIDI Packet (UMP) Support
4 */
5 #ifndef __SOUND_UMP_H
6 #define __SOUND_UMP_H
7
8 #include <sound/rawmidi.h>
9
10 struct snd_ump_endpoint;
11 struct snd_ump_block;
12 struct snd_ump_ops;
13 struct ump_cvt_to_ump;
14 struct snd_seq_ump_ops;
15
16 struct snd_ump_group {
17 int group; /* group index (0-based) */
18 unsigned int dir_bits; /* directions */
19 bool active; /* activeness */
20 bool valid; /* valid group (referred by blocks) */
21 char name[64]; /* group name */
22 };
23
24 struct snd_ump_endpoint {
25 struct snd_rawmidi core; /* raw UMP access */
26
27 struct snd_ump_endpoint_info info;
28
29 const struct snd_ump_ops *ops; /* UMP ops set by the driver */
30 struct snd_rawmidi_substream *substreams[2]; /* opened substreams */
31
32 void *private_data;
33 void (*private_free)(struct snd_ump_endpoint *ump);
34
35 /* UMP Stream message processing */
36 u32 stream_wait_for; /* expected stream message status */
37 bool stream_finished; /* set when message has been processed */
38 bool parsed; /* UMP / FB parse finished? */
39 bool no_process_stream; /* suppress UMP stream messages handling */
40 wait_queue_head_t stream_wait;
41 struct snd_rawmidi_file stream_rfile;
42
43 struct list_head block_list; /* list of snd_ump_block objects */
44
45 /* intermediate buffer for UMP input */
46 u32 input_buf[4];
47 int input_buf_head;
48 int input_pending;
49
50 struct mutex open_mutex;
51
52 struct snd_ump_group groups[SNDRV_UMP_MAX_GROUPS]; /* table of groups */
53
54 #if IS_ENABLED(CONFIG_SND_UMP_LEGACY_RAWMIDI)
55 spinlock_t legacy_locks[2];
56 struct snd_rawmidi *legacy_rmidi;
57 struct snd_rawmidi_substream *legacy_substreams[2][SNDRV_UMP_MAX_GROUPS];
58 unsigned char legacy_mapping[SNDRV_UMP_MAX_GROUPS];
59
60 /* for legacy output; need to open the actual substream unlike input */
61 int legacy_out_opens;
62 struct snd_rawmidi_file legacy_out_rfile;
63 struct ump_cvt_to_ump *out_cvts;
64 #endif
65
66 #if IS_ENABLED(CONFIG_SND_SEQUENCER)
67 struct snd_seq_device *seq_dev;
68 const struct snd_seq_ump_ops *seq_ops;
69 void *seq_client;
70 #endif
71 };
72
73 /* ops filled by UMP drivers */
74 struct snd_ump_ops {
75 int (*open)(struct snd_ump_endpoint *ump, int dir);
76 void (*close)(struct snd_ump_endpoint *ump, int dir);
77 void (*trigger)(struct snd_ump_endpoint *ump, int dir, int up);
78 void (*drain)(struct snd_ump_endpoint *ump, int dir);
79 };
80
81 /* ops filled by sequencer binding */
82 struct snd_seq_ump_ops {
83 void (*input_receive)(struct snd_ump_endpoint *ump,
84 const u32 *data, int words);
85 int (*notify_fb_change)(struct snd_ump_endpoint *ump,
86 struct snd_ump_block *fb);
87 int (*switch_protocol)(struct snd_ump_endpoint *ump);
88 };
89
90 struct snd_ump_block {
91 struct snd_ump_block_info info;
92 struct snd_ump_endpoint *ump;
93
94 void *private_data;
95 void (*private_free)(struct snd_ump_block *blk);
96
97 struct list_head list;
98 };
99
100 #define rawmidi_to_ump(rmidi) container_of(rmidi, struct snd_ump_endpoint, core)
101
102 int snd_ump_endpoint_new(struct snd_card *card, char *id, int device,
103 int output, int input,
104 struct snd_ump_endpoint **ump_ret);
105 int snd_ump_parse_endpoint(struct snd_ump_endpoint *ump);
106 int snd_ump_block_new(struct snd_ump_endpoint *ump, unsigned int blk,
107 unsigned int direction, unsigned int first_group,
108 unsigned int num_groups, struct snd_ump_block **blk_ret);
109 int snd_ump_receive(struct snd_ump_endpoint *ump, const u32 *buffer, int count);
110 int snd_ump_transmit(struct snd_ump_endpoint *ump, u32 *buffer, int count);
111
112 #if IS_ENABLED(CONFIG_SND_UMP_LEGACY_RAWMIDI)
113 int snd_ump_attach_legacy_rawmidi(struct snd_ump_endpoint *ump,
114 char *id, int device);
115 #else
snd_ump_attach_legacy_rawmidi(struct snd_ump_endpoint * ump,char * id,int device)116 static inline int snd_ump_attach_legacy_rawmidi(struct snd_ump_endpoint *ump,
117 char *id, int device)
118 {
119 return 0;
120 }
121 #endif
122
123 int snd_ump_receive_ump_val(struct snd_ump_endpoint *ump, u32 val);
124 int snd_ump_switch_protocol(struct snd_ump_endpoint *ump, unsigned int protocol);
125 void snd_ump_update_group_attrs(struct snd_ump_endpoint *ump);
126
127 /*
128 * Some definitions for UMP
129 */
130
131 /* MIDI 2.0 Message Type */
132 enum {
133 UMP_MSG_TYPE_UTILITY = 0x00,
134 UMP_MSG_TYPE_SYSTEM = 0x01,
135 UMP_MSG_TYPE_MIDI1_CHANNEL_VOICE = 0x02,
136 UMP_MSG_TYPE_DATA = 0x03,
137 UMP_MSG_TYPE_MIDI2_CHANNEL_VOICE = 0x04,
138 UMP_MSG_TYPE_EXTENDED_DATA = 0x05,
139 UMP_MSG_TYPE_FLEX_DATA = 0x0d,
140 UMP_MSG_TYPE_STREAM = 0x0f,
141 };
142
143 /* MIDI 2.0 SysEx / Data Status; same values for both 7-bit and 8-bit SysEx */
144 enum {
145 UMP_SYSEX_STATUS_SINGLE = 0,
146 UMP_SYSEX_STATUS_START = 1,
147 UMP_SYSEX_STATUS_CONTINUE = 2,
148 UMP_SYSEX_STATUS_END = 3,
149 };
150
151 /* UMP Utility Type Status (type 0x0) */
152 enum {
153 UMP_UTILITY_MSG_STATUS_NOOP = 0x00,
154 UMP_UTILITY_MSG_STATUS_JR_CLOCK = 0x01,
155 UMP_UTILITY_MSG_STATUS_JR_TSTAMP = 0x02,
156 UMP_UTILITY_MSG_STATUS_DCTPQ = 0x03,
157 UMP_UTILITY_MSG_STATUS_DC = 0x04,
158 };
159
160 /* UMP Stream Message Status (type 0xf) */
161 enum {
162 UMP_STREAM_MSG_STATUS_EP_DISCOVERY = 0x00,
163 UMP_STREAM_MSG_STATUS_EP_INFO = 0x01,
164 UMP_STREAM_MSG_STATUS_DEVICE_INFO = 0x02,
165 UMP_STREAM_MSG_STATUS_EP_NAME = 0x03,
166 UMP_STREAM_MSG_STATUS_PRODUCT_ID = 0x04,
167 UMP_STREAM_MSG_STATUS_STREAM_CFG_REQUEST = 0x05,
168 UMP_STREAM_MSG_STATUS_STREAM_CFG = 0x06,
169 UMP_STREAM_MSG_STATUS_FB_DISCOVERY = 0x10,
170 UMP_STREAM_MSG_STATUS_FB_INFO = 0x11,
171 UMP_STREAM_MSG_STATUS_FB_NAME = 0x12,
172 UMP_STREAM_MSG_STATUS_START_CLIP = 0x20,
173 UMP_STREAM_MSG_STATUS_END_CLIP = 0x21,
174 };
175
176 /* UMP Endpoint Discovery filter bitmap */
177 enum {
178 UMP_STREAM_MSG_REQUEST_EP_INFO = (1U << 0),
179 UMP_STREAM_MSG_REQUEST_DEVICE_INFO = (1U << 1),
180 UMP_STREAM_MSG_REQUEST_EP_NAME = (1U << 2),
181 UMP_STREAM_MSG_REQUEST_PRODUCT_ID = (1U << 3),
182 UMP_STREAM_MSG_REQUEST_STREAM_CFG = (1U << 4),
183 };
184
185 /* UMP Function Block Discovery filter bitmap */
186 enum {
187 UMP_STREAM_MSG_REQUEST_FB_INFO = (1U << 0),
188 UMP_STREAM_MSG_REQUEST_FB_NAME = (1U << 1),
189 };
190
191 /* UMP Endpoint Info capability bits (used for protocol request/notify, too) */
192 enum {
193 UMP_STREAM_MSG_EP_INFO_CAP_TXJR = (1U << 0), /* Sending JRTS */
194 UMP_STREAM_MSG_EP_INFO_CAP_RXJR = (1U << 1), /* Receiving JRTS */
195 UMP_STREAM_MSG_EP_INFO_CAP_MIDI1 = (1U << 8), /* MIDI 1.0 */
196 UMP_STREAM_MSG_EP_INFO_CAP_MIDI2 = (1U << 9), /* MIDI 2.0 */
197 };
198
199 /* UMP EP / FB name string format; same as SysEx string handling */
200 enum {
201 UMP_STREAM_MSG_FORMAT_SINGLE = 0,
202 UMP_STREAM_MSG_FORMAT_START = 1,
203 UMP_STREAM_MSG_FORMAT_CONTINUE = 2,
204 UMP_STREAM_MSG_FORMAT_END = 3,
205 };
206
207 /*
208 * Helpers for retrieving / filling bits from UMP
209 */
210 /* get the message type (4bit) from a UMP packet (header) */
ump_message_type(u32 data)211 static inline unsigned char ump_message_type(u32 data)
212 {
213 return data >> 28;
214 }
215
216 /* get the group number (0-based, 4bit) from a UMP packet (header) */
ump_message_group(u32 data)217 static inline unsigned char ump_message_group(u32 data)
218 {
219 return (data >> 24) & 0x0f;
220 }
221
222 /* get the MIDI status code (4bit) from a UMP packet (header) */
ump_message_status_code(u32 data)223 static inline unsigned char ump_message_status_code(u32 data)
224 {
225 return (data >> 20) & 0x0f;
226 }
227
228 /* get the MIDI channel number (0-based, 4bit) from a UMP packet (header) */
ump_message_channel(u32 data)229 static inline unsigned char ump_message_channel(u32 data)
230 {
231 return (data >> 16) & 0x0f;
232 }
233
234 /* get the MIDI status + channel combo byte (8bit) from a UMP packet (header) */
ump_message_status_channel(u32 data)235 static inline unsigned char ump_message_status_channel(u32 data)
236 {
237 return (data >> 16) & 0xff;
238 }
239
240 /* compose a UMP packet (header) from type, group and status values */
ump_compose(unsigned char type,unsigned char group,unsigned char status,unsigned char channel)241 static inline u32 ump_compose(unsigned char type, unsigned char group,
242 unsigned char status, unsigned char channel)
243 {
244 return ((u32)type << 28) | ((u32)group << 24) | ((u32)status << 20) |
245 ((u32)channel << 16);
246 }
247
248 /* get SysEx message status (for both 7 and 8bits) from a UMP packet (header) */
ump_sysex_message_status(u32 data)249 static inline unsigned char ump_sysex_message_status(u32 data)
250 {
251 return (data >> 20) & 0xf;
252 }
253
254 /* get SysEx message length (for both 7 and 8bits) from a UMP packet (header) */
ump_sysex_message_length(u32 data)255 static inline unsigned char ump_sysex_message_length(u32 data)
256 {
257 return (data >> 16) & 0xf;
258 }
259
260 /* For Stream Messages */
ump_stream_message_format(u32 data)261 static inline unsigned char ump_stream_message_format(u32 data)
262 {
263 return (data >> 26) & 0x03;
264 }
265
ump_stream_message_status(u32 data)266 static inline unsigned int ump_stream_message_status(u32 data)
267 {
268 return (data >> 16) & 0x3ff;
269 }
270
ump_stream_compose(unsigned char status,unsigned short form)271 static inline u32 ump_stream_compose(unsigned char status, unsigned short form)
272 {
273 return (UMP_MSG_TYPE_STREAM << 28) | ((u32)form << 26) |
274 ((u32)status << 16);
275 }
276
277 #define ump_is_groupless_msg(type) \
278 ((type) == UMP_MSG_TYPE_UTILITY || (type) == UMP_MSG_TYPE_STREAM)
279
280 #endif /* __SOUND_UMP_H */
281