[RFC,1/2] dt-bindings: net: h4-bluetooth: add new bindings for hci_h4

  Add devicetree binding to support defining a bluetooth device using the h4
uart protocol

This was tested with a NXP wireless+BT AW-XM458 module, but might
benefit others as the H4 protocol seems often used.

Signed-off-by: Dominique Martinet <dominique.martinet@atmark-techno.com>
---
 .../devicetree/bindings/net/h4-bluetooth.yaml | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/net/h4-bluetooth.yaml
  

On 08/11/2022 06:55, Dominique Martinet wrote:
> Add devicetree binding to support defining a bluetooth device using the h4
> uart protocol
> 

subject: drop second redundant "bindings"

> This was tested with a NXP wireless+BT AW-XM458 module, but might
> benefit others as the H4 protocol seems often used.
> 
> Signed-off-by: Dominique Martinet <dominique.martinet@atmark-techno.com>
> ---
>  .../devicetree/bindings/net/h4-bluetooth.yaml | 49 +++++++++++++++++++
>  1 file changed, 49 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/h4-bluetooth.yaml
> 
> diff --git a/Documentation/devicetree/bindings/net/h4-bluetooth.yaml b/Documentation/devicetree/bindings/net/h4-bluetooth.yaml
> new file mode 100644
> index 000000000000..5d11b89ca386
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/h4-bluetooth.yaml

If the schema is for one specific device, then filename matching the
compatible, so nxp,aw-xm458-bt.yaml... but I understand you want to
describe here class of devices using H4 Bluetooth? Won't they need their
own specific properties?


> @@ -0,0 +1,49 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/h4-bluetooth.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: H4 Bluetooth
> +
> +maintainers:
> +  - Dominique Martinet <dominique.martinet@atmark-techno.com>
> +
> +description:
> +  H4 is a common bluetooth over uart protocol.

Bluetooth
UART

> +  For example, the AW-XM458 is a WiFi + BT module where the WiFi part is
> +  connected over PCI (M.2), while BT is connected over serial speaking
> +  the H4 protocol. Its firmware is sent on the PCI side.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - nxp,aw-xm458-bt
> +
> +  max-speed: true
> +
> +required:
> +  - compatible
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +    #include <dt-bindings/clock/imx8mp-clock.h>
> +
> +    uart1 {

uart

> +        pinctrl-names = "default";
> +        pinctrl-0 = <&pinctrl_uart1>;
> +        assigned-clocks = <&clk IMX8MP_CLK_UART1>;
> +        assigned-clock-parents = <&clk IMX8MP_SYS_PLL1_80M>;

Drop unrelated properties.

> +        status = "okay";

Drop status.

> +        fsl,dte-mode = <1>;
> +        fsl,uart-has-rtscts;

Are these two related to this hardware?

> +
> +
> +        bluetooth {
> +            compatible = "nxp,aw-xm458-bt";
> +            max-speed = <3000000>;
> +        };
> +    };

Best regards,
Krzysztof
  

On Tue, 08 Nov 2022 14:55:30 +0900, Dominique Martinet wrote:
> Add devicetree binding to support defining a bluetooth device using the h4
> uart protocol
> 
> This was tested with a NXP wireless+BT AW-XM458 module, but might
> benefit others as the H4 protocol seems often used.
> 
> Signed-off-by: Dominique Martinet <dominique.martinet@atmark-techno.com>
> ---
>  .../devicetree/bindings/net/h4-bluetooth.yaml | 49 +++++++++++++++++++
>  1 file changed, 49 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/h4-bluetooth.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
fsl,dte-mode: boolean property with value b'\x00\x00\x00\x01'
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/h4-bluetooth.example.dtb: uart1: fsl,dte-mode: b'\x00\x00\x00\x01' is not of type 'object', 'array', 'boolean', 'null'
	From schema: /usr/local/lib/python3.10/dist-packages/dtschema/schemas/dt-core.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/h4-bluetooth.example.dtb: uart1: 'anyOf' conditional failed, one must be fixed:
	'clocks' is a required property
	'#clock-cells' is a required property
	From schema: /usr/local/lib/python3.10/dist-packages/dtschema/schemas/clock/clock.yaml

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.
  

On Mon, Nov 7, 2022 at 11:56 PM Dominique Martinet
<dominique.martinet@atmark-techno.com> wrote:
>
> Add devicetree binding to support defining a bluetooth device using the h4
> uart protocol

The protocol is mostly irrelevant to the binding. The binding is for a
particular device even if the driver is shared.

