* [PATCH BlueZ 0/1 v2] BT Mesh API doc @ 2018-02-18 6:48 Inga Stotland 2018-02-18 6:48 ` [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API Inga Stotland 0 siblings, 1 reply; 10+ messages in thread From: Inga Stotland @ 2018-02-18 6:48 UTC (permalink / raw) To: linux-bluetooth; +Cc: Inga Stotland Hi, This patch contains revision 2 of initial documentation describing proposed BT Mesh user space/kernel interface. The idea behind this interface is to divide mesh functionality between user space and kernel in order to utilize kernel's finer timing mechanisms and provide efficient filtering of mesh-specific packets. Feedback is appreciated. Inga Stotland (1): Add initial doc describing Bluetooth Mesh API doc/mesh-api.txt | 269 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 doc/mesh-api.txt -- 2.13.6 ^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-18 6:48 [PATCH BlueZ 0/1 v2] BT Mesh API doc Inga Stotland @ 2018-02-18 6:48 ` Inga Stotland 2018-02-26 13:49 ` Marcel Holtmann 0 siblings, 1 reply; 10+ messages in thread From: Inga Stotland @ 2018-02-18 6:48 UTC (permalink / raw) To: linux-bluetooth; +Cc: Inga Stotland --- doc/mesh-api.txt | 269 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 doc/mesh-api.txt diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt new file mode 100644 index 000000000..87311faba --- /dev/null +++ b/doc/mesh-api.txt @@ -0,0 +1,269 @@ +Bluetooth Mesh Socket API +************************* + +Copyright (C) 2018 Intel Corporation. All rights reserved. + +This document decribes the data format that is used for communication with +the kernel via Bluetooth Mesh socket. The data that are passed over this +type of a socket is specific to Bluetooth Mesh Profile. + +The Bluetooth Mesh socket is implemented as part of PF_BLUETOOTH family +and can be created by opening a raw HCI socket with hci_channel set to +HCI_CHANNEL_BTMESH. The mesh socket requires the creating process to have +CAP_NET_ADMIN capability. + +=================================================== +Packet Structure: user space to/from kernel (Tx/Rx) +=================================================== + +Each packet to or from the Over-the-Air interface is sent between the user +space and the kernel must be of nonzero length, and start with the AD_Type, +followed by a variable amount of additional payload. + + 0 8 + +---------------+------------------------------------ + | AD_Type | Mesh Packet + +---------------+------------------------------------ + +AD_Type (1 octet -- Defined by the Bluetooth SIG) +================= + +Provisioning: 0x29 - The payload contains a Mesh Provisioning message +Network: 0x2A - The payload contains a Mesh Data Packet +Beacon: 0x2B - The payload contains a Mesh Beacon + +The AD_Type values correspond to AD types introduced in Mesh Profile +specification. The API is designed to support additional types. + + +A packet with empty (Zero-Length) payload may be sent over the socket in case +when only Control ancillary data is needed (e.g., Flush or Scan, defined below). + +=============== +Socket Options +=============== + +HCI Mesh Scan Filter +==================== + Code: 0x05 + + Filter_Id (1 octet) + Duplicates (1 octet) + Filter (variable length) + +Read/write socket option used to setup scan filters for mesh specific packets. +First octet of filter must include at least the AD_Type but may be longer to +include NIDs or other known data. + +HCI Mesh Default Tx Power +========================= + Code: 0x06 + + Tx_Power (1 octet) + +Read/write socket option for setting default Tx power. + +HCI Mesh Default Cahnnel Map +============================ + Code: 0x07 + + Chan_map (1 octet) + +Read/write socket option for setting default channel map. + +HCI Mesh Accuracy +================= + Code: 0x08 + + Accuracy (1 octet) + +Read-only socket option to obtain the value of the smallest number of +milliseconds that a Mesh Friendship Offer Window can be, for guaranteed +Poll Response transmission within that window. + +================== +Tx Ancillary Data +================== + +The information about which timing settings to use when sending a mesh +packet is contained in mandatory ancillary data accompanying the +payload. Exactly one of the following (mutually exclusive) ancillary +data types must be present with nonzero length Tx payload: + +Mesh Transmit Info +=================== + +cmsg_level cmsg_type cmsg_data[] +-------------------------------------------------- +SOL_BLUETOOTH BTMESH_TX_INFO Parameters + + Code: 0x01 + Parameters: + Count (1 octet) + Interval: (2 octets) + Min_Random_Delay: (1 octet) + Max_Random_Delay: (1 octet) + +The retransmission parameters for a regular outgoing mesh message. + +Count is the total number of times to Tx. A Zero means Tx Until Canceled. + +Interval is the number of milliseconds between each Tx. + +Random Delay is milliseconds added before first Tx. + +Mesh Poll Transmit Info +======================= + +cmsg_level cmsg_type cmsg_data[] +--------------------------------------------------- +SOL_BLUETOOTH BTMESH_POLL_TX_INFO Parameters + + Code: 0x02 + Parameters: + Scan_Delay (1 octet) + Scan_Duration (1 octet) + Filter_Ids[2] (2 octets) + Min_Random_Delay: (1 octet) + Max_Random_Delay: (1 octet) + +Scan_Delay describes the wait period to begin scanning after the Poll message +is sent. + +Filter_Ids contain IDs of two filters that account for two possible values of +IV Update bit in expected Poll response. + +Random Delay is milliseconds added before Tx. + +Mesh Poll Response Transmit Info +================================ + +cmsg_level cmsg_type cmsg_data[] +----------------------------------------------------- +SOL_BLUETOOTH BTMESH_POLL_RSP_TX_INFO Parameters + + Code: 0x03 + Parameters: + Instant (4 octets) + Delay (1 octet) + +The timing parameters for sending a friend poll response. + +Instant is a 4-octet opaque value that corresponds to the instant an +associated incoming mesh message was recieved, for timing purposes. + +Delay defines number of milliseconds after the corresponding Instant +to wait before sending this Tx. + +____________________________________________________________________ + +The following ancillary types are optional with nonzero length Tx payload: + +Transmit Power +============== + +cmsg_level cmsg_type cmsg_data[] +--------------------------------------------------------------- +SOL_BLUETOOTH BTMESH_TX_POWER_INFO Parameters + + Code: 0x04 + Parameters: + Tx_Power (1 octet) + +Transmit power setting can be used for finer control on the outbound messages. +If not present, use default value (builtin or configured as socket options). + +Transmit Channel +================ +cmsg_level cmsg_type cmsg_data[] +--------------------------------------------------------------- +SOL_BLUETOOTH BTMESH_TX_CHANNEL_INFO Parameters + + Code: 0x05 + Parameters: + Tx_Channel (1 octet) + +The presence of this option specifies transmit channel and allows +for better control, e.g., to respond on the same +channel as the one on which incoming message has been received. +If not present, the default value will be used (builtin or configured as +socket options). + + +Additional the ancillary data portion may contain Control type information. + +The following are Control ancillary data types, that me be sent with or +without payloads: + +Scan +======= +cmsg_level cmsg_type cmsg_data[] +--------------------------------------------------------------- +SOL_BLUETOOTH BTMESH_SCAN Parameters + + Code: 0x06 + Parameters: + Filter_Ids[] (variable) + +To enable/disable scanning of Mesh packets. + +If Filter_Ids array is nonzero length, start scanning with the specified +filters (filters are initialized via socket options mechanism). This array +replaces any prior filters. + +If no filter IDs are present (i.e., zero array length), stop scanning. + + +Flush +======= +cmsg_level cmsg_type cmsg_data[] +--------------------------------------------------------------- +SOL_BLUETOOTH BTMESH_TX_FLUSH Parameters + + Code: 0x06 + Parameters: + Pattern (variable) + +Cancel and Flush all the pending Tx mesh packets that match the specified +pattern, including the AD Type. + +If only the AD Type is present, all outgoing packets of that type will +be flushed. + +If no pattern is present (i.e., zero pattern length), flush all pending Tx +packets. + + +================= +Rx Ancillary Data +================= + +Receive Message Info +==================== + +cmsg_level cmsg_type cmsg_data[] +------------------------------------------------------------------------ +SOL_BLUETOOTH BTMESH_RECV_MSG_INFO (Recv Message Info Parameters) + + Code: 0x04 + Parameters: + Instant (4 octets) + Channel (1 octet) + RSSI (1 octet) + + +Instant is an opaque 4-octet value that can be included in +BTMESH_POLL_RSP_TX_INFO ancilary data to accurately time Poll +Response delays + +Channel indicates which channel packet received on or Zero if unknown + +RSSI indicates the signal strength of the received packet + +-------------------------------------------------------------------------- + +The socket API follows "best effort" approach for user space / kernel interface: +there is no asynchronous feedback on status of the data sent over the socket. + +All multi-octet fields are in little-endian byte order (least significant byte +first). -- 2.13.6 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-18 6:48 ` [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API Inga Stotland @ 2018-02-26 13:49 ` Marcel Holtmann 2018-02-26 19:01 ` Gix, Brian 2018-02-28 20:17 ` Stotland, Inga 0 siblings, 2 replies; 10+ messages in thread From: Marcel Holtmann @ 2018-02-26 13:49 UTC (permalink / raw) To: Inga Stotland; +Cc: linux-bluetooth Hi Inga, > --- > doc/mesh-api.txt | 269 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 269 insertions(+) > create mode 100644 doc/mesh-api.txt > > diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt > new file mode 100644 > index 000000000..87311faba > --- /dev/null > +++ b/doc/mesh-api.txt > @@ -0,0 +1,269 @@ > +Bluetooth Mesh Socket API > +************************* > + > +Copyright (C) 2018 Intel Corporation. All rights reserved. > + > +This document decribes the data format that is used for communication with > +the kernel via Bluetooth Mesh socket. The data that are passed over this > +type of a socket is specific to Bluetooth Mesh Profile. > + > +The Bluetooth Mesh socket is implemented as part of PF_BLUETOOTH family > +and can be created by opening a raw HCI socket with hci_channel set to > +HCI_CHANNEL_BTMESH. The mesh socket requires the creating process to have call this HCI_CHANNEL_MESH. There is no point in adding BT* here. > +CAP_NET_ADMIN capability. > + > +=================================================== > +Packet Structure: user space to/from kernel (Tx/Rx) > +=================================================== > + > +Each packet to or from the Over-the-Air interface is sent between the user > +space and the kernel must be of nonzero length, and start with the AD_Type, > +followed by a variable amount of additional payload. > + > + 0 8 > + +---------------+------------------------------------ > + | AD_Type | Mesh Packet > + +---------------+—————————————————— > + Actually I would have really preferred that we followed the Proxy PDU format. 2 Bits reserved 6 Bits packet type Variable data payload I think that we really need the 0x02 type for configuration between the kernel and userspace. > +AD_Type (1 octet -- Defined by the Bluetooth SIG) > +================= > + > +Provisioning: 0x29 - The payload contains a Mesh Provisioning message > +Network: 0x2A - The payload contains a Mesh Data Packet > +Beacon: 0x2B - The payload contains a Mesh Beacon > + > +The AD_Type values correspond to AD types introduced in Mesh Profile > +specification. The API is designed to support additional types. > + > + > +A packet with empty (Zero-Length) payload may be sent over the socket in case > +when only Control ancillary data is needed (e.g., Flush or Scan, defined below). > + > +=============== > +Socket Options > +=============== > + > +HCI Mesh Scan Filter > +==================== > + Code: 0x05 > + > + Filter_Id (1 octet) > + Duplicates (1 octet) > + Filter (variable length) > + > +Read/write socket option used to setup scan filters for mesh specific packets. > +First octet of filter must include at least the AD_Type but may be longer to > +include NIDs or other known data. These ones look more like type 0x02 PDU packets. And this in particular I would have done as Add Network ID and Remove Network ID and let the kernel deal with deciding if it chooses a more global filter (since not enough filters are available) or if it can be more precise with the filtering. > + > +HCI Mesh Default Tx Power > +========================= > + Code: 0x06 > + > + Tx_Power (1 octet) > + > +Read/write socket option for setting default Tx power. Leave this out for now. I assume initially we will always use 127 for do not care. If we think it is valuable for testing, then via debugfs. > + > +HCI Mesh Default Cahnnel Map > +============================ > + Code: 0x07 > + > + Chan_map (1 octet) > + > +Read/write socket option for setting default channel map. Also irrelevant and only for fine tuning and testing. Can be exposed via debugfs. > + > +HCI Mesh Accuracy > +================= > + Code: 0x08 > + > + Accuracy (1 octet) > + > +Read-only socket option to obtain the value of the smallest number of > +milliseconds that a Mesh Friendship Offer Window can be, for guaranteed > +Poll Response transmission within that window. I still would have done this via type 0x02 and a PDU exchange protocol. Mainly because then it also becomes traceable via btmon. So yes, I want the mesh channel also be included in btmon. > + > +================== > +Tx Ancillary Data > +================== > + > +The information about which timing settings to use when sending a mesh > +packet is contained in mandatory ancillary data accompanying the > +payload. Exactly one of the following (mutually exclusive) ancillary > +data types must be present with nonzero length Tx payload: > + > +Mesh Transmit Info > +=================== > + > +cmsg_level cmsg_type cmsg_data[] > +-------------------------------------------------- > +SOL_BLUETOOTH BTMESH_TX_INFO Parameters General format we started using is BT_* and so this should be BT_MESH_* > + > + Code: 0x01 > + Parameters: > + Count (1 octet) > + Interval: (2 octets) > + Min_Random_Delay: (1 octet) > + Max_Random_Delay: (1 octet) > + > +The retransmission parameters for a regular outgoing mesh message. > + > +Count is the total number of times to Tx. A Zero means Tx Until Canceled. > + > +Interval is the number of milliseconds between each Tx. > + > +Random Delay is milliseconds added before first Tx. > + > +Mesh Poll Transmit Info > +======================= > + > +cmsg_level cmsg_type cmsg_data[] > +--------------------------------------------------- > +SOL_BLUETOOTH BTMESH_POLL_TX_INFO Parameters > + > + Code: 0x02 > + Parameters: > + Scan_Delay (1 octet) > + Scan_Duration (1 octet) > + Filter_Ids[2] (2 octets) > + Min_Random_Delay: (1 octet) > + Max_Random_Delay: (1 octet) > + > +Scan_Delay describes the wait period to begin scanning after the Poll message > +is sent. > + > +Filter_Ids contain IDs of two filters that account for two possible values of > +IV Update bit in expected Poll response. > + > +Random Delay is milliseconds added before Tx. > + > +Mesh Poll Response Transmit Info > +================================ > + > +cmsg_level cmsg_type cmsg_data[] > +----------------------------------------------------- > +SOL_BLUETOOTH BTMESH_POLL_RSP_TX_INFO Parameters > + > + Code: 0x03 > + Parameters: > + Instant (4 octets) > + Delay (1 octet) > + > +The timing parameters for sending a friend poll response. > + > +Instant is a 4-octet opaque value that corresponds to the instant an > +associated incoming mesh message was recieved, for timing purposes. > + > +Delay defines number of milliseconds after the corresponding Instant > +to wait before sending this Tx. > + > +____________________________________________________________________ > + > +The following ancillary types are optional with nonzero length Tx payload: > + > +Transmit Power > +============== > + > +cmsg_level cmsg_type cmsg_data[] > +--------------------------------------------------------------- > +SOL_BLUETOOTH BTMESH_TX_POWER_INFO Parameters > + > + Code: 0x04 > + Parameters: > + Tx_Power (1 octet) > + > +Transmit power setting can be used for finer control on the outbound messages. > +If not present, use default value (builtin or configured as socket options). > + > +Transmit Channel > +================ > +cmsg_level cmsg_type cmsg_data[] > +--------------------------------------------------------------- > +SOL_BLUETOOTH BTMESH_TX_CHANNEL_INFO Parameters > + > + Code: 0x05 > + Parameters: > + Tx_Channel (1 octet) > + > +The presence of this option specifies transmit channel and allows > +for better control, e.g., to respond on the same > +channel as the one on which incoming message has been received. > +If not present, the default value will be used (builtin or configured as > +socket options). Don’t bother with these two at the moment. I think they have no use for us except for allowing some testing via debugfs. They needed to be in the HCI spec for completeness and because you can also use the HCI spec to build a mesh sniffer. > + > + > +Additional the ancillary data portion may contain Control type information. > + > +The following are Control ancillary data types, that me be sent with or > +without payloads: > + > +Scan > +======= > +cmsg_level cmsg_type cmsg_data[] > +--------------------------------------------------------------- > +SOL_BLUETOOTH BTMESH_SCAN Parameters > + > + Code: 0x06 > + Parameters: > + Filter_Ids[] (variable) > + > +To enable/disable scanning of Mesh packets. > + > +If Filter_Ids array is nonzero length, start scanning with the specified > +filters (filters are initialized via socket options mechanism). This array > +replaces any prior filters. > + > +If no filter IDs are present (i.e., zero array length), stop scanning. I dislike this. We should have a type 0x02 command that tells us what kind of role we are operating in. And based on that scanning is enabled by binding the socket and closing it. Or changing the role. The whole filter id exposure seems a bit odd to me. I realize that this might look simple, but a few things should be done by the kernel. And managing the scanning filters is one of them. So we need to feed the kernel enough details that it can do that efficiently. Swapping filters around from userspace is painful. Otherwise we could just expose HCI_CHANNEL_MESH as HCI mesh commands. They are all multiplexed via a single opcode anyway and have a single event with and event prefix. So if you want this detailed control of the HCI commands, then don’t try to put too much kernel in between. Just do path through of them. We could do just that and then leave the kernel portion for this alone. Maybe it is worth while to debate pros and cons for this. It is actually not the worst idea to give exclusive access to the mesh commands. It would be similar to HCI_CHANNEL_USER, but only for the mesh commands and we would strip the HCI command header and HCI event header + event prefix off it so that you just have to deal with mesh opcode and mesh subevent code. Hmmm .. it gets a bit tricky for the command complete portion of it. So it might have to be the full HCI anyway, but restricted to one opcode and only matching events being forwarded. Actually if I spin my train of thoughts further now, we might want to put HCI_CHANNEL_MESH on ice and leave that for some future version. I think providing some sort of abstraction and automatic handling of scanning filters etc. is a good abstraction for the kernel, but it might be something that will take a while to be defined and working correctly. Doing the HCI mesh commands directly on a socket has the command complete problem as stated above and having yet another variation of HCI_CHANNEL_RAW with mesh HCI filters seems wrong as well. Especially since eventually I want to have an option to disable HCI_CHANNEL_RAW. In addition it would have been exclusive access to make sure nothing goes wrong. So maybe we just expose HCI mesh commands as MGMT command and MGMT event. Mesh Command ============ Command Code: 0x0043 Controller Index: <controller index> Command Parameters: Opcode (1 Octet) Command parameters (Variable) Return Parameters: Status (1 Octet) Opcode (1 Octet) Return parameters (Variable) Mesh Event ========== Event Code: 0x0026 Controller Index: <controller index> Event Parameters: Subevent (1 Octet) Even parameters (variable) This would map 1:1 to the HCI mesh commands and events with the tiny modification that the event prefix is stripped from the Mesh Event and not provided and with the Mesh Get Options command issued it would be mapped to event prefix length of zero. And then only a settings 16 Mesh would be needed. Or we make the command and event only available when HCI mesh commands are actually supported. That is something that would needs to be discussing. In general, we have not had limited commands based on hardware functionality, but these two would be special since they are vendor specific commands in the first place. For the kernel side we only have the the driver provide the mesh HCI opcode and run Mesh Get Options once to retrieve the firmwares event prefix so that it can be zeroed out by the MGMT commands and events. With that comments? Thoughts? Regards Marcel ^ permalink raw reply [flat|nested] 10+ messages in thread
* RE: [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-26 13:49 ` Marcel Holtmann @ 2018-02-26 19:01 ` Gix, Brian 2018-02-27 12:40 ` Marcel Holtmann 2018-02-28 20:17 ` Stotland, Inga 1 sibling, 1 reply; 10+ messages in thread From: Gix, Brian @ 2018-02-26 19:01 UTC (permalink / raw) To: Marcel Holtmann, Stotland, Inga; +Cc: linux-bluetooth@vger.kernel.org SGkgTWFyY2VsLA0KDQo+IC0tLS0tT3JpZ2luYWwgTWVzc2FnZS0tLS0tDQo+IEZyb206IGxpbnV4 LWJsdWV0b290aC1vd25lckB2Z2VyLmtlcm5lbC5vcmcgW21haWx0bzpsaW51eC1ibHVldG9vdGgt DQo+IG93bmVyQHZnZXIua2VybmVsLm9yZ10gT24gQmVoYWxmIE9mIE1hcmNlbCBIb2x0bWFubg0K PiBTZW50OiBNb25kYXksIEZlYnJ1YXJ5IDI2LCAyMDE4IDU6NTAgQU0NCj4gVG86IFN0b3RsYW5k LCBJbmdhIDxpbmdhLnN0b3RsYW5kQGludGVsLmNvbT4NCj4gQ2M6IGxpbnV4LWJsdWV0b290aEB2 Z2VyLmtlcm5lbC5vcmcNCj4gU3ViamVjdDogUmU6IFtQQVRDSCBCbHVlWiAxLzEgdjJdIEFkZCBp bml0aWFsIGRvYyBkZXNjcmliaW5nIEJsdWV0b290aCBNZXNoDQo+IEFQSQ0KPiANCj4gSGkgSW5n YSwNCj4gDQo+ID4gLS0tDQo+ID4gZG9jL21lc2gtYXBpLnR4dCB8IDI2OQ0KPiA+ICsrKysrKysr KysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysNCj4gPiAxIGZp bGUgY2hhbmdlZCwgMjY5IGluc2VydGlvbnMoKykNCj4gPiBjcmVhdGUgbW9kZSAxMDA2NDQgZG9j L21lc2gtYXBpLnR4dA0KPiA+DQo+ID4gZGlmZiAtLWdpdCBhL2RvYy9tZXNoLWFwaS50eHQgYi9k b2MvbWVzaC1hcGkudHh0IG5ldyBmaWxlIG1vZGUgMTAwNjQ0DQo+ID4gaW5kZXggMDAwMDAwMDAw Li44NzMxMWZhYmENCj4gPiAtLS0gL2Rldi9udWxsDQo+ID4gKysrIGIvZG9jL21lc2gtYXBpLnR4 dA0KPiA+IEBAIC0wLDAgKzEsMjY5IEBADQo+ID4gK0JsdWV0b290aCBNZXNoIFNvY2tldCBBUEkN Cj4gPiArKioqKioqKioqKioqKioqKioqKioqKioqKg0KPiA+ICsNCj4gPiArQ29weXJpZ2h0IChD KSAyMDE4IEludGVsIENvcnBvcmF0aW9uLiBBbGwgcmlnaHRzIHJlc2VydmVkLg0KPiA+ICsNCj4g PiArVGhpcyBkb2N1bWVudCBkZWNyaWJlcyB0aGUgZGF0YSBmb3JtYXQgdGhhdCBpcyB1c2VkIGZv ciBjb21tdW5pY2F0aW9uDQo+ID4gK3dpdGggdGhlIGtlcm5lbCB2aWEgQmx1ZXRvb3RoIE1lc2gg c29ja2V0LiBUaGUgZGF0YSB0aGF0IGFyZSBwYXNzZWQNCj4gPiArb3ZlciB0aGlzIHR5cGUgb2Yg YSBzb2NrZXQgaXMgc3BlY2lmaWMgdG8gQmx1ZXRvb3RoIE1lc2ggUHJvZmlsZS4NCj4gPiArDQo+ ID4gK1RoZSBCbHVldG9vdGggTWVzaCBzb2NrZXQgaXMgaW1wbGVtZW50ZWQgYXMgcGFydCBvZiBQ Rl9CTFVFVE9PVEgNCj4gPiArZmFtaWx5IGFuZCBjYW4gYmUgY3JlYXRlZCBieSBvcGVuaW5nIGEg cmF3IEhDSSBzb2NrZXQgd2l0aA0KPiA+ICtoY2lfY2hhbm5lbCBzZXQgdG8gSENJX0NIQU5ORUxf QlRNRVNILiBUaGUgbWVzaCBzb2NrZXQgcmVxdWlyZXMgdGhlDQo+ID4gK2NyZWF0aW5nIHByb2Nl c3MgdG8gaGF2ZQ0KPiANCj4gY2FsbCB0aGlzIEhDSV9DSEFOTkVMX01FU0guIFRoZXJlIGlzIG5v IHBvaW50IGluIGFkZGluZyBCVCogaGVyZS4NCj4gDQo+ID4gK0NBUF9ORVRfQURNSU4gY2FwYWJp bGl0eS4NCj4gPiArDQo+ID4gKz09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09PT09PQ0KPiA+ICtQYWNrZXQgU3RydWN0dXJlOiB1c2VyIHNwYWNlIHRvL2Zyb20g a2VybmVsIChUeC9SeCkNCj4gPiArPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09 PT09PT09PT09PT09PT09DQo+ID4gKw0KPiA+ICtFYWNoIHBhY2tldCB0byBvciBmcm9tIHRoZSBP dmVyLXRoZS1BaXIgaW50ZXJmYWNlIGlzIHNlbnQgYmV0d2VlbiB0aGUNCj4gPiArdXNlciBzcGFj ZSBhbmQgdGhlIGtlcm5lbCBtdXN0IGJlIG9mIG5vbnplcm8gbGVuZ3RoLCBhbmQgc3RhcnQgd2l0 aA0KPiA+ICt0aGUgQURfVHlwZSwgZm9sbG93ZWQgYnkgYSB2YXJpYWJsZSBhbW91bnQgb2YgYWRk aXRpb25hbCBwYXlsb2FkLg0KPiA+ICsNCj4gPiArCTAgICAgICAgICAgICAgICA4DQo+ID4gKwkr LS0tLS0tLS0tLS0tLS0tKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLQ0KPiA+ ICsJfCAgQURfVHlwZSAgICAgIHwgTWVzaCBQYWNrZXQNCj4gPiArCSstLS0tLS0tLS0tLS0tLS0r 4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCU4oCUDQo+ ID4gKw0KPiANCj4gQWN0dWFsbHkgSSB3b3VsZCBoYXZlIHJlYWxseSBwcmVmZXJyZWQgdGhhdCB3 ZSBmb2xsb3dlZCB0aGUgUHJveHkgUERVDQo+IGZvcm1hdC4NCj4gDQo+IAkyIEJpdHMgcmVzZXJ2 ZWQNCj4gCTYgQml0cyBwYWNrZXQgdHlwZQ0KPiAJVmFyaWFibGUgZGF0YSBwYXlsb2FkDQoNClNv IHdlIHRhbGtlZCBhYm91dCB0aGlzIGVhcmxpZXIsIHRoYXQgaXQgd291bGQgbWFrZSBzZW5zZSB0 byBtYWtlIHRoZSBLZXJuZWwgYXMgYWdub3N0aWMgYXMgcG9zc2libGUgd2hlbiBpdCBjb21lcyB0 bw0KTWVzaCwgc28gdGhhdCB0aGUgaW50cm9kdWN0aW9uIG9mIG5ldyBPVEEgTWVzaCBwYXlsb2Fk cyBjb3VsZCBiZSBpbmNvcnBvcmF0ZWQgd2l0aCBtaW5pbWFsIGtlcm5lbCByZXdyaXRlcy4NCg0K UGFydCBvZiB0aGlzIGFnbm9zdGljaXNtIGluY2x1ZGVzIHRoZSBBRF9UeXBlcy4gTWVzaCBQYWNr ZXRzIGFyZSBpbmRpc3Rpbmd1aXNoYWJsZSBmcm9tIGFueSBvdGhlciBBZHZlcnRpc2VkIGRhdGEg ZXhjZXB0DQpmb3Igd2hhdCB0aGUgQlQgU0lHIGRlY2lkZXMgdG8gYXNzaWduIGFzIHRoZSBBRF9U eXBlIGZvciBlYWNoIE1lc2ggUGFja2V0IFR5cGUuICBXZSBrbm93IHRoYXQgd2UgKndpbGwqIGJl IGFkZGluZyBuZXcNCkFEIFR5cGVzIGluIHRoZSBmdXR1cmUgZm9yIE1lc2gsIGFuZCBpZiB3ZSBk b24ndCBrZWVwIGl0IGFnbm9zdGljLCB3ZSB3aWxsIGhhdmUgdG8gYXQgbGVhc3QgYWRkIG1hcHBp bmcgaW4gYmV0d2VlbiB0aGUgUGFja2V0DQpUeXBlcyBQcm94eSB1c2VzIHRvIHRoZSBBRCBUeXBl cy4uLi4gIFRoYXQgd291bGQgYmUgYSBzbWFsbCBjaGFuZ2UsIHRvIGJlIHN1cmUsIHlldCBpbiBt eSBvcGluaW9uIHVubmVjZXNzYXJ5Lg0KDQpBZGRpdGlvbmFsbHksIHdlIG5lZWQgdG8gY29uc2lk ZXIgdGhlIEFEIFR5cGVzIHdoZW4gZmlsdGVyaW5nIGF0IGVpdGhlciB0aGUgS2VybmVsIGxldmVs LCBvciBpbiB0aGUgZnV0dXJlLCBhdCB0aGUgQ29udHJvbGVyIGxldmVsLg0KVGhpcyBtZWFucyBl aXRoZXI6DQoqIFVzaW5nIHRoZSBQcm94eSB0eXBlcyBmb3IgT3V0Z29pbmcgYW5kIEluY29taW5n IG1lc3NhZ2VzICAgYnV0IG5vdCB0aGUgRmlsdGVyaW5nIC1vci0NCiogVXNpbmcgdGhlIFByb3h5 IHR5cGVzIGZvciB0aGUgZmlsdGVycyB0b28sIGFuZCBtYXBwaW5nIHRoZW0gaW4gdGhlIGtlcm5l bCB0byBBRCBUeXBlcyAobWFraW5nIGFkZGl0aW9uYWwgQUQgVHlwZSBkZXBlbmRlbmN5IGluIHRo ZSBLZXJuZWwgTWVzaCBjb2RlKQ0KDQpJIGFtIG5vIGxvbmdlciBpbiBsb3ZlIHdpdGggc2hvZS1o b3JuaW5nIHRoaXMgaW50byB0aGUgUHJveHkgcGFja2V0Og0KKiBBRCBUeXBlcyBhcmUgaW4gYW4g OC1iaXQgbmFtZXNwYWNlDQoqIFByb3h5IHByb2JhYmx5IGRvZXNuJ3QgbmVlZCBhbnkgb2YgdGhl IHVwY29taW5nIHBhY2tldCB0eXBlcy4NCiogVGhpcyBiZWFyZXIgZG9lc24ndCBuZWVkIHRoZSAi MiBSZXNlcnZlZCBCaXRzIiwgYW5kIGV2ZW4gaWYgd2UgZGlkIHVzZSB0aGVtIGZvciBzb21ldGhp bmcsIGl0IHdvdWxkIGNlcnRhaW5seSBiZSAqdG90YWxseSogZGlmZmVyZW50IGZyb20gdGhlIFBy b3h5LVNBUg0KKiBUaGUgUHJveHkgZm9ybWF0IGlzIGludGVuZGVkIHRvIGJlIHVzZWQgYmV0d2Vl biB0byBwZWVycyB0aGF0IGhhdmUgYWxsIHRoZSBNZXNoIGNyeXB0byBmdW5jdGlvbmFsaXR5DQoN CldlIG9yaWdpbmFsbHkgdHJpZWQgdG8gdXNlIENvbnRyb2wgYml0cyB0byBkaWZmZXJlbnRpYXRl IGJldHdlZW4gVGltaW5nL0NvdW50L0ludGVydmFsIGRpZmZlcmVuY2VzIGJldHdlZW4gdGhlIHZh cmlvdXMga2luZHMgb2YgTWVzaCBUcmFmZmljLCBidXQgdGhhdCBxdWlja2x5IG92ZXJ3aGVsbWVk IHRoZSBjb250cm9sIGJpdHMuLi4gIFdoaWNoIGlzIHdoeSAqYWxsKiB0aW1pbmcvY291bnQvaW50 ZXJ2YWwgaW5mbyBpcyBub3cgaGFuZGxlZCBhcyBBbmNpbGxhcnkgZGF0YSwgYW5kIHRoZSBLZXJu ZWwgZG9lc24ndCBuZWVkIHRvIGtub3cgdGhlIGRpZmZlcmVuY2UgYmV0d2VlbiBEYXRhLCBCZWFj b24sIG9yIFByb3Zpc2lvbmluZyBwYWNrZXRzIGJ5IHRoZSBQYXlsb2FkLi4uICBUaGV5IGp1c3Qg aGF2ZSBkaWZmZXJlbnQgQW5jaWxsYXJ5IGRhdGEuIChGb3IgaW5zdGFuY2UsIHRoZXJlIGRvZXNu J3QgbmVlZCB0byBiZSBhIGRpZmZlcmVuY2UgYmV0d2VlbiBhIEJlYWNvbiBzZW50IG9uY2UgYW5k IGEgc3RhbmRhcmQgRGF0YSBwYWNrZXQgc2VudCBvbmNlKQ0KDQoNCj4gDQo+IEkgdGhpbmsgdGhh dCB3ZSByZWFsbHkgbmVlZCB0aGUgMHgwMiB0eXBlIGZvciBjb25maWd1cmF0aW9uIGJldHdlZW4g dGhlDQo+IGtlcm5lbCBhbmQgdXNlcnNwYWNlLg0KPiANCg0KV2hhdCB3b3VsZCB0aGUgdXNlIGNh c2UgYmUsIGFuZCBob3cgd291bGQgdGhpcyBpbXByb3ZlIHVwb24gdGhlIFNvY2sgT3B0aW9ucyBt ZXRob2Q/ICBUaGUgb25seSByZWFsIGNvbmZpZ3VyYXRpb24gd2UgbmVlZCB0byBkbyB3aXRoIGFu IGFnbm9zdGljIHN5c3RlbSBpcyB0aGUgRmlsdGVycy4gIEFuZCB0aGUgU2NhbiBlbmFibGUvZGlz YWJsZSBhcyBBbmNpbGxhcnkgZGF0YSBhcHBlYXJzIHRvIHdvcmsgd2VsbCwgYW5kIHdoZW4gY29t YmluZWQgd2l0aCB0aGUgcmVxdWlyZW1lbnQgZm9yIExQTnMgdGhhdCBTY2FuIG5lZWRzIHRvIGJl IHRlbXBvcmFyaWx5IHR1cm5lZCBvbiB3aXRoIHNwZWNpZmljIHRpbWluZyB0aWVkIHRvIGEgc3Bl Y2lmaWMgUE9MTCBwYXlsb2FkLCBpdCB3b3VsZCBiZSBjb25mdXNpbmcgdG8gc29tZXRpbWVzIGhh bmRsZSBTY2FuIHNldHVwIHZpYSBhIENvbmZpZ3VyYXRpb24gbWVzc2FnZSwgYW5kIHNvbWV0aW1l cyBhcyBBbmNpbGxhcnkgZGF0YS4gDQoNCg0KPiA+ICtBRF9UeXBlICgxIG9jdGV0IC0tIERlZmlu ZWQgYnkgdGhlIEJsdWV0b290aCBTSUcpID09PT09PT09PT09PT09PT09DQo+ID4gKw0KPiA+ICtQ cm92aXNpb25pbmc6CTB4MjkgLQlUaGUgcGF5bG9hZCBjb250YWlucyBhIE1lc2ggUHJvdmlzaW9u aW5nDQo+IG1lc3NhZ2UNCj4gPiArTmV0d29yazoJCTB4MkEgLQlUaGUgcGF5bG9hZCBjb250YWlu cyBhIE1lc2ggRGF0YSBQYWNrZXQNCj4gPiArQmVhY29uOgkJMHgyQiAtCVRoZSBwYXlsb2FkIGNv bnRhaW5zIGEgTWVzaCBCZWFjb24NCj4gPiArDQo+ID4gK1RoZSBBRF9UeXBlIHZhbHVlcyBjb3Jy ZXNwb25kIHRvIEFEIHR5cGVzIGludHJvZHVjZWQgaW4gTWVzaCBQcm9maWxlDQo+ID4gK3NwZWNp ZmljYXRpb24uIFRoZSBBUEkgaXMgZGVzaWduZWQgdG8gc3VwcG9ydCBhZGRpdGlvbmFsIHR5cGVz Lg0KPiA+ICsNCj4gPiArDQo+ID4gK0EgcGFja2V0IHdpdGggZW1wdHkgKFplcm8tTGVuZ3RoKSBw YXlsb2FkIG1heSBiZSBzZW50IG92ZXIgdGhlIHNvY2tldA0KPiA+ICtpbiBjYXNlIHdoZW4gb25s eSBDb250cm9sIGFuY2lsbGFyeSBkYXRhIGlzIG5lZWRlZCAoZS5nLiwgRmx1c2ggb3IgU2NhbiwN Cj4gZGVmaW5lZCBiZWxvdykuDQo+ID4gKw0KPiA+ICs9PT09PT09PT09PT09PT0NCj4gPiArU29j a2V0IE9wdGlvbnMNCj4gPiArPT09PT09PT09PT09PT09DQo+ID4gKw0KPiA+ICtIQ0kgTWVzaCBT Y2FuIEZpbHRlcg0KPiA+ICs9PT09PT09PT09PT09PT09PT09PQ0KPiA+ICsJQ29kZToJMHgwNQ0K PiA+ICsNCj4gPiArCUZpbHRlcl9JZAkJKDEgb2N0ZXQpDQo+ID4gKwlEdXBsaWNhdGVzCQkoMSBv Y3RldCkNCj4gPiArCUZpbHRlcgkJCSh2YXJpYWJsZSBsZW5ndGgpDQo+ID4gKw0KPiA+ICtSZWFk L3dyaXRlIHNvY2tldCBvcHRpb24gdXNlZCB0byBzZXR1cCBzY2FuIGZpbHRlcnMgZm9yIG1lc2gg c3BlY2lmaWMNCj4gcGFja2V0cy4NCj4gPiArRmlyc3Qgb2N0ZXQgb2YgZmlsdGVyIG11c3QgaW5j bHVkZSBhdCBsZWFzdCB0aGUgQURfVHlwZSBidXQgbWF5IGJlDQo+ID4gK2xvbmdlciB0byBpbmNs dWRlIE5JRHMgb3Igb3RoZXIga25vd24gZGF0YS4NCj4gDQo+IFRoZXNlIG9uZXMgbG9vayBtb3Jl IGxpa2UgdHlwZSAweDAyIFBEVSBwYWNrZXRzLiBBbmQgdGhpcyBpbiBwYXJ0aWN1bGFyIEkNCj4g d291bGQgaGF2ZSBkb25lIGFzIEFkZCBOZXR3b3JrIElEIGFuZCBSZW1vdmUgTmV0d29yayBJRCBh bmQgbGV0IHRoZQ0KPiBrZXJuZWwgZGVhbCB3aXRoIGRlY2lkaW5nIGlmIGl0IGNob29zZXMgYSBt b3JlIGdsb2JhbCBmaWx0ZXIgKHNpbmNlIG5vdCBlbm91Z2gNCj4gZmlsdGVycyBhcmUgYXZhaWxh YmxlKSBvciBpZiBpdCBjYW4gYmUgbW9yZSBwcmVjaXNlIHdpdGggdGhlIGZpbHRlcmluZy4NCg0K UmVtZW1iZXIgdGhhdCB3ZSBuZWVkIHRvIG5vdCBvbmx5IGJlIGZpbHRlcmluZyBvbiBOSUQsIGJ1 dCBhbHNvIFBST1YgYW5kIEJFQUNPTiBwYWNrZXRzLCB3aGljaCBkb24ndCBpbmNsdWRlIE5JRCB0 eXBlIHBhY2tldHMuDQpBbHNvIHRoaXMgd291bGQgYmUgKnZlcnkqIGRpZmZlcmVudCBmcm9tIFBy b3h5LCBiZWNhdXNlIHdlIGFyZW4ndCB0YWxraW5nIHRvIGEgY3J5cHRvIHBlZXIgYmV0d2VlbiBi bHVleiBhbmQga2VybmVsLg0KDQo+IA0KPiA+ICsNCj4gPiArSENJIE1lc2ggRGVmYXVsdCBUeCBQ b3dlcg0KPiA+ICs9PT09PT09PT09PT09PT09PT09PT09PT09DQo+ID4gKwlDb2RlOgkweDA2DQo+ ID4gKw0KPiA+ICsJVHhfUG93ZXIJCSgxIG9jdGV0KQ0KPiA+ICsNCj4gPiArUmVhZC93cml0ZSBz b2NrZXQgb3B0aW9uIGZvciBzZXR0aW5nIGRlZmF1bHQgVHggcG93ZXIuDQo+IA0KPiBMZWF2ZSB0 aGlzIG91dCBmb3Igbm93LiBJIGFzc3VtZSBpbml0aWFsbHkgd2Ugd2lsbCBhbHdheXMgdXNlIDEy NyBmb3IgZG8gbm90DQo+IGNhcmUuIElmIHdlIHRoaW5rIGl0IGlzIHZhbHVhYmxlIGZvciB0ZXN0 aW5nLCB0aGVuIHZpYSBkZWJ1Z2ZzLg0KPiANCj4gPiArDQo+ID4gK0hDSSBNZXNoIERlZmF1bHQg Q2Fobm5lbCBNYXANCj4gPiArPT09PT09PT09PT09PT09PT09PT09PT09PT09PQ0KPiA+ICsJQ29k ZToJMHgwNw0KPiA+ICsNCj4gPiArCUNoYW5fbWFwCQkoMSBvY3RldCkNCj4gPiArDQo+ID4gK1Jl YWQvd3JpdGUgc29ja2V0IG9wdGlvbiBmb3Igc2V0dGluZyBkZWZhdWx0IGNoYW5uZWwgbWFwLg0K PiANCj4gQWxzbyBpcnJlbGV2YW50IGFuZCBvbmx5IGZvciBmaW5lIHR1bmluZyBhbmQgdGVzdGlu Zy4gQ2FuIGJlIGV4cG9zZWQgdmlhDQo+IGRlYnVnZnMuDQo+IA0KPiA+ICsNCj4gPiArSENJIE1l c2ggQWNjdXJhY3kNCj4gPiArPT09PT09PT09PT09PT09PT0NCj4gPiArCUNvZGU6CTB4MDgNCj4g PiArDQo+ID4gKwlBY2N1cmFjeQkJKDEgb2N0ZXQpDQo+ID4gKw0KPiA+ICtSZWFkLW9ubHkgc29j a2V0IG9wdGlvbiB0byBvYnRhaW4gdGhlIHZhbHVlIG9mIHRoZSBzbWFsbGVzdCBudW1iZXIgb2YN Cj4gPiArbWlsbGlzZWNvbmRzIHRoYXQgYSBNZXNoIEZyaWVuZHNoaXAgT2ZmZXIgV2luZG93IGNh biBiZSwgZm9yDQo+ID4gK2d1YXJhbnRlZWQgUG9sbCBSZXNwb25zZSB0cmFuc21pc3Npb24gd2l0 aGluIHRoYXQgd2luZG93Lg0KPiANCj4gSSBzdGlsbCB3b3VsZCBoYXZlIGRvbmUgdGhpcyB2aWEg dHlwZSAweDAyIGFuZCBhIFBEVSBleGNoYW5nZSBwcm90b2NvbC4NCj4gTWFpbmx5IGJlY2F1c2Ug dGhlbiBpdCBhbHNvIGJlY29tZXMgdHJhY2VhYmxlIHZpYSBidG1vbi4gU28geWVzLCBJIHdhbnQg dGhlDQo+IG1lc2ggY2hhbm5lbCBhbHNvIGJlIGluY2x1ZGVkIGluIGJ0bW9uLg0KPiANCg0KSSB3 b3VsZCB2ZXJ5IG11Y2ggbGlrZSB0byB0YWxrIGFib3V0IHRoaXMgb25lIG92ZXIgYSBDQy4gIFRo aXMgdmFsdWUgd2lsbCBub3QgYmUgc29tZXRoaW5nDQpzdWJqZWN0IHRvIGNoYW5nZSBvdmVyIHRo ZSBsaWZlIG9mIHRoZSBzZXNzaW9uLCBhbmQgaWYgaXQgZG9lcyBjaGFuZ2UsIHdpbGwgd3JlYWsg aGF2b2Mgd2l0aA0KZXhpc3RpbmcgZnJpZW5kc2hpcHMuIChUaGV5IHdpbGwgbmVlZCB0byBiZSBk cm9wcGVkLCByZS1uZWdvdGlhdGVkLCBjYXVzaW5nIExQTnMgdG8gbG9zZSBhbGwNCm1lc3NhZ2Vz IHF1ZXVlZCBhdCB0aGUgRnJpZW5kIGluIHRoZSBtZWFudGltZSkNCg0KPiA+ICsNCj4gPiArPT09 PT09PT09PT09PT09PT09DQo+ID4gK1R4IEFuY2lsbGFyeSBEYXRhDQo+ID4gKz09PT09PT09PT09 PT09PT09PQ0KPiA+ICsNCj4gPiArVGhlIGluZm9ybWF0aW9uIGFib3V0IHdoaWNoIHRpbWluZyBz ZXR0aW5ncyB0byB1c2Ugd2hlbiBzZW5kaW5nIGENCj4gPiArbWVzaCBwYWNrZXQgaXMgY29udGFp bmVkIGluIG1hbmRhdG9yeSBhbmNpbGxhcnkgZGF0YSBhY2NvbXBhbnlpbmcgdGhlDQo+ID4gK3Bh eWxvYWQuIEV4YWN0bHkgb25lIG9mIHRoZSBmb2xsb3dpbmcgKG11dHVhbGx5IGV4Y2x1c2l2ZSkg YW5jaWxsYXJ5DQo+ID4gK2RhdGEgdHlwZXMgbXVzdCBiZSBwcmVzZW50IHdpdGggbm9uemVybyBs ZW5ndGggVHggcGF5bG9hZDoNCj4gPiArDQo+ID4gK01lc2ggVHJhbnNtaXQgSW5mbw0KPiA+ICs9 PT09PT09PT09PT09PT09PT09DQo+ID4gKw0KPiA+ICtjbXNnX2xldmVsICAgICBjbXNnX3R5cGUg ICAgICAgICAgICAgY21zZ19kYXRhW10NCj4gPiArLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0NCj4gPiArU09MX0JMVUVUT09USCAgQlRNRVNIX1RYX0lO Rk8gICAgICAgIFBhcmFtZXRlcnMNCj4gDQo+IEdlbmVyYWwgZm9ybWF0IHdlIHN0YXJ0ZWQgdXNp bmcgaXMgQlRfKiBhbmQgc28gdGhpcyBzaG91bGQgYmUgQlRfTUVTSF8qDQo+IA0KPiA+ICsNCj4g PiArCUNvZGU6CTB4MDENCj4gPiArCVBhcmFtZXRlcnM6DQo+ID4gKwkJQ291bnQJCQkoMSBvY3Rl dCkNCj4gPiArCQlJbnRlcnZhbDoJCSgyIG9jdGV0cykNCj4gPiArCQlNaW5fUmFuZG9tX0RlbGF5 OgkoMSBvY3RldCkNCj4gPiArCQlNYXhfUmFuZG9tX0RlbGF5OgkoMSBvY3RldCkNCj4gPiArDQo+ ID4gK1RoZSByZXRyYW5zbWlzc2lvbiBwYXJhbWV0ZXJzIGZvciBhIHJlZ3VsYXIgb3V0Z29pbmcg bWVzaCBtZXNzYWdlLg0KPiA+ICsNCj4gPiArQ291bnQgaXMgdGhlIHRvdGFsIG51bWJlciBvZiB0 aW1lcyB0byBUeC4gQSBaZXJvIG1lYW5zIFR4IFVudGlsIENhbmNlbGVkLg0KPiA+ICsNCj4gPiAr SW50ZXJ2YWwgaXMgdGhlIG51bWJlciBvZiBtaWxsaXNlY29uZHMgYmV0d2VlbiBlYWNoIFR4Lg0K PiA+ICsNCj4gPiArUmFuZG9tIERlbGF5IGlzIG1pbGxpc2Vjb25kcyBhZGRlZCBiZWZvcmUgZmly c3QgVHguDQo+ID4gKw0KPiA+ICtNZXNoIFBvbGwgVHJhbnNtaXQgSW5mbw0KPiA+ICs9PT09PT09 PT09PT09PT09PT09PT09PQ0KPiA+ICsNCj4gPiArY21zZ19sZXZlbCAgICAgY21zZ190eXBlICAg ICAgICAgICAgICBjbXNnX2RhdGFbXQ0KPiA+ICstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0NCj4gPiArU09MX0JMVUVUT09USCAgQlRNRVNIX1BPTExf VFhfSU5GTyAgICBQYXJhbWV0ZXJzDQo+ID4gKw0KPiA+ICsJQ29kZToJMHgwMg0KPiA+ICsJUGFy YW1ldGVyczoNCj4gPiArCQlTY2FuX0RlbGF5CQkoMSBvY3RldCkNCj4gPiArCQlTY2FuX0R1cmF0 aW9uCQkoMSBvY3RldCkNCj4gPiArCQlGaWx0ZXJfSWRzWzJdCQkoMiBvY3RldHMpDQo+ID4gKwkJ TWluX1JhbmRvbV9EZWxheToJKDEgb2N0ZXQpDQo+ID4gKwkJTWF4X1JhbmRvbV9EZWxheToJKDEg b2N0ZXQpDQo+ID4gKw0KPiA+ICtTY2FuX0RlbGF5IGRlc2NyaWJlcyB0aGUgd2FpdCBwZXJpb2Qg dG8gYmVnaW4gc2Nhbm5pbmcgYWZ0ZXIgdGhlIFBvbGwNCj4gPiArbWVzc2FnZSBpcyBzZW50Lg0K PiA+ICsNCj4gPiArRmlsdGVyX0lkcyBjb250YWluIElEcyBvZiB0d28gZmlsdGVycyB0aGF0IGFj Y291bnQgZm9yIHR3byBwb3NzaWJsZQ0KPiA+ICt2YWx1ZXMgb2YgSVYgVXBkYXRlIGJpdCBpbiBl eHBlY3RlZCBQb2xsIHJlc3BvbnNlLg0KPiA+ICsNCj4gPiArUmFuZG9tIERlbGF5IGlzIG1pbGxp c2Vjb25kcyBhZGRlZCBiZWZvcmUgVHguDQo+ID4gKw0KPiA+ICtNZXNoIFBvbGwgUmVzcG9uc2Ug VHJhbnNtaXQgSW5mbw0KPiA+ICs9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PQ0KPiA+ ICsNCj4gPiArY21zZ19sZXZlbCAgICAgY21zZ190eXBlICAgICAgICAgICAgICAgIGNtc2dfZGF0 YVtdDQo+ID4gKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tDQo+ID4gK1NPTF9CTFVFVE9PVEggIEJUTUVTSF9QT0xMX1JTUF9UWF9JTkZPICBQYXJh bWV0ZXJzDQo+ID4gKw0KPiA+ICsJQ29kZToJMHgwMw0KPiA+ICsJUGFyYW1ldGVyczoNCj4gPiAr CQlJbnN0YW50CQkoNCBvY3RldHMpDQo+ID4gKwkJRGVsYXkJCSgxIG9jdGV0KQ0KPiA+ICsNCj4g PiArVGhlIHRpbWluZyBwYXJhbWV0ZXJzIGZvciBzZW5kaW5nIGEgZnJpZW5kIHBvbGwgcmVzcG9u c2UuDQo+ID4gKw0KPiA+ICtJbnN0YW50IGlzIGEgNC1vY3RldCBvcGFxdWUgdmFsdWUgdGhhdCBj b3JyZXNwb25kcyB0byB0aGUgaW5zdGFudCBhbg0KPiA+ICthc3NvY2lhdGVkIGluY29taW5nIG1l c2ggbWVzc2FnZSB3YXMgcmVjaWV2ZWQsIGZvciB0aW1pbmcgcHVycG9zZXMuDQo+ID4gKw0KPiA+ ICtEZWxheSBkZWZpbmVzIG51bWJlciBvZiBtaWxsaXNlY29uZHMgYWZ0ZXIgdGhlIGNvcnJlc3Bv bmRpbmcgSW5zdGFudA0KPiA+ICt0byB3YWl0IGJlZm9yZSBzZW5kaW5nIHRoaXMgVHguDQo+ID4g Kw0KPiA+DQo+ICtfX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X19fX19fX19fX18NCj4gX19fX19fX19fX18NCj4gPiArDQo+ID4gK1RoZSBmb2xsb3dpbmcgYW5j aWxsYXJ5IHR5cGVzIGFyZSBvcHRpb25hbCB3aXRoIG5vbnplcm8gbGVuZ3RoIFR4IHBheWxvYWQ6 DQo+ID4gKw0KPiA+ICtUcmFuc21pdCBQb3dlcg0KPiA+ICs9PT09PT09PT09PT09PQ0KPiA+ICsN Cj4gPiArY21zZ19sZXZlbCAgICAgY21zZ190eXBlICAgICAgICAgICAgIGNtc2dfZGF0YVtdDQo+ ID4gKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLQ0KPiA+ICtTT0xfQkxVRVRPT1RIICBCVE1FU0hfVFhfUE9XRVJfSU5GTyAgUGFy YW1ldGVycw0KPiA+ICsNCj4gPiArCUNvZGU6CTB4MDQNCj4gPiArCVBhcmFtZXRlcnM6DQo+ID4g KwkJVHhfUG93ZXIJKDEgb2N0ZXQpDQo+ID4gKw0KPiA+ICtUcmFuc21pdCBwb3dlciBzZXR0aW5n IGNhbiBiZSB1c2VkIGZvciBmaW5lciBjb250cm9sIG9uIHRoZSBvdXRib3VuZA0KPiBtZXNzYWdl cy4NCj4gPiArSWYgbm90IHByZXNlbnQsIHVzZSBkZWZhdWx0IHZhbHVlIChidWlsdGluIG9yIGNv bmZpZ3VyZWQgYXMgc29ja2V0IG9wdGlvbnMpLg0KPiA+ICsNCj4gPiArVHJhbnNtaXQgQ2hhbm5l bA0KPiA+ICs9PT09PT09PT09PT09PT09DQo+ID4gK2Ntc2dfbGV2ZWwgICAgIGNtc2dfdHlwZSAg ICAgICAgICAgICAgIGNtc2dfZGF0YVtdDQo+ID4gKy0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLQ0KPiA+ICtTT0xfQkxVRVRPT1RI ICBCVE1FU0hfVFhfQ0hBTk5FTF9JTkZPICBQYXJhbWV0ZXJzDQo+ID4gKw0KPiA+ICsJQ29kZToJ MHgwNQ0KPiA+ICsJUGFyYW1ldGVyczoNCj4gPiArCQlUeF9DaGFubmVsCSgxIG9jdGV0KQ0KPiA+ ICsNCj4gPiArVGhlIHByZXNlbmNlIG9mIHRoaXMgb3B0aW9uIHNwZWNpZmllcyB0cmFuc21pdCBj aGFubmVsIGFuZCBhbGxvd3MgZm9yDQo+ID4gK2JldHRlciBjb250cm9sLCBlLmcuLCB0byByZXNw b25kIG9uIHRoZSBzYW1lIGNoYW5uZWwgYXMgdGhlIG9uZSBvbg0KPiA+ICt3aGljaCBpbmNvbWlu ZyBtZXNzYWdlIGhhcyBiZWVuIHJlY2VpdmVkLg0KPiA+ICtJZiBub3QgcHJlc2VudCwgdGhlIGRl ZmF1bHQgdmFsdWUgd2lsbCBiZSB1c2VkIChidWlsdGluIG9yIGNvbmZpZ3VyZWQNCj4gPiArYXMg c29ja2V0IG9wdGlvbnMpLg0KPiANCj4gRG9u4oCZdCBib3RoZXIgd2l0aCB0aGVzZSB0d28gYXQg dGhlIG1vbWVudC4gSSB0aGluayB0aGV5IGhhdmUgbm8gdXNlIGZvciB1cw0KPiBleGNlcHQgZm9y IGFsbG93aW5nIHNvbWUgdGVzdGluZyB2aWEgZGVidWdmcy4gVGhleSBuZWVkZWQgdG8gYmUgaW4g dGhlIEhDSQ0KPiBzcGVjIGZvciBjb21wbGV0ZW5lc3MgYW5kIGJlY2F1c2UgeW91IGNhbiBhbHNv IHVzZSB0aGUgSENJIHNwZWMgdG8gYnVpbGQgYQ0KPiBtZXNoIHNuaWZmZXIuDQoNCkkgYW0gZmlu ZSBub3QgaW5jbHVkaW5nIFR4IFBvd2VyIGFuZCBDaGFubmVsIHNldHRpbmdzIGZvciBub3csIGJ1 dCB3ZSBpbmNsdWRlZCB0aGVtDQppbiBjYXNlIHdlIHdhbnRlZCAiRmluZSBDb250cm9sIiBvdmVy IHRoZW0gaW4gdGhlIGZ1dHVyZS4uLiAgQnV0IHRoZXkgYXJlIGlnbm9yZWQgdG9kYXkuDQoNCj4g DQo+ID4gKw0KPiA+ICsNCj4gPiArQWRkaXRpb25hbCB0aGUgYW5jaWxsYXJ5IGRhdGEgcG9ydGlv biBtYXkgY29udGFpbiBDb250cm9sIHR5cGUgaW5mb3JtYXRpb24uDQo+ID4gKw0KPiA+ICtUaGUg Zm9sbG93aW5nIGFyZSBDb250cm9sIGFuY2lsbGFyeSBkYXRhIHR5cGVzLCB0aGF0IG1lIGJlIHNl bnQgd2l0aA0KPiA+ICtvciB3aXRob3V0IHBheWxvYWRzOg0KPiA+ICsNCj4gPiArU2Nhbg0KPiA+ ICs9PT09PT09DQo+ID4gK2Ntc2dfbGV2ZWwgICAgIGNtc2dfdHlwZSAgICAgICAgICAgICBjbXNn X2RhdGFbXQ0KPiA+ICstLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0NCj4gPiArU09MX0JMVUVUT09USCAgQlRNRVNIX1NDQU4gICAg ICAgICAgIFBhcmFtZXRlcnMNCj4gPiArDQo+ID4gKwlDb2RlOgkweDA2DQo+ID4gKwlQYXJhbWV0 ZXJzOg0KPiA+ICsJCUZpbHRlcl9JZHNbXQkodmFyaWFibGUpDQo+ID4gKw0KPiA+ICtUbyBlbmFi bGUvZGlzYWJsZSBzY2FubmluZyBvZiBNZXNoIHBhY2tldHMuDQo+ID4gKw0KPiA+ICtJZiBGaWx0 ZXJfSWRzIGFycmF5IGlzIG5vbnplcm8gbGVuZ3RoLCBzdGFydCBzY2FubmluZyB3aXRoIHRoZQ0K PiA+ICtzcGVjaWZpZWQgZmlsdGVycyAoZmlsdGVycyBhcmUgaW5pdGlhbGl6ZWQgdmlhIHNvY2tl dCBvcHRpb25zDQo+ID4gK21lY2hhbmlzbSkuIFRoaXMgYXJyYXkgcmVwbGFjZXMgYW55IHByaW9y IGZpbHRlcnMuDQo+ID4gKw0KPiA+ICtJZiBubyBmaWx0ZXIgSURzIGFyZSBwcmVzZW50IChpLmUu LCB6ZXJvIGFycmF5IGxlbmd0aCksIHN0b3Agc2Nhbm5pbmcuDQo+IA0KPiBJIGRpc2xpa2UgdGhp cy4gV2Ugc2hvdWxkIGhhdmUgYSB0eXBlIDB4MDIgY29tbWFuZCB0aGF0IHRlbGxzIHVzIHdoYXQg a2luZCBvZg0KPiByb2xlIHdlIGFyZSBvcGVyYXRpbmcgaW4uIEFuZCBiYXNlZCBvbiB0aGF0IHNj YW5uaW5nIGlzIGVuYWJsZWQgYnkgYmluZGluZw0KPiB0aGUgc29ja2V0IGFuZCBjbG9zaW5nIGl0 LiBPciBjaGFuZ2luZyB0aGUgcm9sZS4gVGhlIHdob2xlIGZpbHRlciBpZCBleHBvc3VyZQ0KPiBz ZWVtcyBhIGJpdCBvZGQgdG8gbWUuIEkgcmVhbGl6ZSB0aGF0IHRoaXMgbWlnaHQgbG9vayBzaW1w bGUsIGJ1dCBhIGZldyB0aGluZ3MNCj4gc2hvdWxkIGJlIGRvbmUgYnkgdGhlIGtlcm5lbC4gQW5k IG1hbmFnaW5nIHRoZSBzY2FubmluZyBmaWx0ZXJzIGlzIG9uZSBvZg0KPiB0aGVtLiBTbyB3ZSBu ZWVkIHRvIGZlZWQgdGhlIGtlcm5lbCBlbm91Z2ggZGV0YWlscyB0aGF0IGl0IGNhbiBkbyB0aGF0 DQo+IGVmZmljaWVudGx5LiBTd2FwcGluZyBmaWx0ZXJzIGFyb3VuZCBmcm9tIHVzZXJzcGFjZSBp cyBwYWluZnVsLg0KDQpJbiBteSBvcGluaW9uLCBVc2VyIHNwYWNlIGNvbnRyb2wgb2YgdGhlIGZp bHRlcnMgaXMgZXNzZW50aWFsLiBVbmxlc3MgdGhlIGtlcm5lbCBpcw0KaGFuZGxpbmcgQ3J5cHRv LCB0aGVyZSBpcyBubyB3YXkgdG8ga25vdyBOSURzLCBQcm92aXNpb25pbmcgU2Vzc2lvbiBJRHMg ZXRjLiBXaGlsZQ0KdGhlIEtlcm5lbCBoYW5kbGVzIHRoZSBkaXNjcmV0ZSB0aW1pbmcgZm9yIGlu ZGl2aWR1YWwgcGFja2V0cywgb25seSBVc2VyIHNwYWNlIGtub3dzDQplbm91Z2ggYWJvdXQgdGhl IGN1cnJlbnQgc3RhdGUgb2YgdGhlIE1lc2ggdG8ga25vdyB3aGF0IGZpbHRlcnMgYXJlIHJlcXVp cmVkDQphdCBhbnkgZ2l2ZW4gdGltZS4NCg0KDQo+IA0KPiBPdGhlcndpc2Ugd2UgY291bGQganVz dCBleHBvc2UgSENJX0NIQU5ORUxfTUVTSCBhcyBIQ0kgbWVzaA0KPiBjb21tYW5kcy4gVGhleSBh cmUgYWxsIG11bHRpcGxleGVkIHZpYSBhIHNpbmdsZSBvcGNvZGUgYW55d2F5IGFuZCBoYXZlIGEN Cj4gc2luZ2xlIGV2ZW50IHdpdGggYW5kIGV2ZW50IHByZWZpeC4gU28gaWYgeW91IHdhbnQgdGhp cyBkZXRhaWxlZCBjb250cm9sIG9mIHRoZQ0KPiBIQ0kgY29tbWFuZHMsIHRoZW4gZG9u4oCZdCB0 cnkgdG8gcHV0IHRvbyBtdWNoIGtlcm5lbCBpbiBiZXR3ZWVuLiBKdXN0IGRvDQo+IHBhdGggdGhy b3VnaCBvZiB0aGVtLg0KPiANCj4gV2UgY291bGQgZG8ganVzdCB0aGF0IGFuZCB0aGVuIGxlYXZl IHRoZSBrZXJuZWwgcG9ydGlvbiBmb3IgdGhpcyBhbG9uZS4NCj4gTWF5YmUgaXQgaXMgd29ydGgg d2hpbGUgdG8gZGViYXRlIHByb3MgYW5kIGNvbnMgZm9yIHRoaXMuIEl0IGlzIGFjdHVhbGx5IG5v dCB0aGUNCj4gd29yc3QgaWRlYSB0byBnaXZlIGV4Y2x1c2l2ZSBhY2Nlc3MgdG8gdGhlIG1lc2gg Y29tbWFuZHMuIEl0IHdvdWxkIGJlDQo+IHNpbWlsYXIgdG8gSENJX0NIQU5ORUxfVVNFUiwgYnV0 IG9ubHkgZm9yIHRoZSBtZXNoIGNvbW1hbmRzIGFuZCB3ZQ0KPiB3b3VsZCBzdHJpcCB0aGUgSENJ IGNvbW1hbmQgaGVhZGVyIGFuZCBIQ0kgZXZlbnQgaGVhZGVyICsgZXZlbnQgcHJlZml4DQo+IG9m ZiBpdCBzbyB0aGF0IHlvdSBqdXN0IGhhdmUgdG8gZGVhbCB3aXRoIG1lc2ggb3Bjb2RlIGFuZCBt ZXNoIHN1YmV2ZW50DQo+IGNvZGUuDQoNCkFyZSBjdXJyZW50IHBsYW4gaXMgdG8ganVzdCBwYXNz IHBhY2tldHMgd2Ugd2FudCBzZW50IHdpdGggYSByZXF1ZXN0ZWQgdGltaW5nLA0KYW5kIGZpbHRl ciBpbmNvbWluZyBwYWNrZXRzIGR1cmluZyBkZXNpZ25hdGVkIFNjYW4gd2luZG93cw0KDQo+IA0K PiBIbW1tIC4uIGl0IGdldHMgYSBiaXQgdHJpY2t5IGZvciB0aGUgY29tbWFuZCBjb21wbGV0ZSBw b3J0aW9uIG9mIGl0LiBTbyBpdA0KPiBtaWdodCBoYXZlIHRvIGJlIHRoZSBmdWxsIEhDSSBhbnl3 YXksIGJ1dCByZXN0cmljdGVkIHRvIG9uZSBvcGNvZGUgYW5kIG9ubHkNCj4gbWF0Y2hpbmcgZXZl bnRzIGJlaW5nIGZvcndhcmRlZC4NCg0KV2UgYXJlIG5vdCBkb2luZyAqYW55dGhpbmcqIGxpa2Ug Q29tbWFuZCBDb21wbGV0ZSwgYW5kIEkgc3Ryb25nbHkgYXJndWUgYWdhaW5zdA0KYW55dGhpbmcg bGlrZSBpdC4gSW4gTWVzaCBldmVyeXRoaW5nIGlzICpCZXN0IEVmZm9ydCogd2hldGhlciB3ZSBs aWtlIGl0IG9yIG5vdC4gIENvbW1hbmQNCkNvbXBsZXRlcyBtYXkgZ3VhcmFudGVlIHRoYXQgYSBD b250cm9sbGVyIGhhcyBkb25lIHdoYXQgd2UgYXNrLCBidXQgd2hldGhlciBpdCBoYXMNCmRvbmUg d2hhdCB3ZSBhc2sgaXMgMTAwJSBpbW1hdGVyaWFsLCB1bmxlc3MgeW91IGhhdmUgYSB1c2UtY2Fz ZSBkZW1vbnN0cmF0aW5nIGhvdw0KaXQgY2FuIGJlIHVzZWZ1bCBpbiBhIE1lc2ggZW52aXJvbm1l bnQuICBUaGUgb25seSB0aGluZyB3ZSBjYXJlIGFib3V0IGlzIHdoZXRoZXIgYQ0KcmVtb3RlIGRl dmljZSBoYXMgcmVjZWl2ZWQgb3VyIHBhY2tldHMsIG9yIHdoZXRoZXIgd2UgcmVjZWl2ZSB0aGVp cnMuIEFsbCByZWxpYWJpbGl0eQ0KaXMgYnVpbHQgaW50byB0aGUgVXNlci1TcGFjZSBOZXR3b3Jr IGFuZCBBY2Nlc3MgbGF5ZXJzLi4uIHVubGlrZSBBQ0wgYmFzZWQgc3lzdGVtcy4NCg0KQWxsIGZl ZWRiYWNrIGZyb20gS2VybmVsIC0tPiBVc2VyIHNwYWNlIGNhbiBiZSBoYW5kbGVkIHdpdGggU3Rh dHVzIGNvZGVzIHJldHVybmVkIGZyb20NCnNvY2tldCB3cml0ZXMsIG9yIHNldCBzb2NrIG9wdGlv bnMuDQoNCg0KPiANCj4gQWN0dWFsbHkgaWYgSSBzcGluIG15IHRyYWluIG9mIHRob3VnaHRzIGZ1 cnRoZXIgbm93LCB3ZSBtaWdodCB3YW50IHRvIHB1dA0KPiBIQ0lfQ0hBTk5FTF9NRVNIIG9uIGlj ZSBhbmQgbGVhdmUgdGhhdCBmb3Igc29tZSBmdXR1cmUgdmVyc2lvbi4gSSB0aGluaw0KPiBwcm92 aWRpbmcgc29tZSBzb3J0IG9mIGFic3RyYWN0aW9uIGFuZCBhdXRvbWF0aWMgaGFuZGxpbmcgb2Yg c2Nhbm5pbmcgZmlsdGVycw0KPiBldGMuIGlzIGEgZ29vZCBhYnN0cmFjdGlvbiBmb3IgdGhlIGtl cm5lbCwgYnV0IGl0IG1pZ2h0IGJlIHNvbWV0aGluZyB0aGF0IHdpbGwNCj4gdGFrZSBhIHdoaWxl IHRvIGJlIGRlZmluZWQgYW5kIHdvcmtpbmcgY29ycmVjdGx5LiBEb2luZyB0aGUgSENJIG1lc2gN Cj4gY29tbWFuZHMgZGlyZWN0bHkgb24gYSBzb2NrZXQgaGFzIHRoZSBjb21tYW5kIGNvbXBsZXRl IHByb2JsZW0gYXMNCj4gc3RhdGVkIGFib3ZlIGFuZCBoYXZpbmcgeWV0IGFub3RoZXIgdmFyaWF0 aW9uIG9mIEhDSV9DSEFOTkVMX1JBVyB3aXRoDQo+IG1lc2ggSENJIGZpbHRlcnMgc2VlbXMgd3Jv bmcgYXMgd2VsbC4gRXNwZWNpYWxseSBzaW5jZSBldmVudHVhbGx5IEkgd2FudCB0bw0KPiBoYXZl IGFuIG9wdGlvbiB0byBkaXNhYmxlIEhDSV9DSEFOTkVMX1JBVy4gSW4gYWRkaXRpb24gaXQgd291 bGQgaGF2ZQ0KPiBiZWVuIGV4Y2x1c2l2ZSBhY2Nlc3MgdG8gbWFrZSBzdXJlIG5vdGhpbmcgZ29l cyB3cm9uZy4NCj4gDQo+IFNvIG1heWJlIHdlIGp1c3QgZXhwb3NlIEhDSSBtZXNoIGNvbW1hbmRz IGFzIE1HTVQgY29tbWFuZCBhbmQNCj4gTUdNVCBldmVudC4NCj4gDQo+IE1lc2ggQ29tbWFuZA0K PiA9PT09PT09PT09PT0NCj4gDQo+IAlDb21tYW5kIENvZGU6CQkweDAwNDMNCj4gCUNvbnRyb2xs ZXIgSW5kZXg6CTxjb250cm9sbGVyIGluZGV4Pg0KPiAJQ29tbWFuZCBQYXJhbWV0ZXJzOglPcGNv ZGUgKDEgT2N0ZXQpDQo+IAkJCQlDb21tYW5kIHBhcmFtZXRlcnMgKFZhcmlhYmxlKQ0KPiAJUmV0 dXJuIFBhcmFtZXRlcnM6CVN0YXR1cyAoMSBPY3RldCkNCj4gCQkJCU9wY29kZSAoMSBPY3RldCkN Cj4gCQkJCVJldHVybiBwYXJhbWV0ZXJzIChWYXJpYWJsZSkNCj4gDQo+IE1lc2ggRXZlbnQNCj4g PT09PT09PT09PQ0KPiANCj4gCUV2ZW50IENvZGU6CQkweDAwMjYNCj4gCUNvbnRyb2xsZXIgSW5k ZXg6CTxjb250cm9sbGVyIGluZGV4Pg0KPiAJRXZlbnQgUGFyYW1ldGVyczoJU3ViZXZlbnQgKDEg T2N0ZXQpDQo+IAkJCQlFdmVuIHBhcmFtZXRlcnMgKHZhcmlhYmxlKQ0KPiANCj4gVGhpcyB3b3Vs ZCBtYXAgMToxIHRvIHRoZSBIQ0kgbWVzaCBjb21tYW5kcyBhbmQgZXZlbnRzIHdpdGggdGhlIHRp bnkNCj4gbW9kaWZpY2F0aW9uIHRoYXQgdGhlIGV2ZW50IHByZWZpeCBpcyBzdHJpcHBlZCBmcm9t IHRoZSBNZXNoIEV2ZW50IGFuZCBub3QNCj4gcHJvdmlkZWQgYW5kIHdpdGggdGhlIE1lc2ggR2V0 IE9wdGlvbnMgY29tbWFuZCBpc3N1ZWQgaXQgd291bGQgYmUNCj4gbWFwcGVkIHRvIGV2ZW50IHBy ZWZpeCBsZW5ndGggb2YgemVyby4NCj4gDQo+IEFuZCB0aGVuIG9ubHkgYSBzZXR0aW5ncyAxNiBN ZXNoIHdvdWxkIGJlIG5lZWRlZC4gT3Igd2UgbWFrZSB0aGUNCj4gY29tbWFuZCBhbmQgZXZlbnQg b25seSBhdmFpbGFibGUgd2hlbiBIQ0kgbWVzaCBjb21tYW5kcyBhcmUgYWN0dWFsbHkNCj4gc3Vw cG9ydGVkLiBUaGF0IGlzIHNvbWV0aGluZyB0aGF0IHdvdWxkIG5lZWRzIHRvIGJlIGRpc2N1c3Np bmcuIEluIGdlbmVyYWwsDQo+IHdlIGhhdmUgbm90IGhhZCBsaW1pdGVkIGNvbW1hbmRzIGJhc2Vk IG9uIGhhcmR3YXJlIGZ1bmN0aW9uYWxpdHksIGJ1dA0KPiB0aGVzZSB0d28gd291bGQgYmUgc3Bl Y2lhbCBzaW5jZSB0aGV5IGFyZSB2ZW5kb3Igc3BlY2lmaWMgY29tbWFuZHMgaW4gdGhlDQo+IGZp cnN0IHBsYWNlLg0KPiANCj4gRm9yIHRoZSBrZXJuZWwgc2lkZSB3ZSBvbmx5IGhhdmUgdGhlIHRo ZSBkcml2ZXIgcHJvdmlkZSB0aGUgbWVzaCBIQ0kgb3Bjb2RlDQo+IGFuZCBydW4gTWVzaCBHZXQg T3B0aW9ucyBvbmNlIHRvIHJldHJpZXZlIHRoZSBmaXJtd2FyZXMgZXZlbnQgcHJlZml4IHNvDQo+ IHRoYXQgaXQgY2FuIGJlIHplcm9lZCBvdXQgYnkgdGhlIE1HTVQgY29tbWFuZHMgYW5kIGV2ZW50 cy4NCj4gDQo+IFdpdGggdGhhdCBjb21tZW50cz8gVGhvdWdodHM/DQo+IA0KPiBSZWdhcmRzDQo+ IA0KPiBNYXJjZWwNCj4gDQo+IC0tDQo+IFRvIHVuc3Vic2NyaWJlIGZyb20gdGhpcyBsaXN0OiBz ZW5kIHRoZSBsaW5lICJ1bnN1YnNjcmliZSBsaW51eC1ibHVldG9vdGgiIGluDQo+IHRoZSBib2R5 IG9mIGEgbWVzc2FnZSB0byBtYWpvcmRvbW9Admdlci5rZXJuZWwub3JnIE1vcmUgbWFqb3Jkb21v DQo+IGluZm8gYXQgIGh0dHA6Ly92Z2VyLmtlcm5lbC5vcmcvbWFqb3Jkb21vLWluZm8uaHRtbA0K ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-26 19:01 ` Gix, Brian @ 2018-02-27 12:40 ` Marcel Holtmann 0 siblings, 0 replies; 10+ messages in thread From: Marcel Holtmann @ 2018-02-27 12:40 UTC (permalink / raw) To: Brian Gix; +Cc: Stotland, Inga, linux-bluetooth@vger.kernel.org Hi Brian, <snip> I am focusing first on the later part of the comments. >> I dislike this. We should have a type 0x02 command that tells us what kind of >> role we are operating in. And based on that scanning is enabled by binding >> the socket and closing it. Or changing the role. The whole filter id exposure >> seems a bit odd to me. I realize that this might look simple, but a few things >> should be done by the kernel. And managing the scanning filters is one of >> them. So we need to feed the kernel enough details that it can do that >> efficiently. Swapping filters around from userspace is painful. > > In my opinion, User space control of the filters is essential. Unless the kernel is > handling Crypto, there is no way to know NIDs, Provisioning Session IDs etc. While > the Kernel handles the discrete timing for individual packets, only User space knows > enough about the current state of the Mesh to know what filters are required > at any given time. If we really think that userspace should control the filters, then I am really tempted to say that the HCI mesh commands is the API from userspace to the kernel to the controller. So the kernel just plays a little bit of path through and nothing else. >> Otherwise we could just expose HCI_CHANNEL_MESH as HCI mesh >> commands. They are all multiplexed via a single opcode anyway and have a >> single event with and event prefix. So if you want this detailed control of the >> HCI commands, then don’t try to put too much kernel in between. Just do >> path through of them. >> >> We could do just that and then leave the kernel portion for this alone. >> Maybe it is worth while to debate pros and cons for this. It is actually not the >> worst idea to give exclusive access to the mesh commands. It would be >> similar to HCI_CHANNEL_USER, but only for the mesh commands and we >> would strip the HCI command header and HCI event header + event prefix >> off it so that you just have to deal with mesh opcode and mesh subevent >> code. > > Are current plan is to just pass packets we want sent with a requested timing, > and filter incoming packets during designated Scan windows > >> >> Hmmm .. it gets a bit tricky for the command complete portion of it. So it >> might have to be the full HCI anyway, but restricted to one opcode and only >> matching events being forwarded. > > We are not doing *anything* like Command Complete, and I strongly argue against > anything like it. In Mesh everything is *Best Effort* whether we like it or not. Command > Completes may guarantee that a Controller has done what we ask, but whether it has > done what we ask is 100% immaterial, unless you have a use-case demonstrating how > it can be useful in a Mesh environment. The only thing we care about is whether a > remote device has received our packets, or whether we receive theirs. All reliability > is built into the User-Space Network and Access layers... unlike ACL based systems. > > All feedback from Kernel --> User space can be handled with Status codes returned from > socket writes, or set sock options. Don’t read too much into command complete. That is just flow control handling so you know when the controller has accepted the command and is a way to return status or other return parameters. Regards Marcel ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-26 13:49 ` Marcel Holtmann 2018-02-26 19:01 ` Gix, Brian @ 2018-02-28 20:17 ` Stotland, Inga 2018-02-28 20:45 ` Gix, Brian 2018-02-28 20:51 ` Marcel Holtmann 1 sibling, 2 replies; 10+ messages in thread From: Stotland, Inga @ 2018-02-28 20:17 UTC (permalink / raw) To: marcel@holtmann.org; +Cc: linux-bluetooth@vger.kernel.org [-- Attachment #1: Type: text/plain, Size: 14729 bytes --] Hi Marcel, On Mon, 2018-02-26 at 14:49 +0100, Marcel Holtmann wrote: > Hi Inga, > > > --- > > doc/mesh-api.txt | 269 > > +++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 269 insertions(+) > > create mode 100644 doc/mesh-api.txt > > > > diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt > > new file mode 100644 > > index 000000000..87311faba > > --- /dev/null > > +++ b/doc/mesh-api.txt > > @@ -0,0 +1,269 @@ > > +Bluetooth Mesh Socket API > > +************************* > > + > > +Copyright (C) 2018 Intel Corporation. All rights reserved. > > + > > +This document decribes the data format that is used for > > communication with > > +the kernel via Bluetooth Mesh socket. The data that are passed > > over this > > +type of a socket is specific to Bluetooth Mesh Profile. > > + > > +The Bluetooth Mesh socket is implemented as part of PF_BLUETOOTH > > family > > +and can be created by opening a raw HCI socket with hci_channel > > set to > > +HCI_CHANNEL_BTMESH. The mesh socket requires the creating process > > to have > > call this HCI_CHANNEL_MESH. There is no point in adding BT* here. > > > +CAP_NET_ADMIN capability. > > + > > +=================================================== > > +Packet Structure: user space to/from kernel (Tx/Rx) > > +=================================================== > > + > > +Each packet to or from the Over-the-Air interface is sent between > > the user > > +space and the kernel must be of nonzero length, and start with the > > AD_Type, > > +followed by a variable amount of additional payload. > > + > > + 0 8 > > + +---------------+------------------------------------ > > + | AD_Type | Mesh Packet > > + +---------------+—————————————————— > > + > > Actually I would have really preferred that we followed the Proxy PDU > format. > > 2 Bits reserved > 6 Bits packet type > Variable data payload > > I think that we really need the 0x02 type for configuration between > the kernel and userspace. The idea is to allow the data payload to be identical to the mesh message that would go over the air. Hence, everything that is not part of the actual mesh message ends up in either cmsg or sockopt. Introducing 0x2 "configuration" type will break this paradigm since the configuration for mesh does not map directly to configuration for Proxy. > > +AD_Type (1 octet -- Defined by the Bluetooth SIG) > > +================= > > + > > +Provisioning: 0x29 - The payload contains a Mesh > > Provisioning message > > +Network: 0x2A - The payload contains a Mesh > > Data Packet > > +Beacon: 0x2B - The payload contains a Mesh > > Beacon > > + > > +The AD_Type values correspond to AD types introduced in Mesh > > Profile > > +specification. The API is designed to support additional types. > > + > > + > > +A packet with empty (Zero-Length) payload may be sent over the > > socket in case > > +when only Control ancillary data is needed (e.g., Flush or Scan, > > defined below). > > + > > +=============== > > +Socket Options > > +=============== > > + > > +HCI Mesh Scan Filter > > +==================== > > + Code: 0x05 > > + > > + Filter_Id (1 octet) > > + Duplicates (1 octet) > > + Filter (variable length) > > + > > +Read/write socket option used to setup scan filters for mesh > > specific packets. > > +First octet of filter must include at least the AD_Type but may be > > longer to > > +include NIDs or other known data. > > These ones look more like type 0x02 PDU packets. And this in > particular I would have done as Add Network ID and Remove Network ID > and let the kernel deal with deciding if it chooses a more global > filter (since not enough filters are available) or if it can be more > precise with the filtering. > This is a once in awhile operation, so It felt like socket option seems like a better place for it. It could be made more user friendly at the expense of losing flexibility in future of adding filtering on additional AD Types. > > + > > +HCI Mesh Default Tx Power > > +========================= > > + Code: 0x06 > > + > > + Tx_Power (1 octet) > > + > > +Read/write socket option for setting default Tx power. > > Leave this out for now. I assume initially we will always use 127 for > do not care. If we think it is valuable for testing, then via > debugfs. > I agree. No use for this at the moment. > > + > > +HCI Mesh Default Cahnnel Map > > +============================ > > + Code: 0x07 > > + > > + Chan_map (1 octet) > > + > > +Read/write socket option for setting default channel map. > > Also irrelevant and only for fine tuning and testing. Can be exposed > via debugfs. > Agreed. > > + > > +HCI Mesh Accuracy > > +================= > > + Code: 0x08 > > + > > + Accuracy (1 octet) > > + > > +Read-only socket option to obtain the value of the smallest number > > of > > +milliseconds that a Mesh Friendship Offer Window can be, for > > guaranteed > > +Poll Response transmission within that window. > > I still would have done this via type 0x02 and a PDU exchange > protocol. Mainly because then it also becomes traceable via btmon. So > yes, I want the mesh channel also be included in btmon. > > > + > > +================== > > +Tx Ancillary Data > > +================== > > + > > +The information about which timing settings to use when sending a > > mesh > > +packet is contained in mandatory ancillary data accompanying the > > +payload. Exactly one of the following (mutually exclusive) > > ancillary > > +data types must be present with nonzero length Tx payload: > > + > > +Mesh Transmit Info > > +=================== > > + > > +cmsg_level cmsg_type cmsg_data[] > > +-------------------------------------------------- > > +SOL_BLUETOOTH BTMESH_TX_INFO Parameters > > General format we started using is BT_* and so this should be > BT_MESH_* > > > + > > + Code: 0x01 > > + Parameters: > > + Count (1 octet) > > + Interval: (2 octets) > > + Min_Random_Delay: (1 octet) > > + Max_Random_Delay: (1 octet) > > + > > +The retransmission parameters for a regular outgoing mesh message. > > + > > +Count is the total number of times to Tx. A Zero means Tx Until > > Canceled. > > + > > +Interval is the number of milliseconds between each Tx. > > + > > +Random Delay is milliseconds added before first Tx. > > + > > +Mesh Poll Transmit Info > > +======================= > > + > > +cmsg_level cmsg_type cmsg_data[] > > +--------------------------------------------------- > > +SOL_BLUETOOTH BTMESH_POLL_TX_INFO Parameters > > + > > + Code: 0x02 > > + Parameters: > > + Scan_Delay (1 octet) > > + Scan_Duration (1 octet) > > + Filter_Ids[2] (2 octets) > > + Min_Random_Delay: (1 octet) > > + Max_Random_Delay: (1 octet) > > + > > +Scan_Delay describes the wait period to begin scanning after the > > Poll message > > +is sent. > > + > > +Filter_Ids contain IDs of two filters that account for two > > possible values of > > +IV Update bit in expected Poll response. > > + > > +Random Delay is milliseconds added before Tx. > > + > > +Mesh Poll Response Transmit Info > > +================================ > > + > > +cmsg_level cmsg_type cmsg_data[] > > +----------------------------------------------------- > > +SOL_BLUETOOTH BTMESH_POLL_RSP_TX_INFO Parameters > > + > > + Code: 0x03 > > + Parameters: > > + Instant (4 octets) > > + Delay (1 octet) > > + > > +The timing parameters for sending a friend poll response. > > + > > +Instant is a 4-octet opaque value that corresponds to the instant > > an > > +associated incoming mesh message was recieved, for timing > > purposes. > > + > > +Delay defines number of milliseconds after the corresponding > > Instant > > +to wait before sending this Tx. > > + > > +__________________________________________________________________ > > __ > > + > > +The following ancillary types are optional with nonzero length Tx > > payload: > > + > > +Transmit Power > > +============== > > + > > +cmsg_level cmsg_type cmsg_data[] > > +--------------------------------------------------------------- > > +SOL_BLUETOOTH BTMESH_TX_POWER_INFO Parameters > > + > > + Code: 0x04 > > + Parameters: > > + Tx_Power (1 octet) > > + > > +Transmit power setting can be used for finer control on the > > outbound messages. > > +If not present, use default value (builtin or configured as socket > > options). > > + > > +Transmit Channel > > +================ > > +cmsg_level cmsg_type cmsg_data[] > > +--------------------------------------------------------------- > > +SOL_BLUETOOTH BTMESH_TX_CHANNEL_INFO Parameters > > + > > + Code: 0x05 > > + Parameters: > > + Tx_Channel (1 octet) > > + > > +The presence of this option specifies transmit channel and allows > > +for better control, e.g., to respond on the same > > +channel as the one on which incoming message has been received. > > +If not present, the default value will be used (builtin or > > configured as > > +socket options). > > Don’t bother with these two at the moment. I think they have no use > for us except for allowing some testing via debugfs. They needed to > be in the HCI spec for completeness and because you can also use the > HCI spec to build a mesh sniffer. > > > + > > + > > +Additional the ancillary data portion may contain Control type > > information. > > + > > +The following are Control ancillary data types, that me be sent > > with or > > +without payloads: > > + > > +Scan > > +======= > > +cmsg_level cmsg_type cmsg_data[] > > +--------------------------------------------------------------- > > +SOL_BLUETOOTH BTMESH_SCAN Parameters > > + > > + Code: 0x06 > > + Parameters: > > + Filter_Ids[] (variable) > > + > > +To enable/disable scanning of Mesh packets. > > + > > +If Filter_Ids array is nonzero length, start scanning with the > > specified > > +filters (filters are initialized via socket options mechanism). > > This array > > +replaces any prior filters. > > + > > +If no filter IDs are present (i.e., zero array length), stop > > scanning. > > I dislike this. We should have a type 0x02 command that tells us what > kind of role we are operating in. And based on that scanning is > enabled by binding the socket and closing it. Or changing the role. > The whole filter id exposure seems a bit odd to me. I realize that > this might look simple, but a few things should be done by the > kernel. And managing the scanning filters is one of them. So we need > to feed the kernel enough details that it can do that efficiently. > Swapping filters around from userspace is painful. > Adding filters should remain dynamic, e.g., when a new network key is added (or looking forward, new AD Type). > Otherwise we could just expose HCI_CHANNEL_MESH as HCI mesh commands. > They are all multiplexed via a single opcode anyway and have a single > event with and event prefix. So if you want this detailed control of > the HCI commands, then don’t try to put too much kernel in between. > Just do path through of them. > > We could do just that and then leave the kernel portion for this > alone. Maybe it is worth while to debate pros and cons for this. It > is actually not the worst idea to give exclusive access to the mesh > commands. It would be similar to HCI_CHANNEL_USER, but only for the > mesh commands and we would strip the HCI command header and HCI event > header + event prefix off it so that you just have to deal with mesh > opcode and mesh subevent code. > > Hmmm .. it gets a bit tricky for the command complete portion of it. > So it might have to be the full HCI anyway, but restricted to one > opcode and only matching events being forwarded. > > Actually if I spin my train of thoughts further now, we might want to > put HCI_CHANNEL_MESH on ice and leave that for some future version. I > think providing some sort of abstraction and automatic handling of > scanning filters etc. is a good abstraction for the kernel, but it > might be something that will take a while to be defined and working > correctly. Doing the HCI mesh commands directly on a socket has the > command complete problem as stated above and having yet another > variation of HCI_CHANNEL_RAW with mesh HCI filters seems wrong as > well. Especially since eventually I want to have an option to disable > HCI_CHANNEL_RAW. In addition it would have been exclusive access to > make sure nothing goes wrong. > > So maybe we just expose HCI mesh commands as MGMT command and MGMT > event. > > Mesh Command > ============ > > Command Code: 0x0043 > Controller Index: <controller index> > Command Parameters: Opcode (1 Octet) > Command parameters (Variable) > Return Parameters: Status (1 Octet) > Opcode (1 Octet) > Return parameters (Variable) > > Mesh Event > ========== > > Event Code: 0x0026 > Controller Index: <controller index> > Event Parameters: Subevent (1 Octet) > Even parameters (variable) > > This would map 1:1 to the HCI mesh commands and events with the tiny > modification that the event prefix is stripped from the Mesh Event > and not provided and with the Mesh Get Options command issued it > would be mapped to event prefix length of zero. > > And then only a settings 16 Mesh would be needed. Or we make the > command and event only available when HCI mesh commands are actually > supported. That is something that would needs to be discussing. In > general, we have not had limited commands based on hardware > functionality, but these two would be special since they are vendor > specific commands in the first place. > > For the kernel side we only have the the driver provide the mesh HCI > opcode and run Mesh Get Options once to retrieve the firmwares event > prefix so that it can be zeroed out by the MGMT commands and events. > > With that comments? Thoughts? Well, while this approach could work. The advantage is the access to command complete and comand status events. But then having an independent mesh daemon (also ell based) may become problematic. Also, putting actual mesh access layer messages via management socket is a bit questionable: my understanding is that mgmt socket is mainly for control and configuration messsages. > > Regards > > Marcel > [-- Attachment #2: smime.p7s --] [-- Type: application/x-pkcs7-signature, Size: 3266 bytes --] ^ permalink raw reply [flat|nested] 10+ messages in thread
* RE: [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-28 20:17 ` Stotland, Inga @ 2018-02-28 20:45 ` Gix, Brian 2018-02-28 21:03 ` Marcel Holtmann 2018-02-28 20:51 ` Marcel Holtmann 1 sibling, 1 reply; 10+ messages in thread From: Gix, Brian @ 2018-02-28 20:45 UTC (permalink / raw) To: Stotland, Inga, marcel@holtmann.org; +Cc: linux-bluetooth@vger.kernel.org SGkgSW5nYSwgTWFyY2VsLA0KDQo+IEZyb206IGxpbnV4LWJsdWV0b290aC1vd25lckB2Z2VyLmtl cm5lbC5vcmcgW21haWx0bzpsaW51eC1ibHVldG9vdGgtDQo+IA0KPiBIaSBNYXJjZWwsDQo+IA0K PiBPbiBNb24sIDIwMTgtMDItMjYgYXQgMTQ6NDkgKzAxMDAsIE1hcmNlbCBIb2x0bWFubiB3cm90 ZToNCj4gPiBIaSBJbmdhLA0KPiA+DQo+ID4gPiAtLS0NCj4gPiBNZXNoIENvbW1hbmQNCj4gPiA9 PT09PT09PT09PT0NCj4gPg0KPiA+IAlDb21tYW5kIENvZGU6CQkweDAwNDMNCj4gPiAJQ29udHJv bGxlciBJbmRleDoJPGNvbnRyb2xsZXIgaW5kZXg+DQo+ID4gCUNvbW1hbmQgUGFyYW1ldGVyczoJ T3Bjb2RlICgxIE9jdGV0KQ0KPiA+IAkJCQlDb21tYW5kIHBhcmFtZXRlcnMgKFZhcmlhYmxlKQ0K PiA+IAlSZXR1cm4gUGFyYW1ldGVyczoJU3RhdHVzICgxIE9jdGV0KQ0KPiA+IAkJCQlPcGNvZGUg KDEgT2N0ZXQpDQo+ID4gCQkJCVJldHVybiBwYXJhbWV0ZXJzIChWYXJpYWJsZSkNCj4gPg0KPiA+ IE1lc2ggRXZlbnQNCj4gPiA9PT09PT09PT09DQo+ID4NCj4gPiAJRXZlbnQgQ29kZToJCTB4MDAy Ng0KPiA+IAlDb250cm9sbGVyIEluZGV4Ogk8Y29udHJvbGxlciBpbmRleD4NCj4gPiAJRXZlbnQg UGFyYW1ldGVyczoJU3ViZXZlbnQgKDEgT2N0ZXQpDQo+ID4gCQkJCUV2ZW4gcGFyYW1ldGVycyAo dmFyaWFibGUpDQo+ID4NCj4gPiBUaGlzIHdvdWxkIG1hcCAxOjEgdG8gdGhlIEhDSSBtZXNoIGNv bW1hbmRzIGFuZCBldmVudHMgd2l0aCB0aGUgdGlueQ0KPiA+IG1vZGlmaWNhdGlvbiB0aGF0IHRo ZSBldmVudCBwcmVmaXggaXMgc3RyaXBwZWQgZnJvbSB0aGUgTWVzaCBFdmVudA0KPiA+IGFuZCBu b3QgcHJvdmlkZWQgYW5kIHdpdGggdGhlIE1lc2ggR2V0IE9wdGlvbnMgY29tbWFuZCBpc3N1ZWQg aXQNCj4gPiB3b3VsZCBiZSBtYXBwZWQgdG8gZXZlbnQgcHJlZml4IGxlbmd0aCBvZiB6ZXJvLg0K PiA+DQo+ID4gQW5kIHRoZW4gb25seSBhIHNldHRpbmdzIDE2IE1lc2ggd291bGQgYmUgbmVlZGVk LiBPciB3ZSBtYWtlIHRoZQ0KPiA+IGNvbW1hbmQgYW5kIGV2ZW50IG9ubHkgYXZhaWxhYmxlIHdo ZW4gSENJIG1lc2ggY29tbWFuZHMgYXJlIGFjdHVhbGx5DQo+ID4gc3VwcG9ydGVkLiBUaGF0IGlz IHNvbWV0aGluZyB0aGF0IHdvdWxkIG5lZWRzIHRvIGJlIGRpc2N1c3NpbmcuIEluDQo+ID4gZ2Vu ZXJhbCwgd2UgaGF2ZSBub3QgaGFkIGxpbWl0ZWQgY29tbWFuZHMgYmFzZWQgb24gaGFyZHdhcmUN Cj4gPiBmdW5jdGlvbmFsaXR5LCBidXQgdGhlc2UgdHdvIHdvdWxkIGJlIHNwZWNpYWwgc2luY2Ug dGhleSBhcmUgdmVuZG9yDQo+ID4gc3BlY2lmaWMgY29tbWFuZHMgaW4gdGhlIGZpcnN0IHBsYWNl Lg0KPiA+DQo+ID4gRm9yIHRoZSBrZXJuZWwgc2lkZSB3ZSBvbmx5IGhhdmUgdGhlIHRoZSBkcml2 ZXIgcHJvdmlkZSB0aGUgbWVzaCBIQ0kNCj4gPiBvcGNvZGUgYW5kIHJ1biBNZXNoIEdldCBPcHRp b25zIG9uY2UgdG8gcmV0cmlldmUgdGhlIGZpcm13YXJlcyBldmVudA0KPiA+IHByZWZpeCBzbyB0 aGF0IGl0IGNhbiBiZSB6ZXJvZWQgb3V0IGJ5IHRoZSBNR01UIGNvbW1hbmRzIGFuZCBldmVudHMu DQo+ID4NCj4gPiBXaXRoIHRoYXQgY29tbWVudHM/IFRob3VnaHRzPw0KPiANCj4gV2VsbCwgd2hp bGUgdGhpcyBhcHByb2FjaCBjb3VsZCB3b3JrLiBUaGUgYWR2YW50YWdlIGlzIHRoZSBhY2Nlc3Mg dG8NCj4gY29tbWFuZCBjb21wbGV0ZSBhbmQgY29tYW5kIHN0YXR1cyBldmVudHMuIEJ1dCB0aGVu IGhhdmluZyBhbg0KPiBpbmRlcGVuZGVudCBtZXNoIGRhZW1vbiAoYWxzbyBlbGwgYmFzZWQpIG1h eSBiZWNvbWUgcHJvYmxlbWF0aWMuDQo+IEFsc28sIHB1dHRpbmcgYWN0dWFsIG1lc2ggYWNjZXNz IGxheWVyIG1lc3NhZ2VzIHZpYSBtYW5hZ2VtZW50IHNvY2tldA0KPiBpcyBhIGJpdCBxdWVzdGlv bmFibGU6IG15IHVuZGVyc3RhbmRpbmcgaXMgdGhhdCBtZ210IHNvY2tldCBpcyBtYWlubHkNCj4g Zm9yIGNvbnRyb2wgYW5kIGNvbmZpZ3VyYXRpb24gbWVzc3NhZ2VzLg0KPiANCg0KSSB0aGluayBp ZiB3ZSBhcnJpdmUgYXQgYSBwb3NpdGlvbiB3aGVyZSB3ZSBuZWVkICJDb21tYW5kIENvbXBsZXRl IiBzdHlsZSBmZWVkYmFjayB0byBVc2VyIFNwYWNlIChpZi93aGVuIHdlIGdldCBDb250cm9sbGVy cyBuYXRpdmVseSBhd2FyZSBvZiBNZXNoKSwgd2Ugc2hvdWxkIHVzZSBhbiBBbmNpbGxhcnkgKENN U0cpIHJlc3BvbnNlIHdpdGggYW4gRW1wdHkgUGF5bG9hZCBtZXNzYWdlIG9uIHRoZSBzYW1lIHNv Y2tldC4gIFRoaXMgIlNpbmdsZSBTb2NrZXQiIG1vZGVsIGFsbG93cyB1cyB0byBrZWVwICJTZXF1 ZW5jZSBvZiBFdmVudHMiIGJldHRlciB0aGFuIHVzaW5nIHRoZSBNR01UIGludGVyZmFjZS4uLiBh bmQgYXMgSW5nYSBub3RlZCwgd2l0aCBhIHNlcGFyYXRlIE1lc2ggRGFlbW9uLCB3ZSBtYWtlIGl0 IHBvc3NpYmxlIHRvIGhhdmUgYSBtdWNoIGxlYW5lciAiTWVzaCBPbmx5IiB1c2FnZSBtb2RlbCwg d2l0aG91dCB0aGUgVXNlciBTcGFjZSBiYWdnYWdlIG9mIEJSL0VEUi9MUCBpbmZyYXN0cnVjdHVy ZS4NCiANCg0KLS1Ccmlhbg0K ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-28 20:45 ` Gix, Brian @ 2018-02-28 21:03 ` Marcel Holtmann 0 siblings, 0 replies; 10+ messages in thread From: Marcel Holtmann @ 2018-02-28 21:03 UTC (permalink / raw) To: Brian Gix; +Cc: Stotland, Inga, linux-bluetooth@vger.kernel.org Hi Brian, >>>> --- >>> Mesh Command >>> ============ >>> >>> Command Code: 0x0043 >>> Controller Index: <controller index> >>> Command Parameters: Opcode (1 Octet) >>> Command parameters (Variable) >>> Return Parameters: Status (1 Octet) >>> Opcode (1 Octet) >>> Return parameters (Variable) >>> >>> Mesh Event >>> ========== >>> >>> Event Code: 0x0026 >>> Controller Index: <controller index> >>> Event Parameters: Subevent (1 Octet) >>> Even parameters (variable) >>> >>> This would map 1:1 to the HCI mesh commands and events with the tiny >>> modification that the event prefix is stripped from the Mesh Event >>> and not provided and with the Mesh Get Options command issued it >>> would be mapped to event prefix length of zero. >>> >>> And then only a settings 16 Mesh would be needed. Or we make the >>> command and event only available when HCI mesh commands are actually >>> supported. That is something that would needs to be discussing. In >>> general, we have not had limited commands based on hardware >>> functionality, but these two would be special since they are vendor >>> specific commands in the first place. >>> >>> For the kernel side we only have the the driver provide the mesh HCI >>> opcode and run Mesh Get Options once to retrieve the firmwares event >>> prefix so that it can be zeroed out by the MGMT commands and events. >>> >>> With that comments? Thoughts? >> >> Well, while this approach could work. The advantage is the access to >> command complete and comand status events. But then having an >> independent mesh daemon (also ell based) may become problematic. >> Also, putting actual mesh access layer messages via management socket >> is a bit questionable: my understanding is that mgmt socket is mainly >> for control and configuration messsages. >> > > I think if we arrive at a position where we need "Command Complete" style feedback to User Space (if/when we get Controllers natively aware of Mesh), we should use an Ancillary (CMSG) response with an Empty Payload message on the same socket. This "Single Socket" model allows us to keep "Sequence of Events" better than using the MGMT interface... and as Inga noted, with a separate Mesh Daemon, we make it possible to have a much leaner "Mesh Only" usage model, without the User Space baggage of BR/EDR/LP infrastructure. the command complete is really just for flow control and return parameter transport. And we can still have a separate mesh daemon even with mgmt. Meaning you would still open a separate mgmt socket. And you need to do that anyway to list all available controllers and find the one that supports mesh. Regards Marcel ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-28 20:17 ` Stotland, Inga 2018-02-28 20:45 ` Gix, Brian @ 2018-02-28 20:51 ` Marcel Holtmann 2018-03-02 20:04 ` Stotland, Inga 1 sibling, 1 reply; 10+ messages in thread From: Marcel Holtmann @ 2018-02-28 20:51 UTC (permalink / raw) To: Stotland, Inga; +Cc: linux-bluetooth@vger.kernel.org Hi Inga, >>> --- >>> doc/mesh-api.txt | 269 >>> +++++++++++++++++++++++++++++++++++++++++++++++++++++++ >>> 1 file changed, 269 insertions(+) >>> create mode 100644 doc/mesh-api.txt >>> >>> diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt >>> new file mode 100644 >>> index 000000000..87311faba >>> --- /dev/null >>> +++ b/doc/mesh-api.txt >>> @@ -0,0 +1,269 @@ >>> +Bluetooth Mesh Socket API >>> +************************* >>> + >>> +Copyright (C) 2018 Intel Corporation. All rights reserved. >>> + >>> +This document decribes the data format that is used for >>> communication with >>> +the kernel via Bluetooth Mesh socket. The data that are passed >>> over this >>> +type of a socket is specific to Bluetooth Mesh Profile. >>> + >>> +The Bluetooth Mesh socket is implemented as part of PF_BLUETOOTH >>> family >>> +and can be created by opening a raw HCI socket with hci_channel >>> set to >>> +HCI_CHANNEL_BTMESH. The mesh socket requires the creating process >>> to have >> >> call this HCI_CHANNEL_MESH. There is no point in adding BT* here. >> >>> +CAP_NET_ADMIN capability. >>> + >>> +=================================================== >>> +Packet Structure: user space to/from kernel (Tx/Rx) >>> +=================================================== >>> + >>> +Each packet to or from the Over-the-Air interface is sent between >>> the user >>> +space and the kernel must be of nonzero length, and start with the >>> AD_Type, >>> +followed by a variable amount of additional payload. >>> + >>> + 0 8 >>> + +---------------+------------------------------------ >>> + | AD_Type | Mesh Packet >>> + +---------------+—————————————————— >>> + >> >> Actually I would have really preferred that we followed the Proxy PDU >> format. >> >> 2 Bits reserved >> 6 Bits packet type >> Variable data payload >> >> I think that we really need the 0x02 type for configuration between >> the kernel and userspace. > > The idea is to allow the data payload to be identical to the mesh > message that would go over the air. Hence, everything that is not part > of the actual mesh message ends up in either cmsg or sockopt. > Introducing 0x2 "configuration" type will break this paradigm since the > configuration for mesh does not map directly to configuration for > Proxy. > > >>> +AD_Type (1 octet -- Defined by the Bluetooth SIG) >>> +================= >>> + >>> +Provisioning: 0x29 - The payload contains a Mesh >>> Provisioning message >>> +Network: 0x2A - The payload contains a Mesh >>> Data Packet >>> +Beacon: 0x2B - The payload contains a Mesh >>> Beacon >>> + >>> +The AD_Type values correspond to AD types introduced in Mesh >>> Profile >>> +specification. The API is designed to support additional types. >>> + >>> + >>> +A packet with empty (Zero-Length) payload may be sent over the >>> socket in case >>> +when only Control ancillary data is needed (e.g., Flush or Scan, >>> defined below). >>> + >>> +=============== >>> +Socket Options >>> +=============== >>> + >>> +HCI Mesh Scan Filter >>> +==================== >>> + Code: 0x05 >>> + >>> + Filter_Id (1 octet) >>> + Duplicates (1 octet) >>> + Filter (variable length) >>> + >>> +Read/write socket option used to setup scan filters for mesh >>> specific packets. >>> +First octet of filter must include at least the AD_Type but may be >>> longer to >>> +include NIDs or other known data. >> >> These ones look more like type 0x02 PDU packets. And this in >> particular I would have done as Add Network ID and Remove Network ID >> and let the kernel deal with deciding if it chooses a more global >> filter (since not enough filters are available) or if it can be more >> precise with the filtering. >> > > This is a once in awhile operation, so It felt like socket option seems > like a better place for it. It could be made more user friendly at the > expense of losing flexibility in future of adding filtering on > additional AD Types. > >>> + >>> +HCI Mesh Default Tx Power >>> +========================= >>> + Code: 0x06 >>> + >>> + Tx_Power (1 octet) >>> + >>> +Read/write socket option for setting default Tx power. >> >> Leave this out for now. I assume initially we will always use 127 for >> do not care. If we think it is valuable for testing, then via >> debugfs. >> > > I agree. No use for this at the moment. > >>> + >>> +HCI Mesh Default Cahnnel Map >>> +============================ >>> + Code: 0x07 >>> + >>> + Chan_map (1 octet) >>> + >>> +Read/write socket option for setting default channel map. >> >> Also irrelevant and only for fine tuning and testing. Can be exposed >> via debugfs. >> > > Agreed. > >>> + >>> +HCI Mesh Accuracy >>> +================= >>> + Code: 0x08 >>> + >>> + Accuracy (1 octet) >>> + >>> +Read-only socket option to obtain the value of the smallest number >>> of >>> +milliseconds that a Mesh Friendship Offer Window can be, for >>> guaranteed >>> +Poll Response transmission within that window. >> >> I still would have done this via type 0x02 and a PDU exchange >> protocol. Mainly because then it also becomes traceable via btmon. So >> yes, I want the mesh channel also be included in btmon. >> >>> + >>> +================== >>> +Tx Ancillary Data >>> +================== >>> + >>> +The information about which timing settings to use when sending a >>> mesh >>> +packet is contained in mandatory ancillary data accompanying the >>> +payload. Exactly one of the following (mutually exclusive) >>> ancillary >>> +data types must be present with nonzero length Tx payload: >>> + >>> +Mesh Transmit Info >>> +=================== >>> + >>> +cmsg_level cmsg_type cmsg_data[] >>> +-------------------------------------------------- >>> +SOL_BLUETOOTH BTMESH_TX_INFO Parameters >> >> General format we started using is BT_* and so this should be >> BT_MESH_* >> >>> + >>> + Code: 0x01 >>> + Parameters: >>> + Count (1 octet) >>> + Interval: (2 octets) >>> + Min_Random_Delay: (1 octet) >>> + Max_Random_Delay: (1 octet) >>> + >>> +The retransmission parameters for a regular outgoing mesh message. >>> + >>> +Count is the total number of times to Tx. A Zero means Tx Until >>> Canceled. >>> + >>> +Interval is the number of milliseconds between each Tx. >>> + >>> +Random Delay is milliseconds added before first Tx. >>> + >>> +Mesh Poll Transmit Info >>> +======================= >>> + >>> +cmsg_level cmsg_type cmsg_data[] >>> +--------------------------------------------------- >>> +SOL_BLUETOOTH BTMESH_POLL_TX_INFO Parameters >>> + >>> + Code: 0x02 >>> + Parameters: >>> + Scan_Delay (1 octet) >>> + Scan_Duration (1 octet) >>> + Filter_Ids[2] (2 octets) >>> + Min_Random_Delay: (1 octet) >>> + Max_Random_Delay: (1 octet) >>> + >>> +Scan_Delay describes the wait period to begin scanning after the >>> Poll message >>> +is sent. >>> + >>> +Filter_Ids contain IDs of two filters that account for two >>> possible values of >>> +IV Update bit in expected Poll response. >>> + >>> +Random Delay is milliseconds added before Tx. >>> + >>> +Mesh Poll Response Transmit Info >>> +================================ >>> + >>> +cmsg_level cmsg_type cmsg_data[] >>> +----------------------------------------------------- >>> +SOL_BLUETOOTH BTMESH_POLL_RSP_TX_INFO Parameters >>> + >>> + Code: 0x03 >>> + Parameters: >>> + Instant (4 octets) >>> + Delay (1 octet) >>> + >>> +The timing parameters for sending a friend poll response. >>> + >>> +Instant is a 4-octet opaque value that corresponds to the instant >>> an >>> +associated incoming mesh message was recieved, for timing >>> purposes. >>> + >>> +Delay defines number of milliseconds after the corresponding >>> Instant >>> +to wait before sending this Tx. >>> + >>> +__________________________________________________________________ >>> __ >>> + >>> +The following ancillary types are optional with nonzero length Tx >>> payload: >>> + >>> +Transmit Power >>> +============== >>> + >>> +cmsg_level cmsg_type cmsg_data[] >>> +--------------------------------------------------------------- >>> +SOL_BLUETOOTH BTMESH_TX_POWER_INFO Parameters >>> + >>> + Code: 0x04 >>> + Parameters: >>> + Tx_Power (1 octet) >>> + >>> +Transmit power setting can be used for finer control on the >>> outbound messages. >>> +If not present, use default value (builtin or configured as socket >>> options). >>> + >>> +Transmit Channel >>> +================ >>> +cmsg_level cmsg_type cmsg_data[] >>> +--------------------------------------------------------------- >>> +SOL_BLUETOOTH BTMESH_TX_CHANNEL_INFO Parameters >>> + >>> + Code: 0x05 >>> + Parameters: >>> + Tx_Channel (1 octet) >>> + >>> +The presence of this option specifies transmit channel and allows >>> +for better control, e.g., to respond on the same >>> +channel as the one on which incoming message has been received. >>> +If not present, the default value will be used (builtin or >>> configured as >>> +socket options). >> >> Don’t bother with these two at the moment. I think they have no use >> for us except for allowing some testing via debugfs. They needed to >> be in the HCI spec for completeness and because you can also use the >> HCI spec to build a mesh sniffer. >> >>> + >>> + >>> +Additional the ancillary data portion may contain Control type >>> information. >>> + >>> +The following are Control ancillary data types, that me be sent >>> with or >>> +without payloads: >>> + >>> +Scan >>> +======= >>> +cmsg_level cmsg_type cmsg_data[] >>> +--------------------------------------------------------------- >>> +SOL_BLUETOOTH BTMESH_SCAN Parameters >>> + >>> + Code: 0x06 >>> + Parameters: >>> + Filter_Ids[] (variable) >>> + >>> +To enable/disable scanning of Mesh packets. >>> + >>> +If Filter_Ids array is nonzero length, start scanning with the >>> specified >>> +filters (filters are initialized via socket options mechanism). >>> This array >>> +replaces any prior filters. >>> + >>> +If no filter IDs are present (i.e., zero array length), stop >>> scanning. >> >> I dislike this. We should have a type 0x02 command that tells us what >> kind of role we are operating in. And based on that scanning is >> enabled by binding the socket and closing it. Or changing the role. >> The whole filter id exposure seems a bit odd to me. I realize that >> this might look simple, but a few things should be done by the >> kernel. And managing the scanning filters is one of them. So we need >> to feed the kernel enough details that it can do that efficiently. >> Swapping filters around from userspace is painful. >> > > Adding filters should remain dynamic, e.g., when a new network key is > added (or looking forward, new AD Type). > >> Otherwise we could just expose HCI_CHANNEL_MESH as HCI mesh commands. >> They are all multiplexed via a single opcode anyway and have a single >> event with and event prefix. So if you want this detailed control of >> the HCI commands, then don’t try to put too much kernel in between. >> Just do path through of them. >> >> We could do just that and then leave the kernel portion for this >> alone. Maybe it is worth while to debate pros and cons for this. It >> is actually not the worst idea to give exclusive access to the mesh >> commands. It would be similar to HCI_CHANNEL_USER, but only for the >> mesh commands and we would strip the HCI command header and HCI event >> header + event prefix off it so that you just have to deal with mesh >> opcode and mesh subevent code. >> >> Hmmm .. it gets a bit tricky for the command complete portion of it. >> So it might have to be the full HCI anyway, but restricted to one >> opcode and only matching events being forwarded. >> >> Actually if I spin my train of thoughts further now, we might want to >> put HCI_CHANNEL_MESH on ice and leave that for some future version. I >> think providing some sort of abstraction and automatic handling of >> scanning filters etc. is a good abstraction for the kernel, but it >> might be something that will take a while to be defined and working >> correctly. Doing the HCI mesh commands directly on a socket has the >> command complete problem as stated above and having yet another >> variation of HCI_CHANNEL_RAW with mesh HCI filters seems wrong as >> well. Especially since eventually I want to have an option to disable >> HCI_CHANNEL_RAW. In addition it would have been exclusive access to >> make sure nothing goes wrong. >> >> So maybe we just expose HCI mesh commands as MGMT command and MGMT >> event. >> >> Mesh Command >> ============ >> >> Command Code: 0x0043 >> Controller Index: <controller index> >> Command Parameters: Opcode (1 Octet) >> Command parameters (Variable) >> Return Parameters: Status (1 Octet) >> Opcode (1 Octet) >> Return parameters (Variable) >> >> Mesh Event >> ========== >> >> Event Code: 0x0026 >> Controller Index: <controller index> >> Event Parameters: Subevent (1 Octet) >> Even parameters (variable) >> >> This would map 1:1 to the HCI mesh commands and events with the tiny >> modification that the event prefix is stripped from the Mesh Event >> and not provided and with the Mesh Get Options command issued it >> would be mapped to event prefix length of zero. >> >> And then only a settings 16 Mesh would be needed. Or we make the >> command and event only available when HCI mesh commands are actually >> supported. That is something that would needs to be discussing. In >> general, we have not had limited commands based on hardware >> functionality, but these two would be special since they are vendor >> specific commands in the first place. >> >> For the kernel side we only have the the driver provide the mesh HCI >> opcode and run Mesh Get Options once to retrieve the firmwares event >> prefix so that it can be zeroed out by the MGMT commands and events. >> >> With that comments? Thoughts? > > Well, while this approach could work. The advantage is the access to > command complete and comand status events. But then having an > independent mesh daemon (also ell based) may become problematic. > Also, putting actual mesh access layer messages via management socket > is a bit questionable: my understanding is that mgmt socket is mainly > for control and configuration messsages. putting it in a separate daemon is not a problem actually. The kernel will handle that just fine. We can easily have two control sockets open at the same. We might want to add an extra handling that mesh events only go to one specific socket and not all of them. I will think about this for a bit, but we have done that before with the extended controller events and the kernel can already handle that nicely. That code is already present. The only reason why this might be useful is that we decide to use the HCI mesh commands / events as a base interface. And this comes mainly from the comments that the mesh daemon will require tight control over the filters. If the kernel turns into a passthrough anyway, then way not make it really simple for the kernel code. So mgmt API is suppose to be parts of GAP and handle certain things that are transactional on HCI. I can convince myself that with HCI mesh API this is the same, but that there is just nothing to do except figure out the event prefix. So it would become super lightweight for the kernel. If we base everything around the HCI mesh commands / events, then switching from Mesh MGMT to HCI_CHANNEL_USER is dead simple and only needs a minimal shim for transport abstraction. Maybe this is actually an advantage. One thing that I really like is that mgmt is already include in btmon tracing. So we would get that for free. The one thing that I didn’t consider enough is that with CMSG usage, we loose an easy way of being able to trace all the packets and parameters. It is such a powerful feature, that I am not in favor of missing it. Regards Marcel ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API 2018-02-28 20:51 ` Marcel Holtmann @ 2018-03-02 20:04 ` Stotland, Inga 0 siblings, 0 replies; 10+ messages in thread From: Stotland, Inga @ 2018-03-02 20:04 UTC (permalink / raw) To: marcel@holtmann.org; +Cc: linux-bluetooth@vger.kernel.org, Gix, Brian [-- Attachment #1: Type: text/plain, Size: 19138 bytes --] Hi Marcel, On Wed, 2018-02-28 at 21:51 +0100, Marcel Holtmann wrote: > Hi Inga, > > > > > --- > > > > doc/mesh-api.txt | 269 > > > > +++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > > > 1 file changed, 269 insertions(+) > > > > create mode 100644 doc/mesh-api.txt > > > > > > > > diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt > > > > new file mode 100644 > > > > index 000000000..87311faba > > > > --- /dev/null > > > > +++ b/doc/mesh-api.txt > > > > @@ -0,0 +1,269 @@ > > > > +Bluetooth Mesh Socket API > > > > +************************* > > > > + > > > > +Copyright (C) 2018 Intel Corporation. All rights reserved. > > > > + > > > > +This document decribes the data format that is used for > > > > communication with > > > > +the kernel via Bluetooth Mesh socket. The data that are passed > > > > over this > > > > +type of a socket is specific to Bluetooth Mesh Profile. > > > > + > > > > +The Bluetooth Mesh socket is implemented as part of > > > > PF_BLUETOOTH > > > > family > > > > +and can be created by opening a raw HCI socket with > > > > hci_channel > > > > set to > > > > +HCI_CHANNEL_BTMESH. The mesh socket requires the creating > > > > process > > > > to have > > > > > > call this HCI_CHANNEL_MESH. There is no point in adding BT* here. > > > > > > > +CAP_NET_ADMIN capability. > > > > + > > > > +=================================================== > > > > +Packet Structure: user space to/from kernel (Tx/Rx) > > > > +=================================================== > > > > + > > > > +Each packet to or from the Over-the-Air interface is sent > > > > between > > > > the user > > > > +space and the kernel must be of nonzero length, and start with > > > > the > > > > AD_Type, > > > > +followed by a variable amount of additional payload. > > > > + > > > > + 0 8 > > > > + +---------------+------------------------------------ > > > > + | AD_Type | Mesh Packet > > > > + +---------------+—————————————————— > > > > + > > > > > > Actually I would have really preferred that we followed the Proxy > > > PDU > > > format. > > > > > > 2 Bits reserved > > > 6 Bits packet type > > > Variable data payload > > > > > > I think that we really need the 0x02 type for configuration > > > between > > > the kernel and userspace. > > > > The idea is to allow the data payload to be identical to the mesh > > message that would go over the air. Hence, everything that is not > > part > > of the actual mesh message ends up in either cmsg or sockopt. > > Introducing 0x2 "configuration" type will break this paradigm since > > the > > configuration for mesh does not map directly to configuration for > > Proxy. > > > > > > > > +AD_Type (1 octet -- Defined by the Bluetooth SIG) > > > > +================= > > > > + > > > > +Provisioning: 0x29 - The payload contains a Mesh > > > > Provisioning message > > > > +Network: 0x2A - The payload contains a > > > > Mesh > > > > Data Packet > > > > +Beacon: 0x2B - The payload contains a > > > > Mesh > > > > Beacon > > > > + > > > > +The AD_Type values correspond to AD types introduced in Mesh > > > > Profile > > > > +specification. The API is designed to support additional > > > > types. > > > > + > > > > + > > > > +A packet with empty (Zero-Length) payload may be sent over the > > > > socket in case > > > > +when only Control ancillary data is needed (e.g., Flush or > > > > Scan, > > > > defined below). > > > > + > > > > +=============== > > > > +Socket Options > > > > +=============== > > > > + > > > > +HCI Mesh Scan Filter > > > > +==================== > > > > + Code: 0x05 > > > > + > > > > + Filter_Id (1 octet) > > > > + Duplicates (1 octet) > > > > + Filter (variable length) > > > > + > > > > +Read/write socket option used to setup scan filters for mesh > > > > specific packets. > > > > +First octet of filter must include at least the AD_Type but > > > > may be > > > > longer to > > > > +include NIDs or other known data. > > > > > > These ones look more like type 0x02 PDU packets. And this in > > > particular I would have done as Add Network ID and Remove Network > > > ID > > > and let the kernel deal with deciding if it chooses a more global > > > filter (since not enough filters are available) or if it can be > > > more > > > precise with the filtering. > > > > > > > This is a once in awhile operation, so It felt like socket option > > seems > > like a better place for it. It could be made more user friendly at > > the > > expense of losing flexibility in future of adding filtering on > > additional AD Types. > > > > > > + > > > > +HCI Mesh Default Tx Power > > > > +========================= > > > > + Code: 0x06 > > > > + > > > > + Tx_Power (1 octet) > > > > + > > > > +Read/write socket option for setting default Tx power. > > > > > > Leave this out for now. I assume initially we will always use 127 > > > for > > > do not care. If we think it is valuable for testing, then via > > > debugfs. > > > > > > > I agree. No use for this at the moment. > > > > > > + > > > > +HCI Mesh Default Cahnnel Map > > > > +============================ > > > > + Code: 0x07 > > > > + > > > > + Chan_map (1 octet) > > > > + > > > > +Read/write socket option for setting default channel map. > > > > > > Also irrelevant and only for fine tuning and testing. Can be > > > exposed > > > via debugfs. > > > > > > > Agreed. > > > > > > + > > > > +HCI Mesh Accuracy > > > > +================= > > > > + Code: 0x08 > > > > + > > > > + Accuracy (1 octet) > > > > + > > > > +Read-only socket option to obtain the value of the smallest > > > > number > > > > of > > > > +milliseconds that a Mesh Friendship Offer Window can be, for > > > > guaranteed > > > > +Poll Response transmission within that window. > > > > > > I still would have done this via type 0x02 and a PDU exchange > > > protocol. Mainly because then it also becomes traceable via > > > btmon. So > > > yes, I want the mesh channel also be included in btmon. > > > > > > > + > > > > +================== > > > > +Tx Ancillary Data > > > > +================== > > > > + > > > > +The information about which timing settings to use when > > > > sending a > > > > mesh > > > > +packet is contained in mandatory ancillary data accompanying > > > > the > > > > +payload. Exactly one of the following (mutually exclusive) > > > > ancillary > > > > +data types must be present with nonzero length Tx payload: > > > > + > > > > +Mesh Transmit Info > > > > +=================== > > > > + > > > > +cmsg_level cmsg_type cmsg_data[] > > > > +-------------------------------------------------- > > > > +SOL_BLUETOOTH BTMESH_TX_INFO Parameters > > > > > > General format we started using is BT_* and so this should be > > > BT_MESH_* > > > > > > > + > > > > + Code: 0x01 > > > > + Parameters: > > > > + Count (1 octet) > > > > + Interval: (2 octets) > > > > + Min_Random_Delay: (1 octet) > > > > + Max_Random_Delay: (1 octet) > > > > + > > > > +The retransmission parameters for a regular outgoing mesh > > > > message. > > > > + > > > > +Count is the total number of times to Tx. A Zero means Tx > > > > Until > > > > Canceled. > > > > + > > > > +Interval is the number of milliseconds between each Tx. > > > > + > > > > +Random Delay is milliseconds added before first Tx. > > > > + > > > > +Mesh Poll Transmit Info > > > > +======================= > > > > + > > > > +cmsg_level cmsg_type cmsg_data[] > > > > +--------------------------------------------------- > > > > +SOL_BLUETOOTH BTMESH_POLL_TX_INFO Parameters > > > > + > > > > + Code: 0x02 > > > > + Parameters: > > > > + Scan_Delay (1 octet) > > > > + Scan_Duration (1 octet) > > > > + Filter_Ids[2] (2 octets) > > > > + Min_Random_Delay: (1 octet) > > > > + Max_Random_Delay: (1 octet) > > > > + > > > > +Scan_Delay describes the wait period to begin scanning after > > > > the > > > > Poll message > > > > +is sent. > > > > + > > > > +Filter_Ids contain IDs of two filters that account for two > > > > possible values of > > > > +IV Update bit in expected Poll response. > > > > + > > > > +Random Delay is milliseconds added before Tx. > > > > + > > > > +Mesh Poll Response Transmit Info > > > > +================================ > > > > + > > > > +cmsg_level cmsg_type cmsg_data[] > > > > +----------------------------------------------------- > > > > +SOL_BLUETOOTH BTMESH_POLL_RSP_TX_INFO Parameters > > > > + > > > > + Code: 0x03 > > > > + Parameters: > > > > + Instant (4 octets) > > > > + Delay (1 octet) > > > > + > > > > +The timing parameters for sending a friend poll response. > > > > + > > > > +Instant is a 4-octet opaque value that corresponds to the > > > > instant > > > > an > > > > +associated incoming mesh message was recieved, for timing > > > > purposes. > > > > + > > > > +Delay defines number of milliseconds after the corresponding > > > > Instant > > > > +to wait before sending this Tx. > > > > + > > > > +______________________________________________________________ > > > > ____ > > > > __ > > > > + > > > > +The following ancillary types are optional with nonzero length > > > > Tx > > > > payload: > > > > + > > > > +Transmit Power > > > > +============== > > > > + > > > > +cmsg_level cmsg_type cmsg_data[] > > > > +------------------------------------------------------------ > > > > --- > > > > +SOL_BLUETOOTH BTMESH_TX_POWER_INFO Parameters > > > > + > > > > + Code: 0x04 > > > > + Parameters: > > > > + Tx_Power (1 octet) > > > > + > > > > +Transmit power setting can be used for finer control on the > > > > outbound messages. > > > > +If not present, use default value (builtin or configured as > > > > socket > > > > options). > > > > + > > > > +Transmit Channel > > > > +================ > > > > +cmsg_level cmsg_type cmsg_data[] > > > > +------------------------------------------------------------ > > > > --- > > > > +SOL_BLUETOOTH BTMESH_TX_CHANNEL_INFO Parameters > > > > + > > > > + Code: 0x05 > > > > + Parameters: > > > > + Tx_Channel (1 octet) > > > > + > > > > +The presence of this option specifies transmit channel and > > > > allows > > > > +for better control, e.g., to respond on the same > > > > +channel as the one on which incoming message has been > > > > received. > > > > +If not present, the default value will be used (builtin or > > > > configured as > > > > +socket options). > > > > > > Don’t bother with these two at the moment. I think they have no > > > use > > > for us except for allowing some testing via debugfs. They needed > > > to > > > be in the HCI spec for completeness and because you can also use > > > the > > > HCI spec to build a mesh sniffer. > > > > > > > + > > > > + > > > > +Additional the ancillary data portion may contain Control type > > > > information. > > > > + > > > > +The following are Control ancillary data types, that me be > > > > sent > > > > with or > > > > +without payloads: > > > > + > > > > +Scan > > > > +======= > > > > +cmsg_level cmsg_type cmsg_data[] > > > > +------------------------------------------------------------ > > > > --- > > > > +SOL_BLUETOOTH BTMESH_SCAN Parameters > > > > + > > > > + Code: 0x06 > > > > + Parameters: > > > > + Filter_Ids[] (variable) > > > > + > > > > +To enable/disable scanning of Mesh packets. > > > > + > > > > +If Filter_Ids array is nonzero length, start scanning with the > > > > specified > > > > +filters (filters are initialized via socket options > > > > mechanism). > > > > This array > > > > +replaces any prior filters. > > > > + > > > > +If no filter IDs are present (i.e., zero array length), stop > > > > scanning. > > > > > > I dislike this. We should have a type 0x02 command that tells us > > > what > > > kind of role we are operating in. And based on that scanning is > > > enabled by binding the socket and closing it. Or changing the > > > role. > > > The whole filter id exposure seems a bit odd to me. I realize > > > that > > > this might look simple, but a few things should be done by the > > > kernel. And managing the scanning filters is one of them. So we > > > need > > > to feed the kernel enough details that it can do that > > > efficiently. > > > Swapping filters around from userspace is painful. > > > > > > > Adding filters should remain dynamic, e.g., when a new network key > > is > > added (or looking forward, new AD Type). > > > > > Otherwise we could just expose HCI_CHANNEL_MESH as HCI mesh > > > commands. > > > They are all multiplexed via a single opcode anyway and have a > > > single > > > event with and event prefix. So if you want this detailed control > > > of > > > the HCI commands, then don’t try to put too much kernel in > > > between. > > > Just do path through of them. > > > > > > We could do just that and then leave the kernel portion for this > > > alone. Maybe it is worth while to debate pros and cons for this. > > > It > > > is actually not the worst idea to give exclusive access to the > > > mesh > > > commands. It would be similar to HCI_CHANNEL_USER, but only for > > > the > > > mesh commands and we would strip the HCI command header and HCI > > > event > > > header + event prefix off it so that you just have to deal with > > > mesh > > > opcode and mesh subevent code. > > > > > > Hmmm .. it gets a bit tricky for the command complete portion of > > > it. > > > So it might have to be the full HCI anyway, but restricted to one > > > opcode and only matching events being forwarded. > > > > > > Actually if I spin my train of thoughts further now, we might > > > want to > > > put HCI_CHANNEL_MESH on ice and leave that for some future > > > version. I > > > think providing some sort of abstraction and automatic handling > > > of > > > scanning filters etc. is a good abstraction for the kernel, but > > > it > > > might be something that will take a while to be defined and > > > working > > > correctly. Doing the HCI mesh commands directly on a socket has > > > the > > > command complete problem as stated above and having yet another > > > variation of HCI_CHANNEL_RAW with mesh HCI filters seems wrong as > > > well. Especially since eventually I want to have an option to > > > disable > > > HCI_CHANNEL_RAW. In addition it would have been exclusive access > > > to > > > make sure nothing goes wrong. > > > > > > So maybe we just expose HCI mesh commands as MGMT command and > > > MGMT > > > event. > > > > > > Mesh Command > > > ============ > > > > > > Command Code: 0x0043 > > > Controller Index: <controller index> > > > Command Parameters: Opcode (1 Octet) > > > Command parameters (Variable) > > > Return Parameters: Status (1 Octet) > > > Opcode (1 Octet) > > > Return parameters (Variable) > > > > > > Mesh Event > > > ========== > > > > > > Event Code: 0x0026 > > > Controller Index: <controller index> > > > Event Parameters: Subevent (1 Octet) > > > Even parameters (variable) > > > > > > This would map 1:1 to the HCI mesh commands and events with the > > > tiny > > > modification that the event prefix is stripped from the Mesh > > > Event > > > and not provided and with the Mesh Get Options command issued it > > > would be mapped to event prefix length of zero. > > > > > > And then only a settings 16 Mesh would be needed. Or we make the > > > command and event only available when HCI mesh commands are > > > actually > > > supported. That is something that would needs to be discussing. > > > In > > > general, we have not had limited commands based on hardware > > > functionality, but these two would be special since they are > > > vendor > > > specific commands in the first place. > > > > > > For the kernel side we only have the the driver provide the mesh > > > HCI > > > opcode and run Mesh Get Options once to retrieve the firmwares > > > event > > > prefix so that it can be zeroed out by the MGMT commands and > > > events. > > > > > > With that comments? Thoughts? > > > > Well, while this approach could work. The advantage is the access > > to > > command complete and comand status events. But then having an > > independent mesh daemon (also ell based) may become problematic. > > Also, putting actual mesh access layer messages via management > > socket > > is a bit questionable: my understanding is that mgmt socket is > > mainly > > for control and configuration messsages. > > putting it in a separate daemon is not a problem actually. The kernel > will handle that just fine. We can easily have two control sockets > open at the same. We might want to add an extra handling that mesh > events only go to one specific socket and not all of them. I will > think about this for a bit, but we have done that before with the > extended controller events and the kernel can already handle that > nicely. That code is already present. > > The only reason why this might be useful is that we decide to use the > HCI mesh commands / events as a base interface. And this comes mainly > from the comments that the mesh daemon will require tight control > over the filters. If the kernel turns into a passthrough anyway, then > way not make it really simple for the kernel code. So mgmt API is > suppose to be parts of GAP and handle certain things that are > transactional on HCI. I can convince myself that with HCI mesh API > this is the same, but that there is just nothing to do except figure > out the event prefix. So it would become super lightweight for the > kernel. > > If we base everything around the HCI mesh commands / events, then > switching from Mesh MGMT to HCI_CHANNEL_USER is dead simple and only > needs a minimal shim for transport abstraction. Maybe this is > actually an advantage. > > One thing that I really like is that mgmt is already include in btmon > tracing. So we would get that for free. The one thing that I didn’t > consider enough is that with CMSG usage, we loose an easy way of > being able to trace all the packets and parameters. It is such a > powerful feature, that I am not in favor of missing it. > > Regards > > Marcel > We could move scan, add filters and flush into mgmt socket since these are really control commands. I am still very much in favor of having a separate socket with HCI_CHANNEL_MESH for actual mesh data tx/rx: CMSG mechanism is well suited for having timing tightly coupled with the data payload. As for btmon tracing, we can add prefixes for cmd mesh packet. Capturing mesh event will require extra processing in any case, which is doable. Regards, Inga [-- Attachment #2: smime.p7s --] [-- Type: application/x-pkcs7-signature, Size: 3266 bytes --] ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2018-03-02 20:04 UTC | newest] Thread overview: 10+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2018-02-18 6:48 [PATCH BlueZ 0/1 v2] BT Mesh API doc Inga Stotland 2018-02-18 6:48 ` [PATCH BlueZ 1/1 v2] Add initial doc describing Bluetooth Mesh API Inga Stotland 2018-02-26 13:49 ` Marcel Holtmann 2018-02-26 19:01 ` Gix, Brian 2018-02-27 12:40 ` Marcel Holtmann 2018-02-28 20:17 ` Stotland, Inga 2018-02-28 20:45 ` Gix, Brian 2018-02-28 21:03 ` Marcel Holtmann 2018-02-28 20:51 ` Marcel Holtmann 2018-03-02 20:04 ` Stotland, Inga
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox