mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2026-08-30 15:43:08 -04:00
docs: iio: add documentation for adf41513 driver
Add documentation for ADF41513 driver, which describes the device driver files and shows how userspace may consume the ABI for various tasks. Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Rodrigo Alencar <rodrigo.alencar@analog.com> Signed-off-by: Jonathan Cameron <jic23@kernel.org>
This commit is contained in:
Rodrigo Alencar
committed by
Jonathan Cameron
Jonathan Cameron
parent
5809020d86
commit
3eaacb0f1f
199
Documentation/iio/adf41513.rst
Normal file
199
Documentation/iio/adf41513.rst
Normal file
@@ -0,0 +1,199 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
===============
|
||||
ADF41513 driver
|
||||
===============
|
||||
|
||||
This driver supports Analog Devices' ADF41513 and similar SPI PLL frequency
|
||||
synthesizers.
|
||||
|
||||
1. Supported devices
|
||||
====================
|
||||
|
||||
* `ADF41510 <https://www.analog.com/ADF41510>`_
|
||||
* `ADF41513 <https://www.analog.com/ADF41513>`_
|
||||
|
||||
The ADF41513 is an ultralow noise frequency synthesizer that can be used to
|
||||
implement local oscillators (LOs) as high as 26.5 GHz in the upconversion and
|
||||
downconversion sections of wireless receivers and transmitters. The ADF41510
|
||||
is a similar device that supports frequencies up to 10 GHz.
|
||||
|
||||
Both devices support integer-N and fractional-N operation modes, providing
|
||||
excellent phase noise performance and flexible frequency generation
|
||||
capabilities.
|
||||
|
||||
Key Features:
|
||||
|
||||
- **ADF41510**: 1 GHz to 10 GHz frequency range
|
||||
- **ADF41513**: 1 GHz to 26.5 GHz frequency range
|
||||
- Integer-N and fractional-N operation modes
|
||||
- Ultra-low phase noise (-235 dBc/Hz integer-N, -231 dBc/Hz fractional-N)
|
||||
- High maximum PFD frequency (250 MHz integer-N, 125 MHz fractional-N)
|
||||
- 25-bit fixed modulus or 49-bit variable modulus fractional modes
|
||||
- Programmable charge pump currents with 16x range
|
||||
- Digital lock detect functionality
|
||||
- Phase resync capability for consistent output phase
|
||||
|
||||
2. Device attributes
|
||||
====================
|
||||
|
||||
The ADF41513 driver provides the following IIO extended attributes for
|
||||
frequency control and monitoring:
|
||||
|
||||
Each IIO device has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
|
||||
where X is the IIO index of the device. Under these folders reside a set of
|
||||
device files that provide access to the synthesizer's functionality.
|
||||
|
||||
The following table shows the ADF41513 related device files:
|
||||
|
||||
+--------------------------------------+-------------------------------------------------------+
|
||||
| Device file | Description |
|
||||
+======================================+=======================================================+
|
||||
| out_altvoltage0_frequency | RF output frequency control and readback (Hz) |
|
||||
+--------------------------------------+-------------------------------------------------------+
|
||||
| out_altvoltage0_frequency_resolution | Target frequency resolution control (Hz) |
|
||||
+--------------------------------------+-------------------------------------------------------+
|
||||
| out_altvoltage0_powerdown | Power management control (0=active, 1=power down) |
|
||||
+--------------------------------------+-------------------------------------------------------+
|
||||
| out_altvoltage0_phase | RF output phase adjustment and readback (radians) |
|
||||
+--------------------------------------+-------------------------------------------------------+
|
||||
|
||||
2.1 Frequency Control
|
||||
----------------------
|
||||
|
||||
The ``out_altvoltage0_frequency`` attribute controls the RF output frequency
|
||||
with sub-Hz precision. The driver automatically selects between integer-N and
|
||||
fractional-N modes to achieve the requested frequency with the best possible
|
||||
phase noise performance.
|
||||
|
||||
**Supported ranges:**
|
||||
|
||||
- **ADF41510**: 1,000,000,000 Hz to 10,000,000,000 Hz (1 GHz to 10 GHz)
|
||||
- **ADF41513**: 1,000,000,000 Hz to 26,500,000,000 Hz (1 GHz to 26.5 GHz)
|
||||
|
||||
The frequency is specified in Hz, for sub-Hz precision use decimal notation.
|
||||
For example, 12.102 GHz would be written as "12102000000.000000".
|
||||
|
||||
2.2 Frequency Resolution Control
|
||||
--------------------------------
|
||||
|
||||
The ``out_altvoltage0_frequency_resolution`` attribute controls the target
|
||||
frequency resolution that the driver attempts to achieve. This affects the
|
||||
choice between integer-N and fractional-N modes, including fixed modulus
|
||||
(25-bit) and variable modulus (49-bit) fractional-N modes:
|
||||
|
||||
- **Integer-N**: Resolution = :math:`f_{PFD}` (same as PFD frequency)
|
||||
- **Fixed modulus**: Resolution = :math:`f_{PFD} / 2^{25}` (~3 Hz with 100 MHz PFD)
|
||||
- **Variable modulus**: Resolution = :math:`f_{PFD} / 2^{49}` (µHz resolution possible)
|
||||
|
||||
Default resolution is 1 Hz (1,000,000 µHz).
|
||||
|
||||
2.3 Phase adjustment
|
||||
--------------------
|
||||
|
||||
The ``out_altvoltage0_phase`` attribute allows adjustment of the output phase
|
||||
in radians. Setting this attribute enables phase adjustment. It can be set
|
||||
from 0 to :math:`2\pi` radians. Reading this attribute returns the current
|
||||
phase offset of the output signal. To create a consistent phase relationship
|
||||
with the reference signal, the phase resync feature needs to be enabled by
|
||||
setting a non-zero value to the ``adi,phase-resync-period-ns`` device property,
|
||||
which triggers a phase resynchronization after locking is achieved.
|
||||
|
||||
3. Operating modes
|
||||
==================
|
||||
|
||||
3.1 Integer-N Mode
|
||||
------------------
|
||||
|
||||
When the requested frequency can be achieved as an integer multiple of the PFD
|
||||
frequency (within the specified resolution tolerance), the driver automatically
|
||||
selects integer-N mode for optimal phase noise performance.
|
||||
|
||||
In integer-N mode:
|
||||
|
||||
- Phase noise: -235 dBc/Hz normalized floor
|
||||
- Frequency resolution: :math:`f_{PFD}` (same as PFD frequency)
|
||||
- Maximum PFD frequency: 250 MHz
|
||||
- Bleed current: Disabled
|
||||
|
||||
3.2 Fractional-N Mode
|
||||
---------------------
|
||||
|
||||
When sub-integer frequency steps are required, the driver automatically selects
|
||||
fractional-N mode using either fixed or variable modulus.
|
||||
|
||||
**Fixed Modulus (25-bit)**:
|
||||
|
||||
- Used when variable modulus is not required
|
||||
- Resolution: :math:`f_{PFD} / 2^{25}`
|
||||
- Simpler implementation, faster settling
|
||||
|
||||
**Variable Modulus (49-bit)**:
|
||||
|
||||
- Used for maximum resolution requirements
|
||||
- Resolution: :math:`f_{PFD} / 2^{49}` (theoretical)
|
||||
- Exact frequency synthesis capability
|
||||
|
||||
In fractional-N mode:
|
||||
|
||||
- Phase noise: -231 dBc/Hz normalized floor
|
||||
- Maximum PFD frequency: 125 MHz
|
||||
- Bleed current: Automatically enabled and optimized
|
||||
- Dithering: Enabled to reduce fractional spurs
|
||||
|
||||
3.3 Automatic Mode Selection
|
||||
----------------------------
|
||||
|
||||
The driver automatically selects the optimal operating mode based on:
|
||||
|
||||
1. **Frequency accuracy requirements**: Determined by ``frequency_resolution`` setting
|
||||
2. **Phase noise optimization**: Integer-N preferred when possible
|
||||
3. **PFD frequency constraints**: Different limits for integer vs fractional modes
|
||||
4. **Prescaler selection**: Automatic 4/5 vs 8/9 prescaler selection based on frequency
|
||||
|
||||
4. Usage examples
|
||||
=================
|
||||
|
||||
4.1 Basic Frequency Setting
|
||||
----------------------------
|
||||
|
||||
Set output frequency to 12.102 GHz:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
root:/sys/bus/iio/devices/iio:device0> echo 12102000000 > out_altvoltage0_frequency
|
||||
|
||||
Read current frequency:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
root:/sys/bus/iio/devices/iio:device0> cat out_altvoltage0_frequency
|
||||
12101999999.582767
|
||||
|
||||
4.2 High Resolution Frequency Control
|
||||
-------------------------------------
|
||||
|
||||
Configure for sub-Hz resolution and set a precise frequency:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Set resolution to 0.1 Hz (100,000 µHz)
|
||||
root:/sys/bus/iio/devices/iio:device0> echo 0.1 > out_altvoltage0_frequency_resolution
|
||||
|
||||
# Set frequency to 12.102 GHz (1 µHz precision)
|
||||
root:/sys/bus/iio/devices/iio:device0> echo 12102000000 > out_altvoltage0_frequency
|
||||
root:/sys/bus/iio/devices/iio:device0> cat out_altvoltage0_frequency
|
||||
12101999999.980131
|
||||
|
||||
4.3 Monitor Lock Status
|
||||
-----------------------
|
||||
|
||||
When lock detect GPIO is configured, check if PLL is locked:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Read frequency - will return error if not locked
|
||||
root:/sys/bus/iio/devices/iio:device0> cat out_altvoltage0_frequency
|
||||
|
||||
If the PLL is not locked, the frequency read will return ``-EBUSY`` (Device or
|
||||
resource busy).
|
||||
@@ -31,6 +31,7 @@ Industrial I/O Kernel Drivers
|
||||
ad7625
|
||||
ad7944
|
||||
ade9000
|
||||
adf41513
|
||||
adis16475
|
||||
adis16480
|
||||
adis16550
|
||||
|
||||
@@ -1708,6 +1708,7 @@ L: linux-iio@vger.kernel.org
|
||||
S: Supported
|
||||
W: https://ez.analog.com/linux-software-drivers
|
||||
F: Documentation/devicetree/bindings/iio/frequency/adi,adf41513.yaml
|
||||
F: Documentation/iio/adf41513.rst
|
||||
F: drivers/iio/frequency/adf41513.c
|
||||
|
||||
ANALOG DEVICES INC ADF4377 DRIVER
|
||||
|
||||
Reference in New Issue
Block a user