Difference between revisions of "Si5338 driver"

Revision as of 18:05, 15 December 2013

The drivers/misc/si5338.c driver allows real-time control of the Silicon Labs si5338 Clock Generator using Linux sysfs interface. It also allows setting up parameters using the Device Tree.

It is also possible to use the register map file generated by Silicon Labs software, converted by a Python script to a Device Tree fragment (or fed to the driver using sysfs interface).

Reference Documentation

This driver is developed using excellent documentation provided by the chip manufacturer: [1] - detailed description of the device registers [2] - overall chip documentation including configuration procedure

sysfs interface

top level files

outputs (read only)

Provides information about each of the 4 outputs, like in the example below:

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat outputs
0: 1V5_HSTL_A+, output frequency: 15000000 Hz, output route: MS0:1, ms_power_up, disabled state: dis_hi-z, output_power_up, output_en, Spread spectrum is ON, down amplitude= 500 ( *0.01%), spread rate= 31500 Hz
1: 2V5_LVPECL, output frequency: 0 Hz, output route: No clock, disabled state: dis_hi-z, output_power_down, output_en, Spread spectrum is OFF, down amplitude= 50 ( *0.01%), spread rate= 31500 Hz
2: 2V5_LVPECL, output frequency: 0 Hz, output route: No clock, disabled state: dis_hi-z, output_power_down, output_en, Spread spectrum is OFF, down amplitude= 50 ( *0.01%), spread rate= 31500 Hz
3: 1V8_LVDS, output frequency: 150000000 Hz, output route: MS3:1, ms_power_up, disabled state: dis_hi-z, output_power_up, output_en, Spread spectrum is ON, down amplitude= 50 ( *0.01%), spread rate= 31500 Hz

This includes:

• output voltage (1V5 - 1.5V)
• standard (HSTL)
• output inversion for of the 2 paired outputs in single-ended mode ("A+B-" A positive, B - inverted; "A+" - output B is disabled)
• output frequency
• output route - each output can be fed from multiple sources, for example "IN3:2:8" means signal from input 3 divided by 2 in the input stage and by 8 in the output stage. "MS0:1" means that output is connected to the MultiSynth output 0 with no divider
• disable state - low, high, hi-z or always on - state of the output pin when it is disabled
• output stage (and divider) power up/down state
• output enable/disable state (all outputs can be independently disabled by the global output disable)
• spread spectrum: on/off state, amplitude (in 0.01% of the output frequency steps) and the sweep rate. Only down spread is supported, so the center frequency is half-amplitude less than with spread spectrum disabled

status (read only)

Read and interpret status register.

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat status
0x8 input clock: OK, feedback clock: LOST, PLL lock: OK, calibration: DONE

pre_init (write only)

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "0" > pre_init

Disables all outputs, loss of lock signal before setting parameters and initializing PLL

pre_init_clear (write only)

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "0" > pre_init_clear

Same as pre_init, but additionally clears all output routes and input multiplexers before setting up the needed ones

post_init (write only)

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "0" > post_init

Initializes and calibrates PLL - should be called after the PLL parameters (or the whole frequency plan) are set up.

input/ folder

input/in_frequency12

input/in_frequency12xo

input/in_frequency3

input/in_frequency4

input/in_frequency56

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "25000000" > input/in_frequency3
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/in_frequency3
25000000

Set the input frequency applied to one of the differential input pairs (12, 56) or single-ended (3,4). "in_frequency12xo: is used to specify the frequency of the crystal connected between inputs 1 and 2. While the driver tries to make as little assumptions as possible and reads data from the si5338 registers (or actually from their cached shadows), the input frequency has to be stored off-chip and may be needed to be set up if you plan to use high-level functions to change frequency parameters even if the registers where initialized from the pre-calculated register map. Each write to these nodes also programs the input multiplexers and routes the specified pin (pin pair) to the PLL reference input, so if there are several active inputs, the last specified input will be routed.

input/in_mux

input/ref_mux

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "1" input/in_mux
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/in_mux
1

Directly control in input and feedback multiplexers

input/in_mux_txt (read only)

input/ref_mux_txt (read only)

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/in_mux_txt 
IN3(single ended)