>
> This was tested with a NXP wireless+BT AW-XM458 module, but might
> benefit others as the H4 protocol seems often used.
>
> Signed-off-by: Dominique Martinet <dominique.martinet@atmark-techno.com>
> ---
>  .../devicetree/bindings/net/h4-bluetooth.yaml | 49 +++++++++++++++++++

Use the compatible string for the filename.

There's now a pending (in linux-next) net/bluetooth/ directory and a
bluetooth-controller.yaml schema which you should reference.

>  1 file changed, 49 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/h4-bluetooth.yaml
>
> diff --git a/Documentation/devicetree/bindings/net/h4-bluetooth.yaml b/Documentation/devicetree/bindings/net/h4-bluetooth.yaml
> new file mode 100644
> index 000000000000..5d11b89ca386
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/h4-bluetooth.yaml
> @@ -0,0 +1,49 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/h4-bluetooth.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: H4 Bluetooth
> +
> +maintainers:
> +  - Dominique Martinet <dominique.martinet@atmark-techno.com>
> +
> +description:
> +  H4 is a common bluetooth over uart protocol.
> +  For example, the AW-XM458 is a WiFi + BT module where the WiFi part is
> +  connected over PCI (M.2), while BT is connected over serial speaking
> +  the H4 protocol. Its firmware is sent on the PCI side.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - nxp,aw-xm458-bt
> +
> +  max-speed: true
> +
> +required:
> +  - compatible
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +    #include <dt-bindings/clock/imx8mp-clock.h>
> +
> +    uart1 {

serial {

> +        pinctrl-names = "default";
> +        pinctrl-0 = <&pinctrl_uart1>;
> +        assigned-clocks = <&clk IMX8MP_CLK_UART1>;
> +        assigned-clock-parents = <&clk IMX8MP_SYS_PLL1_80M>;
> +        status = "okay";
> +        fsl,dte-mode = <1>;
> +        fsl,uart-has-rtscts;

All these properties are irrelevant to the example. Drop.

> +
> +
> +        bluetooth {
> +            compatible = "nxp,aw-xm458-bt";
> +            max-speed = <3000000>;
> +        };
> +    };
> --
> 2.35.1
>
>
  

Thanks for all the replies!

All remarks make sense, I'll do my homework and send a v2 once extra
questions have been answered.

Rob Herring wrote on Tue, Nov 08, 2022 at 07:59:33AM -0600:
> On Mon, Nov 7, 2022 at 11:56 PM Dominique Martinet
> <dominique.martinet@atmark-techno.com> wrote:
> > Add devicetree binding to support defining a bluetooth device using the h4
> > uart protocol
> 
> The protocol is mostly irrelevant to the binding. The binding is for a
> particular device even if the driver is shared.

This echoes the point below: I wanted to make this a bit more generic
for other adapters, question at the end of my first reply to Krzysztof
below.

> There's now a pending (in linux-next) net/bluetooth/ directory and a
> bluetooth-controller.yaml schema which you should reference.

Will check it out and add that.

Krzysztof Kozlowski wrote on Tue, Nov 08, 2022 at 12:37:39PM +0100:
> > diff --git a/Documentation/devicetree/bindings/net/h4-bluetooth.yaml b/Documentation/devicetree/bindings/net/h4-bluetooth.yaml
> > new file mode 100644
> > index 000000000000..5d11b89ca386
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/net/h4-bluetooth.yaml
> 
> If the schema is for one specific device, then filename matching the
> compatible, so nxp,aw-xm458-bt.yaml... but I understand you want to
> describe here class of devices using H4 Bluetooth? Won't they need their
> own specific properties?

H4 bluetooth itself has very little configurable elements, from what I
can see about the device I'm using the actual configuration is done by
the wifi driver that uploads a "combo" firmware over the PCI side
(it's based on mwifiex, so for example mrvl/pcieuart8997_combo_v4.bin
upstream works the same way afaik)

This is a pretty terrible design, as the Bluetooth side cannot actually
know when the device is ready as the initialization takes place, but
that means there really aren't any property to give here

(I haven't reproduced during normal boot, but in particular if I run
bluetoothd before loading the wifi driver, I need to unbind/bind the
serial device from the hci_uart_h4 driver to recover bluetooth...
With that in mind it might actually be best to try to coordinate this
from userspace with btattach after all, and I'd be happy with that if I
didn't have to fight our init system so much, but as things stand having
it autoloaded by the kernel is more convenient for us... Which is
admitedly a weak reason for you all, feel free to tell me this isn't
viable)


Anyway, there probably would be other devices benefiting from this, at
the very least other cards in the mwifiex family, but I'm doing this as
a end user so I'm not comfortable adding devices I cannot test.

So with all of this (sorry for the wall of text), should I try to keep
this generic, or just give up and make it specific to nxp,aw-xm458-bt
and let whoever adds the next device rename the file?


> > +examples:
> > +  - |
> > +    #include <dt-bindings/gpio/gpio.h>
> > +    #include <dt-bindings/clock/imx8mp-clock.h>
> > +
> > +    uart {
> > +        fsl,dte-mode = <1>;
> > +        fsl,uart-has-rtscts;
> 
> Are these two related to this hardware?

I'd say it's related to my soc rather than the Bluetooth adapter; I
tried to give a full example but it's unrelated and I'll drop this as
well.
  

Dominique Martinet wrote on Wed, Nov 09, 2022 at 08:54:42AM +0900:
> This is a pretty terrible design, as the Bluetooth side cannot actually
> know when the device is ready as the initialization takes place, but
> that means there really aren't any property to give here
> 
> (I haven't reproduced during normal boot, but in particular if I run
> bluetoothd before loading the wifi driver, I need to unbind/bind the
> serial device from the hci_uart_h4 driver to recover bluetooth...
> With that in mind it might actually be best to try to coordinate this
> from userspace with btattach after all, and I'd be happy with that if I
> didn't have to fight our init system so much, but as things stand having
> it autoloaded by the kernel is more convenient for us... Which is
> admitedly a weak reason for you all, feel free to tell me this isn't
> viable)

This actually hasn't taken long to bite us: while the driver does work,
we get error messages early on before the firmware is loaded.
(In hindsight, I probably should have waited a few days before sending
this...)


My current workaround is to return EPROBE_DEFER until we can find a
netdev with a known name in the init namespace, but that isn't really
something I'd consider upstreamable for obvious reasons (interfaces can
be renamed or moved to different namespaces so this is inherently racy
and it's just out of place in BT code)

That makes these two patches on their own rather useless as well, so
unless one of you have an idea that's less ugly I'd guess just dropping
this is the way to go, as much as I dislike the idea of adding more
non-upstream code than we already have :(

Thank you both for your time, the replies have been very helpful and
I'll remember for next time I try to submit something!

And if you have a suggestion, I'll be happy to do some legwork to clean
this mess, so feel free to ask :)


Thanks,
  

On Wed, Nov 09, 2022 at 04:29:52PM +0900, Dominique Martinet wrote:
> Dominique Martinet wrote on Wed, Nov 09, 2022 at 08:54:42AM +0900:
> > This is a pretty terrible design, as the Bluetooth side cannot actually
> > know when the device is ready as the initialization takes place, but
> > that means there really aren't any property to give here
> > 
> > (I haven't reproduced during normal boot, but in particular if I run
> > bluetoothd before loading the wifi driver, I need to unbind/bind the
> > serial device from the hci_uart_h4 driver to recover bluetooth...
> > With that in mind it might actually be best to try to coordinate this
> > from userspace with btattach after all, and I'd be happy with that if I
> > didn't have to fight our init system so much, but as things stand having
> > it autoloaded by the kernel is more convenient for us... Which is
> > admitedly a weak reason for you all, feel free to tell me this isn't
> > viable)

Punting the issue to userspace is not a great solution...


> This actually hasn't taken long to bite us: while the driver does work,
> we get error messages early on before the firmware is loaded.
> (In hindsight, I probably should have waited a few days before sending
> this...)
> 
> 
> My current workaround is to return EPROBE_DEFER until we can find a
> netdev with a known name in the init namespace, but that isn't really
> something I'd consider upstreamable for obvious reasons (interfaces can
> be renamed or moved to different namespaces so this is inherently racy
> and it's just out of place in BT code)

Can't you just try to access the BT h/w in some way and defer when that 
fails?

Or perhaps use fw_devlink to create a dependency on the wifi node. I'm 
not sure offhand how exactly you do that with a custom property.

Rob
  

Rob Herring wrote on Wed, Nov 09, 2022 at 04:00:05PM -0600:
> Punting the issue to userspace is not a great solution...

I can definitely agree with that :)

Userspace has the advantage of being easy to shove ugly things under the
rug, whereas I still have faint hope of keeping down the divergences we
have with upstream kernel... But that's about it.

If we can work out a solution here I'll be very happy.


Rob Herring wrote on Wed, Nov 09, 2022 at 04:00:05PM -0600:
> > This actually hasn't taken long to bite us: while the driver does work,
> > we get error messages early on before the firmware is loaded.
> > (In hindsight, I probably should have waited a few days before sending
> > this...)
> > 
> > 
> > My current workaround is to return EPROBE_DEFER until we can find a
> > netdev with a known name in the init namespace, but that isn't really
> > something I'd consider upstreamable for obvious reasons (interfaces can
> > be renamed or moved to different namespaces so this is inherently racy
> > and it's just out of place in BT code)
> 
> Can't you just try to access the BT h/w in some way and defer when that 
> fails?

This is just a serial link; I've tried poking at it a bit before the
firmware is loaded but mostly never got any reply, or while the driver
sometimes got garbage back at some point (baudrate not matching with
fresh boot default?)
Either way, no reply isn't great -- just waiting a few ms for reply or
not is not my idea of good design...

> Or perhaps use fw_devlink to create a dependency on the wifi node. I'm 
> not sure offhand how exactly you do that with a custom property.

That sounds great if we can figure how to do that!
From what I can see this doesn't look possible to express in pure
devicetree, but I see some code initializing a fwnode manually in a
constructor function with fwnode_init and a fwnode_operations vector
that has .add_links, which in turn could add a link.
... My problem at this point would be that I currently load the wireless
driver as a module as it's vendor provided out of tree... (it's loaded
through its pci alias, I guess it's udev checking depmod infos? not
familiar how that part of autoloading really works...)

