This version (25 Mar 2021 13:39) was approved by Michael Hennerich.The Previously approved version (23 Dec 2020 17:50) is available.

ADF5355 IIO Wideband Synthesizer Linux Driver

Supported Devices

Reference Circuits

Evaluation Boards

Description

This is a Linux industrial I/O (IIO) subsystem driver, targeting serial interface PLL Synthesizers. The industrial I/O subsystem provides a unified framework for drivers for many different types of converters and sensors using a number of different physical interfaces (i2c, spi, etc). See IIO for more information.

Source Code

Status

Source	Mainlined?
git	WIP

Files

Function	File
driver	master?drivers/iio/frequency/adf5355.c
include	master?include/linux/iio/frequency/adf5355.h
Documentation	master?Documentation/devicetree/bindings/iio/frequency/adf5355.txt

Example platform device initialization

For compile time configuration, it’s common Linux practice to keep board- and application-specific configuration out of the main driver file, instead putting it into the board support file.

For devices on custom boards, as typical of embedded and SoC-(system-on-chip) based hardware, Linux uses platform_data to point to board-specific structures describing devices and how they are connected to the SoC. This can include available ports, chip variants, preferred modes, default initialization, additional pin roles, and so on. This shrinks the board-support packages (BSPs) and minimizes board and application specific #ifdefs in drivers.

21 Oct 2010 16:10

The reference frequency and GPIO numbers may vary between boards. The platform_data for the device's “struct device” holds this information.

/**
 * struct adf5355_platform_data - platform specific information
 * @name:		Optional device name.
 * @clkin:		REFin frequency in Hz.
 * @channel_spacing:	Channel spacing in Hz (influences MODULUS).
 * @power_up_frequency:	Optional, If set in Hz the PLL tunes to the desired
 *			frequency on probe.
 * @ref_div_factor:	Optional, if set the driver skips dynamic calculation
 *			and uses this default value instead.
 * @ref_doubler_en:	Enables reference doubler.
 * @ref_div2_en:		Enables reference divider.
 * @gpio_lock_detect:	Optional, if set with a valid GPIO number,
 *			pll lock state is tested upon read.
 *			If not used - set to -1.
 * @outa_en: 		Enables or disables the primary RF output
 * @outb_en: 		Enables or disables the auxiliary/high RF output
 * @outa_power		Set the value of the primary RF output power level
 * @outb_power		Set the value of the auxiliary/high RF output power level
 * @mute_till_lock_detect_en: If enabled, the supply current to the RF
			output stage is shut down until the device achieves lock,
			as determined by the digital lock detect circuitry.
 * @phase_detector_polarity_neg: When a passive loop filter or a noninverting
 * 			active loop filter is used, set to positive.
 * 			If an active filter with an inverting characteristic is
 * 			used, set this to negative.
 * @cp_neg_bleed_en:	Use of constant negative bleed. (recommended for most
 *			fractional-N applications)
 * @cp_gated_bleed_en:  Enables gated bleed.
 * @cp_curr_uA:		Set the charge pump current in uA. Set this value to
 * 			the charge pump current that the loop
 *			filter is designed with. For the lowest spurs, the
 *			0.9 mA setting is recommended.
 * @mux_out_sel:		Controls the on-chip multiplexer (MUXOUT).
 * @mux_out_3V3_en:	MUXOUT is programmable to two logic levels. Clear this to
 *			select 1.8 V logic, and set it to select 3.3 V logic.
 * 
 */
 
 struct adf5355_platform_data {
 	char			name[32];
 	unsigned long		clkin;
 	unsigned long long	power_up_frequency;
 
 	u32			ref_div_factor; /* 10-bit R counter */
 	bool 			ref_diff_en;
 	bool			ref_doubler_en;
 	bool			ref_div2_en;
 
	bool			mux_out_3V3_en; /* otherwise 1V8 */
	u32			mux_out_sel;
 
	u32			cp_curr_uA;
	bool			cp_neg_bleed_en;
	bool			cp_gated_bleed_en;
	bool			phase_detector_polarity_neg;
 
	bool			mute_till_lock_detect_en;
	bool 			outb_en;
	bool 			outa_en;
	u32			outb_power;
	u32			outa_power;
 
 	int			gpio_lock_detect;
 };

Declaring SPI slave devices

Unlike PCI or USB devices, SPI devices are not enumerated at the hardware level. Instead, the software must know which devices are connected on each SPI bus segment, and what slave selects these devices are using. For this reason, the kernel code must instantiate SPI devices explicitly. The most common method is to declare the SPI devices by bus number.

This method is appropriate when the SPI bus is a system bus, as in many embedded systems, wherein each SPI bus has a number which is known in advance. It is thus possible to pre-declare the SPI devices that inhabit this bus. This is done with an array of struct spi_board_info, which is registered by calling spi_register_board_info().

For more information see: Documentation/spi/spi-summary.rst

21 Oct 2010 16:10

Devicetree bindings

Required properties:
	- compatible: Should be one of
		* "adi,adf5355": When using the ADF5355 device
		* "adi,adf5356": When using the ADF5356 device
		* "adi,adf4355": When using the ADF4355 device
		* "adi,adf4355-2": When using the ADF4355-2 device
		* "adi,adf4355-3": When using the ADF4355-3 device
	- reg: SPI chip select numbert for the device
	- spi-max-frequency: Max SPI frequency to use (< 20000000)
	- clocks: From common clock binding. Clock is phandle to clock for
		ADF5355 Reference Clock (CLKIN).