Interpret the state of the input and feedback multiplexers

input/in_p1_div

input/in_p2_div

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "32" > input/in_p1_div
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/in_p1_div
32

Read/write input dividers, valid values are 1,2,4,8,16 and 32

input/in_pfd_ref

input/in_pfd_fb

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "0" > input/in_pfd_ref
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/in_pfd_ref
0

Read/write PLL reference and feedback multiplexers selections. The feedback input can be switched to the output of the feedback multiplexer from the MSn MultiSynth output with the "input/fb_external".

input/in_pfd_ref_txt (read only)

input/in_pfd_fb_txt (read only)

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/in_pfd_ref_txt
p1div_in(refclk)

Read and interpret the state of the reference and feedback multiplexers.

input/fb_external

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "0" > input/fb_external
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/fb_external
0

Switch between internal PLL feedback from the MSn divider (0) and the external input (1). The external feedback can be used in the zero-delay buffer mode, most applications use internal feedback mode.

input/xtal_freq_txt (read only)

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/xtal_freq_txt
26MHz..30Mhz

Read crystal oscillator mode settings. Appropriate settings are selected by writing to "input/in_frequency12xo" or loading the register map prepared by the Silicon Labs software.

input/pll_ref_frequency (read only)

input/pll_fb_frequency (read only)

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/pll_ref_frequency
25000000
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat input/pll_fb_frequency
0

Read reference and feedback frequency values. Determined by the input frequency settings, dividers and multiplexers.

pll/ folder

VCO frequency (use in PLL) can be set up either directly, or to match specified output frequency (one of the 4 channels). The valid range is 2.2GHz to 2.84GHz (2200000000 to 2840000000). Frequencies are specified in Hz with possible fractional part (numerator then denominator), so "2550000000 0 1" is the same as just "2550000000". In both cases "_int" and "_fract" applies to the feedback divider, the lowest jitter is achieved with integer dividers. Reading any of these nodes return the PLL frequency in Hz. "pll/pll_freq_int" is the most common option to use.

pll/pll_freq_int

Specify VCO frequency in HZ, require integer divider. Read VCO frequency in Hz.

pll/pll_freq_fract

Specify VCO frequency in HZ, allow fractional divider. Read VCO frequency in Hz.

pll/pll_by_out_int

Match VCO frequency to the required output frequency in HZ, require integer divider in both feedback and output dividers. Read VCO frequency in Hz.

pll/pll_by_out_fract

Match VCO frequency to the required output frequency in HZ, allow fractional feedback (MSn) divider. Read VCO frequency in Hz.

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat pll/pll_by_out_int
2550000000 0 1

multiSynth/ folder

The si5338 chip uses 5 "multiSynth" fractional dividers - 4 of them (MS0..MS3) are used for the output frequencies generations, and the fifth one (MSn) is used as the PLL feeback divider. This subdirectory allows low-level control of these dividers - in most cases they can be set up indirectly by specifying the required frequencies.

multiSynth/ms0_p123

multiSynth/ms1_p123

multiSynth/ms2_p123

multiSynth/ms3_p123

multiSynth/msn_p123

Read/write a set of 3 registers as defined in the Reference Manual (P1, P2 and P3):

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "21248 0 1" multiSynth/ms0_p123
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat multiSynth/ms0_p123
21248 0 1

multiSynth/ms0_abc

multiSynth/ms1_abc

multiSynth/ms2_abc

multiSynth/ms3_abc

multiSynth/msn_abc

Read/write MultiSynth dividers using integer part, numerator and denominator (a,b and c) as referenced in the manual

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat multiSynth/ms0_abc
170 0 1

multiSynth/ms0_freq_int

multiSynth/ms0_freq_fract

multiSynth/ms1_freq_int

multiSynth/ms1_freq_fract

multiSynth/ms2_freq_int

multiSynth/ms2_freq_fract

multiSynth/ms3_freq_int

multiSynth/ms3_freq_fract

Setting integer/fractional MultiSynth dividers by the required output frequency (single integer or 3 numbers - integer, numerator and denominator). Reading back provides actual value of the frequency.

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat multiSynth/ms0_freq_int
15000000 0 1

