From a930bebb42a48213942a4ea024217ff1971dddd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Fri, 5 Nov 2021 13:32:07 -0700 Subject: [PATCH] dts: bindings: improve nordic,nrf21540-fem docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The way the nRF21540 device is configured makes sense once you understand it, but it's quite unusual: a single peripheral is configured with two separate devicetree nodes linked by a phandle. Since this risks entering "exploding head" territory for beginners, it deserves a thorough example. Add one to the binding's description. Signed-off-by: Martí Bolívar --- .../net/wireless/nordic,nrf21540-fem.yaml | 55 ++++++++++++++++++- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/dts/bindings/net/wireless/nordic,nrf21540-fem.yaml b/dts/bindings/net/wireless/nordic,nrf21540-fem.yaml index 9d20b682f0a..304d3c01962 100644 --- a/dts/bindings/net/wireless/nordic,nrf21540-fem.yaml +++ b/dts/bindings/net/wireless/nordic,nrf21540-fem.yaml @@ -1,9 +1,60 @@ -# Copyright (c) 2020 Nordic Semiconductor ASA +# Copyright (c) 2020, 2021 Nordic Semiconductor ASA # SPDX-License-Identifier: Apache-2.0 description: | - This is a representation of the nRF21540 Radio Front-End module + This is a representation of the nRF21540 Radio Front-End module. + + See the "nordic,nrf21540-fem-spi" binding to configure the SPI + interface. The SPI interface should be configured as a child node + of the SPI bus you have connected to the FEM. Then you "connect" + the FEM and SPI configurations using the spi-if property. + + Here is an example nRF21540 configuration with a SPI interface + selected, using the SPIM0 peripheral found on several nRF5 SoCs: + + &spi0 { + compatible = "nordic,nrf-spim"; + status = "okay"; + cs-gpios = <&gpio1 3 GPIO_ACTIVE_LOW>; + /* ... MISO/MOSI/SCK pin configuration goes here ... */ + + my_spi_if: nrf21540-spi@0 { + compatible = "nordic,nrf21540-fem-spi"; + reg = <0>; + spi-max-frequency = <8000000>; + }; + }; + + nrf_radio_fem: nrf21540 { + compatible = "nordic,nrf21540-fem"; + tx-en-gpios = <&gpio0 2 GPIO_ACTIVE_HIGH>; + rx-en-gpios = <&gpio0 5 GPIO_ACTIVE_HIGH>; + spi-if = <&my_spi_if>; + pdn-gpios = <...>; + ant-sel-gpios = <...>; + mode-gpios = <...>; + /* ... other nRF21540 properties go here ... */ + }; + + In the above example, the nRF21540 is configured for use with: + + - TX_EN on P0.2 (from 'tx-en-gpios') + - RX_EN on P0.5 (from 'rx-en-gpios') + - SPI communication via SPIM0 (the bus, or parent node, of + the 'my_spi_if' node + - CSN on P1.3 (from index 0 in the bus node's 'cs-gpios' property) + + You must perform any additional required SPI pin configuration + (nRF21540 MISO, MOSI, and SCK pins) within the SPI bus node + ('spi0' in the above example). See your SPI node's binding for + details on these pin mux properties. You can use any SPI node + available in your SoC's devicetree. + + Configure any other nRF21540 pins as needed using 'pdn-gpios', + 'ant-sel-gpios', and 'mode-gpios' properties. If unsure about the + format, use 'tx-en-gpios' as an example. + compatible: "nordic,nrf21540-fem" include: base.yaml