[BlueZ,1/2] docs: Add support for Mesh Scanning and Sending

Adds four new MGMT Commands:
	- MESH_RECEIVER - Enable Mesh Receiver with Passive scanning
	  with a list of AD Types (Mesh and/or Extended Mesh).

	- MESH_FEATURES - Requests information on how many simultaneous
	  outbound  mesh packets can be pending at one time.

	- MESH_TX_PACKET - Send a requested Mesh Packet, perhaps with a
	  specific fine-timed delay.

	- MESH_TX_CANCEL - Cancel a prior Mesh TX request that has not
	  yet completed.

Adds two new MGMT Events:
	- MESH_DEVICE_FOUND - Returned when Mesh is enabled, and one of
	  the requested AD Types is detected in an incoming
	  Advertisement.

	- MESH_TX_COMPLETE - Reports that a prior requested transmission
	  has completed and no longer consumes one of the available
	  outbound slots.
---
 doc/mgmt-api.txt | 170 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 170 insertions(+)

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

Dear submitter,

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

---Test result---

Test Summary:
CheckPatch                    FAIL      2.90 seconds
GitLint                       FAIL      2.06 seconds
Prep - Setup ELL              PASS      42.82 seconds
Build - Prep                  PASS      0.70 seconds
Build - Configure             PASS      8.63 seconds
Build - Make                  PASS      1251.02 seconds
Make Check                    PASS      11.29 seconds
Make Check w/Valgrind         PASS      429.57 seconds
Make Distcheck                PASS      222.48 seconds
Build w/ext ELL - Configure   PASS      8.50 seconds
Build w/ext ELL - Make        PASS      1240.28 seconds
Incremental Build with patchesPASS      2598.77 seconds

Details
##############################
Test: CheckPatch - FAIL
Desc: Run checkpatch.pl script with rule in .checkpatch.conf
Output:
[BlueZ,2/2] mgmt-tester: Adds turning on Mesh Experimental feature
WARNING:LONG_LINE: line length of 101 exceeds 80 columns
#135: FILE: tools/mgmt-tester.c:7358:
+			tester_warn("Invalid cmd response parameter size %d %d", length, expect_len);

/github/workspace/src/12797546.patch total: 0 errors, 1 warnings, 77 lines checked

NOTE: For some of the reported defects, checkpatch may be able to
      mechanically convert to the typical style using --fix or --fix-inplace.

/github/workspace/src/12797546.patch has style problems, please review.

NOTE: Ignored message types: COMMIT_MESSAGE COMPLEX_MACRO CONST_STRUCT FILE_PATH_CHANGES MISSING_SIGN_OFF PREFER_PACKED SPDX_LICENSE_TAG SPLIT_STRING SSCANF_TO_KSTRTO

NOTE: If any of the errors are false positives, please report
      them to the maintainer, see CHECKPATCH in MAINTAINERS.


##############################
Test: GitLint - FAIL
Desc: Run gitlint with rule in .gitlint
Output:
[BlueZ,1/2] docs: Add support for Mesh Scanning and Sending
4: B3 Line contains hard tab characters (\t): "	- MESH_RECEIVER - Enable Mesh Receiver with Passive scanning"
5: B3 Line contains hard tab characters (\t): "	  with a list of AD Types (Mesh and/or Extended Mesh)."
7: B3 Line contains hard tab characters (\t): "	- MESH_FEATURES - Requests information on how many simultaneous"
8: B3 Line contains hard tab characters (\t): "	  outbound  mesh packets can be pending at one time."
10: B3 Line contains hard tab characters (\t): "	- MESH_TX_PACKET - Send a requested Mesh Packet, perhaps with a"
11: B3 Line contains hard tab characters (\t): "	  specific fine-timed delay."
13: B3 Line contains hard tab characters (\t): "	- MESH_TX_CANCEL - Cancel a prior Mesh TX request that has not"
14: B3 Line contains hard tab characters (\t): "	  yet completed."
17: B3 Line contains hard tab characters (\t): "	- MESH_DEVICE_FOUND - Returned when Mesh is enabled, and one of"
18: B3 Line contains hard tab characters (\t): "	  the requested AD Types is detected in an incoming"
19: B3 Line contains hard tab characters (\t): "	  Advertisement."
21: B3 Line contains hard tab characters (\t): "	- MESH_TX_COMPLETE - Reports that a prior requested transmission"
22: B3 Line contains hard tab characters (\t): "	  has completed and no longer consumes one of the available"
23: B3 Line contains hard tab characters (\t): "	  outbound slots."




