[pulseaudio-commits] [Git][pulseaudio/pulseaudio][master] 4 commits: Improve the port available_group and type documentation
Tanu Kaskinen
gitlab at gitlab.freedesktop.org
Mon Aug 10 18:05:39 UTC 2020
Tanu Kaskinen pushed to branch master at PulseAudio / pulseaudio
Commits:
0ce30086 by Tanu Kaskinen at 2020-08-10T20:54:21+03:00
Improve the port available_group and type documentation
- - - - -
1b44b44c by Tanu Kaskinen at 2020-08-10T20:54:21+03:00
alsa-mixer: Fix mapping_group_available() logic
There were three bugs:
1) j->state_plugged was set to PA_AVAILABLE_UNKNOWN too early. It must
be set only after we have found that the jack is shared by two ports.
The result of setting it too early was that no jack ever could have
the PA_AVAILABLE_YES status.
2) The inner jack loop iterated through p->jacks instead of p2->jacks,
so the code didn't compare jacks between two ports at all. As a result
all ports were put in the same availability group.
3) The inner jack loop checked j->state_plugged instead of
j2->state_plugged. The result was that the speaker port, which uses the
Headphone jack to toggle between unknown and unavailable, was put in the
same group with the headphone port.
- - - - -
af42b3eb by Tanu Kaskinen at 2020-08-10T20:54:21+03:00
Rename "available group" to "availability group"
"Availability group" is more clear about what the field is about.
Credits to Arun Raghavan for coming up with the better name.
- - - - -
a863b579 by Tanu Kaskinen at 2020-08-10T20:56:43+03:00
alsa-mixer: Fix indentation
- - - - -
13 changed files:
- PROTOCOL
- src/modules/alsa/alsa-mixer.c
- src/modules/alsa/alsa-mixer.h
- src/modules/alsa/alsa-ucm.c
- src/modules/alsa/mixer/paths/analog-output.conf.common
- src/modules/module-tunnel.c
- src/pulse/def.h
- src/pulse/introspect.c
- src/pulse/introspect.h
- src/pulsecore/device-port.c
- src/pulsecore/device-port.h
- src/pulsecore/protocol-native.c
- src/utils/pactl.c
Changes:
=====================================
PROTOCOL
=====================================
@@ -429,7 +429,11 @@ Added two values to the pa_encoding_t enum:
## v34, implemented by >= 14.0
-Added available_group and type fields to the device port info.
+New fields in the port introspection data (duplicated for all port types:
+sink, source and card ports):
+
+ string availability_group
+ uint32 type
#### If you just changed the protocol, read this
## module-tunnel depends on the sink/source/sink-input/source-input protocol
=====================================
src/modules/alsa/alsa-mixer.c
=====================================
@@ -758,7 +758,7 @@ void pa_alsa_path_free(pa_alsa_path *p) {
}
pa_proplist_free(p->proplist);
- pa_xfree(p->available_group);
+ pa_xfree(p->availability_group);
pa_xfree(p->name);
pa_xfree(p->description);
pa_xfree(p->description_key);
@@ -4276,7 +4276,7 @@ fail:
}
/* the logic is simple: if we see the jack in multiple paths */
-/* assign all those jacks to one available_group */
+/* assign all those jacks to one availability_group */
static void mapping_group_available(pa_hashmap *paths)
{
void *state, *state2;
@@ -4288,34 +4288,34 @@ static void mapping_group_available(pa_hashmap *paths)
const char *found = NULL;
bool has_control = false;
PA_LLIST_FOREACH(j, p->jacks) {
- if (!j->has_control || j->state_plugged == PA_AVAILABLE_NO)
- continue;
- has_control = true;
- j->state_plugged = PA_AVAILABLE_UNKNOWN;
- PA_HASHMAP_FOREACH(p2, paths, state2) {
- if (p2 == p)
+ if (!j->has_control || j->state_plugged == PA_AVAILABLE_NO)
+ continue;
+ has_control = true;
+ PA_HASHMAP_FOREACH(p2, paths, state2) {
+ if (p2 == p)
break;
- PA_LLIST_FOREACH(j2, p->jacks) {
- if (!j2->has_control || j->state_plugged == PA_AVAILABLE_NO)
- continue;
- if (pa_streq(j->name, j2->name)) {
- j2->state_plugged = PA_AVAILABLE_UNKNOWN;
- found = p2->available_group;
- break;
- }
- }
- }
- if (found)
- break;
- }
- if (!has_control)
- continue;
- if (!found) {
- p->available_group = pa_sprintf_malloc("Legacy %d", num);
- } else {
- p->available_group = pa_xstrdup(found);
- }
- if (!found)
+ PA_LLIST_FOREACH(j2, p2->jacks) {
+ if (!j2->has_control || j2->state_plugged == PA_AVAILABLE_NO)
+ continue;
+ if (pa_streq(j->name, j2->name)) {
+ j->state_plugged = PA_AVAILABLE_UNKNOWN;
+ j2->state_plugged = PA_AVAILABLE_UNKNOWN;
+ found = p2->availability_group;
+ break;
+ }
+ }
+ }
+ if (found)
+ break;
+ }
+ if (!has_control)
+ continue;
+ if (!found) {
+ p->availability_group = pa_sprintf_malloc("Legacy %d", num);
+ } else {
+ p->availability_group = pa_xstrdup(found);
+ }
+ if (!found)
num++;
}
}
@@ -5173,7 +5173,7 @@ static pa_device_port* device_port_alsa_init(pa_hashmap *ports, /* card ports */
pa_device_port_new_data_set_description(&port_data, description);
pa_device_port_new_data_set_direction(&port_data, path->direction == PA_ALSA_DIRECTION_OUTPUT ? PA_DIRECTION_OUTPUT : PA_DIRECTION_INPUT);
pa_device_port_new_data_set_type(&port_data, path->device_port_type);
- pa_device_port_new_data_set_available_group(&port_data, path->available_group);
+ pa_device_port_new_data_set_availability_group(&port_data, path->availability_group);
p = pa_device_port_new(core, &port_data, sizeof(pa_alsa_port_data));
pa_device_port_new_data_done(&port_data);
=====================================
src/modules/alsa/alsa-mixer.h
=====================================
@@ -211,7 +211,7 @@ struct pa_alsa_path {
char *name;
char *description_key;
char *description;
- char *available_group;
+ char *availability_group;
pa_device_port_type_t device_port_type;
unsigned priority;
bool autodetect_eld_device;
=====================================
src/modules/alsa/alsa-ucm.c
=====================================
@@ -1065,7 +1065,7 @@ static void ucm_add_port_combination(
pa_device_port_new_data_set_type(&port_data, type);
pa_device_port_new_data_set_direction(&port_data, is_sink ? PA_DIRECTION_OUTPUT : PA_DIRECTION_INPUT);
if (jack)
- pa_device_port_new_data_set_available_group(&port_data, jack->name);
+ pa_device_port_new_data_set_availability_group(&port_data, jack->name);
port = pa_device_port_new(core, &port_data, sizeof(pa_alsa_ucm_port_data));
pa_device_port_new_data_done(&port_data);
=====================================
src/modules/alsa/mixer/paths/analog-output.conf.common
=====================================
@@ -53,6 +53,8 @@
; [General]
+; type = ... # The device type. It's highly recommended to set a type for every path.
+; # See parse_type() in alsa-mixer.c for supported values.
; priority = ... # Priority for this path
; description-key = ... # The path description is looked up from a table in path_verify() in
; # src/modules/alsa/alsa-mixer.c. By default the path name (i.e. the file name
=====================================
src/modules/module-tunnel.c
=====================================
@@ -1040,7 +1040,7 @@ static int read_ports(struct userdata *u, pa_tagstruct *t) {
return -PA_ERR_PROTOCOL;
}
if (u->version >= 34 &&
- (pa_tagstruct_gets(t, &s) < 0 || /* available_group */
+ (pa_tagstruct_gets(t, &s) < 0 || /* availability group */
pa_tagstruct_getu32(t, &priority) < 0)) { /* device port type */
pa_log("Parse failure");
return -PA_ERR_PROTOCOL;
=====================================
src/pulse/def.h
=====================================
@@ -1070,7 +1070,9 @@ typedef enum pa_port_available {
/** \endcond */
#endif
-/** Port type. \since 14.0 */
+/** Port type. New types can be added in the future, so applications should
+ * gracefully handle situations where a type identifier doesn't match any item
+ * in this enumeration. \since 14.0 */
typedef enum pa_device_port_type {
PA_DEVICE_PORT_TYPE_UNKNOWN = 0,
PA_DEVICE_PORT_TYPE_AUX = 1,
=====================================
src/pulse/introspect.c
=====================================
@@ -219,10 +219,10 @@ static void context_get_sink_info_callback(pa_pdispatch *pd, uint32_t command, u
goto fail;
i.ports[j]->available = av;
}
- i.ports[j]->available_group = NULL;
+ i.ports[j]->availability_group = NULL;
i.ports[j]->type = PA_DEVICE_PORT_TYPE_UNKNOWN;
if (o->context->version >= 34) {
- if (pa_tagstruct_gets(t, &i.ports[j]->available_group) < 0 ||
+ if (pa_tagstruct_gets(t, &i.ports[j]->availability_group) < 0 ||
pa_tagstruct_getu32(t, &i.ports[j]->type) < 0)
goto fail;
}
@@ -499,10 +499,10 @@ static void context_get_source_info_callback(pa_pdispatch *pd, uint32_t command,
goto fail;
i.ports[j]->available = av;
}
- i.ports[j]->available_group = NULL;
+ i.ports[j]->availability_group = NULL;
i.ports[j]->type = PA_DEVICE_PORT_TYPE_UNKNOWN;
if (o->context->version >= 34) {
- if (pa_tagstruct_gets(t, &i.ports[j]->available_group) < 0 ||
+ if (pa_tagstruct_gets(t, &i.ports[j]->availability_group) < 0 ||
pa_tagstruct_getu32(t, &i.ports[j]->type))
goto fail;
}
@@ -879,11 +879,11 @@ static int fill_card_port_info(pa_context *context, pa_tagstruct* t, pa_card_inf
port->type = PA_DEVICE_PORT_TYPE_UNKNOWN;
if (context->version >= 34) {
- if (pa_tagstruct_gets(t, &port->available_group) < 0 ||
+ if (pa_tagstruct_gets(t, &port->availability_group) < 0 ||
pa_tagstruct_getu32(t, &port->type) < 0)
return -PA_ERR_PROTOCOL;
} else
- port->available_group = NULL;
+ port->availability_group = NULL;
}
return 0;
=====================================
src/pulse/introspect.h
=====================================
@@ -229,8 +229,31 @@ typedef struct pa_sink_port_info {
const char *description; /**< Description of this port */
uint32_t priority; /**< The higher this value is, the more useful this port is as a default. */
int available; /**< A flags (see #pa_port_available), indicating availability status of this port. \since 2.0 */
- const char *available_group; /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
- uint32_t type; /**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
+ const char *availability_group; /**< An indentifier for the group of ports that share their availability status with
+ * each other. This is meant especially for handling cases where one 3.5 mm connector
+ * is used for headphones, headsets and microphones, and the hardware can only tell
+ * that something was plugged in but not what exactly. In this situation the ports for
+ * all those devices share their availability status, and PulseAudio can't tell which
+ * one is actually plugged in, and some application may ask the user what was plugged
+ * in. Such applications should get a list of all card ports and compare their
+ * `availability_group` fields. Ports that have the same group are those that need
+ * input from the user to determine which device was plugged in. The application should
+ * then activate the user-chosen port.
+ *
+ * May be NULL, in which case the port is not part of any availability group (which is
+ * the same as having a group with only one member).
+ *
+ * The group identifier must be treated as an opaque identifier. The string may look
+ * like an ALSA control name, but applications must not assume any such relationship.
+ * The group naming scheme can change without a warning.
+ *
+ * Since one group can include both input and output ports, the grouping should be done
+ * using pa_card_port_info instead of pa_sink_port_info, but this field is duplicated
+ * also in pa_sink_port_info (and pa_source_port_info) in case someone finds that
+ * convenient.
+ *
+ * \since 14.0 */
+ uint32_t type; /**< Port type, see #pa_device_port_type. \since 14.0 */
} pa_sink_port_info;
/** Stores information about sinks. Please note that this structure
@@ -311,8 +334,31 @@ typedef struct pa_source_port_info {
const char *description; /**< Description of this port */
uint32_t priority; /**< The higher this value is, the more useful this port is as a default. */
int available; /**< A flags (see #pa_port_available), indicating availability status of this port. \since 2.0 */
- const char *available_group; /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
- uint32_t type; /**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
+ const char *availability_group; /**< An indentifier for the group of ports that share their availability status with
+ * each other. This is meant especially for handling cases where one 3.5 mm connector
+ * is used for headphones, headsets and microphones, and the hardware can only tell
+ * that something was plugged in but not what exactly. In this situation the ports for
+ * all those devices share their availability status, and PulseAudio can't tell which
+ * one is actually plugged in, and some application may ask the user what was plugged
+ * in. Such applications should get a list of all card ports and compare their
+ * `availability_group` fields. Ports that have the same group are those that need
+ * input from the user to determine which device was plugged in. The application should
+ * then activate the user-chosen port.
+ *
+ * May be NULL, in which case the port is not part of any availability group (which is
+ * the same as having a group with only one member).
+ *
+ * The group identifier must be treated as an opaque identifier. The string may look
+ * like an ALSA control name, but applications must not assume any such relationship.
+ * The group naming scheme can change without a warning.
+ *
+ * Since one group can include both input and output ports, the grouping should be done
+ * using pa_card_port_info instead of pa_source_port_info, but this field is duplicated
+ * also in pa_source_port_info (and pa_sink_port_info) in case someone finds that
+ * convenient.
+ *
+ * \since 14.0 */
+ uint32_t type; /**< Port type, see #pa_device_port_type. \since 14.0 */
} pa_source_port_info;
/** Stores information about sources. Please note that this structure
@@ -513,8 +559,26 @@ typedef struct pa_card_port_info {
pa_proplist *proplist; /**< Property list */
int64_t latency_offset; /**< Latency offset of the port that gets added to the sink/source latency when the port is active. \since 3.0 */
pa_card_profile_info2** profiles2; /**< Array of pointers to available profiles, or NULL. Array is terminated by an entry set to NULL. \since 5.0 */
- const char *available_group; /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
- uint32_t type; /**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
+ const char *availability_group; /**< An indentifier for the group of ports that share their availability status with
+ * each other. This is meant especially for handling cases where one 3.5 mm connector
+ * is used for headphones, headsets and microphones, and the hardware can only tell
+ * that something was plugged in but not what exactly. In this situation the ports for
+ * all those devices share their availability status, and PulseAudio can't tell which
+ * one is actually plugged in, and some application may ask the user what was plugged
+ * in. Such applications should get a list of all card ports and compare their
+ * `availability_group` fields. Ports that have the same group are those that need
+ * input from the user to determine which device was plugged in. The application should
+ * then activate the user-chosen port.
+ *
+ * May be NULL, in which case the port is not part of any availability group (which is
+ * the same as having a group with only one member).
+ *
+ * The group identifier must be treated as an opaque identifier. The string may look
+ * like an ALSA control name, but applications must not assume any such relationship.
+ * The group naming scheme can change without a warning.
+ *
+ * \since 14.0 */
+ uint32_t type; /**< Port type, see #pa_device_port_type. \since 14.0 */
} pa_card_port_info;
/** Stores information about cards. Please note that this structure
=====================================
src/pulsecore/device-port.c
=====================================
@@ -54,11 +54,11 @@ void pa_device_port_new_data_set_available(pa_device_port_new_data *data, pa_ava
data->available = available;
}
-void pa_device_port_new_data_set_available_group(pa_device_port_new_data *data, const char *group) {
+void pa_device_port_new_data_set_availability_group(pa_device_port_new_data *data, const char *group) {
pa_assert(data);
- pa_xfree(data->available_group);
- data->available_group = pa_xstrdup(group);
+ pa_xfree(data->availability_group);
+ data->availability_group = pa_xstrdup(group);
}
void pa_device_port_new_data_set_direction(pa_device_port_new_data *data, pa_direction_t direction) {
@@ -78,7 +78,7 @@ void pa_device_port_new_data_done(pa_device_port_new_data *data) {
pa_xfree(data->name);
pa_xfree(data->description);
- pa_xfree(data->available_group);
+ pa_xfree(data->availability_group);
}
void pa_device_port_set_preferred_profile(pa_device_port *p, const char *new_pp) {
@@ -164,7 +164,7 @@ static void device_port_free(pa_object *o) {
if (p->profiles)
pa_hashmap_free(p->profiles);
- pa_xfree(p->available_group);
+ pa_xfree(p->availability_group);
pa_xfree(p->preferred_profile);
pa_xfree(p->name);
pa_xfree(p->description);
@@ -190,8 +190,8 @@ pa_device_port *pa_device_port_new(pa_core *c, pa_device_port_new_data *data, si
p->card = NULL;
p->priority = 0;
p->available = data->available;
- p->available_group = data->available_group;
- data->available_group = NULL;
+ p->availability_group = data->availability_group;
+ data->availability_group = NULL;
p->profiles = pa_hashmap_new(pa_idxset_string_hash_func, pa_idxset_string_compare_func);
p->direction = data->direction;
p->type = data->type;
=====================================
src/pulsecore/device-port.h
=====================================
@@ -47,7 +47,7 @@ struct pa_device_port {
unsigned priority;
pa_available_t available; /* PA_AVAILABLE_UNKNOWN, PA_AVAILABLE_NO or PA_AVAILABLE_YES */
- char *available_group; /* a string indentifier which determine the group of devices handling the available state simulteneously */
+ char *availability_group; /* a string indentifier which determine the group of devices handling the available state simulteneously */
pa_proplist *proplist;
pa_hashmap *profiles; /* Does not own the profiles */
@@ -69,7 +69,7 @@ typedef struct pa_device_port_new_data {
char *name;
char *description;
pa_available_t available;
- char *available_group;
+ char *availability_group;
pa_direction_t direction;
pa_device_port_type_t type;
} pa_device_port_new_data;
@@ -78,7 +78,7 @@ pa_device_port_new_data *pa_device_port_new_data_init(pa_device_port_new_data *d
void pa_device_port_new_data_set_name(pa_device_port_new_data *data, const char *name);
void pa_device_port_new_data_set_description(pa_device_port_new_data *data, const char *description);
void pa_device_port_new_data_set_available(pa_device_port_new_data *data, pa_available_t available);
-void pa_device_port_new_data_set_available_group(pa_device_port_new_data *data, const char *group);
+void pa_device_port_new_data_set_availability_group(pa_device_port_new_data *data, const char *group);
void pa_device_port_new_data_set_direction(pa_device_port_new_data *data, pa_direction_t direction);
void pa_device_port_new_data_set_type(pa_device_port_new_data *data, pa_device_port_type_t type);
void pa_device_port_new_data_done(pa_device_port_new_data *data);
=====================================
src/pulsecore/protocol-native.c
=====================================
@@ -3208,7 +3208,7 @@ static void sink_fill_tagstruct(pa_native_connection *c, pa_tagstruct *t, pa_sin
if (c->version >= 24) {
pa_tagstruct_putu32(t, p->available);
if (c->version >= 34) {
- pa_tagstruct_puts(t, p->available_group);
+ pa_tagstruct_puts(t, p->availability_group);
pa_tagstruct_putu32(t, p->type);
}
}
@@ -3283,7 +3283,7 @@ static void source_fill_tagstruct(pa_native_connection *c, pa_tagstruct *t, pa_s
if (c->version >= 24) {
pa_tagstruct_putu32(t, p->available);
if (c->version >= 34) {
- pa_tagstruct_puts(t, p->available_group);
+ pa_tagstruct_puts(t, p->availability_group);
pa_tagstruct_putu32(t, p->type);
}
}
@@ -3371,7 +3371,7 @@ static void card_fill_tagstruct(pa_native_connection *c, pa_tagstruct *t, pa_car
if (c->version >= 27) {
pa_tagstruct_puts64(t, port->latency_offset);
if (c->version >= 34) {
- pa_tagstruct_puts(t, port->available_group);
+ pa_tagstruct_puts(t, port->availability_group);
pa_tagstruct_putu32(t, port->type);
}
}
=====================================
src/utils/pactl.c
=====================================
@@ -363,8 +363,8 @@ static void get_sink_info_callback(pa_context *c, const pa_sink_info *i, int is_
for (p = i->ports; *p; p++)
printf(_("\t\t%s: %s (type: %s, priority: %u%s%s%s)\n"),
(*p)->name, (*p)->description, get_device_port_type((*p)->type),
- (*p)->priority, (*p)->available_group ? _(", available group: ") : "",
- (*p)->available_group ?: "", get_available_str_ynonly((*p)->available));
+ (*p)->priority, (*p)->availability_group ? _(", availability group: ") : "",
+ (*p)->availability_group ?: "", get_available_str_ynonly((*p)->available));
}
if (i->active_port)
@@ -471,8 +471,8 @@ static void get_source_info_callback(pa_context *c, const pa_source_info *i, int
for (p = i->ports; *p; p++)
printf(_("\t\t%s: %s (type: %s, priority: %u%s%s%s)\n"),
(*p)->name, (*p)->description, get_device_port_type((*p)->type),
- (*p)->priority, (*p)->available_group ? _(", available group: ") : "",
- (*p)->available_group ?: "", get_available_str_ynonly((*p)->available));
+ (*p)->priority, (*p)->availability_group ? _(", availability group: ") : "",
+ (*p)->availability_group ?: "", get_available_str_ynonly((*p)->available));
}
if (i->active_port)
@@ -635,7 +635,7 @@ static void get_card_info_callback(pa_context *c, const pa_card_info *i, int is_
pa_card_profile_info **pr = (*p)->profiles;
printf(_("\t\t%s: %s (type: %s, priority: %u, latency offset: %" PRId64 " usec%s%s%s)\n"), (*p)->name,
(*p)->description, get_device_port_type((*p)->type), (*p)->priority, (*p)->latency_offset,
- (*p)->available_group ? _(", available group: ") : "", (*p)->available_group ?: "",
+ (*p)->availability_group ? _(", availability group: ") : "", (*p)->availability_group ?: "",
get_available_str_ynonly((*p)->available));
if (!pa_proplist_isempty((*p)->proplist)) {
View it on GitLab: https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/compare/2c790e193730f17b70734a26a417f46189fbc6c0...a863b5795a6a67bd1dc6398fe4f240934641ea8e
--
View it on GitLab: https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/compare/2c790e193730f17b70734a26a417f46189fbc6c0...a863b5795a6a67bd1dc6398fe4f240934641ea8e
You're receiving this email because of your account on gitlab.freedesktop.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/pulseaudio-commits/attachments/20200810/2d5c5773/attachment-0001.htm>
More information about the pulseaudio-commits
mailing list