Optional properties:
	- gpios:	GPIO Lock detect - If set with a valid phandle and GPIO
			number, pll lock state is tested upon read.
	- clock-output-names : From common clock binding to override the
			default output clock name.			
	- adi,power-up-frequency: If set in Hz the PLL tunes to
			the desired frequency on probe.
	- adi,reference-div-factor: If set the driver skips dynamic calculation
			and uses this default value instead.
	- adi,reference-doubler-enable: Enables reference doubler.
	- adi,reference-div2-enable: Enables reference divider.
	- adi,reference-differential-input-enable: The device permits use of 
			either differential or single ended reference sources. 
			For differential sources set this property.
	- adi,phase-detector-polarity-negative-enable: When a passive loop 
			filter or a noninverting active loop filter is used,
			clear for positive. If an active filter with an 
			inverting characteristic is used, set this to negative.
	- adi,charge-pump-current: Set the charge pump current in uA. 
			Set this value to the charge pump current that the loop
			filter is designed with. For the lowest spurs, the
			900 uA setting is recommended.
	- adi,charge-pump-negative-bleed-enable: Use of constant negative bleed.
			(recommended for most fractional-N applications)
	- adi,charge-pump-gated-bleed-enable: Enables gated bleed.
	- adi,muxout-select: On chip multiplexer output selection.
			Valid values for the multiplexer output are:
			0: Three-State Output (default)
			1: DVDD
			2: DGND
			3: R-Counter output
			4: N-Divider output
			5: Analog lock detect
			6: Digital lock detect
	- adi,muxout-level-3v3-enable: MUXOUT is programmable to two logic 
			levels. Clear this to select 1.8 V logic, 
			and set it to select 3.3 V logic.
	- adi,mute-till-lock-enable: If enabled, the supply current to the RF
			output stage is shut down until the device achieves lock,
			as determined by the digital lock detect circuitry.
	- adi,output-b-enable: Enables or disables the primary RF output
	- adi,output-a-enable: Enables or disables the auxiliary/high RF output
	- adi,output-a-power: Primary RF output power selection. 
			Valid values for the power mode are:
			0: -4dBm (default)
			1: -1dBm
			2: +2dBm
			3: +5dBm
	- adi,output-b-power: Auxiliary output power selection.
			Valid values for the power mode are:
			0: -4dBm (default)
			1: -1dBm
			2: +2dBm
			3: +5dBm

Example:

&spi0 {
	status = "okay";

	adf5355@0 {
		compatible = "adf5355";
		reg = <0>;
		spi-max-frequency = <1000000>;
		clocks = <&adf4351_clkin>;
		clock-names = "clkin";
		clock-output-names = "adf5355_out";
		adi,charge-pump-current = <900>;
		adi,muxout-select = <6>;
		adi,mute-till-lock-enable;
		adi,output-a-power = <2>;
		adi,output-b-power = <2>;
		adi,output-b-enable;
		adi,output-a-enable;
		adi,charge-pump-negative-bleed-enable;
		adi,reference-differential-input-enable;
		adi,muxout-level-3v3-enable;
		adi,power-up-frequency = /bits/ 64 <123000000>;
	};

	adf5356@1 {
		#clock-cells = <0>;
		compatible = "adi,adf5356";
		reg = <1>;
		spi-max-frequency = <1000000>;
		clocks = <&ad9361_clkin>;
		clock-names = "clkin";
		clock-output-names = "ADF5356";
		adi,charge-pump-current = <900>;
		adi,muxout-select = <6>;
                adi,muxout-level-3v3-enable;
		adi,mute-till-lock-enable;
		adi,output-a-power = <3>;
		adi,output-b-power = <0>;
		adi,charge-pump-negative-bleed-enable;
		adi,reference-differential-input-enable;
		adi,power-up-frequency = /bits/ 64 <1500000000>;
		adi,output-a-enable;
		adi,clock-shift = <2>;
                adi,reference-div2-enable;
                adi,reference-div-factor = <1>;
	};
};

Adding Linux driver support

Configure kernel with “make menuconfig” (alternatively use “make xconfig” or “make qconfig”)

The ADF5355 Driver depends on CONFIG_SPI

Linux Kernel Configuration
	Device Drivers  --->
		<*>     Industrial I/O support --->
		    --- Industrial I/O support
		    -*-   Enable ring buffer support within IIO
		    -*-     Industrial I/O lock free software ring
		    -*-   Enable triggered sampling support

			          *** Phase-Locked Loop (PLL) frequency synthesizers ***

		    [--snip--]
			    <*>   Analog Devices ADF5355/ADF4355 Wideband Synthesizers
		    [--snip--]

Hardware configuration

Driver testing

Each and every IIO device, typically a hardware chip, has a device folder under /sys/bus/iio/devices/iio:deviceX. Where X is the IIO index of the device. Under every of these directory folders reside a set of files, depending on the characteristics and features of the hardware device in question. These files are consistently generalized and documented in the IIO ABI documentation. In order to determine which IIO deviceX corresponds to which hardware device, the user can read the name file /sys/bus/iio/devices/iio:deviceX/name. In case the sequence in which the iio device drivers are loaded/registered is constant, the numbering is constant and may be known in advance.

02 Mar 2011 15:16