---
Regards,
Linux Bluetooth

Hi Brian,

> Adds four new MGMT Commands:
> 	- MESH_RECEIVER - Enable Mesh Receiver with Passive scanning
> 	  with a list of AD Types (Mesh and/or Extended Mesh).
> 
> 	- MESH_FEATURES - Requests information on how many simultaneous
> 	  outbound  mesh packets can be pending at one time.
> 
> 	- MESH_TX_PACKET - Send a requested Mesh Packet, perhaps with a
> 	  specific fine-timed delay.
> 
> 	- MESH_TX_CANCEL - Cancel a prior Mesh TX request that has not
> 	  yet completed.
> 
> Adds two new MGMT Events:
> 	- MESH_DEVICE_FOUND - Returned when Mesh is enabled, and one of
> 	  the requested AD Types is detected in an incoming
> 	  Advertisement.
> 
> 	- MESH_TX_COMPLETE - Reports that a prior requested transmission
> 	  has completed and no longer consumes one of the available
> 	  outbound slots.
> ---
> doc/mgmt-api.txt | 170 +++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 170 insertions(+)
> 
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index ebe56afa4..2da89e2f3 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -332,6 +332,7 @@ Read Controller Information Command
> 		15	Static Address
> 		16	PHY Configuration
> 		17	Wideband Speech

we need to leave 18 to Quality Reporting.

> +		18	Mesh Mode
> 
> 	This command generates a Command Complete event on success or
> 	a Command Status event on failure.
> @@ -3858,6 +3859,128 @@ Add Advertisement Patterns Monitor With RSSI Threshold Command
> 				Invalid Parameters
> 

Lets leave 0x0057 to Set Quality Report command.

> 
> +Set Mesh Receiver Command
> +=========================
> +
> +	Command Code:		0x0057
> +	Controller Index:	<controller id>
> +	Command Parameters:	Enable (1 Octets)
> +				Window (2 Octets)
> +				Period (2 Octets)
> +				Num AD Types (1 Octets)
> +				AD Types (variable)
> +
> +	This command Enables or Disables Mesh Receiving. When enabled passive
> +	scanning remains enabled for this controller.
> +
> +	The Window/Period values are used to set the Scan Parameters when no
> +	other scanning is being done.
> +
> +	Num AD Types and AD Types parameter, filter Advertising and Scan
> +	responses by AD type. Reponses that do not contain at least one of the
> +	requested AD types will be ignored. Otherwise they will be delivered
> +	with the Mesh Device Found event.
> +
> +	Possible errors:	Failed
> +				No Resources
> +				Invalid Parameters
> +
> +Read Mesh Features Command
> +==========================
> +
> +	Command Code:		0x0058
> +	Controller Index:	<controller id>
> +	Command Parameters:
> +	Return Parameters:	Index (2 Octets)
> +				Max Handles (1 Octets)
> +				Used Handles (1 Octets)
> +				Handle (variable)
> +
> +	This command is used to both verify that Outbound Mesh packet
> +	support is enabled, and to indicate the number of packets that
> +	can and are simultaneously queued.
> +
> +	Index identifies the HCI Controller that this information is valid for.

Scrap the Index. It is already present the basic mgmt frame structure.

> +
> +	Max Handles indicates the maximum number of packets that may be queued.
> +
> +	Used Handles indicates the number of packets awaiting transmission.
> +
> +	Handle is an array of the currently outstanding packets.
> +
> +	Possible errors:	Failed
> +				No Resources
> +				Invalid Parameters

I rather have 0x0058 Read Mesh Features, 0x0059 Set Mesh Receiver, 0x005a Transmit Mesh Packet and 0x005b Cancel Transmit Mesh Packet.

