include/sound/ump.h

   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         bool is_midi1;                  /* belongs to a MIDI1 FB */
  22         char name[64];                  /* group name */
  23 };
  24
  25 struct 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 */
  75 struct 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 */
  83 struct 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
  92 struct 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
 104 int snd_ump_endpoint_new(struct snd_card *card, char *id, int device,
 105                          int output, int input,
 106                          struct snd_ump_endpoint **ump_ret);
 107 int snd_ump_parse_endpoint(struct snd_ump_endpoint *ump);
 108 int 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);
 111 int snd_ump_receive(struct snd_ump_endpoint *ump, const u32 *buffer, int count);
 112 int snd_ump_transmit(struct snd_ump_endpoint *ump, u32 *buffer, int count);
 113
 114 #if IS_ENABLED(CONFIG_SND_UMP_LEGACY_RAWMIDI)
 115 int snd_ump_attach_legacy_rawmidi(struct snd_ump_endpoint *ump,
 116                                   char *id, int device);
 117 #else
 118 static 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
 125 int snd_ump_receive_ump_val(struct snd_ump_endpoint *ump, u32 val);
 126 int snd_ump_switch_protocol(struct snd_ump_endpoint *ump, unsigned int protocol);
 127 void 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 */
 134 enum {
 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 */
 146 enum {
 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) */
 154 enum {
 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) */
 163 enum {
 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 */
 179 enum {
 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 */
 188 enum {
 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) */
 194 enum {
 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 */
 202 enum {
 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) */
 213 static 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) */
 219 static 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) */
 225 static 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) */
 231 static 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) */
 237 static 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 */
 243 static 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) */
 251 static 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) */
 257 static inline unsigned char ump_sysex_message_length(u32 data)
 258 {
 259         return (data >> 16) & 0xf;
 260 }
 261
 262 /* For Stream Messages */
 263 static inline unsigned char ump_stream_message_format(u32 data)
 264 {
 265         return (data >> 26) & 0x03;
 266 }
 267
 268 static inline unsigned int ump_stream_message_status(u32 data)
 269 {
 270         return (data >> 16) & 0x3ff;
 271 }
 272
 273 static 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 */