1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4ADF41513 driver 5=============== 6 7This driver supports Analog Devices' ADF41513 and similar SPI PLL frequency 8synthesizers. 9 101. Supported devices 11==================== 12 13* `ADF41510 <https://www.analog.com/ADF41510>`_ 14* `ADF41513 <https://www.analog.com/ADF41513>`_ 15 16The ADF41513 is an ultralow noise frequency synthesizer that can be used to 17implement local oscillators (LOs) as high as 26.5 GHz in the upconversion and 18downconversion sections of wireless receivers and transmitters. The ADF41510 19is a similar device that supports frequencies up to 10 GHz. 20 21Both devices support integer-N and fractional-N operation modes, providing 22excellent phase noise performance and flexible frequency generation 23capabilities. 24 25Key Features: 26 27- **ADF41510**: 1 GHz to 10 GHz frequency range 28- **ADF41513**: 1 GHz to 26.5 GHz frequency range 29- Integer-N and fractional-N operation modes 30- Ultra-low phase noise (-235 dBc/Hz integer-N, -231 dBc/Hz fractional-N) 31- High maximum PFD frequency (250 MHz integer-N, 125 MHz fractional-N) 32- 25-bit fixed modulus or 49-bit variable modulus fractional modes 33- Programmable charge pump currents with 16x range 34- Digital lock detect functionality 35- Phase resync capability for consistent output phase 36 372. Device attributes 38==================== 39 40The ADF41513 driver provides the following IIO extended attributes for 41frequency control and monitoring: 42 43Each IIO device has a device folder under ``/sys/bus/iio/devices/iio:deviceX``, 44where X is the IIO index of the device. Under these folders reside a set of 45device files that provide access to the synthesizer's functionality. 46 47The following table shows the ADF41513 related device files: 48 49+--------------------------------------+-------------------------------------------------------+ 50| Device file | Description | 51+======================================+=======================================================+ 52| out_altvoltage0_frequency | RF output frequency control and readback (Hz) | 53+--------------------------------------+-------------------------------------------------------+ 54| out_altvoltage0_frequency_resolution | Target frequency resolution control (Hz) | 55+--------------------------------------+-------------------------------------------------------+ 56| out_altvoltage0_powerdown | Power management control (0=active, 1=power down) | 57+--------------------------------------+-------------------------------------------------------+ 58| out_altvoltage0_phase | RF output phase adjustment and readback (radians) | 59+--------------------------------------+-------------------------------------------------------+ 60 612.1 Frequency Control 62---------------------- 63 64The ``out_altvoltage0_frequency`` attribute controls the RF output frequency 65with sub-Hz precision. The driver automatically selects between integer-N and 66fractional-N modes to achieve the requested frequency with the best possible 67phase noise performance. 68 69**Supported ranges:** 70 71- **ADF41510**: 1,000,000,000 Hz to 10,000,000,000 Hz (1 GHz to 10 GHz) 72- **ADF41513**: 1,000,000,000 Hz to 26,500,000,000 Hz (1 GHz to 26.5 GHz) 73 74The frequency is specified in Hz, for sub-Hz precision use decimal notation. 75For example, 12.102 GHz would be written as "12102000000.000000". 76 772.2 Frequency Resolution Control 78-------------------------------- 79 80The ``out_altvoltage0_frequency_resolution`` attribute controls the target 81frequency resolution that the driver attempts to achieve. This affects the 82choice between integer-N and fractional-N modes, including fixed modulus 83(25-bit) and variable modulus (49-bit) fractional-N modes: 84 85- **Integer-N**: Resolution = :math:`f_{PFD}` (same as PFD frequency) 86- **Fixed modulus**: Resolution = :math:`f_{PFD} / 2^{25}` (~3 Hz with 100 MHz PFD) 87- **Variable modulus**: Resolution = :math:`f_{PFD} / 2^{49}` (µHz resolution possible) 88 89Default resolution is 1 Hz (1,000,000 µHz). 90 912.3 Phase adjustment 92-------------------- 93 94The ``out_altvoltage0_phase`` attribute allows adjustment of the output phase 95in radians. Setting this attribute enables phase adjustment. It can be set 96from 0 to :math:`2\pi` radians. Reading this attribute returns the current 97phase offset of the output signal. To create a consistent phase relationship 98with the reference signal, the phase resync feature needs to be enabled by 99setting a non-zero value to the ``adi,phase-resync-period-ns`` device property, 100which triggers a phase resynchronization after locking is achieved. 101 1023. Operating modes 103================== 104 1053.1 Integer-N Mode 106------------------ 107 108When the requested frequency can be achieved as an integer multiple of the PFD 109frequency (within the specified resolution tolerance), the driver automatically 110selects integer-N mode for optimal phase noise performance. 111 112In integer-N mode: 113 114- Phase noise: -235 dBc/Hz normalized floor 115- Frequency resolution: :math:`f_{PFD}` (same as PFD frequency) 116- Maximum PFD frequency: 250 MHz 117- Bleed current: Disabled 118 1193.2 Fractional-N Mode 120--------------------- 121 122When sub-integer frequency steps are required, the driver automatically selects 123fractional-N mode using either fixed or variable modulus. 124 125**Fixed Modulus (25-bit)**: 126 127- Used when variable modulus is not required 128- Resolution: :math:`f_{PFD} / 2^{25}` 129- Simpler implementation, faster settling 130 131**Variable Modulus (49-bit)**: 132 133- Used for maximum resolution requirements 134- Resolution: :math:`f_{PFD} / 2^{49}` (theoretical) 135- Exact frequency synthesis capability 136 137In fractional-N mode: 138 139- Phase noise: -231 dBc/Hz normalized floor 140- Maximum PFD frequency: 125 MHz 141- Bleed current: Automatically enabled and optimized 142- Dithering: Enabled to reduce fractional spurs 143 1443.3 Automatic Mode Selection 145---------------------------- 146 147The driver automatically selects the optimal operating mode based on: 148 1491. **Frequency accuracy requirements**: Determined by ``frequency_resolution`` setting 1502. **Phase noise optimization**: Integer-N preferred when possible 1513. **PFD frequency constraints**: Different limits for integer vs fractional modes 1524. **Prescaler selection**: Automatic 4/5 vs 8/9 prescaler selection based on frequency 153 1544. Usage examples 155================= 156 1574.1 Basic Frequency Setting 158---------------------------- 159 160Set output frequency to 12.102 GHz: 161 162.. code-block:: bash 163 164 root:/sys/bus/iio/devices/iio:device0> echo 12102000000 > out_altvoltage0_frequency 165 166Read current frequency: 167 168.. code-block:: bash 169 170 root:/sys/bus/iio/devices/iio:device0> cat out_altvoltage0_frequency 171 12101999999.582767 172 1734.2 High Resolution Frequency Control 174------------------------------------- 175 176Configure for sub-Hz resolution and set a precise frequency: 177 178.. code-block:: bash 179 180 # Set resolution to 0.1 Hz (100,000 µHz) 181 root:/sys/bus/iio/devices/iio:device0> echo 0.1 > out_altvoltage0_frequency_resolution 182 183 # Set frequency to 12.102 GHz (1 µHz precision) 184 root:/sys/bus/iio/devices/iio:device0> echo 12102000000 > out_altvoltage0_frequency 185 root:/sys/bus/iio/devices/iio:device0> cat out_altvoltage0_frequency 186 12101999999.980131 187 1884.3 Monitor Lock Status 189----------------------- 190 191When lock detect GPIO is configured, check if PLL is locked: 192 193.. code-block:: bash 194 195 # Read frequency - will return error if not locked 196 root:/sys/bus/iio/devices/iio:device0> cat out_altvoltage0_frequency 197 198If the PLL is not locked, the frequency read will return ``-EBUSY`` (Device or 199resource busy). 200