1# Copyright (c) 2020 Nordic Semiconductor ASA
2# SPDX-License-Identifier: Apache-2.0
3
4description: |
5    Nordic nRF family RADIO peripheral.
6
7    This controls the 2.4 GHz radio transceiver on nRF5x
8    SoCs, which is available for use with Bluetooth, 802.15.4,
9    and proprietary wireless protocols (not all of these
10    protocols are available on all SoCs; consult the product
11    specifications for details).
12
13    This binding is not relevant to the nRF91x baseband radio.
14
15    Front-End Module (FEM) support
16    ------------------------------
17
18    External front-end modules are range extenders used for boosting
19    the link robustness and link budget of wireless SoCs. If your
20    system includes an external FEM, set it up in the devicetree using
21    this binding's 'fem' property, like this example:
22
23      &radio {
24              fem = <&nrf_radio_fem>;
25      };
26
27      nrf_radio_fem: my-fem {
28              compatible = "...";
29              ....
30      };
31
32    Currently supported "compatible" properties for the FEM node are:
33
34      - generic-fem-two-ctrl-pins
35      - nordic,nrf21540-fem
36
37    Refer to the bindings for these compatibles for more information
38    about how to configure the FEM.
39
40    Direction Finding Extension
41    ---------------------------
42
43    Some radios support the Bluetooth Direction Finding Extension (DFE).
44    The 'dfe-supported' property will be set when it is available.
45    In this case, the 'dfegpio[n]-gpios' properties configure GPIO pins
46    to use to drive antenna switching.
47
48    Each dfegpio[n]-gpios property which is set is used to initialize the
49    corresponding PSEL.DFEGPIO[n] register.
50
51    None of the dfegpio[n]-gpios properties are marked 'required',
52    since which PSEL.DFEGPIO[n] registers will be used to drive
53    antenna switches depends on the use case. Nevertheless, at least two
54    antennas must be available to use DFE.
55
56    That in turn means that at least one dfegpio[n]-gpios
57    property must be provided if DFE is used, to give the radio the
58    possibility to switch between two antennas. To use 12 antennas,
59    4 GPIOs must be provided (since 4 GPIO pins support switching up to
60    16 antennas).
61
62    GPIOs are used in order, following the indices of the dfegpio[n]-gpios
63    properties. The order is important because it affects the mapping of
64    antenna switch patterns to GPIOs.
65
66    Antenna switching patterns
67    --------------------------
68
69    An antenna switching pattern is a binary number where each bit is
70    applied to a particular antenna GPIO pin. For example, the pattern
71    0x3 means that antenna GPIOs at indexes 0 and 1 will be set, while
72    the following are left unset.
73
74    The number of GPIOs specified with dfegpio[n]-gpios properties
75    affects the allowed pattern values. For example, when using four
76    GPIOs, the pattern count cannot be greater than 16, and the
77    maximum allowed value is 15.
78
79    Antenna switch patterns are stored in DFE internal memory by
80    writes to the SWITCHPATTERN register. DFE handling code applies
81    antenna switch patterns during Constant Tone Extension (CTE)
82    receive (Angle of Arrival mode) or transmission (Angle of
83    Departure mode) procedure.
84
85    DFE States
86    ----------
87
88    There are four states of DFE operation:
89
90    * Idle: in this state, PDU transmission happens.
91      DFE uses SWITCHPATTERN[0] to select the antenna in this state.
92      (The 'dfe-pdu-antenna' property value described below is stored
93      in SWITCHPATTERN[0] by the radio controller code.)
94
95    * Guard: in this state, DFE prepares for reception or transmission
96      of CTE. For this state, DFE selects the antenna by applying
97      SWITCHPATTERN[1].
98
99    * Reference: in this state, DFE starts to receive or transmit CTE.
100      In AoA mode, DFE collects reference IQ samples. The selected
101      antenna is the same as in the guard state.
102
103    * Switch-sample: in this state, actual antenna switching happens.
104      DFE selects antennas by applying SWITCHPATTERN[2..N]. If the
105      number of switch-sample periods is greater than the number of
106      stored switching patterns, DFE loops back to SWITCHPATTERN[2].
107
108
109compatible: "nordic,nrf-radio"
110
111include: [base.yaml]
112
113properties:
114  reg:
115    required: true
116
117  interrupts:
118    required: true
119
120  fem:
121    type: phandle
122    description: |
123      Phandle linking the RADIO node to its external front-end module.
124
125  coex:
126    type: phandle
127    description: |
128      Phandle linking the RADIO node to the external radio coexistence arbitrator.
129
130  dfe-supported:
131    type: boolean
132    description: |
133      If set, the radio hardware supports the Direction Finding Extension.
134      This property should be treated as read-only and should not be overridden;
135      the correct value is provided for your target's SoC already.
136
137  dfe-antenna-num:
138    type: int
139    description: |
140      Number of available antennas for the Direction Finding Extension.
141
142      This should only be set if dfe-supported is true. If you set this
143      property, the value must be at least two.
144
145  dfe-pdu-antenna:
146    type: int
147    description: |
148      Antenna switch pattern to be used for transmission of PDU before start
149      of transmission of Constant Tone Extension.
150
151      This should only be set if dfe-supported is true.
152
153      This pattern is stored in SWITCHPATTERN[0] before actual antenna
154      switching patterns. This pattern will also be used to drive GPIOs
155      when the radio releases control of GPIOs used to switch antennas.
156
157  dfegpio0-gpios:
158    type: phandle-array
159    description: |
160      Pin select for DFE pin 0. This should only be set if dfe-supported
161      is true.
162
163      For example, to use P0.2 on an nRF5x SoC:
164
165        dfegpio1-gpios = <&gpio0 2 0>;
166
167      To use P1.4:
168
169        dfegpio1-gpios = <&gpio1 4 0>;
170
171      Note the last 'flags' cell in the property is not used,
172      and should be set to 0 as shown.
173
174  dfegpio1-gpios:
175    type: phandle-array
176    description: |
177      Pin select for DFE pin 1. See description for dfegpio0-gpios.
178
179  dfegpio2-gpios:
180    type: phandle-array
181    description: |
182      Pin select for DFE pin 2. See description for dfegpio0-gpios.
183
184  dfegpio3-gpios:
185    type: phandle-array
186    description: |
187      Pin select for DFE pin 3. See description for dfegpio0-gpios.
188
189  dfegpio4-gpios:
190    type: phandle-array
191    description: |
192      Pin select for DFE pin 4. See description for dfegpio0-gpios.
193
194  dfegpio5-gpios:
195    type: phandle-array
196    description: |
197      Pin select for DFE pin 5. See description for dfegpio0-gpios.
198
199  dfegpio6-gpios:
200    type: phandle-array
201    description: |
202      Pin select for DFE pin 6. See description for dfegpio0-gpios.
203
204  dfegpio7-gpios:
205    type: phandle-array
206    description: |
207      Pin select for DFE pin 7. See description for dfegpio0-gpios.
208
209  ieee802154-supported:
210    type: boolean
211    description: |
212      If set, indicates that the radio hardware supports the IEEE 802.15.4
213      mode.
214
215  ble-2mbps-supported:
216    type: boolean
217    description: |
218      If set, indicates that the radio hardware supports the 2 Mbps BLE mode.
219
220  ble-coded-phy-supported:
221    type: boolean
222    description: |
223      If set, indicates that the radio hardware supports coded BLE PHY.
224
225  tx-high-power-supported:
226    type: boolean
227    description: |
228      If set, indicates that the radio hardware supports high TX power
229      settings.
230
231  cs-supported:
232    type: boolean
233    description: |
234      If set, the radio hardware supports the BLE Channel Sounding feature.
235      This property should be treated as read-only and should not be overridden;
236      the correct value is provided for your target's SoC already.
237