> +
> +Transmit Mesh Packet Command
> +============================
> +
> +	Command Code:		0x0059
> +	Controller Index:	<controller id>
> +	Command Parameters:	Addr (6 octets)
> +				Addr Type (1 Octets)
> +				Instant (8 Octets)
> +				Delay (2 Octets)
> +				Count (1 Octets)
> +				Data (variable)
> +	Return Parameters:	Handle
> +
> +	This command sends a Mesh Packet as a NONCONN LE Advertisement.
> +
> +	The Addr + Addr Type parameters specifify the address to use in the
> +	outbound advertising packet. If BD_ADDR_ANY and LE_RANDOM is set, the
> +	kernel will create a single use non-resolvable address.
> +
> +	The Instant parameter is used in combination with the Delay
> +	parameter, to finely time the sending of the Advertising packet. It
> +	should be set to the Instant value tag of a received incoming
> +	Mesh Device Found Event. It is only useful in POLL-RESPONSE situations
> +	where a response must be sent within a negotiated time window. The value
> +	of the Instant parameter should not be interpreted by the host, and
> +	only has meaning to the controller.
> +
> +	The Delay parameter, if 0x0000, will cause the packet to be sent
> +	at the earliest opportunity. If non-Zero, and the controller supports
> +	delayed delivery, the Instant and Delay parameters will be used
> +	to delay the outbound packet. While the Instant is not defined, the
> +	Delay is specified in milliseconds.
> +
> +	The Count parameter must be sent to a non-Zero value indicating the
> +	number of times this packet will be sent before transmission completes.
> +	If the Delay parameter is non-Zero, then Count must be 1 only.
> +
> +	The Data parameter is an octet array of the AD Type and Mesh Packet.
> +
> +	This command will return immediately, and if it succeeds, will generate
> +	a Mesh Packet Transmission Complete event when after the packet has been
> +	sent.
> +
> +	Possible errors:	Failed
> +				Busy
> +				No Resources
> +				Invalid Parameters
> +
> +Cancel Transmit Mesh Packet Command
> +===================================
> +
> +	Command Code:		0x005A
> +	Controller Index:	<controller id>
> +	Command Parameters:	Handle (1 octets)
> +
> +	This command may be used to cancel an outbound transmission request.
> +
> +	The Handle parameter is the returned handle from a successful Transmit
> +	Mesh Packet request. If Zero is specified as the handle, all outstanding
> +	send requests are canceled.
> +
> +	For each mesh packet canceled, the Mesh Packet Transmission Complete
> +	event will be generated, regardless of whether the packet was sent
> +	successfully.
> +
> +	Possible errors:	Failed
> +				Invalid Parameters
> +
> +
> Command Complete Event
> ======================
> 
> @@ -4978,3 +5101,50 @@ Advertisement Monitor Device Lost Event
> 		2	LE Random
> 
> 	This event will be sent to all management sockets.
> +
> +
> +Mesh Device Found Event
> +=======================
> +
> +	Event code:		0x0031
> +	Controller Index:	<controller_id>
> +	Event Parameters:	Address (6 Octets)
> +				Address_Type (1 Octet)
> +				RSSI (1 Octet)
> +				Flags (4 Octets)
> +				Instant (4 Octets)
> +				AD_Data_Length (2 Octets)
> +				AD_Data (0-65535 Octets)
> +
> +	This event indicates that the controller has received an Advertisement
> +	or Scan Result containing an AD Type matching the Mesh scan set.
> +
> +	The address of the sending device is returned, and must be a valid LE
> +	Address_Type.
> +
> +	Possible values for the Address_Type parameter:
> +		0	Reserved (not in use)
> +		1	LE Public
> +		2	LE Random
> +
> +	The RSSI field is a signed octet, and is the RSSI reported by the
> +	receiving controller.
> +
> +	The Instant field is 32 bit value that represents the instant in time
> +	the packet was received. It's value is not intended to be interpretted
> +	by the host, and is only useful if the host wants to make a timed
> +	response to the received packet. (i.e. a Poll/Response)
> +
> +	This event will be sent to all management sockets.

Describe the Flags field please.

> +
> +Mesh Packet Transmit Complete Event
> +===================================
> +
> +	Event code:		0x0032
> +	Controller Index:	<controller_id>
> +	Event Parameters:	Handle (2 Octets)
> +
> +	This event indicates that a requested outbound Mesh packet has
> +	completed and no longer occupies a transmit slot.
> +
> +	This event will be sent to all management sockets.

Regards

Marcel