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

source code of linux/include/sound/ump.h