But that makes me think that rather than defining the bluetooth serdev
in dts early, I could try to have the wireless driver create it once
it's ready? hmm...

Let me sleep on that a bit and have another look at both fwnode
(fw_devlink) and dynamic device creation.


Cheers,
  

On Thu, Nov 10, 2022 at 1:38 AM Dominique Martinet
<dominique.martinet@atmark-techno.com> wrote:
>
> Rob Herring wrote on Wed, Nov 09, 2022 at 04:00:05PM -0600:
> > Punting the issue to userspace is not a great solution...
>
> I can definitely agree with that :)
>
> Userspace has the advantage of being easy to shove ugly things under the
> rug, whereas I still have faint hope of keeping down the divergences we
> have with upstream kernel... But that's about it.
>
> If we can work out a solution here I'll be very happy.
>
>
> Rob Herring wrote on Wed, Nov 09, 2022 at 04:00:05PM -0600:
> > > This actually hasn't taken long to bite us: while the driver does work,
> > > we get error messages early on before the firmware is loaded.
> > > (In hindsight, I probably should have waited a few days before sending
> > > this...)
> > >
> > >
> > > My current workaround is to return EPROBE_DEFER until we can find a
> > > netdev with a known name in the init namespace, but that isn't really
> > > something I'd consider upstreamable for obvious reasons (interfaces can
> > > be renamed or moved to different namespaces so this is inherently racy
> > > and it's just out of place in BT code)
> >
> > Can't you just try to access the BT h/w in some way and defer when that
> > fails?
>
> This is just a serial link; I've tried poking at it a bit before the
> firmware is loaded but mostly never got any reply, or while the driver
> sometimes got garbage back at some point (baudrate not matching with
> fresh boot default?)
> Either way, no reply isn't great -- just waiting a few ms for reply or
> not is not my idea of good design...
>
> > Or perhaps use fw_devlink to create a dependency on the wifi node. I'm
> > not sure offhand how exactly you do that with a custom property.
>
> That sounds great if we can figure how to do that!
> From what I can see this doesn't look possible to express in pure
> devicetree, but I see some code initializing a fwnode manually in a
> constructor function with fwnode_init and a fwnode_operations vector
> that has .add_links, which in turn could add a link.

If the wifi node was a standard provider (clocks, resets, etc.) to the
BT node, it does just work with DT. The issue here is either you'd
have some custom property or no property and the BT side driver just
knows there is a dependency to create. That case is what .add_links is
for IIRC.

> ... My problem at this point would be that I currently load the wireless
> driver as a module as it's vendor provided out of tree... (it's loaded
> through its pci alias, I guess it's udev checking depmod infos? not
> familiar how that part of autoloading really works...)

Well, that's a fun complication. I guess it has no DT info? You can
populate your DT with the necessary PCI nodes to represent the wifi
device. Under the PCI host node, you'll need at least a root port node
and then probably the wifi device is under that. It's got to match the
hierarchy to assign a device_node ptr to the PCI device.

Module aliases are the magic that makes the autoloading work.

> But that makes me think that rather than defining the bluetooth serdev
> in dts early, I could try to have the wireless driver create it once
> it's ready? hmm...

That is yet another option. The wireless driver could create the BT
device when ready. The issue there is serdev devices created
asynchronously isn't supported. serdev looks if the serial device has
a child node and will register with serdev and create the serdev
device. Otherwise, the serial device is bound to the tty layer.

Rob