2023-09-22 20:09:05

by Luiz Augusto von Dentz

Subject: [PATCH v2 1/6] media-api: Update to reflect the last code changes

From: Luiz Augusto von Dentz <[email protected]>

This reflect the last code changes adding the missing Broadcast
properties.
---
doc/media-api.rst | 179 +++++++++++++++++++++++++++++++++++-----------
1 file changed, 138 insertions(+), 41 deletions(-)

diff --git a/doc/media-api.rst b/doc/media-api.rst
index 34bf44e8ffbb..b37ae8f01630 100644
--- a/doc/media-api.rst
+++ b/doc/media-api.rst
@@ -710,28 +710,45 @@ void SetConfiguration(object transport, dict properties)
properties:

:array{byte} Capabilities [Mandatory]:
+
+ See Endpoint.Capabilities property.
+
:array{byte} Metadata [ISO only]:
- :byte CIG [ISO only]:
- :byte CIS [ISO only]:
- :uint32 Interval [ISO only]:
- :bool Framing [ISO only]:
- :string PHY [ISO only]:
- :uint16 SDU [ISO only]:
- :byte Retransmissions [ISO only]:
- :uint16 Latency [ISO only]:
- :uint32 Delay [ISO only]:
- :uint8 TargetLatency [ISO Latency]:
- :byte BIG [ISO broadcast only]:
- :byte BIS [ISO broadcast only]:
- :byte SyncInterval [ISO broadcast only]:
- :byte Encryption [ISO broadcast only]:
- :byte Options [ISO broadcast only]:
- :uint16 Skip [ISO broadcast only]:
- :uint16 SyncTimeout [ISO broadcast only]:
- :byte SyncCteType [ISO broadcast only]:
- :byte MSE [ISO broadcast only]:
- :uint16 Timeout [ISO broadcast only]:
- :array{byte} BroadcastCode [ISO broadcast only]:
+
+ See Endpoint.Metadata property.
+
+ :uint32 Location [ISO only]:
+
+ See Endpoint.Location property.
+
+ :byte Framing [ISO only]:
+
+ See Endpoint.Framing property.
+
+ :byte PHY [ISO only]:
+
+ See Endpoint.PHY property.
+
+ :uint16 MaximumLatency [ISO only]:
+
+ See Endpoint.MaximumLatency property.
+
+ :uint32 MinimumDelay [ISO only]:
+
+ See Endpoint.MinimumDelay property.
+
+ :uint32 MaximumDelay [ISO only]:
+
+ See Endpoint.MaximumDelay property.
+
+ :uint32 PreferredMinimumDelay [ISO only]:
+
+ See Endpoint.PreferredMinimumDelay property.
+
+ :uint32 PreferredMaximumDelay [ISO only]:
+
+ See Endpoint.PreferredMaximumDelay property.
+