multiSynth/ms_power_up

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "0 3" > multiSynth/ms_power_up
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat multiSynth/ms_power_up
0 3

Power up selected channels, read returns the list of the powered up channels

multiSynth/ms_power_down

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "1 2" > multiSynth/ms_power_down
root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat multiSynth/ms_power_down
1 2

Power down selected channels, read returns the list of the powered down channels

multiSynth/ms_reset

Reset multiSynth dividers (not clear when exactly they should be reset - possibly after spread spectrum changes).

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# echo "0" > multiSynth/ms_reset

root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# ls -all output_clocks/ drwxr-xr-x 2 root root 0 Dec 12 02:30 . drwxr-xr-x 10 root root 0 Dec 12 00:36 .. -rw-r--r-- 1 root root 4096 Dec 12 02:30 out0_div --w------- 1 root root 4096 Dec 12 02:30 out0_div_by_freq -rw-r--r-- 1 root root 4096 Dec 12 02:30 out0_freq_fract -rw-r--r-- 1 root root 4096 Dec 12 02:30 out0_freq_int -rw-r--r-- 1 root root 4096 Dec 12 02:30 out0_route -rw-r--r-- 1 root root 4096 Dec 12 02:30 out0_source -r--r--r-- 1 root root 4096 Dec 12 02:30 out0_source_freq -r--r--r-- 1 root root 4096 Dec 12 02:30 out0_source_txt -rw-r--r-- 1 root root 4096 Dec 12 02:30 out1_div --w------- 1 root root 4096 Dec 12 02:30 out1_div_by_freq -rw-r--r-- 1 root root 4096 Dec 12 02:30 out1_freq_fract -rw-r--r-- 1 root root 4096 Dec 12 02:30 out1_freq_int -rw-r--r-- 1 root root 4096 Dec 12 02:30 out1_route -rw-r--r-- 1 root root 4096 Dec 12 02:30 out1_source -r--r--r-- 1 root root 4096 Dec 12 02:30 out1_source_freq -r--r--r-- 1 root root 4096 Dec 12 02:30 out1_source_txt -rw-r--r-- 1 root root 4096 Dec 12 02:30 out2_div --w------- 1 root root 4096 Dec 12 02:30 out2_div_by_freq -rw-r--r-- 1 root root 4096 Dec 12 02:30 out2_freq_fract -rw-r--r-- 1 root root 4096 Dec 12 02:30 out2_freq_int -rw-r--r-- 1 root root 4096 Dec 12 02:30 out2_route -rw-r--r-- 1 root root 4096 Dec 12 02:30 out2_source -r--r--r-- 1 root root 4096 Dec 12 02:30 out2_source_freq -r--r--r-- 1 root root 4096 Dec 12 02:30 out2_source_txt -rw-r--r-- 1 root root 4096 Dec 12 02:30 out3_div --w------- 1 root root 4096 Dec 12 02:30 out3_div_by_freq -rw-r--r-- 1 root root 4096 Dec 12 02:30 out3_freq_fract -rw-r--r-- 1 root root 4096 Dec 12 02:30 out3_freq_int -rw-r--r-- 1 root root 4096 Dec 12 02:30 out3_route -rw-r--r-- 1 root root 4096 Dec 12 02:30 out3_source -r--r--r-- 1 root root 4096 Dec 12 02:30 out3_source_freq -r--r--r-- 1 root root 4096 Dec 12 02:30 out3_source_txt root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat output_clocks/out0_div 1 root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat output_clocks/out0_freq_int 15000000 0 1 root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat output_clocks/out0_source 6 root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat output_clocks/out0_source_txt MS0 root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat output_clocks/out0_source_freq 15000000 0 1 root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# cat output_clocks/out0_route MS0:1 root@elphel393:/sys/devices/amba.0/e0004000.ps7-i2c/i2c-0/0-0070# Broadcast message from root@elphel393 (ttyPS0) (Thu Dec 12 05:03:33 2013): The system is going down for reboot NOW! Connection to 192.168.0.8 closed by remote host. Connection to 192.168.0.8 closed.