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