summaryrefslogtreecommitdiffstats
path: root/desc-defs.h
diff options
context:
space:
mode:
Diffstat (limited to 'desc-defs.h')
-rw-r--r--desc-defs.h182
1 files changed, 182 insertions, 0 deletions
diff --git a/desc-defs.h b/desc-defs.h
new file mode 100644
index 0000000..27891bc
--- /dev/null
+++ b/desc-defs.h
@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * USB descriptor definitions
+ *
+ * Copyright (C) 2017-2018 Michael Drake <michael.drake@codethink.co.uk>
+ */
+
+#ifndef _DESC_DEFS_H
+#define _DESC_DEFS_H
+
+/* ---------------------------------------------------------------------- */
+
+/**
+ * Descriptor field value type.
+ *
+ * Note that there are more types here than exist in the descriptor definitions
+ * in the specifications. This is because the type here is used to do `lsusb`
+ * specific rendering of certain fields.
+ *
+ * Note that the use of certain types mandates the setting of various entries
+ * in the type-specific anonymous union in `struct desc`.
+ */
+enum desc_type {
+ DESC_CONSTANT, /** Plain numerical value; no annotation. */
+ DESC_NUMBER, /** Plain numerical value; no annotation. */
+ DESC_NUMBER_POSTFIX, /**< Number with a postfix string. */
+ DESC_BITMAP, /**< Plain hex rendered value; no annotation. */
+ DESC_BCD, /**< Binary coded decimal */
+ DESC_BMCONTROL_1, /**< UAC1 style bmControl field */
+ DESC_BMCONTROL_2, /**< UAC2/UAC3 style bmControl field */
+ DESC_STR_DESC_INDEX, /**< String index. */
+ DESC_CS_STR_DESC_ID, /**< UAC3 style class-specific string request. */
+ DESC_TERMINAL_STR, /**< Audio terminal string. */
+ DESC_BITMAP_STRINGS, /**< Bitfield with string per bit. */
+ DESC_NUMBER_STRINGS, /**< Use for enum-style value to string. */
+ DESC_EXTENSION, /**< Various possible descriptor extensions. */
+ DESC_SNOWFLAKE, /**< Value with custom annotation callback function. */
+};
+
+/**
+ * Callback function for the DESC_SNOWFLAKE descriptor field value type.
+ *
+ * This is used when some special rendering of the value is required, which
+ * is specific to the field in question, so no generic type's rendering is
+ * suitable.
+ *
+ * The core descriptor dumping code will have already dumped the numerical
+ * value for the field, but not the trailing newline character. It is up
+ * to the callback function to ensure it always finishes by writing a '\n'
+ * character to stdout.
+ *
+ * \param[in] value The value to dump a human-readable representation of.
+ * \param[in] indent The current indent level.
+ */
+typedef void (*desc_snowflake_dump_fn)(
+ unsigned long long value,
+ unsigned int indent);
+
+
+/**
+ * Descriptor field definition.
+ *
+ * Whole descriptors can be defined as NULL terminated arrays of these
+ * structures.
+ */
+struct desc {
+ const char *field; /**< Field's name */
+ unsigned int size; /**< Byte size of field, if (size_field == NULL) */
+ const char *size_field; /**< Name of field specifying field size. */
+ enum desc_type type; /**< Field's value type. */
+
+ /** Anonymous union containing type-specific data. */
+ union {
+ /**
+ * Corresponds to types DESC_BMCONTROL_1 and DESC_BMCONTROL_2.
+ *
+ * Must be a NULL terminated array of '\0' terminated strings.
+ */
+ const char * const *bmcontrol;
+ /** Corresponds to type DESC_BITMAP_STRINGS */
+ struct {
+ /** Must contain '\0' terminated strings. */
+ const char * const *strings;
+ /** Number of strings in strings array. */
+ unsigned int count;
+ } bitmap_strings;
+ /**
+ * Corresponds to type DESC_NUMBER_STRINGS.
+ *
+ * Must be a NULL terminated array of '\0' terminated strings.
+ */
+ const char * const *number_strings;
+ /**
+ * Corresponds to type DESC_NUMBER_POSTFIX.
+ *
+ * Must be a '\0' terminated string.
+ */
+ const char *number_postfix;
+ /**
+ * Corresponds to type DESC_EXTENSION.
+ *
+ * This allows the value of this field to be processed by
+ * another descriptor definition. The definition used to
+ * process the value of this field can be controlled by
+ * the value of another field.
+ */
+ struct {
+ /**
+ * Name of field specifying descriptor type to select.
+ */
+ const char *type_field;
+ /**
+ * Array of descriptor definitions and their
+ * associated types values. Array must be terminated
+ * by entry with NULL `desc` member.
+ */
+ const struct desc_ext {
+ /**
+ * Array of descriptor field definitions.
+ * Terminated by entry with NULL `field` member.
+ */
+ const struct desc *desc;
+ /**
+ * Type value for this descriptor definition.
+ * If it matches the type read from the
+ * field `type_field`, then this descriptor
+ * definition will be used to decode this value.
+ */
+ unsigned int type;
+ } *d;
+ } extension;
+ /**
+ * Corresponds to type DESC_SNOWFLAKE.
+ *
+ * Callback function called to annotate snowflake value type.
+ */
+ desc_snowflake_dump_fn snowflake;
+ };
+
+ /** Grouping of array-specific fields. */
+ struct {
+ bool array; /**< True if entry is an array. */
+ bool bits; /**< True if array length is specified in bits */
+ /** Name of field specifying the array entry count. */
+ const char *length_field1;
+ /** Name of field specifying multiplier for array entry count. */
+ const char *length_field2;
+ } array;
+};
+
+/* ---------------------------------------------------------------------- */
+
+/* Undefined descriptor */
+extern const struct desc desc_undefined[];
+
+/* Audio Control (AC) descriptor definitions */
+extern const struct desc * const desc_audio_ac_header[3];
+extern const struct desc * const desc_audio_ac_effect_unit[3];
+extern const struct desc * const desc_audio_ac_input_terminal[3];
+extern const struct desc * const desc_audio_ac_output_terminal[3];
+extern const struct desc * const desc_audio_ac_extended_terminal[3];
+extern const struct desc * const desc_audio_ac_power_domain[3];
+extern const struct desc * const desc_audio_ac_mixer_unit[3];
+extern const struct desc * const desc_audio_ac_selector_unit[3];
+extern const struct desc * const desc_audio_ac_processing_unit[3];
+extern const struct desc * const desc_audio_ac_feature_unit[3];
+extern const struct desc * const desc_audio_ac_extension_unit[3];
+extern const struct desc * const desc_audio_ac_clock_source[3];
+extern const struct desc * const desc_audio_ac_clock_selector[3];
+extern const struct desc * const desc_audio_ac_clock_multiplier[3];
+extern const struct desc * const desc_audio_ac_sample_rate_converter[3];
+
+/* Audio Streaming (AS) descriptor definitions */
+extern const struct desc * const desc_audio_as_interface[3];
+extern const struct desc * const desc_audio_as_isochronous_audio_data_endpoint[3];
+
+/* Device Capability (DC) descriptor definitions */
+extern const struct desc desc_usb3_dc_configuration_summary[];
+
+/* ---------------------------------------------------------------------- */
+
+#endif /* _DESC_DEFS_H */