array{byte} SelectConfiguration(array{byte} capabilities)
`````````````````````````````````````````````````````````
@@ -984,33 +1001,65 @@ dict QoS [readonly, optional, ISO only, experimental]

Indicates configured CIG.

+ Possible values:
+
+ :0x00 - 0xef:
+
+ Valid ID range.
+
+ :0xff:
+
+ Auto allocate.
+
:byte CIS:

Indicates configured CIS.

- :uint32 Interval:
+ Possible values:

- Indicates configured ISO interval.
+ :0x00 - 0xef:

- :boolean Framing:
+ Valid ID range.
+
+ :0xff:
+
+ Auto allocate.
+
+ :byte Framing:

Indicates configured framing.

- :byte PHY:
+ Possible values:

- Indicates configured PHY.
+ :0x00:

- :uint16 SDU:
+ Unframed.

- Indicates configured SDU.
+ :0x01:

- :byte Retransmissions:
+ Framed.

- Indicates configured retransmissions.
+ :uint32 PresentationDelay:

- :uint16 Latency:
+ Indicates configured transport presentation delay (us).

- Indicates configured transport latency.
+ :byte TargetLatency:
+
+ Indicates the requested target latency.
+
+ Possible values:
+
+ :0x01:
+
+ Low Latency.
+
+ :0x02:
+
+ Balanced Latency/Reliability.
+
+ :0x03:
+
+ High Reliability.

Possible values for Broadcast:

@@ -1022,26 +1071,74 @@ dict QoS [readonly, optional, ISO only, experimental]

Indicates configured BIS.

- :uint32 SyncFactor:
+ :byte SyncFactor:

- Indicates configured sync factor.
+ Indicates configured broadcast sync factor.

- :uint32 Interval:
+ :byte Packing:

- Indicates configured ISO interval.
+ Indicates configured packing.

- :byte PHY:
+ :byte Framing:

- Indicates configured PHY.
+ Indicates configured framing.

- :uint16 SDU:
+ :byte Options:

- Indicates configured maximum SDU.
+ Indicates configured broadcast options.
+
+ :uint16 Skip:
+
+ Indicates configured broadcast skip.

:byte SyncTimeout:

Indicates configured broadcast sync timeout.

+ :byte SyncType:
+
+ Indicates configured broadcast sync CTE type.
+
+ :byte MSE:
+
+ Indicates configured broadcast MSE.
+
+ :uint16 Timeout:
+
+ Indicates configured broadcast timeout.
+
+ Possible values for both Unicast and Broadcast:
+
+ :uint32 Interval:
+
+ Indicates configured ISO interval (us).
+
:uint16 Latency:

- Indicates configured transport latency.
+ Indicates configured transport latency (ms).
+
+ :uint16 SDU:
+
+ Indicates configured maximum SDU.
+
+ :byte PHY:
+
+ Indicates configured PHY.
+
+ Possible values:
+
+ :bit 0:
+
+ LE 1M
+
+ :bit 1:
+
+ LE 2M
+
+ :bit 2:
+
+ LE Coded
+
+ :byte Retransmissions:
+
+ Indicates configured retransmissions.
--
2.41.0

2023-09-22 22:01:10

by bluez.test.bot

Subject: RE: [v2,1/6] media-api: Update to reflect the last code changes

This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=786884

---Test result---

Test Summary:
CheckPatch PASS 4.24 seconds
GitLint FAIL 2.39 seconds
BuildEll PASS 28.66 seconds
BluezMake PASS 1020.76 seconds
MakeCheck PASS 12.07 seconds
MakeDistcheck PASS 163.66 seconds
CheckValgrind PASS 265.29 seconds
CheckSmatch PASS 358.10 seconds
bluezmakeextell PASS 109.72 seconds
IncrementalBuild PASS 5193.51 seconds
ScanBuild PASS 1080.16 seconds

Details
##############################
Test: GitLint - FAIL
Desc: Run gitlint
Output:
[v2,3/6] client: Make transport.show to print QoS property

WARNING: I3 - ignore-body-lines: gitlint will be switching from using Python regex 'match' (match beginning) to 'search' (match anywhere) semantics. Please review your ignore-body-lines.regex option accordingly. To remove this warning, set general.regex-style-search=True. More details: https://jorisroovers.github.io/gitlint/configuration/#regex-style-search
10: B3 Line contains hard tab characters (\t): " UUID: 00002bcb-0000-1000-8000-00805f9b34fb"
11: B3 Line contains hard tab characters (\t): " Codec: 0x06 (6)"
12: B3 Line contains hard tab characters (\t): " Configuration:"
14: B3 Line contains hard tab characters (\t): " Device: /org/bluez/hci0/dev_00_AA_01_01_00_03"
15: B3 Line contains hard tab characters (\t): " State: idle"
16: B3 Line contains hard tab characters (\t): " Endpoint: /org/bluez/hci0/dev_00_AA_01_01_00_03/pac_sink0"
17: B3 Line contains hard tab characters (\t): " QoS Key: CIG"
18: B3 Line contains hard tab characters (\t): " QoS Value: 0x00 (0)"
19: B3 Line contains hard tab characters (\t): " QoS Key: CIS"
20: B3 Line contains hard tab characters (\t): " QoS Value: 0x00 (0)"
21: B3 Line contains hard tab characters (\t): " QoS Key: Framing"
22: B3 Line contains hard tab characters (\t): " QoS Value: 0x00 (0)"
23: B3 Line contains hard tab characters (\t): " QoS Key: PresentationDelay"
24: B3 Line contains hard tab characters (\t): " QoS Value: 0x00009c40 (40000)"
25: B3 Line contains hard tab characters (\t): " QoS Key: Interval"
26: B3 Line contains hard tab characters (\t): " QoS Value: 0x00002710 (10000)"
27: B3 Line contains hard tab characters (\t): " QoS Key: Latency"
28: B3 Line contains hard tab characters (\t): " QoS Value: 0x000a (10)"
29: B3 Line contains hard tab characters (\t): " QoS Key: SDU"
30: B3 Line contains hard tab characters (\t): " QoS Value: 0x0028 (40)"
31: B3 Line contains hard tab characters (\t): " QoS Key: PHY"
32: B3 Line contains hard tab characters (\t): " QoS Value: 0x02 (2)"
33: B3 Line contains hard tab characters (\t): " QoS Key: Retransmissions"
34: B3 Line contains hard tab characters (\t): " QoS Value: 0x02 (2)"
35: B3 Line contains hard tab characters (\t): " Location: 0x00000003 (3)"
36: B3 Line contains hard tab characters (\t): " Links: /org/bluez/hci0/dev_00_AA_01_01_00_03/pac_source0/fd0"


---
Regards,
Linux Bluetooth

2023-09-22 22:50:30

by Luiz Augusto von Dentz

Subject: [PATCH v2 4/6] media: Implement QoS property

From: Luiz Augusto von Dentz <[email protected]>

This implements QoS as a dict instead of listing each field as
a individual property.
---
profiles/audio/media.c | 157 ++++++++++++++++++++++++-----------------
1 file changed, 91 insertions(+), 66 deletions(-)

diff --git a/profiles/audio/media.c b/profiles/audio/media.c
index 66f512e007e4..da0e220bf217 100644
--- a/profiles/audio/media.c
+++ b/profiles/audio/media.c
@@ -743,15 +743,100 @@ static int parse_array(DBusMessageIter *iter, struct iovec *iov)
return 0;
}

+static int parse_ucast_qos(DBusMessageIter *iter, struct bt_bap_qos *qos)
+{
+ DBusMessageIter array;
+ const char *key;
+ struct bt_bap_io_qos io_qos;
+
+ dbus_message_iter_recurse(iter, &array);
+
+ memset(&io_qos, 0, sizeof(io_qos));
+ while (dbus_message_iter_get_arg_type(&array) == DBUS_TYPE_DICT_ENTRY) {
+ DBusMessageIter value, entry;
+ int var;
+
+ dbus_message_iter_recurse(&array, &entry);
+ dbus_message_iter_get_basic(&entry, &key);
+
+ dbus_message_iter_next(&entry);
+ dbus_message_iter_recurse(&entry, &value);
+
+ var = dbus_message_iter_get_arg_type(&value);
+
+ if (!strcasecmp(key, "CIG")) {
+ if (var != DBUS_TYPE_BYTE)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value, &qos->ucast.cig_id);
+ } else if (!strcasecmp(key, "CIS")) {
+ if (var != DBUS_TYPE_BYTE)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value, &qos->ucast.cis_id);
+ } else if (!strcasecmp(key, "Interval")) {
+ if (var != DBUS_TYPE_UINT32)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value, &io_qos.interval);
+ } else if (!strcasecmp(key, "Framing")) {
+ if (var != DBUS_TYPE_BYTE)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value,
+ &qos->ucast.framing);
+ } else if (!strcasecmp(key, "PHY")) {
+ if (var != DBUS_TYPE_BYTE)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value, &io_qos.phy);
+ } else if (!strcasecmp(key, "SDU")) {
+ if (var != DBUS_TYPE_UINT16)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value, &io_qos.sdu);
+ } else if (!strcasecmp(key, "Retransmissions")) {
+ if (var != DBUS_TYPE_BYTE)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value, &io_qos.rtn);
+ } else if (!strcasecmp(key, "Latency")) {
+ if (var != DBUS_TYPE_UINT16)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value, &io_qos.latency);
+ } else if (!strcasecmp(key, "PresentationDelay")) {
+ if (var != DBUS_TYPE_UINT32)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value, &qos->ucast.delay);
+ } else if (!strcasecmp(key, "TargetLatency")) {
+ if (var != DBUS_TYPE_BYTE)
+ goto fail;
+
+ dbus_message_iter_get_basic(&value,
+ &qos->ucast.target_latency);
+ }
+
+ dbus_message_iter_next(&array);
+ }
+
+ memcpy(&qos->ucast.io_qos, &io_qos, sizeof(io_qos));
+
+ return 0;
+
+fail:
+ DBG("Failed parsing %s", key);
+
+ return -EINVAL;
+}
+
static int parse_select_properties(DBusMessageIter *props, struct iovec *caps,
struct iovec *metadata,
struct bt_bap_qos *qos)
{
const char *key;
- struct bt_bap_io_qos io_qos;
- uint8_t framing = 0;

- memset(&io_qos, 0, sizeof(io_qos));
while (dbus_message_iter_get_arg_type(props) == DBUS_TYPE_DICT_ENTRY) {
DBusMessageIter value, entry;
int var;
@@ -776,77 +861,17 @@ static int parse_select_properties(DBusMessageIter *props, struct iovec *caps,

if (parse_array(&value, metadata))
goto fail;
- } else if (!strcasecmp(key, "CIG")) {
- if (var != DBUS_TYPE_BYTE)
+ } else if (!strcasecmp(key, "QoS")) {
+ if (var != DBUS_TYPE_ARRAY)
goto fail;

- dbus_message_iter_get_basic(&value, &qos->ucast.cig_id);
- } else if (!strcasecmp(key, "CIS")) {
- if (var != DBUS_TYPE_BYTE)
+ if (parse_ucast_qos(&value, qos))
goto fail;
-
- dbus_message_iter_get_basic(&value, &qos->ucast.cis_id);
- } else if (!strcasecmp(key, "Interval")) {
- if (var != DBUS_TYPE_UINT32)
- goto fail;
-
- dbus_message_iter_get_basic(&value, &io_qos.interval);
- } else if (!strcasecmp(key, "Framing")) {
- dbus_bool_t val;
-
- if (var != DBUS_TYPE_BOOLEAN)
- goto fail;
-
- dbus_message_iter_get_basic(&value, &val);
-
- framing = val;
- } else if (!strcasecmp(key, "PHY")) {
- const char *str;
-
- if (var != DBUS_TYPE_STRING)
- goto fail;
-
- dbus_message_iter_get_basic(&value, &str);
-
- if (!strcasecmp(str, "1M"))
- io_qos.phy = 0x01;
- else if (!strcasecmp(str, "2M"))
- io_qos.phy = 0x02;
- else
- goto fail;
- } else if (!strcasecmp(key, "SDU")) {
- if (var != DBUS_TYPE_UINT16)
- goto fail;
-
- dbus_message_iter_get_basic(&value, &io_qos.sdu);
- } else if (!strcasecmp(key, "Retransmissions")) {
- if (var != DBUS_TYPE_BYTE)
- goto fail;
-
- dbus_message_iter_get_basic(&value, &io_qos.rtn);
- } else if (!strcasecmp(key, "Latency")) {
- if (var != DBUS_TYPE_UINT16)
- goto fail;
-
- dbus_message_iter_get_basic(&value, &io_qos.latency);
- } else if (!strcasecmp(key, "Delay")) {
- if (var != DBUS_TYPE_UINT32)
- goto fail;
-
- dbus_message_iter_get_basic(&value, &qos->ucast.delay);
- } else if (!strcasecmp(key, "TargetLatency")) {
- if (var != DBUS_TYPE_BYTE)
- goto fail;
-
- dbus_message_iter_get_basic(&value,
- &qos->ucast.target_latency);
}

dbus_message_iter_next(props);
}

- memcpy(&qos->ucast.io_qos, &io_qos, sizeof(io_qos));
- qos->ucast.framing = framing;
return 0;

fail:
--
2.41.0

2023-09-22 23:38:17

by Luiz Augusto von Dentz

Subject: [PATCH v2 3/6] client: Make transport.show to print QoS property

From: Luiz Augusto von Dentz <[email protected]>

This makes transport.show to print QoS property since it is now a single
property:

transport.show <transport>
Transport /org/bluez/hci0/dev_00_AA_01_01_00_03/pac_sink0/fd1
UUID: 00002bcb-0000-1000-8000-00805f9b34fb
Codec: 0x06 (6)
Configuration:
02 01 03 02 02 01 03 04 28 00 ........(.
Device: /org/bluez/hci0/dev_00_AA_01_01_00_03
State: idle
Endpoint: /org/bluez/hci0/dev_00_AA_01_01_00_03/pac_sink0
QoS Key: CIG
QoS Value: 0x00 (0)
QoS Key: CIS
QoS Value: 0x00 (0)
QoS Key: Framing
QoS Value: 0x00 (0)
QoS Key: PresentationDelay
QoS Value: 0x00009c40 (40000)
QoS Key: Interval
QoS Value: 0x00002710 (10000)
QoS Key: Latency
QoS Value: 0x000a (10)
QoS Key: SDU
QoS Value: 0x0028 (40)
QoS Key: PHY
QoS Value: 0x02 (2)
QoS Key: Retransmissions
QoS Value: 0x02 (2)
Location: 0x00000003 (3)
Links: /org/bluez/hci0/dev_00_AA_01_01_00_03/pac_source0/fd0
---
client/player.c | 6 +-----
1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/client/player.c b/client/player.c
index fdc27c281ed8..d72ad6a5da01 100644
--- a/client/player.c
+++ b/client/player.c
@@ -3799,11 +3799,7 @@ static void cmd_show_transport(int argc, char *argv[])
print_property(proxy, "Volume");
print_property(proxy, "Endpoint");

- print_property(proxy, "Interval");
- print_property(proxy, "Framing");
- print_property(proxy, "SDU");
- print_property(proxy, "Retransmissions");
- print_property(proxy, "Latency");
+ print_property(proxy, "QoS");
print_property(proxy, "Location");
print_property(proxy, "Metadata");
print_property(proxy, "Links");
--
2.41.0

2023-09-23 01:45:30

by Luiz Augusto von Dentz

Subject: [PATCH v2 5/6] client: Make Endpoint.SelectProperties reply properly

From: Luiz Augusto von Dentz <[email protected]>

This makes Endpoint.SelectProperties reply with QoS property since it
is now a single property.
---
client/player.c | 316 +++++++++++++++++++++++++++---------------------
client/print.c | 16 ++-
2 files changed, 188 insertions(+), 144 deletions(-)

diff --git a/client/player.c b/client/player.c
index d72ad6a5da01..6953eff28543 100644
--- a/client/player.c
+++ b/client/player.c
@@ -1199,7 +1199,7 @@ static const struct capabilities {
struct codec_qos {
uint32_t interval;
uint8_t framing;
- char *phy;
+ uint8_t phy;
uint16_t sdu;
uint8_t rtn;
uint16_t latency;
@@ -1274,22 +1274,22 @@ static struct codec_preset sbc_presets[] = {
QOS_CONFIG(_interval, 0x01, _phy, _sdu, _rtn, _latency, _delay)

#define QOS_UNFRAMED_1M(_interval, _sdu, _rtn, _latency, _delay) \
- QOS_UNFRAMED(_interval, "1M", _sdu, _rtn, _latency, _delay) \
+ QOS_UNFRAMED(_interval, 0x01, _sdu, _rtn, _latency, _delay) \

#define QOS_FRAMED_1M(_interval, _sdu, _rtn, _latency, _delay) \
- QOS_FRAMED(_interval, "1M", _sdu, _rtn, _latency, _delay) \
+ QOS_FRAMED(_interval, 0x01, _sdu, _rtn, _latency, _delay) \

#define QOS_UNFRAMED_2M(_interval, _sdu, _rtn, _latency, _delay) \
- QOS_UNFRAMED(_interval, "2M", _sdu, _rtn, _latency, _delay) \
+ QOS_UNFRAMED(_interval, 0x02, _sdu, _rtn, _latency, _delay) \

#define QOS_FRAMED_2M(_interval, _sdu, _rtn, _latency, _delay) \
- QOS_FRAMED(_interval, "2M", _sdu, _rtn, _latency, _delay) \
+ QOS_FRAMED(_interval, 0x02, _sdu, _rtn, _latency, _delay) \

#define LC3_7_5_UNFRAMED(_sdu, _rtn, _latency, _delay) \
- QOS_UNFRAMED(7500u, "2M", _sdu, _rtn, _latency, _delay)
+ QOS_UNFRAMED(7500u, 0x02, _sdu, _rtn, _latency, _delay)

#define LC3_7_5_FRAMED(_sdu, _rtn, _latency, _delay) \
- QOS_FRAMED(7500u, "2M", _sdu, _rtn, _latency, _delay)
+ QOS_FRAMED(7500u, 0x02, _sdu, _rtn, _latency, _delay)

#define LC3_10_UNFRAMED(_sdu, _rtn, _latency, _delay) \
QOS_UNFRAMED_2M(10000u, _sdu, _rtn, _latency, _delay)
@@ -1770,14 +1770,174 @@ static struct bt_iso_qos bcast_qos = {
}
};

+static void append_io_qos(DBusMessageIter *iter, struct endpoint_config *cfg)
+{
+ struct codec_qos *qos = (void *)cfg->qos;
+
+ bt_shell_printf("Interval %u\n", qos->interval);
+
+ g_dbus_dict_append_entry(iter, "Interval", DBUS_TYPE_UINT32,
+ &qos->interval);
+
+ bt_shell_printf("PHY 0x%02x\n", qos->phy);
+
+ g_dbus_dict_append_entry(iter, "PHY", DBUS_TYPE_BYTE, &qos->phy);
+
+ bt_shell_printf("SDU %u\n", cfg->qos->sdu);
+
+ g_dbus_dict_append_entry(iter, "SDU", DBUS_TYPE_UINT16, &qos->sdu);
+
+ bt_shell_printf("Retransmissions %u\n", qos->rtn);
+
+ g_dbus_dict_append_entry(iter, "Retransmissions",
+ DBUS_TYPE_BYTE, &qos->rtn);
+
+ bt_shell_printf("Latency %u\n", qos->latency);
+
+ g_dbus_dict_append_entry(iter, "Latency",
+ DBUS_TYPE_UINT16, &qos->latency);
+}
+
+static void append_ucast_qos(DBusMessageIter *iter, struct endpoint_config *cfg)
+{
+ struct codec_qos *qos = (void *)cfg->qos;
+
+ if (cfg->ep->iso_group != BT_ISO_QOS_GROUP_UNSET) {
+ bt_shell_printf("CIG 0x%2.2x\n", cfg->ep->iso_group);
+ g_dbus_dict_append_entry(iter, "CIG", DBUS_TYPE_BYTE,
+ &cfg->ep->iso_group);
+ }
+
+ if (cfg->ep->iso_stream != BT_ISO_QOS_STREAM_UNSET) {
+ bt_shell_printf("CIS 0x%2.2x\n", cfg->ep->iso_stream);
+ g_dbus_dict_append_entry(iter, "CIS", DBUS_TYPE_BYTE,
+ &cfg->ep->iso_stream);
+ }
+
+ bt_shell_printf("Framing 0x%02x\n", qos->framing);
+
+ g_dbus_dict_append_entry(iter, "Framing", DBUS_TYPE_BYTE,
+ &qos->framing);
+
+ bt_shell_printf("PresentationDelay %u\n", qos->delay);
+
+ g_dbus_dict_append_entry(iter, "PresentationDelay",
+ DBUS_TYPE_UINT32, &qos->delay);
+
+ if (cfg->target_latency) {
+ bt_shell_printf("TargetLatency 0x%02x\n", cfg->target_latency);
+ g_dbus_dict_append_entry(iter, "TargetLatency",
+ DBUS_TYPE_BYTE, &cfg->target_latency);
+ }
+
+ append_io_qos(iter, cfg);
+}
+
+static void append_bcast_qos(DBusMessageIter *iter, struct endpoint_config *cfg)
+{
+ if (bcast_qos.bcast.big != BT_ISO_QOS_BIG_UNSET) {
+ bt_shell_printf("BIG 0x%2.2x\n", bcast_qos.bcast.big);
+ g_dbus_dict_append_entry(iter, "BIG", DBUS_TYPE_BYTE,
+ &bcast_qos.bcast.big);
+ }
+
+ if (bcast_qos.bcast.bis != BT_ISO_QOS_BIS_UNSET) {
+ bt_shell_printf("BIS 0x%2.2x\n", bcast_qos.bcast.bis);
+ g_dbus_dict_append_entry(iter, "BIS", DBUS_TYPE_BYTE,
+ &bcast_qos.bcast.bis);
+ }
+
+ bt_shell_printf("Framing 0x%02x\n", bcast_qos.bcast.framing);
+
+ g_dbus_dict_append_entry(iter, "Framing", DBUS_TYPE_BYTE,
+ &bcast_qos.bcast.framing);
+
+ bt_shell_printf("SyncFactor %u\n", bcast_qos.bcast.sync_factor);
+
+ g_dbus_dict_append_entry(iter, "SyncFactor", DBUS_TYPE_BYTE,
+ &bcast_qos.bcast.sync_factor);
+
+ bt_shell_printf("Options %u\n", bcast_qos.bcast.options);
+
+ g_dbus_dict_append_entry(iter, "Options", DBUS_TYPE_BYTE,
+ &bcast_qos.bcast.options);
+
+ bt_shell_printf("Skip %u\n", bcast_qos.bcast.skip);
+
+ g_dbus_dict_append_entry(iter, "Skip", DBUS_TYPE_UINT16,
+ &bcast_qos.bcast.skip);
+
+ bt_shell_printf("SyncTimeout %u\n", bcast_qos.bcast.sync_timeout);
+
+ g_dbus_dict_append_entry(iter, "SyncTimeout", DBUS_TYPE_UINT16,
+ &bcast_qos.bcast.sync_timeout);
+
+ bt_shell_printf("SyncCteType %u\n", bcast_qos.bcast.sync_cte_type);
+
+ g_dbus_dict_append_entry(iter, "SyncType", DBUS_TYPE_BYTE,
+ &bcast_qos.bcast.sync_cte_type);
+
+ bt_shell_printf("MSE %u\n", bcast_qos.bcast.mse);
+
+ g_dbus_dict_append_entry(iter, "MSE", DBUS_TYPE_BYTE,
+ &bcast_qos.bcast.mse);
+
+ bt_shell_printf("Timeout %u\n", bcast_qos.bcast.timeout);
+
+ g_dbus_dict_append_entry(iter, "Timeout", DBUS_TYPE_UINT16,
+ &bcast_qos.bcast.timeout);
+
+ if (cfg->ep->bcode) {
+ const char *key = "BCode";
+
+ bt_shell_printf("BCode:\n");
+ bt_shell_hexdump(cfg->ep->bcode->iov_base,
+ cfg->ep->bcode->iov_len);
+
+ g_dbus_dict_append_basic_array(iter, DBUS_TYPE_STRING,
+ &key, DBUS_TYPE_BYTE,
+ &cfg->ep->bcode->iov_base,
+ cfg->ep->bcode->iov_len);
+ }
+
+ append_io_qos(iter, cfg);
+}
+
+static void append_qos(DBusMessageIter *iter, struct endpoint_config *cfg)
+{
+ DBusMessageIter entry, var, dict;
+ struct codec_qos *qos = (void *)cfg->qos;
+ const char *key = "QoS";
+
+ if (!qos)
+ return;
+
+ dbus_message_iter_open_container(iter, DBUS_TYPE_DICT_ENTRY,
+ NULL, &entry);
+
+ dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &key);
+
+ dbus_message_iter_open_container(&entry, DBUS_TYPE_VARIANT,
+ "a{sv}", &var);
+
+ dbus_message_iter_open_container(&var, DBUS_TYPE_ARRAY, "{sv}",
+ &dict);
+
+ if (cfg->ep->broadcast)
+ append_bcast_qos(&dict, cfg);
+ else
+ append_ucast_qos(&dict, cfg);
+
+ dbus_message_iter_close_container(&var, &dict);
+ dbus_message_iter_close_container(&entry, &var);
+ dbus_message_iter_close_container(iter, &entry);
+}
+
static void append_properties(DBusMessageIter *iter,
struct endpoint_config *cfg)
{
DBusMessageIter dict;
- struct codec_qos *qos = (void *)cfg->qos;
const char *key = "Capabilities";
- const char *meta = "Metadata";
- const char *keyBCode = "BroadcastCode";

dbus_message_iter_open_container(iter, DBUS_TYPE_ARRAY, "{sv}", &dict);

@@ -1789,6 +1949,8 @@ static void append_properties(DBusMessageIter *iter,
cfg->caps->iov_len);

if (cfg->meta && cfg->meta->iov_len) {
+ const char *meta = "Metadata";
+
g_dbus_dict_append_basic_array(&dict, DBUS_TYPE_STRING, &meta,
DBUS_TYPE_BYTE, &cfg->meta->iov_base,
cfg->meta->iov_len);
@@ -1797,132 +1959,8 @@ static void append_properties(DBusMessageIter *iter,
bt_shell_hexdump(cfg->meta->iov_base, cfg->meta->iov_len);
}

- if (!qos)
- goto done;
+ append_qos(&dict, cfg);

- if (cfg->target_latency) {
- bt_shell_printf("TargetLatency 0x%02x\n", qos->interval);
- g_dbus_dict_append_entry(&dict, "TargetLatency",
- DBUS_TYPE_BYTE, &cfg->target_latency);
- }
-
- if ((!cfg->ep->broadcast) &&
- (cfg->ep->iso_group != BT_ISO_QOS_GROUP_UNSET)) {
- bt_shell_printf("CIG 0x%2.2x\n", cfg->ep->iso_group);
- g_dbus_dict_append_entry(&dict, "CIG", DBUS_TYPE_BYTE,
- &cfg->ep->iso_group);
- } else {
- bt_shell_printf("BIG 0x%2.2x\n", bcast_qos.bcast.big);
- g_dbus_dict_append_entry(&dict, "BIG", DBUS_TYPE_BYTE,
- &bcast_qos.bcast.big);
- }
-
- if ((!cfg->ep->broadcast) &&
- (cfg->ep->iso_stream != BT_ISO_QOS_STREAM_UNSET)) {
- bt_shell_printf("CIS 0x%2.2x\n", cfg->ep->iso_stream);
- g_dbus_dict_append_entry(&dict, "CIS", DBUS_TYPE_BYTE,
- &cfg->ep->iso_stream);
-
- } else {
- bt_shell_printf("BIS 0x%2.2x\n", bcast_qos.bcast.bis);
- g_dbus_dict_append_entry(&dict, "BIS", DBUS_TYPE_BYTE,
- &bcast_qos.bcast.bis);
- }
-
- bt_shell_printf("Interval %u\n", qos->interval);
-
- g_dbus_dict_append_entry(&dict, "Interval", DBUS_TYPE_UINT32,
- &qos->interval);
-
- if (!cfg->ep->broadcast) {
- bt_shell_printf("Framing %s\n",
- qos->framing ? "true" : "false");
-
- g_dbus_dict_append_entry(&dict, "Framing", DBUS_TYPE_BOOLEAN,
- &qos->framing);
- } else {
- bt_shell_printf("Framing %s\n",
- bcast_qos.bcast.framing ? "true" : "false");
-
- g_dbus_dict_append_entry(&dict, "Framing", DBUS_TYPE_BOOLEAN,
- &bcast_qos.bcast.framing);
- }
-
- bt_shell_printf("PHY %s\n", qos->phy);
-
- g_dbus_dict_append_entry(&dict, "PHY", DBUS_TYPE_STRING, &qos->phy);
-
- bt_shell_printf("SDU %u\n", cfg->qos->sdu);
-
- g_dbus_dict_append_entry(&dict, "SDU", DBUS_TYPE_UINT16, &qos->sdu);
-
- bt_shell_printf("Retransmissions %u\n", qos->rtn);
-
- g_dbus_dict_append_entry(&dict, "Retransmissions", DBUS_TYPE_BYTE,
- &qos->rtn);
-
- bt_shell_printf("Latency %u\n", qos->latency);
-
- g_dbus_dict_append_entry(&dict, "Latency", DBUS_TYPE_UINT16,
- &qos->latency);
-
- bt_shell_printf("Delay %u\n", qos->delay);
-
- g_dbus_dict_append_entry(&dict, "Delay", DBUS_TYPE_UINT32,
- &qos->delay);
-
- if (!cfg->ep->broadcast)
- goto done;
-
- bt_shell_printf("SyncInterval %u\n", bcast_qos.bcast.sync_factor);
-
- g_dbus_dict_append_entry(&dict, "SyncInterval", DBUS_TYPE_BYTE,
- &bcast_qos.bcast.sync_factor);
-
- bt_shell_printf("Encryption %u\n", bcast_qos.bcast.encryption);
-
- g_dbus_dict_append_entry(&dict, "Encryption", DBUS_TYPE_BYTE,
- &bcast_qos.bcast.encryption);
-
- bt_shell_printf("Options %u\n", bcast_qos.bcast.options);
-
- g_dbus_dict_append_entry(&dict, "Options", DBUS_TYPE_BYTE,
- &bcast_qos.bcast.options);
-
- bt_shell_printf("Skip %u\n", bcast_qos.bcast.skip);
-
- g_dbus_dict_append_entry(&dict, "Skip", DBUS_TYPE_UINT16,
- &bcast_qos.bcast.skip);
-
- bt_shell_printf("SyncTimeout %u\n", bcast_qos.bcast.sync_timeout);
-
- g_dbus_dict_append_entry(&dict, "SyncTimeout", DBUS_TYPE_UINT16,
- &bcast_qos.bcast.sync_timeout);
-
- bt_shell_printf("SyncCteType %u\n", bcast_qos.bcast.sync_cte_type);
-
- g_dbus_dict_append_entry(&dict, "SyncCteType", DBUS_TYPE_BYTE,
- &bcast_qos.bcast.sync_cte_type);
-
- bt_shell_printf("MSE %u\n", bcast_qos.bcast.mse);
-
- g_dbus_dict_append_entry(&dict, "MSE", DBUS_TYPE_BYTE,
- &bcast_qos.bcast.mse);
-
- bt_shell_printf("Timeout %u\n", bcast_qos.bcast.timeout);
-
- g_dbus_dict_append_entry(&dict, "Timeout", DBUS_TYPE_UINT16,
- &bcast_qos.bcast.timeout);
-
- bt_shell_printf("BroadcastCode:\n");
- bt_shell_hexdump(cfg->ep->bcode->iov_base, cfg->ep->bcode->iov_len);
-
- g_dbus_dict_append_basic_array(&dict, DBUS_TYPE_STRING, &keyBCode,
- DBUS_TYPE_BYTE,
- &cfg->ep->bcode->iov_base,
- cfg->ep->bcode->iov_len);
-
-done:
dbus_message_iter_close_container(iter, &dict);
}

@@ -2892,9 +2930,9 @@ static void custom_phy(const char *input, void *user_data)
struct codec_qos *qos = (void *)&p->qos;

if (!strcmp(input, "1M"))
- qos->phy = "1M";
+ qos->phy = 0x01;
else if (!strcmp(input, "2M"))
- qos->phy = "2M";
+ qos->phy = 0x02;
else {
char *endptr = NULL;
uint8_t phy = strtol(input, &endptr, 0);
@@ -2906,10 +2944,8 @@ static void custom_phy(const char *input, void *user_data)

switch (phy) {
case 0x01:
- qos->phy = "1M";
- break;
case 0x02:
- qos->phy = "2M";
+ qos->phy = phy;
break;
default:
bt_shell_printf("Invalid argument: %s\n", input);
diff --git a/client/print.c b/client/print.c
index 66439e541307..8d721e21df4b 100644
--- a/client/print.c
+++ b/client/print.c
@@ -165,11 +165,19 @@ void print_iter(const char *label, const char *name, DBusMessageIter *iter)
break;
case DBUS_TYPE_DICT_ENTRY:
dbus_message_iter_recurse(iter, &subiter);
- entry = g_strconcat(name, " Key", NULL);
- print_iter(label, entry, &subiter);
- g_free(entry);

- entry = g_strconcat(name, " Value", NULL);
+ if (dbus_message_iter_get_arg_type(&subiter) ==
+ DBUS_TYPE_STRING) {
+ dbus_message_iter_get_basic(&subiter, &valstr);
+ entry = g_strconcat(name, ".", valstr, NULL);
+ } else {
+ entry = g_strconcat(name, ".Key", NULL);
+ print_iter(label, entry, &subiter);
+ g_free(entry);
+
+ entry = g_strconcat(name, ".Value", NULL);
+ }
+
dbus_message_iter_next(&subiter);
print_iter(label, entry, &subiter);
g_free(entry);
--
2.41.0

2023-09-23 07:17:01

by Luiz Augusto von Dentz

Subject: [PATCH v2 2/6] transport: Implement QoS property

From: Luiz Augusto von Dentz <[email protected]>

This implements Transport.QoS as a dict instead of listing each field as
a individual property.
---
client/player.c | 6 +-
lib/bluetooth.h | 2 +-
profiles/audio/bap.c | 6 +-
profiles/audio/transport.c | 431 ++++++++-----------------------------
src/shared/bap.h | 2 +-
src/shared/bass.c | 2 +-
tools/iso-tester.c | 6 +-
tools/isotest.c | 2 +-
8 files changed, 98 insertions(+), 359 deletions(-)

diff --git a/client/player.c b/client/player.c
index 42721c21062b..fdc27c281ed8 100644
--- a/client/player.c
+++ b/client/player.c
@@ -1756,7 +1756,7 @@ static struct bt_iso_qos bcast_qos = {
.bcast = {
.big = BT_ISO_QOS_BIG_UNSET,
.bis = BT_ISO_QOS_BIS_UNSET,
- .sync_interval = 24,
+ .sync_factor = 24,
.packing = 0x00,
.framing = 0x00,
.encryption = 0x00,
@@ -1874,10 +1874,10 @@ static void append_properties(DBusMessageIter *iter,
if (!cfg->ep->broadcast)
goto done;

- bt_shell_printf("SyncInterval %u\n", bcast_qos.bcast.sync_interval);
+ bt_shell_printf("SyncInterval %u\n", bcast_qos.bcast.sync_factor);

g_dbus_dict_append_entry(&dict, "SyncInterval", DBUS_TYPE_BYTE,
- &bcast_qos.bcast.sync_interval);
+ &bcast_qos.bcast.sync_factor);

bt_shell_printf("Encryption %u\n", bcast_qos.bcast.encryption);

diff --git a/lib/bluetooth.h b/lib/bluetooth.h
index 1286aa763208..ba08c70e61b8 100644
--- a/lib/bluetooth.h
+++ b/lib/bluetooth.h
@@ -174,7 +174,7 @@ struct bt_iso_ucast_qos {
struct bt_iso_bcast_qos {
uint8_t big;
uint8_t bis;
- uint8_t sync_interval;
+ uint8_t sync_factor;
uint8_t packing;
uint8_t framing;
struct bt_iso_io_qos in;
diff --git a/profiles/audio/bap.c b/profiles/audio/bap.c
index d70ad872eb87..b05d7a2d9675 100644
--- a/profiles/audio/bap.c
+++ b/profiles/audio/bap.c
@@ -533,7 +533,7 @@ static int parse_properties(DBusMessageIter *props, struct iovec **caps,
goto fail;

dbus_message_iter_get_basic(&value,
- &qos->bcast.sync_interval);
+ &qos->bcast.sync_factor);
} else if (!strcasecmp(key, "MSE")) {
if (var != DBUS_TYPE_BYTE)
goto fail;
@@ -744,7 +744,7 @@ static void update_bcast_qos(struct bt_iso_qos *qos,
{
bap_qos->bcast.big = qos->bcast.big;
bap_qos->bcast.bis = qos->bcast.bis;
- bap_qos->bcast.sync_interval = qos->bcast.sync_interval;
+ bap_qos->bcast.sync_factor = qos->bcast.sync_factor;
bap_qos->bcast.packing = qos->bcast.packing;
bap_qos->bcast.framing = qos->bcast.framing;
bap_qos->bcast.encryption = qos->bcast.encryption;
@@ -1659,7 +1659,7 @@ static void bap_create_bcast_io(struct bap_data *data, struct bap_ep *ep,

iso_qos.bcast.big = ep->qos.bcast.big;
iso_qos.bcast.bis = ep->qos.bcast.bis;
- iso_qos.bcast.sync_interval = ep->qos.bcast.sync_interval;
+ iso_qos.bcast.sync_factor = ep->qos.bcast.sync_factor;
iso_qos.bcast.packing = ep->qos.bcast.packing;
iso_qos.bcast.framing = ep->qos.bcast.framing;
iso_qos.bcast.encryption = ep->qos.bcast.encryption;
diff --git a/profiles/audio/transport.c b/profiles/audio/transport.c
index dd923b03ed9d..1e03b7b51475 100644
--- a/profiles/audio/transport.c
+++ b/profiles/audio/transport.c
@@ -850,160 +850,41 @@ static const GDBusPropertyTable a2dp_properties[] = {
{ }
};

-static gboolean qos_exists(const GDBusPropertyTable *property, void *data)
+static void append_io_qos(DBusMessageIter *dict, struct bt_bap_io_qos *qos)
{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- if (media_endpoint_is_broadcast(transport->endpoint))
- return bap->qos.bcast.io_qos.sdu != 0x00;
-
- return bap->qos.ucast.io_qos.phy != 0x00;
+ dict_append_entry(dict, "Interval", DBUS_TYPE_UINT32, &qos->interval);
+ dict_append_entry(dict, "Latency", DBUS_TYPE_UINT16, &qos->latency);
+ dict_append_entry(dict, "SDU", DBUS_TYPE_UINT16, &qos->sdu);
+ dict_append_entry(dict, "PHY", DBUS_TYPE_BYTE, &qos->phy);
+ dict_append_entry(dict, "Retransmissions", DBUS_TYPE_BYTE, &qos->rtn);
}

-static gboolean get_cig(const GDBusPropertyTable *property,
+static gboolean get_ucast_qos(const GDBusPropertyTable *property,
DBusMessageIter *iter, void *data)
{
struct media_transport *transport = data;
struct bap_transport *bap = transport->data;
+ DBusMessageIter dict;

- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.ucast.cig_id);
+ dbus_message_iter_open_container(iter, DBUS_TYPE_ARRAY,
+ DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
+ DBUS_TYPE_STRING_AS_STRING
+ DBUS_TYPE_VARIANT_AS_STRING
+ DBUS_DICT_ENTRY_END_CHAR_AS_STRING,
+ &dict);

- return TRUE;
-}
+ dict_append_entry(&dict, "CIG", DBUS_TYPE_BYTE,
+ &bap->qos.ucast.cig_id);
+ dict_append_entry(&dict, "CIS", DBUS_TYPE_BYTE,
+ &bap->qos.ucast.cis_id);
+ dict_append_entry(&dict, "Framing", DBUS_TYPE_BYTE,
+ &bap->qos.ucast.framing);
+ dict_append_entry(&dict, "PresentationDelay", DBUS_TYPE_UINT32,
+ &bap->qos.ucast.delay);

-static gboolean get_big(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
+ append_io_qos(&dict, &bap->qos.ucast.io_qos);

- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.bcast.big);
-
- return TRUE;
-}
-
-static gboolean get_cis(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.ucast.cis_id);
-
- return TRUE;
-}
-
-static gboolean get_bis(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.bcast.bis);
-
- return TRUE;
-}
-
-static gboolean get_interval(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT32,
- &bap->qos.ucast.io_qos.interval);
-
- return TRUE;
-}
-
-static gboolean get_framing(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
- dbus_bool_t val = bap->qos.ucast.framing;
-
- if (media_endpoint_is_broadcast(transport->endpoint))
- val = bap->qos.bcast.framing;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BOOLEAN, &val);
-
- return TRUE;
-}
-
-static gboolean get_phy(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- if (media_endpoint_is_broadcast(transport->endpoint)) {
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.bcast.io_qos.phy);
- return TRUE;
- }
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.ucast.io_qos.phy);
-
- return TRUE;
-}
-
-static gboolean get_sdu(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- if (media_endpoint_is_broadcast(transport->endpoint)) {
- dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT16,
- &bap->qos.bcast.io_qos.sdu);
- return TRUE;
- }
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT16,
- &bap->qos.ucast.io_qos.sdu);
-
- return TRUE;
-}
-
-static gboolean get_retransmissions(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.ucast.io_qos.rtn);
-
- return TRUE;
-}
-
-static gboolean get_latency(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT16,
- &bap->qos.ucast.io_qos.latency);
-
- return TRUE;
-}
-
-static gboolean get_delay(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT32,
- &bap->qos.ucast.delay);
+ dbus_message_iter_close_container(iter, &dict);

return TRUE;
}
@@ -1084,119 +965,12 @@ static gboolean get_links(const GDBusPropertyTable *property,
return TRUE;
}

-static gboolean get_sync_interval(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
+static gboolean qos_ucast_exists(const GDBusPropertyTable *property, void *data)
{
struct media_transport *transport = data;
struct bap_transport *bap = transport->data;

- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.bcast.sync_interval);
-
- return TRUE;
-}
-
-static gboolean get_packing(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.bcast.packing);
-
- return TRUE;
-}
-
-static gboolean get_bcode(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
- DBusMessageIter array;
-
- dbus_message_iter_open_container(iter, DBUS_TYPE_ARRAY,
- DBUS_TYPE_BYTE_AS_STRING, &array);
-
- if (bap->qos.bcast.bcode && bap->qos.bcast.bcode->iov_len)
- dbus_message_iter_append_fixed_array(&array, DBUS_TYPE_BYTE,
- &bap->qos.bcast.bcode->iov_base,
- bap->qos.bcast.bcode->iov_len);
-
- dbus_message_iter_close_container(iter, &array);
- return TRUE;
-}
-
-static gboolean get_options(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.bcast.options);
-
- return TRUE;
-}
-
-static gboolean get_skip(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT16,
- &bap->qos.bcast.skip);
-
- return TRUE;
-}
-
-static gboolean get_sync_timeout(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT16,
- &bap->qos.bcast.sync_timeout);
-
- return TRUE;
-}
-
-static gboolean get_sync_cte_type(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.bcast.sync_cte_type);
-
- return TRUE;
-}
-
-static gboolean get_mse(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_BYTE,
- &bap->qos.bcast.mse);
-
- return TRUE;
-}
-
-static gboolean get_timeout(const GDBusPropertyTable *property,
- DBusMessageIter *iter, void *data)
-{
- struct media_transport *transport = data;
- struct bap_transport *bap = transport->data;
-
- dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT16,
- &bap->qos.bcast.timeout);
-
- return TRUE;
+ return bap->qos.ucast.io_qos.phy != 0x00;
}

static const GDBusPropertyTable bap_ucast_properties[] = {
@@ -1205,15 +979,7 @@ static const GDBusPropertyTable bap_ucast_properties[] = {
{ "Codec", "y", get_codec },
{ "Configuration", "ay", get_configuration },
{ "State", "s", get_state },
- { "CIG", "y", get_cig, NULL, qos_exists },
- { "CIS", "y", get_cis, NULL, qos_exists },
- { "Interval", "u", get_interval, NULL, qos_exists },
- { "Framing", "b", get_framing, NULL, qos_exists },
- { "PHY", "y", get_phy, NULL, qos_exists },
- { "SDU", "q", get_sdu, NULL, qos_exists },
- { "Retransmissions", "y", get_retransmissions, NULL, qos_exists },
- { "Latency", "q", get_latency, NULL, qos_exists },
- { "Delay", "u", get_delay, NULL, qos_exists },
+ { "QoS", "a{sv}", get_ucast_qos, NULL, qos_ucast_exists },
{ "Endpoint", "o", get_endpoint, NULL, endpoint_exists },
{ "Location", "u", get_location },
{ "Metadata", "ay", get_metadata },
@@ -1221,6 +987,61 @@ static const GDBusPropertyTable bap_ucast_properties[] = {
{ }
};

+static gboolean get_bcast_qos(const GDBusPropertyTable *property,
+ DBusMessageIter *iter, void *data)
+{
+ struct media_transport *transport = data;
+ struct bap_transport *bap = transport->data;
+ DBusMessageIter dict;
+
+ dbus_message_iter_open_container(iter, DBUS_TYPE_ARRAY,
+ DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
+ DBUS_TYPE_STRING_AS_STRING
+ DBUS_TYPE_VARIANT_AS_STRING
+ DBUS_DICT_ENTRY_END_CHAR_AS_STRING,
+ &dict);
+
+ dict_append_entry(&dict, "BIG", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.big);
+ dict_append_entry(&dict, "BIS", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.bis);
+ dict_append_entry(&dict, "SyncFactor", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.sync_factor);
+ dict_append_entry(&dict, "Packing", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.packing);
+ dict_append_entry(&dict, "Framing", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.framing);
+ if (bap->qos.bcast.bcode)
+ dict_append_array(&dict, "BCode", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.bcode->iov_base,
+ bap->qos.bcast.bcode->iov_len);
+ dict_append_entry(&dict, "Options", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.options);
+ dict_append_entry(&dict, "Skip", DBUS_TYPE_UINT16,
+ &bap->qos.bcast.skip);
+ dict_append_entry(&dict, "SyncTimeout", DBUS_TYPE_UINT16,
+ &bap->qos.bcast.sync_timeout);
+ dict_append_entry(&dict, "SyncType", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.sync_cte_type);
+ dict_append_entry(&dict, "MSE", DBUS_TYPE_BYTE,
+ &bap->qos.bcast.mse);
+ dict_append_entry(&dict, "Timeout", DBUS_TYPE_UINT16,
+ &bap->qos.bcast.timeout);
+
+ append_io_qos(&dict, &bap->qos.bcast.io_qos);
+
+ dbus_message_iter_close_container(iter, &dict);
+
+ return TRUE;
+}
+
+static gboolean qos_bcast_exists(const GDBusPropertyTable *property, void *data)
+{
+ struct media_transport *transport = data;
+ struct bap_transport *bap = transport->data;
+
+ return bap->qos.bcast.io_qos.phy != 0x00;
+}

static const GDBusPropertyTable bap_bcast_properties[] = {
{ "Device", "o", get_device },
@@ -1228,17 +1049,7 @@ static const GDBusPropertyTable bap_bcast_properties[] = {
{ "Codec", "y", get_codec },
{ "Configuration", "ay", get_configuration },
{ "State", "s", get_state },
- { "BIG", "y", get_big, NULL, qos_exists },
- { "BIS", "y", get_bis, NULL, qos_exists },
- { "SyncInterval", "y", get_sync_interval, NULL, qos_exists },
- { "Packing", "y", get_packing, NULL, qos_exists },
- { "BCode", "ay", get_bcode, NULL, qos_exists },
- { "Options", "y", get_options, NULL, qos_exists },
- { "Skip", "q", get_skip, NULL, qos_exists },
- { "SyncTimeout", "q", get_sync_timeout, NULL, qos_exists },
- { "SyncCteType", "y", get_sync_cte_type, NULL, qos_exists },
- { "MSE", "y", get_mse, NULL, qos_exists },
- { "Timeout", "q", get_timeout, NULL, qos_exists },
+ { "QoS", "a{sv}", get_bcast_qos, NULL, qos_bcast_exists },
{ "Endpoint", "o", get_endpoint, NULL, endpoint_exists },
{ "Location", "u", get_location },
{ "Metadata", "ay", get_metadata },
@@ -1471,31 +1282,7 @@ static void bap_update_qos(const struct media_transport *transport)

g_dbus_emit_property_changed(btd_get_dbus_connection(),
transport->path, MEDIA_TRANSPORT_INTERFACE,
- "CIG");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "CIS");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Interval");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Framing");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "PHY");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "SDU");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Retransmissions");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Latency");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Delay");
+ "QoS");
}

static gboolean bap_resume_complete_cb(void *data)
@@ -1538,55 +1325,7 @@ static void bap_update_bcast_qos(const struct media_transport *transport)

g_dbus_emit_property_changed(btd_get_dbus_connection(),
transport->path, MEDIA_TRANSPORT_INTERFACE,
- "BIG");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "BIS");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "SyncInterval");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Packing");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Framing");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "BCode");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Options");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Skip");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "SyncTimeout");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "SyncCteType");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "MSE");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Timeout");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Interval");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "Latency");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "PHY");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "SDU");
- g_dbus_emit_property_changed(btd_get_dbus_connection(),
- transport->path, MEDIA_TRANSPORT_INTERFACE,
- "RTN");
+ "QoS");
g_dbus_emit_property_changed(btd_get_dbus_connection(),
transport->path, MEDIA_TRANSPORT_INTERFACE,
"Codec");
diff --git a/src/shared/bap.h b/src/shared/bap.h
index edb5c1bed27e..e4eae86502f3 100644
--- a/src/shared/bap.h
+++ b/src/shared/bap.h
@@ -75,7 +75,7 @@ struct bt_bap_ucast_qos {
struct bt_bap_bcast_qos {
uint8_t big;
uint8_t bis;
- uint8_t sync_interval;
+ uint8_t sync_factor;
uint8_t packing;
uint8_t framing;
uint8_t encryption;
diff --git a/src/shared/bass.c b/src/shared/bass.c
index 86dab03e3993..37255aff64f3 100644
--- a/src/shared/bass.c
+++ b/src/shared/bass.c
@@ -102,7 +102,7 @@ static struct bt_iso_qos default_qos = {
.bcast = {
.big = BT_ISO_QOS_BIG_UNSET,
.bis = BT_ISO_QOS_BIS_UNSET,
- .sync_interval = 0x07,
+ .sync_factor = 0x07,
.packing = 0x00,
.framing = 0x00,
.in = DEFAULT_IO_QOS,
diff --git a/tools/iso-tester.c b/tools/iso-tester.c
index 410da2c930ac..a392a06ebcb3 100644
--- a/tools/iso-tester.c
+++ b/tools/iso-tester.c
@@ -241,7 +241,7 @@
.bcast = { \
.big = _big, \
.bis = _bis, \
- .sync_interval = 0x07, \
+ .sync_factor = 0x07, \
.packing = 0x00, \
.framing = 0x00, \
.in = _in, \
@@ -1676,9 +1676,9 @@ static bool check_bcast_qos(const struct bt_iso_qos *qos1,
return false;
}

- if (qos1->bcast.sync_interval != qos2->bcast.sync_interval) {
+ if (qos1->bcast.sync_factor != qos2->bcast.sync_factor) {
tester_warn("Unexpected QoS sync interval: 0x%02x != 0x%02x",
- qos1->bcast.sync_interval, qos2->bcast.sync_interval);
+ qos1->bcast.sync_factor, qos2->bcast.sync_factor);
return false;
}

diff --git a/tools/isotest.c b/tools/isotest.c
index 68729d97730e..234e4f1b0453 100644
--- a/tools/isotest.c
+++ b/tools/isotest.c
@@ -1028,7 +1028,7 @@ static void multy_connect_mode(char *peer)
.bcast = { \
.big = BT_ISO_QOS_BIG_UNSET, \
.bis = BT_ISO_QOS_BIS_UNSET, \
- .sync_interval = 0x07, \
+ .sync_factor = 0x07, \
.packing = 0x00, \
.framing = 0x00, \
.out = QOS_IO(_interval, _latency, _sdu, _phy, _rtn), \
--
2.41.0

2023-09-23 08:38:11

by Luiz Augusto von Dentz

Subject: [PATCH v2 6/6] doc/media: Convert media-api.rst into manpages

From: Luiz Augusto von Dentz <[email protected]>

This splits media-api.rst into org.bluez.Media<interface>.rst and
generate manpages for them.
---
Makefile.am | 21 +-
doc/media-api.rst | 1144 ------------------------------
doc/org.bluez.Media.rst | 133 ++++
doc/org.bluez.MediaControl.rst | 80 +++
doc/org.bluez.MediaEndpoint.rst | 219 ++++++
doc/org.bluez.MediaFolder.rst | 117 +++
doc/org.bluez.MediaItem.rst | 131 ++++
doc/org.bluez.MediaPlayer.rst | 315 ++++++++
doc/org.bluez.MediaTransport.rst | 274 +++++++
9 files changed, 1287 insertions(+), 1147 deletions(-)
delete mode 100644 doc/media-api.rst
create mode 100644 doc/org.bluez.Media.rst
create mode 100644 doc/org.bluez.MediaControl.rst
create mode 100644 doc/org.bluez.MediaEndpoint.rst
create mode 100644 doc/org.bluez.MediaFolder.rst
create mode 100644 doc/org.bluez.MediaItem.rst
create mode 100644 doc/org.bluez.MediaPlayer.rst
create mode 100644 doc/org.bluez.MediaTransport.rst

diff --git a/Makefile.am b/Makefile.am
index 30db74a0c441..a17841b0668d 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -357,8 +357,16 @@ CLEANFILES += $(builtin_files) src/bluetooth.service

if MANPAGES
man_MANS += src/bluetoothd.8
+man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
+ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
+ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
+ doc/org.bluez.MediaTransport.5
endif
manual_pages += src/bluetoothd.8
+manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
+ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
+ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
+ doc/org.bluez.MediaTransport.5

EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
src/main.conf profiles/network/network.conf \
@@ -397,9 +405,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
EXTRA_DIST += doc/mgmt-api.txt \
doc/adapter-api.txt doc/device-api.txt \
doc/agent-api.txt doc/profile-api.txt \
- doc/network-api.txt doc/media-api.rst \
- doc/health-api.txt doc/sap-api.txt \
- doc/input-api.txt
+ doc/network-api.txt doc/health-api.txt \
+ doc/sap-api.txt doc/input-api.txt
+
+EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
+ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \
+ doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \
+ doc/org.bluez.MediaTransport.rst

EXTRA_DIST += doc/gatt-api.txt doc/advertising-api.txt

@@ -667,6 +679,9 @@ endif
%.1: %.rst Makefile
$(RST2MAN_PROCESS)

+%.5: %.rst Makefile
+ $(RST2MAN_PROCESS)
+
%.8: %.rst Makefile
$(RST2MAN_PROCESS)

diff --git a/doc/media-api.rst b/doc/media-api.rst
deleted file mode 100644
index b37ae8f01630..000000000000
--- a/doc/media-api.rst
+++ /dev/null
@@ -1,1144 +0,0 @@
-===================================
-BlueZ D-Bus Media API documentation
-===================================
-
-
-Media interface
-===============
-
-:Service: org.bluez
-:Interface: org.bluez.Media1
-:Object path: [variable prefix]/{hci0,hci1,...}
-
-Methods
--------
-
-void RegisterEndpoint(object endpoint, dict properties)
-```````````````````````````````````````````````````````
-
- Register a local end point to sender, the sender can register as many
- end points as it likes.
-
- Note: If the sender disconnects the end points are automatically
- unregistered.
-
- possible properties:
-
- :string UUID:
-
- UUID of the profile which the endpoint is for.
-
- UUID must be in the list of SupportedUUIDS.
-
- :byte Codec:
-
- Assigned number of codec that the endpoint implements. The
- values should match the profile specification which is
- indicated by the UUID.
-
- :uint32_t Vendor [Optional]:
-
- Vendor-specific Company ID, Codec ID tuple that the endpoint
- implements.
-
- It shall be set to appropriate value when Vendor Specific Codec
- (0xff) is used.
-
- :array{byte} Capabilities:
-
- Capabilities blob, it is used as it is so the size and byte
- order must match.
-
- :array{byte} Metadata [Optional]:
-
- Metadata blob, it is used as it is so the size and byte order
- must match.
-
- Possible Errors:
-
- :org.bluez.Error.InvalidArguments:
- :org.bluez.Error.NotSupported:
-
- emitted when interface for the end-point is disabled
-
-void UnregisterEndpoint(object endpoint)
-````````````````````````````````````````
- Unregister sender end point.
-
-void RegisterPlayer(object player, dict properties)
-```````````````````````````````````````````````````
-
- Register a media player object to sender, the sender can register as
- many objects as it likes.
-
- Object must implement at least org.mpris.MediaPlayer2.Player as defined
- in MPRIS 2.2 spec:
-
- http://specifications.freedesktop.org/mpris-spec/latest/
-
- Note: If the sender disconnects its objects are automatically
- unregistered.
-
- Possible Errors:
-
- :org.bluez.Error.InvalidArguments:
- :org.bluez.Error.NotSupported:
-
-void UnregisterPlayer(object player)
-````````````````````````````````````
-
- Unregister sender media player.
-
-void RegisterApplication(object root, dict options)
-```````````````````````````````````````````````````
-
- Register endpoints an player objects within root object which must
- implement ObjectManager.
-
- The application object path together with the D-Bus system bus
- connection ID define the identification of the application.
-
- Possible errors:
-
- :org.bluez.Error.InvalidArguments:
- :org.bluez.Error.AlreadyExists:
-
-void UnregisterApplication(object application)
-``````````````````````````````````````````````
-
- This unregisters the services that has been previously registered. The
- object path parameter must match the same value that has been used on
- registration.
-
- Possible errors:
-
- :org.bluez.Error.InvalidArguments:
- :org.bluez.Error.DoesNotExist:
-
-Properties
-----------
-
-array{string} SupportedUUIDs [readonly]
-```````````````````````````````````````
-
- List of 128-bit UUIDs that represents the supported Endpoint
- registration.
-
-MediaControl interface
-======================
-
-:Service: org.bluez
-:Interface: org.bluez.MediaControl1
-:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
-
-Methods
--------
-
-void Play() [Deprecated]
-````````````````````````
-
- Resume playback.
-
-void Pause() [Deprecated]
-`````````````````````````
-
- Pause playback.
-
-void Stop() [Deprecated]
-````````````````````````
-
- Stop playback.
-
-void Next() [Deprecated]
-````````````````````````
-
- Next item.
-
-void Previous() [Deprecated]
-````````````````````````````
-
- Previous item.
-
-void VolumeUp() [Deprecated]
-````````````````````````````
-
- Adjust remote volume one step up
-
-void VolumeDown() [Deprecated]
-``````````````````````````````
-
- Adjust remote volume one step down
-
-void FastForward() [Deprecated]
-```````````````````````````````
-
- Fast forward playback, this action is only stopped when another method
- in this interface is called.
-
-void Rewind() [Deprecated]
-``````````````````````````
-
- Rewind playback, this action is only stopped when another method in
- this interface is called.
-
-Properties
-----------
-
-boolean Connected [readonly]
-````````````````````````````
-
-object Player [readonly, optional]
-``````````````````````````````````
-
- Addressed Player object path.
-
-MediaPlayer interface
-=====================
-
-:Service: org.bluez (Controller role)
-:Interface: org.bluez.MediaPlayer1
-:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX
-
-Methods
--------
-
-void Play()
-```````````
-
- Resume playback.
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void Pause()
-````````````
-
- Pause playback.
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void Stop()
-```````````
-
- Stop playback.
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void Next()
-```````````
-
- Next item.
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void Previous()
-```````````````
-
- Previous item.
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void FastForward()
-``````````````````
-
- Fast forward playback, this action is only stopped when another method
- in this interface is called.
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void Rewind()
-`````````````
-
- Rewind playback, this action is only stopped when another method in
- this interface is called.
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void Press(byte avc_key)
-````````````````````````
-
- Press a specific key to send as passthrough command. The key will be
- released automatically. Use Hold() instead if the intention is to hold
- down the key.
-
- Possible Errors:
-
- :org.bluez.Error.InvalidArguments:
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void Hold(byte avc_key)
-```````````````````````
-
- Press and hold a specific key to send as passthrough command. It is
- your responsibility to make sure that Release() is called after calling
- this method. The held key will also be released when any other method
- in this interface is called.
-
- Possible Errors:
-
- :org.bluez.Error.InvalidArguments:
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void Release()
-``````````````
-
- Release the previously held key invoked using Hold().
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-Properties
-----------
-
-string Equalizer [readwrite]
-````````````````````````````
-
- Possible values: "off" or "on"
-
-string Repeat [readwrite]
-`````````````````````````
-
- Possible values: "off", "singletrack", "alltracks" or "group"
-
-string Shuffle [readwrite]
-``````````````````````````
-
- Possible values: "off", "alltracks" or "group"
-
-string Scan [readwrite]
-```````````````````````
-
- Possible values: "off", "alltracks" or "group"
-
-string Status [readonly]
-````````````````````````
-
- Possible status: "playing", "stopped", "paused", "forward-seek",
- "reverse-seek" or "error"
-
-uint32 Position [readonly]
-``````````````````````````
-
- Playback position in milliseconds. Changing the position may generate
- additional events that will be sent to the remote device. When position
- is 0 it means the track is starting and when it's greater than or equal
- to track's duration the track has ended.
-
- Note that even if duration is not available in metadata it's possible
- to signal its end by setting position to the maximum uint32 value.
-
-dict Track [readonly]
-`````````````````````
-
- Track metadata.
-
- Possible values:
-
- :string Title:
-
- Track title name
-
- :string Artist:
-
- Track artist name
-
- :string Album:
-
- Track album name
-
- :string Genre:
-
- Track genre name
-
- :uint32 NumberOfTracks:
-
- Number of tracks in total
-
- :uint32 TrackNumber:
-
- Track number
-
- :uint32 Duration:
-
- Track duration in milliseconds
-
-object Device [readonly]
-````````````````````````
-
- Device object path.
-
-string Name [readonly]
-``````````````````````
-
- Player name
-
-string Type [readonly]
-``````````````````````
-
- Player type
-
- Possible values:
-
- "Audio"
- "Video"
- "Audio Broadcasting"
- "Video Broadcasting"
-
-string Subtype [readonly]
-`````````````````````````
-
- Player subtype
-
- Possible values:
-
- "Audio Book"
- "Podcast"
-
-boolean Browsable [readonly]
-````````````````````````````
-
- If present indicates the player can be browsed using MediaFolder
- interface.
-
- Possible values:
-
- :True:
-
- Supported and active
-
- :False:
-
- Supported but inactive
-
- Note: If supported but inactive clients can enable it by using
- MediaFolder interface but it might interfere in the playback of other
- players.
-
-boolean Searchable [readonly]
-`````````````````````````````
-
- If present indicates the player can be searched using MediaFolder
- interface.
-
- Possible values:
-
- :True:
-
- Supported and active
-
- :False:
-
- Supported but inactive
-
- Note: If supported but inactive clients can enable it by using
- MediaFolder interface but it might interfere in the playback of other
- players.
-
-object Playlist
-```````````````
-
- Playlist object path.
-
-MediaFolder interface
-=====================
-
-:Service: unique name (Target role)
- org.bluez (Controller role)
-:Interface: org.bluez.MediaFolder1
-:Object path: freely definable (Target role)
- [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX
- (Controller role)
-
-Methods
--------
-
-object Search(string value, dict filter)
-````````````````````````````````````````
-
- Return a folder object containing the search result.
-
- To list the items found use the folder object returned and pass to
- ChangeFolder.
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-array{objects, properties} ListItems(dict filter)
-`````````````````````````````````````````````````
-
- Return a list of items found
-
- Possible Errors:
-
- :org.bluez.Error.InvalidArguments:
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void ChangeFolder(object folder)
-````````````````````````````````
-
- Change current folder.
-
- Note: By changing folder the items of previous folder might be destroyed
- and have to be listed again, the exception is NowPlaying folder which
- should be always present while the player is active.
-
- Possible Errors:
-
- :org.bluez.Error.InvalidArguments:
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-Properties
-----------
-
-uint32 NumberOfItems [readonly]
-```````````````````````````````
-
- Number of items in the folder
-
-string Name [readonly]
-``````````````````````
-
- Folder name:
-
- Possible values:
-
- :"/Filesystem/...":
-
- Filesystem scope
-
- :"/NowPlaying/...":
-
- NowPlaying scope
-
- Note: /NowPlaying folder might not be listed if player is stopped,
- folders created by Search are virtual so once another Search is perform
- or the folder is changed using ChangeFolder it will no longer be listed.
-
-Filters
--------
-
-:uint32 Start:
-
- Offset of the first item.
-
- Default value: 0
-
-:uint32 End:
-
- Offset of the last item.
-
- Default value: NumbeOfItems
-
-:array{string} Attributes:
-
- Item properties that should be included in the list.
-
- Possible Values:
-
- "title", "artist", "album", "genre", "number-of-tracks",
- "number", "duration"
-
- Default Value: All
-
-MediaItem interface
-===================
-
-:Service: unique name (Target role)
- org.bluez (Controller role)
-:Interface: org.bluez.MediaItem1
-:Object path: freely definable (Target role)
- [variable
- prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX/itemX
- (Controller role)
-
-Methods
--------
-
-void Play()
-```````````
-
- Play item
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-void AddtoNowPlaying()
-``````````````````````
-
- Add item to now playing list
-
- Possible Errors:
-
- :org.bluez.Error.NotSupported:
- :org.bluez.Error.Failed:
-
-Properties
-----------
-
-object Player [readonly]
-````````````````````````
-
- Player object path the item belongs to
-
-string Name [readonly]
-``````````````````````
-
- Item displayable name
-
-string Type [readonly]
-``````````````````````
-
- Item type
-
- Possible values: "video", "audio", "folder"
-
-string FolderType [readonly, optional]
-``````````````````````````````````````
-
- Folder type.
-
- Possible values: "mixed", "titles", "albums", "artists"
-
- Available if property Type is "Folder"
-
-boolean Playable [readonly, optional]
-`````````````````````````````````````
-
- Indicates if the item can be played
-
- Available if property Type is "folder"
-
-dict Metadata [readonly]
-````````````````````````
-
- Item metadata.
-
- Possible values:
-
- :string Title:
-
- Item title name
-
- Available if property Type is "audio" or "video"
-
- :string Artist:
-
- Item artist name
-
- Available if property Type is "audio" or "video"
-
- :string Album:
-
- Item album name
-
- Available if property Type is "audio" or "video"
-
- :string Genre:
-
- Item genre name
-
- Available if property Type is "audio" or "video"
-
- :uint32 NumberOfTracks:
-
- Item album number of tracks in total
-
- Available if property Type is "audio" or "video"
-
- :uint32 Number:
-
- Item album number
-
- Available if property Type is "audio" or "video"
-
- :uint32 Duration:
-
- Item duration in milliseconds
-
- Available if property Type is "audio" or "video"
-
-MediaEndpoint interface
-=======================
-
-:Service: unique name (Server role)
- org.bluez (Client role)
-:Interface: org.bluez.MediaEndpoint1
-:Object path: freely definable (Server role)
- [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/sepX
- (Client role)
-
-Methods
--------
-
-void SetConfiguration(object transport, dict properties)
-````````````````````````````````````````````````````````
-
- Set configuration for the transport.
-
- For client role transport must be set with a server endpoint oject which
- will be configured and the properties must contain the following
- properties:
-
- :array{byte} Capabilities [Mandatory]:
-
- See Endpoint.Capabilities property.
-
- :array{byte} Metadata [ISO only]:
-
- See Endpoint.Metadata property.
-
- :uint32 Location [ISO only]:
-
- See Endpoint.Location property.
-
- :byte Framing [ISO only]:
-
- See Endpoint.Framing property.
-
- :byte PHY [ISO only]:
-
- See Endpoint.PHY property.
-
- :uint16 MaximumLatency [ISO only]:
-
- See Endpoint.MaximumLatency property.
-
- :uint32 MinimumDelay [ISO only]:
-
- See Endpoint.MinimumDelay property.
-
- :uint32 MaximumDelay [ISO only]:
-
- See Endpoint.MaximumDelay property.
-
- :uint32 PreferredMinimumDelay [ISO only]:
-
- See Endpoint.PreferredMinimumDelay property.
-
- :uint32 PreferredMaximumDelay [ISO only]:
-
- See Endpoint.PreferredMaximumDelay property.
-
-
-array{byte} SelectConfiguration(array{byte} capabilities)
-`````````````````````````````````````````````````````````
-
- Select preferable configuration from the supported capabilities.
-
- Returns a configuration which can be used to setup a transport.
-
- Note: There is no need to cache the selected configuration since on
- success the configuration is send back as parameter of SetConfiguration.
-
-dict SelectProperties(dict properties)
-``````````````````````````````````````
-
- Select preferable properties from the supported properties:
-
- :object Endpoint [ISO only]:
- :Refer to SetConfiguration for the list of other possible properties.:
-
- Returns propeties which can be used to setup a transport.
-
- Note: There is no need to cache the selected properties since on
- success the configuration is send back as parameter of SetConfiguration.
-
-void ClearConfiguration(object transport)
-`````````````````````````````````````````
-
- Clear transport configuration.
-
-void Release()
-``````````````
-
- This method gets called when the service daemon unregisters the
- endpoint. An endpoint can use it to do cleanup tasks. There is no need
- to unregister the endpoint, because when this method gets called it has
- already been unregistered.
-
-Properties
-----------
-
-string UUID [readonly, optional]
-````````````````````````````````
-
- UUID of the profile which the endpoint is for.
-
-byte Codec [readonly, optional]
-```````````````````````````````
-
- Assigned number of codec that the endpoint implements.
- The values should match the profile specification which is indicated by
- the UUID.
-
-uint32_t Vendor [readonly, Optional]
-````````````````````````````````````
-
- Vendor-specific Company ID, Codec ID tuple that the endpoint implements.
-
- It shall be set to appropriate value when Vendor Specific Codec (0xff)
- is used.
-
-array{byte} Capabilities [readonly, optional]
-`````````````````````````````````````````````
-
- Capabilities blob, it is used as it is so the size and byte order must
- match.
-
-array{byte} Metadata [readonly, Optional]
-`````````````````````````````````````````
-
- Metadata blob, it is used as it is so the size and byte order must
- match.
-
-object Device [readonly, optional]
-``````````````````````````````````
-
- Device object which the endpoint is belongs to.
-
-bool DelayReporting [readonly, optional]
-````````````````````````````````````````
-
- Indicates if endpoint supports Delay Reporting.
-
-byte Framing [ISO only]
-```````````````````````
-
- Indicates endpoint support framing.
-
-byte PHY [ISO only]
-```````````````````
-
- Indicates endpoint supported PHY.
-
-uint16_t MaximumLatency [ISO only]
-``````````````````````````````````
-
- Indicates endpoint maximum latency.
-
-uint32_t MinimumDelay [ISO only]
-````````````````````````````````
-
- Indicates endpoint minimum presentation delay.
-
-uint32_t MaximumDelay [ISO only]
-````````````````````````````````
-
- Indicates endpoint maximum presentation delay.
-
-uint32_t PreferredMinimumDelay [ISO only]
-`````````````````````````````````````````
-
- Indicates endpoint preferred minimum presentation delay.
-
-uint32_t PreferredMinimumDelay [ISO only]
-`````````````````````````````````````````
-
- Indicates endpoint preferred minimum presentation delay.
-
-uint32 Location [ISO only]
-``````````````````````````
-
- Indicates endpoint supported locations.
-
-uint16 SupportedContext [ISO only]
-``````````````````````````````````
-
- Indicates endpoint supported audio context.
-
-uint16 Context [ISO only]
-`````````````````````````
-
- Indicates endpoint available audio context.
-
-MediaTransport interface
-========================
-
-:Service: org.bluez
-:Interface: org.bluez.MediaTransport1
-:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/fdX
-
-Methods
--------
-
-fd, uint16, uint16 Acquire()
-````````````````````````````
-
- Acquire transport file descriptor and the MTU for read and write
- respectively.
-
- Possible Errors:
-
- :org.bluez.Error.NotAuthorized:
- :org.bluez.Error.Failed:
-
-fd, uint16, uint16 TryAcquire()
-```````````````````````````````
-
- Acquire transport file descriptor only if the transport is in "pending"
- state at the time the message is received by BlueZ. Otherwise no request
- will be sent to the remote device and the function will just fail with
- org.bluez.Error.NotAvailable.
-
- Possible Errors:
-
- :org.bluez.Error.NotAuthorized:
- :org.bluez.Error.Failed:
- :org.bluez.Error.NotAvailable:
-
-void Release()
-``````````````
-
- Releases file descriptor.
-
-Properties
-----------
-
-object Device [readonly]
-````````````````````````
-
- Device object which the transport is connected to.
-
-string UUID [readonly]
-``````````````````````
-
- UUID of the profile which the transport is for.
-
-byte Codec [readonly]
-`````````````````````
-
- Assigned number of codec that the transport support.
- The values should match the profile specification which is indicated by
- the UUID.
-
-array{byte} Configuration [readonly]
-````````````````````````````````````
-
- Configuration blob, it is used as it is so the size and byte order must
- match.
-
-string State [readonly]
-```````````````````````
-
- Indicates the state of the transport. Possible values are:
-
- :"idle": not streaming
- :"pending": streaming but not acquired
- :"active": streaming and acquired
-
-uint16 Delay [readwrite, optional]
-``````````````````````````````````
-
- Transport delay in 1/10 of millisecond, this property is only writeable
- when the transport was acquired by the sender.
-
-uint16 Volume [readwrite, optional]
-```````````````````````````````````
-
- Indicates volume level of the transport, this property is only writeable
- when the transport was acquired by the sender.
-
- Possible Values: 0-127
-
-object Endpoint [readonly, optional, experimental]
-``````````````````````````````````````````````````
-
- Endpoint object which the transport is associated with.
-
-uint32 Location [readonly, ISO only, experimental]
-``````````````````````````````````````````````````
-
- Indicates transport Audio Location.
-
-array{byte} Metadata [readwrite, ISO Only, experimental]
-````````````````````````````````````````````````````````
-
- Indicates transport Metadata.
-
-array{object} Links [readonly, optional, ISO only, experimental]
-````````````````````````````````````````````````````````````````
-
- Linked transport objects which the transport is associated with.
-
-dict QoS [readonly, optional, ISO only, experimental]
-`````````````````````````````````````````````````````
-
- Only present when QoS is configured.
-
- Possible values for Unicast:
-
- :byte CIG:
-
- Indicates configured CIG.
-
- Possible values:
-
- :0x00 - 0xef:
-
- Valid ID range.
-
- :0xff:
-
- Auto allocate.
-
- :byte CIS:
-
- Indicates configured CIS.
-
- Possible values:
-
- :0x00 - 0xef:
-
- Valid ID range.
-
- :0xff:
-
- Auto allocate.
-
- :byte Framing:
-
- Indicates configured framing.
-
- Possible values:
-
- :0x00:
-
- Unframed.
-
- :0x01:
-
- Framed.
-
- :uint32 PresentationDelay:
-
- Indicates configured transport presentation delay (us).
-
- :byte TargetLatency:
-
- Indicates the requested target latency.
-
- Possible values:
-
- :0x01:
-
- Low Latency.
-
- :0x02:
-
- Balanced Latency/Reliability.
-
- :0x03:
-
- High Reliability.
-
- Possible values for Broadcast:
-
- :byte BIG:
-
- Indicates configured QoS BIG.
-
- :byte BIS:
-
- Indicates configured BIS.
-
- :byte SyncFactor:
-
- Indicates configured broadcast sync factor.
-
- :byte Packing:
-
- Indicates configured packing.
-
- :byte Framing:
-
- Indicates configured framing.
-
- :byte Options:
-
- Indicates configured broadcast options.
-
- :uint16 Skip:
-
- Indicates configured broadcast skip.
-
- :byte SyncTimeout:
-
- Indicates configured broadcast sync timeout.
-
- :byte SyncType:
-
- Indicates configured broadcast sync CTE type.
-
- :byte MSE:
-
- Indicates configured broadcast MSE.
-
- :uint16 Timeout:
-
- Indicates configured broadcast timeout.
-
- Possible values for both Unicast and Broadcast:
-
- :uint32 Interval:
-
- Indicates configured ISO interval (us).
-
- :uint16 Latency:
-
- Indicates configured transport latency (ms).
-
- :uint16 SDU:
-
- Indicates configured maximum SDU.
-
- :byte PHY:
-
- Indicates configured PHY.
-
- Possible values:
-
- :bit 0:
-
- LE 1M
-
- :bit 1:
-
- LE 2M
-
- :bit 2:
-
- LE Coded
-
- :byte Retransmissions:
-
- Indicates configured retransmissions.
diff --git a/doc/org.bluez.Media.rst b/doc/org.bluez.Media.rst
new file mode 100644
index 000000000000..678e6090c6e1
--- /dev/null
+++ b/doc/org.bluez.Media.rst
@@ -0,0 +1,133 @@
+===============
+org.bluez.Media
+===============
+
+-----------------------------------
+BlueZ D-Bus Media API documentation
+-----------------------------------
+
+:Version: BlueZ
+:Date: September 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez
+:Interface: org.bluez.Media1
+:Object path: [variable prefix]/{hci0,hci1,...}
+
+Methods
+-------
+
+void RegisterEndpoint(object endpoint, dict properties)
+```````````````````````````````````````````````````````
+
+ Register a local end point to sender, the sender can register as many
+ end points as it likes.
+
+ Note: If the sender disconnects the end points are automatically
+ unregistered.
+
+ possible properties:
+
+ :string UUID:
+
+ UUID of the profile which the endpoint is for.
+
+ UUID must be in the list of SupportedUUIDS.
+
+ :byte Codec:
+
+ Assigned number of codec that the endpoint implements. The
+ values should match the profile specification which is
+ indicated by the UUID.
+
+ :uint32_t Vendor [Optional]:
+
+ Vendor-specific Company ID, Codec ID tuple that the endpoint
+ implements.
+
+ It shall be set to appropriate value when Vendor Specific Codec
+ (0xff) is used.
+
+ :array{byte} Capabilities:
+
+ Capabilities blob, it is used as it is so the size and byte
+ order must match.
+
+ :array{byte} Metadata [Optional]:
+
+ Metadata blob, it is used as it is so the size and byte order
+ must match.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+
+ emitted when interface for the end-point is disabled
+
+void UnregisterEndpoint(object endpoint)
+````````````````````````````````````````
+ Unregister sender end point.
+
+void RegisterPlayer(object player, dict properties)
+```````````````````````````````````````````````````
+
+ Register a media player object to sender, the sender can register as
+ many objects as it likes.
+
+ Object must implement at least org.mpris.MediaPlayer2.Player as defined
+ in MPRIS 2.2 spec:
+
+ http://specifications.freedesktop.org/mpris-spec/latest/
+
+ Note: If the sender disconnects its objects are automatically
+ unregistered.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+
+void UnregisterPlayer(object player)
+````````````````````````````````````
+
+ Unregister sender media player.
+
+void RegisterApplication(object root, dict options)
+```````````````````````````````````````````````````
+
+ Register endpoints an player objects within root object which must
+ implement ObjectManager.
+
+ The application object path together with the D-Bus system bus
+ connection ID define the identification of the application.
+
+ Possible errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.AlreadyExists:
+
+void UnregisterApplication(object application)
+``````````````````````````````````````````````
+
+ This unregisters the services that has been previously registered. The
+ object path parameter must match the same value that has been used on
+ registration.
+
+ Possible errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.DoesNotExist:
+
+Properties
+----------
+
+array{string} SupportedUUIDs [readonly]
+```````````````````````````````````````
+
+ List of 128-bit UUIDs that represents the supported Endpoint
+ registration.
diff --git a/doc/org.bluez.MediaControl.rst b/doc/org.bluez.MediaControl.rst
new file mode 100644
index 000000000000..54e84e8c62eb
--- /dev/null
+++ b/doc/org.bluez.MediaControl.rst
@@ -0,0 +1,80 @@
+======================
+org.bluez.MediaControl
+======================
+
+------------------------------------------
+BlueZ D-Bus MediaControl API documentation
+------------------------------------------
+
+:Version: BlueZ
+:Date: September 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez
+:Interface: org.bluez.MediaControl1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Methods
+-------
+
+void Play() [Deprecated]
+````````````````````````
+
+ Resume playback.
+
+void Pause() [Deprecated]
+`````````````````````````
+
+ Pause playback.
+
+void Stop() [Deprecated]
+````````````````````````
+
+ Stop playback.
+
+void Next() [Deprecated]
+````````````````````````
+
+ Next item.
+
+void Previous() [Deprecated]
+````````````````````````````
+
+ Previous item.
+
+void VolumeUp() [Deprecated]
+````````````````````````````
+
+ Adjust remote volume one step up
+
+void VolumeDown() [Deprecated]
+``````````````````````````````
+
+ Adjust remote volume one step down
+
+void FastForward() [Deprecated]
+```````````````````````````````
+
+ Fast forward playback, this action is only stopped when another method
+ in this interface is called.
+
+void Rewind() [Deprecated]
+``````````````````````````
+
+ Rewind playback, this action is only stopped when another method in
+ this interface is called.
+
+Properties
+----------
+
+boolean Connected [readonly]
+````````````````````````````
+
+object Player [readonly, optional]
+``````````````````````````````````
+
+ Addressed Player object path.
diff --git a/doc/org.bluez.MediaEndpoint.rst b/doc/org.bluez.MediaEndpoint.rst
new file mode 100644
index 000000000000..6d00a6d05e8a
--- /dev/null
+++ b/doc/org.bluez.MediaEndpoint.rst
@@ -0,0 +1,219 @@
+=======================
+org.bluez.MediaEndpoint
+=======================
+
+-------------------------------------------
+BlueZ D-Bus MediaEndpoint API documentation
+-------------------------------------------
+
+:Version: BlueZ
+:Date: September 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: unique name (Server role)
+ org.bluez (Client role)
+:Interface: org.bluez.MediaEndpoint1
+:Object path: freely definable (Server role)
+ [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/sepX
+ (Client role)
+
+Methods
+-------
+
+void SetConfiguration(object transport, dict properties)
+````````````````````````````````````````````````````````
+
+ Set configuration for the transport.
+
+ For client role transport must be set with a server endpoint oject which
+ will be configured and the properties must contain the following
+ properties:
+
+ :array{byte} Capabilities [Mandatory]:
+
+ See Capabilities property.
+
+ :array{byte} Metadata [ISO only]:
+
+ See Metadata property.
+
+ :uint32 Location [ISO only]:
+
+ See Location property.
+
+ :byte Framing [ISO only]:
+
+ See Framing property.
+
+ :byte PHY [ISO only]:
+
+ See PHY property.
+
+ :uint16 MaximumLatency [ISO only]:
+
+ See MaximumLatency property.
+
+ :uint32 MinimumDelay [ISO only]:
+
+ See MinimumDelay property.
+
+ :uint32 MaximumDelay [ISO only]:
+
+ See MaximumDelay property.
+
+ :uint32 PreferredMinimumDelay [ISO only]:
+
+ See PreferredMinimumDelay property.
+
+ :uint32 PreferredMaximumDelay [ISO only]:
+
+ See PreferredMaximumDelay property.
+
+array{byte} SelectConfiguration(array{byte} capabilities)
+`````````````````````````````````````````````````````````
+
+ Select preferable configuration from the supported capabilities.
+
+ Returns a configuration which can be used to setup a transport.
+
+ Note: There is no need to cache the selected configuration since on
+ success the configuration is send back as parameter of SetConfiguration.
+
+dict SelectProperties(dict properties)
+``````````````````````````````````````
+
+ Select preferable properties from the supported properties:
+
+ :object Endpoint [ISO only]:
+ :Refer to SetConfiguration for the list of other possible properties.:
+
+ Returns propeties which can be used to setup a transport.
+
+ Note: There is no need to cache the selected properties since on
+ success the configuration is send back as parameter of SetConfiguration.
+
+void ClearConfiguration(object transport)
+`````````````````````````````````````````
+
+ Clear transport configuration.
+
+void Release()
+``````````````
+
+ This method gets called when the service daemon unregisters the
+ endpoint. An endpoint can use it to do cleanup tasks. There is no need
+ to unregister the endpoint, because when this method gets called it has
+ already been unregistered.
+
+MediaEndpoint Properties
+------------------------
+
+string UUID [readonly, optional]
+````````````````````````````````
+
+ UUID of the profile which the endpoint is for.
+
+byte Codec [readonly, optional]
+```````````````````````````````
+
+ Assigned number of codec that the endpoint implements.
+ The values should match the profile specification which is indicated by
+ the UUID.
+
+uint32_t Vendor [readonly, Optional]
+````````````````````````````````````
+
+ Vendor-specific Company ID, Codec ID tuple that the endpoint implements.
+
+ It shall be set to appropriate value when Vendor Specific Codec (0xff)
+ is used.
+
+array{byte} Capabilities [readonly, optional]
+`````````````````````````````````````````````
+
+ Capabilities blob, it is used as it is so the size and byte order must
+ match.
+
+array{byte} Metadata [readonly, Optional]
+`````````````````````````````````````````
+
+ Metadata blob, it is used as it is so the size and byte order must
+ match.
+
+object Device [readonly, optional]
+``````````````````````````````````
+
+ Device object which the endpoint is belongs to.
+
+bool DelayReporting [readonly, optional]
+````````````````````````````````````````
+
+ Indicates if endpoint supports Delay Reporting.
+
+byte Framing [ISO only]
+```````````````````````
+
+ Indicates endpoint support framing.
+
+byte PHY [ISO only]
+```````````````````
+
+ Indicates endpoint supported PHY.
+
+ Possible values:
+
+ :bit 0:
+
+ LE 1M
+
+ :bit 1:
+
+ LE 2M
+
+ :bit 2:
+
+ LE Coded
+
+uint16_t MaximumLatency [ISO only]
+``````````````````````````````````
+
+ Indicates endpoint maximum latency.
+
+uint32_t MinimumDelay [ISO only]
+````````````````````````````````
+
+ Indicates endpoint minimum presentation delay.
+
+uint32_t MaximumDelay [ISO only]
+````````````````````````````````
+
+ Indicates endpoint maximum presentation delay.
+
+uint32_t PreferredMinimumDelay [ISO only]
+`````````````````````````````````````````
+
+ Indicates endpoint preferred minimum presentation delay.
+
+uint32_t PreferredMaximumDelay [ISO only]
+`````````````````````````````````````````
+
+ Indicates endpoint preferred maximum presentation delay.
+
+uint32 Location [ISO only]
+``````````````````````````
+
+ Indicates endpoint supported locations.
+
+uint16 SupportedContext [ISO only]
+``````````````````````````````````
+
+ Indicates endpoint supported audio context.
+
+uint16 Context [ISO only]
+`````````````````````````
+
+ Indicates endpoint available audio context.
diff --git a/doc/org.bluez.MediaFolder.rst b/doc/org.bluez.MediaFolder.rst
new file mode 100644
index 000000000000..dd56f06b41e4
--- /dev/null
+++ b/doc/org.bluez.MediaFolder.rst
@@ -0,0 +1,117 @@
+=====================
+org.bluez.MediaFolder
+=====================
+
+-----------------------------------------
+BlueZ D-Bus MediaFolder API documentation
+-----------------------------------------
+
+:Version: BlueZ
+:Date: September 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: unique name (Target role)
+ org.bluez (Controller role)
+:Interface: org.bluez.MediaFolder1
+:Object path: freely definable (Target role)
+ [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX
+ (Controller role)
+
+Methods
+-------
+
+object Search(string value, dict filter)
+````````````````````````````````````````
+
+ Return a folder object containing the search result.
+
+ To list the items found use the folder object returned and pass to
+ ChangeFolder.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+array{objects, properties} ListItems(dict filter)
+`````````````````````````````````````````````````
+
+ Return a list of items found
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void ChangeFolder(object folder)
+````````````````````````````````
+
+ Change current folder.
+
+ Note: By changing folder the items of previous folder might be destroyed
+ and have to be listed again, the exception is NowPlaying folder which
+ should be always present while the player is active.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+Properties
+----------
+
+uint32 NumberOfItems [readonly]
+```````````````````````````````
+
+ Number of items in the folder
+
+string Name [readonly]
+``````````````````````
+
+ Folder name:
+
+ Possible values:
+
+ :"/Filesystem/...":
+
+ Filesystem scope
+
+ :"/NowPlaying/...":
+
+ NowPlaying scope
+
+ Note: /NowPlaying folder might not be listed if player is stopped,
+ folders created by Search are virtual so once another Search is perform
+ or the folder is changed using ChangeFolder it will no longer be listed.
+
+Filters
+-------
+
+:uint32 Start:
+
+ Offset of the first item.
+
+ Default value: 0
+
+:uint32 End:
+
+ Offset of the last item.
+
+ Default value: NumbeOfItems
+
+:array{string} Attributes:
+
+ Item properties that should be included in the list.
+
+ Possible Values:
+
+ "title", "artist", "album", "genre", "number-of-tracks",
+ "number", "duration"
+
+ Default Value: All
diff --git a/doc/org.bluez.MediaItem.rst b/doc/org.bluez.MediaItem.rst
new file mode 100644
index 000000000000..855e8a6395b7
--- /dev/null
+++ b/doc/org.bluez.MediaItem.rst
@@ -0,0 +1,131 @@
+===================
+org.bluez.MediaItem
+===================
+
+---------------------------------------
+BlueZ D-Bus MediaItem API documentation
+---------------------------------------
+
+:Version: BlueZ
+:Date: September 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: unique name (Target role)
+ org.bluez (Controller role)
+:Interface: org.bluez.MediaItem1
+:Object path: freely definable (Target role)
+ [variable
+ prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX/itemX
+ (Controller role)
+
+Methods
+-------
+
+void Play()
+```````````
+
+ Play item
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void AddtoNowPlaying()
+``````````````````````
+
+ Add item to now playing list
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+Properties
+----------
+
+object Player [readonly]
+````````````````````````
+
+ Player object path the item belongs to
+
+string Name [readonly]
+``````````````````````
+
+ Item displayable name
+
+string Type [readonly]
+``````````````````````
+
+ Item type
+
+ Possible values: "video", "audio", "folder"
+
+string FolderType [readonly, optional]
+``````````````````````````````````````
+
+ Folder type.
+
+ Possible values: "mixed", "titles", "albums", "artists"
+
+ Available if property Type is "Folder"
+
+boolean Playable [readonly, optional]
+`````````````````````````````````````
+
+ Indicates if the item can be played
+
+ Available if property Type is "folder"
+
+dict Metadata [readonly]
+````````````````````````
+
+ Item metadata.
+
+ Possible values:
+
+ :string Title:
+
+ Item title name
+
+ Available if property Type is "audio" or "video"
+
+ :string Artist:
+
+ Item artist name
+
+ Available if property Type is "audio" or "video"
+
+ :string Album:
+
+ Item album name
+
+ Available if property Type is "audio" or "video"
+
+ :string Genre:
+
+ Item genre name
+
+ Available if property Type is "audio" or "video"
+
+ :uint32 NumberOfTracks:
+
+ Item album number of tracks in total
+
+ Available if property Type is "audio" or "video"
+
+ :uint32 Number:
+
+ Item album number
+
+ Available if property Type is "audio" or "video"
+
+ :uint32 Duration:
+
+ Item duration in milliseconds
+
+ Available if property Type is "audio" or "video"
diff --git a/doc/org.bluez.MediaPlayer.rst b/doc/org.bluez.MediaPlayer.rst
new file mode 100644
index 000000000000..60bd679bb7c0
--- /dev/null
+++ b/doc/org.bluez.MediaPlayer.rst
@@ -0,0 +1,315 @@
+=====================
+org.bluez.MediaPlayer
+=====================
+
+-----------------------------------------
+BlueZ D-Bus MediaPlayer API documentation
+-----------------------------------------
+
+:Version: BlueZ
+:Date: September 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez (Controller role)
+:Interface: org.bluez.MediaPlayer1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX
+
+Methods
+-------
+
+void Play()
+```````````
+
+ Resume playback.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Pause()
+````````````
+
+ Pause playback.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Stop()
+```````````
+
+ Stop playback.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Next()
+```````````
+
+ Next item.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Previous()
+```````````````
+
+ Previous item.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void FastForward()
+``````````````````
+
+ Fast forward playback, this action is only stopped when another method
+ in this interface is called.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Rewind()
+`````````````
+
+ Rewind playback, this action is only stopped when another method in
+ this interface is called.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Press(byte avc_key)
+````````````````````````
+
+ Press a specific key to send as passthrough command. The key will be
+ released automatically. Use Hold() instead if the intention is to hold
+ down the key.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Hold(byte avc_key)
+```````````````````````
+
+ Press and hold a specific key to send as passthrough command. It is
+ your responsibility to make sure that Release() is called after calling
+ this method. The held key will also be released when any other method
+ in this interface is called.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Release()
+``````````````
+
+ Release the previously held key invoked using Hold().
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+Properties
+----------
+
+string Equalizer [readwrite]
+````````````````````````````
+
+ Indicates Player Equalizer setting.
+
+ Possible values:
+
+ :"off":
+ :"on":
+
+string Repeat [readwrite]
+`````````````````````````
+
+ Indicates Player Repeat setting.
+
+ Possible values:
+
+ :"off":
+ :"singletrack":
+ :"alltracks":
+ :"group":
+
+string Shuffle [readwrite]
+``````````````````````````
+
+ Indicates Player Suffle setting.
+
+ Possible values:
+
+ :"off":
+ :"alltracks":
+ :"group":
+
+string Scan [readwrite]
+```````````````````````
+
+ Indicates Player Scan setting.
+
+ Possible values:
+
+ :"off":
+ :"alltracks":
+ :"group":
+
+string Status [readonly]
+````````````````````````
+
+ Indicates Player Status setting.
+
+ Possible status:
+
+ :"playing":
+ :"stopped":
+ :"paused":
+ :"forward-seek":
+ :"reverse-seek":
+ :"error":
+
+uint32 Position [readonly]
+``````````````````````````
+
+ Playback position in milliseconds. Changing the position may generate
+ additional events that will be sent to the remote device. When position
+ is 0 it means the track is starting and when it's greater than or equal
+ to track's duration the track has ended.
+
+ Note that even if duration is not available in metadata it's possible
+ to signal its end by setting position to the maximum uint32 value.
+
+dict Track [readonly]
+`````````````````````
+
+ Track metadata.
+
+ Possible values:
+
+ :string Title:
+
+ Track title name
+
+ :string Artist:
+
+ Track artist name
+
+ :string Album:
+
+ Track album name
+
+ :string Genre:
+
+ Track genre name
+
+ :uint32 NumberOfTracks:
+
+ Number of tracks in total
+
+ :uint32 TrackNumber:
+
+ Track number
+
+ :uint32 Duration:
+
+ Track duration in milliseconds
+
+object Device [readonly]
+````````````````````````
+
+ Device object path.
+
+string Name [readonly]
+``````````````````````
+
+ Player name
+
+string Type [readonly]
+``````````````````````
+
+ Player type
+
+ Possible values:
+
+ "Audio"
+ "Video"
+ "Audio Broadcasting"
+ "Video Broadcasting"
+
+string Subtype [readonly]
+`````````````````````````
+
+ Player subtype
+
+ Possible values:
+
+ "Audio Book"
+ "Podcast"
+
+boolean Browsable [readonly]
+````````````````````````````
+
+ If present indicates the player can be browsed using MediaFolder
+ interface.
+
+ Possible values:
+
+ :True:
+
+ Supported and active
+
+ :False:
+
+ Supported but inactive
+
+ Note: If supported but inactive clients can enable it by using
+ MediaFolder interface but it might interfere in the playback of other
+ players.
+
+boolean Searchable [readonly]
+`````````````````````````````
+
+ If present indicates the player can be searched using MediaFolder
+ interface.
+
+ Possible values:
+
+ :True:
+
+ Supported and active
+
+ :False:
+
+ Supported but inactive
+
+ Note: If supported but inactive clients can enable it by using
+ MediaFolder interface but it might interfere in the playback of other
+ players.
+
+object Playlist
+```````````````
+
+ Playlist object path.
diff --git a/doc/org.bluez.MediaTransport.rst b/doc/org.bluez.MediaTransport.rst
new file mode 100644
index 000000000000..6e95df8f2ee8
--- /dev/null
+++ b/doc/org.bluez.MediaTransport.rst
@@ -0,0 +1,274 @@
+========================
+org.bluez.MediaTransport
+========================
+
+--------------------------------------------
+BlueZ D-Bus MediaTransport API documentation
+--------------------------------------------
+
+:Version: BlueZ
+:Date: September 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez
+:Interface: org.bluez.MediaTransport1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/fdX
+
+Methods
+-------
+
+fd, uint16, uint16 Acquire()
+````````````````````````````
+
+ Acquire transport file descriptor and the MTU for read and write
+ respectively.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotAuthorized:
+ :org.bluez.Error.Failed:
+
+fd, uint16, uint16 TryAcquire()
+```````````````````````````````
+
+ Acquire transport file descriptor only if the transport is in "pending"
+ state at the time the message is received by BlueZ. Otherwise no request
+ will be sent to the remote device and the function will just fail with
+ org.bluez.Error.NotAvailable.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotAuthorized:
+ :org.bluez.Error.Failed:
+ :org.bluez.Error.NotAvailable:
+
+void Release()
+``````````````
+
+ Releases file descriptor.
+
+Properties
+----------
+
+object Device [readonly]
+````````````````````````
+
+ Device object which the transport is connected to.
+
+string UUID [readonly]
+``````````````````````
+
+ UUID of the profile which the transport is for.
+
+byte Codec [readonly]
+`````````````````````
+
+ Assigned number of codec that the transport support.
+ The values should match the profile specification which is indicated by
+ the UUID.
+
+array{byte} Configuration [readonly]
+````````````````````````````````````
+
+ Configuration blob, it is used as it is so the size and byte order must
+ match.
+
+string State [readonly]
+```````````````````````
+
+ Indicates the state of the transport. Possible values are:
+
+ :"idle": not streaming
+ :"pending": streaming but not acquired
+ :"active": streaming and acquired
+
+uint16 Delay [readwrite, optional]
+``````````````````````````````````
+
+ Transport delay in 1/10 of millisecond, this property is only writeable
+ when the transport was acquired by the sender.
+
+uint16 Volume [readwrite, optional]
+```````````````````````````````````
+
+ Indicates volume level of the transport, this property is only writeable
+ when the transport was acquired by the sender.
+
+ Possible Values: 0-127
+
+object Endpoint [readonly, optional, experimental]
+``````````````````````````````````````````````````
+
+ Endpoint object which the transport is associated with.
+
+uint32 Location [readonly, ISO only, experimental]
+``````````````````````````````````````````````````
+
+ Indicates transport Audio Location.
+
+array{byte} Metadata [readwrite, ISO Only, experimental]
+````````````````````````````````````````````````````````
+
+ Indicates transport Metadata.
+
+array{object} Links [readonly, optional, ISO only, experimental]
+````````````````````````````````````````````````````````````````
+
+ Linked transport objects which the transport is associated with.
+
+dict QoS [readonly, optional, ISO only, experimental]
+`````````````````````````````````````````````````````
+
+ Only present when QoS is configured.
+
+ Possible values for Unicast:
+
+ :byte CIG:
+
+ Indicates configured CIG.
+
+ Possible values:
+
+ :0x00 - 0xef:
+
+ Valid ID range.
+
+ :0xff:
+
+ Auto allocate.
+
+ :byte CIS:
+
+ Indicates configured CIS.
+
+ Possible values:
+
+ :0x00 - 0xef:
+
+ Valid ID range.
+
+ :0xff:
+
+ Auto allocate.
+
+ :byte Framing:
+
+ Indicates configured framing.
+
+ Possible values:
+
+ :0x00:
+
+ Unframed.
+
+ :0x01:
+
+ Framed.
+
+ :uint32 PresentationDelay:
+
+ Indicates configured transport presentation delay (us).
+
+ :byte TargetLatency:
+
+ Indicates the requested target latency.
+
+ Possible values:
+
+ :0x01:
+
+ Low Latency.
+
+ :0x02:
+
+ Balanced Latency/Reliability.
+
+ :0x03:
+
+ High Reliability.
+
+ Possible values for Broadcast:
+
+ :byte BIG:
+
+ Indicates configured QoS BIG.
+
+ :byte BIS:
+
+ Indicates configured BIS.
+
+ :byte SyncFactor:
+
+ Indicates configured broadcast sync factor.
+
+ :byte Packing:
+
+ Indicates configured packing.
+
+ :byte Framing:
+
+ Indicates configured framing.
+
+ :byte Options:
+
+ Indicates configured broadcast options.
+
+ :uint16 Skip:
+
+ Indicates configured broadcast skip.
+
+ :byte SyncTimeout:
+
+ Indicates configured broadcast sync timeout.
+
+ :byte SyncType:
+
+ Indicates configured broadcast sync CTE type.
+
+ :byte MSE:
+
+ Indicates configured broadcast MSE.
+
+ :uint16 Timeout:
+
+ Indicates configured broadcast timeout.
+
+ Possible values for both Unicast and Broadcast:
+
+ :uint32 Interval:
+
+ Indicates configured ISO interval (us).
+
+ :uint16 Latency:
+
+ Indicates configured transport latency (ms).
+
+ :uint16 SDU:
+
+ Indicates configured maximum SDU.
+
+ :byte PHY:
+
+ Indicates configured PHY.
+
+ Possible values:
+
+ :bit 0:
+
+ LE 1M
+
+ :bit 1:
+
+ LE 2M
+
+ :bit 2:
+
+ LE Coded
+
+ :byte Retransmissions:
+
+ Indicates configured retransmissions.
--
2.41.0

2023-09-23 09:14:40

by Pauli Virtanen

Subject: Re: [PATCH v2 6/6] doc/media: Convert media-api.rst into manpages

Hi Luiz,

pe, 2023-09-22 kello 12:23 -0700, Luiz Augusto von Dentz kirjoitti:
> From: Luiz Augusto von Dentz <[email protected]>
>
> This splits media-api.rst into org.bluez.Media<interface>.rst and
> generate manpages for them.

I made a pass looking at the implementations of the transport/endpoint
and SetConfiguration/SelectProperties/SelectConfiguration and comparing
to docs.

Note that the SelectProperties API has a problem with BAP endpoint
configuration. We maybe should redesign it while we still can?

I think generally at least from Pipewire side there's no need to keep
backward compatibility while this is experimental. We can target BlueZ
master branch.


SelectProperties API problem:

As BAP client one first does Config Codec (ASCS §5.1) which takes
Target_Latency, Target_PHY and Codec.

After this, the ASE properties (ACSS Table 4.3) in Codec Configured
state contain the server supported values for Max_Transport_Latency,
Presentation_Delay_Min/Max etc.

SelectProperties is called before Config Codec, so it cannot
necessarily know the server supported values. In this case the sound
server cannot fill in QoS correctly.

The client-invoked SetConfiguration API also seems to have similar
issue.

Probably: SelectProperties should be called twice, once to get
parameters for Config Codec, and then again to get parameters for
Config QoS. Or, there should be a separate "SelectCodec" and
"SelectQoS" calls. Calling "SelectProperties" twice could be simpler
for everyone. 

In client-invoked "SetConfiguration" API, one probably should only pass
in the parameters needed for Config Codec, and BlueZ should then make a
SelectProperties call to get the QoS ones once the server-side values
are known.

I can take a look at this...


MediaTransport:

"Delay" field only exists for A2DP in code.

"Volume" field only exists for A2DP in code.

"Links" is ucast only in code.

"QoS.TargetLatency" does not exist in code. Maybe it should be exposed
for consistency, since it's expected as return from SelectProperties.


SetConfiguration:

SetConfiguration properties dict when called by BlueZ contains exactly
the properties of the transport. The documentation probably should say
that this is so.

When called by client, the contents of the properties dict are expected
to be different. QoS parameters are not packed in a "QoS" dict. Maybe
they should be. The "PHY" key is also still a string here.

The documented input parameters expected from client are wrong, the
documentation explains fields of struct bt_bap_pac_qos, but what the
code parses are that of struct bt_bap_qos.

"MaximumLatency": no such field in code, seems to be called "Latency"
everywhere.


SelectProperties:

In code, the return parameter expects QoS parameters (struct
bt_bap_qos) to be packed in "QoS" dict.

They are not packed in "QoS" dict in the input parameters. These are
not exactly QoS, but instead struct bt_bap_pac_qos, so not clear if
they should be packed.

The input and return parameters are not documented. The input QoS
contains fields of struct bt_bap_pac_qos. The return QoS has fields of
struct bt_bap_qos.


MediaEndpoint:

The endpoints published by BlueZ only have the properties
"UUID", "Codec", "Capabilities", "Device".

The documentation lists various other things, but they are not
implemented as server endpoint properties.

As client endpoint properties:

"RTN" is expected to be present in code, but is not documented.

"MaximumLatency" "Location" "SupportedContext" "Context" are documented
but not present in code.


--
Pauli Virtanen

2023-09-23 11:35:50

by Pauli Virtanen

Subject: Re: [PATCH v2 6/6] doc/media: Convert media-api.rst into manpages

Hi,

la, 2023-09-23 kello 12:14 +0300, Pauli Virtanen kirjoitti:
> Hi Luiz,
>
> pe, 2023-09-22 kello 12:23 -0700, Luiz Augusto von Dentz kirjoitti:
> > From: Luiz Augusto von Dentz <[email protected]>
> >
> > This splits media-api.rst into org.bluez.Media<interface>.rst and
> > generate manpages for them.
>
> I made a pass looking at the implementations of the transport/endpoint
> and SetConfiguration/SelectProperties/SelectConfiguration and comparing
> to docs.
>
> Note that the SelectProperties API has a problem with BAP endpoint
> configuration. We maybe should redesign it while we still can?
>
> I think generally at least from Pipewire side there's no need to keep
> backward compatibility while this is experimental. We can target BlueZ
> master branch.
>
>
> SelectProperties API problem:
>
> As BAP client one first does Config Codec (ASCS §5.1) which takes
> Target_Latency, Target_PHY and Codec.
>
> After this, the ASE properties (ACSS Table 4.3) in Codec Configured
> state contain the server supported values for Max_Transport_Latency,
> Presentation_Delay_Min/Max etc.
>
> SelectProperties is called before Config Codec, so it cannot
> necessarily know the server supported values. In this case the sound
> server cannot fill in QoS correctly.
>
> The client-invoked SetConfiguration API also seems to have similar
> issue.
>
> Probably: SelectProperties should be called twice, once to get
> parameters for Config Codec, and then again to get parameters for
> Config QoS. Or, there should be a separate "SelectCodec" and
> "SelectQoS" calls. Calling "SelectProperties" twice could be simpler
> for everyone. 
>
> In client-invoked "SetConfiguration" API, one probably should only pass
> in the parameters needed for Config Codec, and BlueZ should then make a
> SelectProperties call to get the QoS ones once the server-side values
> are known.
>
> I can take a look at this...
>
>
> MediaTransport:
>
> "Delay" field only exists for A2DP in code.
>
> "Volume" field only exists for A2DP in code.
>
> "Links" is ucast only in code.
>
> "QoS.TargetLatency" does not exist in code. Maybe it should be exposed
> for consistency, since it's expected as return from SelectProperties.
>
>
> SetConfiguration:
>
> SetConfiguration properties dict when called by BlueZ contains exactly
> the properties of the transport. The documentation probably should say
> that this is so.
>
> When called by client, the contents of the properties dict are expected
> to be different. QoS parameters are not packed in a "QoS" dict. Maybe
> they should be. The "PHY" key is also still a string here.

Also, "Framing" is boolean here (elsewhere it's byte).

>
> The documented input parameters expected from client are wrong, the
> documentation explains fields of struct bt_bap_pac_qos, but what the
> code parses are that of struct bt_bap_qos.
>
> "MaximumLatency": no such field in code, seems to be called "Latency"
> everywhere.
>
>
> SelectProperties:
>
> In code, the return parameter expects QoS parameters (struct
> bt_bap_qos) to be packed in "QoS" dict.
>
> They are not packed in "QoS" dict in the input parameters. These are
> not exactly QoS, but instead struct bt_bap_pac_qos, so not clear if
> they should be packed.
>
> The input and return parameters are not documented. The input QoS
> contains fields of struct bt_bap_pac_qos. The return QoS has fields of
> struct bt_bap_qos.
>
>
> MediaEndpoint:
>
> The endpoints published by BlueZ only have the properties
> "UUID", "Codec", "Capabilities", "Device".
>
> The documentation lists various other things, but they are not
> implemented as server endpoint properties.
>
> As client endpoint properties:
>
> "RTN" is expected to be present in code, but is not documented.

"RTN" is called "Retransmissions" elsewhere.

>
> "MaximumLatency" "Location" "SupportedContext" "Context" are documented
> but not present in code.
>
>

2023-09-25 20:32:57

by Luiz Augusto von Dentz

Subject: Re: [PATCH v2 6/6] doc/media: Convert media-api.rst into manpages

Hi Pauli,

On Sat, Sep 23, 2023 at 2:14 AM Pauli Virtanen <[email protected]> wrote:
>
> Hi Luiz,
>
> pe, 2023-09-22 kello 12:23 -0700, Luiz Augusto von Dentz kirjoitti:
> > From: Luiz Augusto von Dentz <[email protected]>
> >
> > This splits media-api.rst into org.bluez.Media<interface>.rst and
> > generate manpages for them.
>
> I made a pass looking at the implementations of the transport/endpoint
> and SetConfiguration/SelectProperties/SelectConfiguration and comparing
> to docs.
>
> Note that the SelectProperties API has a problem with BAP endpoint
> configuration. We maybe should redesign it while we still can?
>
> I think generally at least from Pipewire side there's no need to keep
> backward compatibility while this is experimental. We can target BlueZ
> master branch.
>
>
> SelectProperties API problem:
>
> As BAP client one first does Config Codec (ASCS §5.1) which takes
> Target_Latency, Target_PHY and Codec.
>
> After this, the ASE properties (ACSS Table 4.3) in Codec Configured
> state contain the server supported values for Max_Transport_Latency,
> Presentation_Delay_Min/Max etc.
>
> SelectProperties is called before Config Codec, so it cannot
> necessarily know the server supported values. In this case the sound
> server cannot fill in QoS correctly.
>
> The client-invoked SetConfiguration API also seems to have similar
> issue.
>
> Probably: SelectProperties should be called twice, once to get
> parameters for Config Codec, and then again to get parameters for
> Config QoS. Or, there should be a separate "SelectCodec" and
> "SelectQoS" calls. Calling "SelectProperties" twice could be simpler
> for everyone.
>
> In client-invoked "SetConfiguration" API, one probably should only pass
> in the parameters needed for Config Codec, and BlueZ should then make a
> SelectProperties call to get the QoS ones once the server-side values
> are known.
>
> I can take a look at this...

Sound like a good idea, it means the actual configuration is always
done via SelectProperties, that said we need to make sure this works
with A2DP as well or state that it only applies to BAP, we could
perhaps introduce a property to indicate that the endpoint implements
SelectProperties.

>
> MediaTransport:
>
> "Delay" field only exists for A2DP in code.

Yeah, the PresentationDelay was moved into QoS property.

> "Volume" field only exists for A2DP in code.

That is subject to change though.

> "Links" is ucast only in code.

Will mark it as unicast only.

> "QoS.TargetLatency" does not exist in code. Maybe it should be exposed
> for consistency, since it's expected as return from SelectProperties.

Yeah, it seems we never implemented it, but I consider it a gap not a
inconsistency with the code.

>
> SetConfiguration:
>
> SetConfiguration properties dict when called by BlueZ contains exactly
> the properties of the transport. The documentation probably should say
> that this is so.
>
> When called by client, the contents of the properties dict are expected
> to be different. QoS parameters are not packed in a "QoS" dict. Maybe
> they should be. The "PHY" key is also still a string here.

Is it? Or perhaps I had changed it later on when splitting the
documentation on a per-interface, at least on
org.bluez.MediaEndpoint.rst there is no entry were PHY is a string, or
you are talking about the actual code here?

> The documented input parameters expected from client are wrong, the
> documentation explains fields of struct bt_bap_pac_qos, but what the
> code parses are that of struct bt_bap_qos.
>
> "MaximumLatency": no such field in code, seems to be called "Latency"
> everywhere.

The way Im designing these properties are that MediaEndpoint actually
carries the preferences and MediaTransport the configuration as far as
BAP is concerned, perhaps I shall actually state it though.

>
> SelectProperties:
>
> In code, the return parameter expects QoS parameters (struct
> bt_bap_qos) to be packed in "QoS" dict.
>
> They are not packed in "QoS" dict in the input parameters. These are
> not exactly QoS, but instead struct bt_bap_pac_qos, so not clear if
> they should be packed.

Input shall be considered the remote preferences and the output the
local configuration.

> The input and return parameters are not documented. The input QoS
> contains fields of struct bt_bap_pac_qos. The return QoS has fields of
> struct bt_bap_qos.

I will attempt to clarify that.

>
> MediaEndpoint:
>
> The endpoints published by BlueZ only have the properties
> "UUID", "Codec", "Capabilities", "Device".
>
> The documentation lists various other things, but they are not
> implemented as server endpoint properties.
>
> As client endpoint properties:
>
> "RTN" is expected to be present in code, but is not documented.
>
> "MaximumLatency" "Location" "SupportedContext" "Context" are documented
> but not present in code.
>
>
> --
> Pauli Virtanen



--
Luiz Augusto von Dentz