ad9088.c File Reference

Implementation of the AD9088/AD9084 (Apollo) MxFE driver. More...

#include "ad9088.h"
#include "no_os_delay.h"
#include "no_os_alloc.h"
#include "no_os_util.h"
#include <string.h>
#include "adi_cms_api_common.h"
#include "adi_apollo_startup.h"
#include "adi_apollo_device.h"
#include "adi_apollo_mailbox.h"

Include dependency graph for ad9088.c:

Classes
struct	fw_entry

Macros
#define	INDIRECT_REG_TEST_ADDR   (0x60366045)
#define	ARM_REG_TEST_BASE_ADDR   (0x20000000U)

Functions
int	adi_ad9088_calc_nco_ftw (struct ad9088_phy *phy, uint64_t freq, int64_t nco_shift, uint32_t div, uint32_t bits, uint64_t *ftw, uint64_t *frac_a, uint64_t *frac_b)
	Convert an NCO frequency shift into a frequency tuning word.
int	adi_ad9088_calc_nco_freq (struct ad9088_phy *phy, uint64_t freq, uint64_t ftw, uint32_t a, uint32_t b, uint32_t bits, int64_t *nco_shift)
	Convert a frequency tuning word back into a frequency shift.
int	ad9088_set_cnco_freq (struct ad9088_phy *phy, adi_apollo_terminal_e terminal, uint8_t side, uint8_t cddc_num, int64_t freq_hz)
	Set the coarse NCO frequency shift.
int	ad9088_get_cnco_freq (struct ad9088_phy *phy, adi_apollo_terminal_e terminal, uint8_t side, uint8_t cddc_num, int64_t *freq_hz)
	Read back the coarse NCO frequency shift.
int	ad9088_set_fnco_freq (struct ad9088_phy *phy, adi_apollo_terminal_e terminal, uint8_t side, uint8_t fddc_num, int64_t freq_hz)
	Set the fine NCO frequency shift.
int	ad9088_get_fnco_freq (struct ad9088_phy *phy, adi_apollo_terminal_e terminal, uint8_t side, uint8_t fddc_num, int64_t *freq_hz)
	Read back the fine NCO frequency shift.
int	ad9088_check_apollo_error (int ret, const char *api_name)
	Translate a vendor API return code into an errno value.
uint8_t	ad9088_to_link (uint8_t linkid)
	Map a state-machine link identifier onto a device link identifier.
int	ad9088_inspect_jrx_link_all (struct ad9088_phy *phy)
	Print the negotiated link parameters of every deframer link.
int	ad9088_inspect_jtx_link_all (struct ad9088_phy *phy)
	Print the negotiated link parameters of every framer link.
void	ad9088_print_link_phase (struct ad9088_phy *phy, struct jesd204_link *lnk)
	Print the deframer phase difference for one link.
void	ad9088_print_sysref_phase (struct ad9088_phy *phy)
	Print the captured SYSREF phase several times over.
int	ad9088_jesd_tx_link_status_print (struct ad9088_phy *phy, struct jesd204_link *lnk, int retry)
	Poll a framer link until it reports good, then print its status.
int	ad9088_jesd_rx_link_status_print (struct ad9088_phy *phy, struct jesd204_link *lnk, int retry)
	Poll a deframer link until it reports good, then print its status.
int32_t	ad9088_log_write (void *user_data, int32_t log_type, const char *message, va_list argp)
	Vendor API callback: emit a log message.
int	ad9088_init (struct ad9088_phy **device, const struct ad9088_init_param *init_param)
	Initialize the device.
int	ad9088_remove (struct ad9088_phy *phy)
	Free the resources allocated by ad9088_init().

Variables
const char *const	ad9088_fsm_links_to_str []

Detailed Description

Implementation of the AD9088/AD9084 (Apollo) MxFE driver.

Author

CHegbeli (cipri.nosp@m.an.h.nosp@m.egbel.nosp@m.i@an.nosp@m.alog..nosp@m.com)

Copyright 2022-2026(c) Analog Devices, Inc.

SPDX-License-Identifier: BSD-3-Clause

Macro Definition Documentation

ARM_REG_TEST_BASE_ADDR

#define ARM_REG_TEST_BASE_ADDR   (0x20000000U)

INDIRECT_REG_TEST_ADDR

#define INDIRECT_REG_TEST_ADDR   (0x60366045)

Function Documentation

ad9088_check_apollo_error()

int ad9088_check_apollo_error	(	int	ret,
		const char *	api_name )

Translate a vendor API return code into an errno value.

The vendor API has its own error space and does not log, so every call site funnels through here to get the failure reported once, with the name of the call that produced it.

Parameters

ret	- Value returned by the vendor API call.
api_name	- Name of that call, used in the error message.

Returns

- 0 when the call succeeded, -EIO otherwise.

ad9088_get_cnco_freq()

int ad9088_get_cnco_freq	(	struct ad9088_phy *	phy,
		adi_apollo_terminal_e	terminal,
		uint8_t	side,
		uint8_t	cddc_num,
		int64_t *	freq_hz )

Read back the coarse NCO frequency shift.

Parameters

phy	- The device structure.
terminal	- Selects the transmit or receive datapath.
side	- Datapath side index.
cddc_num	- Coarse datapath index within the side.
freq_hz	- Signed frequency shift, in Hz.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_get_fnco_freq()

int ad9088_get_fnco_freq	(	struct ad9088_phy *	phy,
		adi_apollo_terminal_e	terminal,
		uint8_t	side,
		uint8_t	fddc_num,
		int64_t *	freq_hz )

Read back the fine NCO frequency shift.

Parameters

phy	- The device structure.
terminal	- Selects the transmit or receive datapath.
side	- Datapath side index.
fddc_num	- Fine datapath index within the side.
freq_hz	- Signed frequency shift, in Hz.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_init()

int ad9088_init	(	struct ad9088_phy **	device,
		const struct ad9088_init_param *	init_param )

Initialize the device.

Allocates the device structure, wires up the vendor API to the SPI and GPIO descriptors, verifies the buses, loads the firmware and device profile, and registers the device with the JESD204 state machine. The links themselves are brought up by that state machine, not here.

Parameters

device	- The device structure.
init_param	- The structure that contains the device initialisation parameters.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_inspect_jrx_link_all()

int ad9088_inspect_jrx_link_all

(

struct ad9088_phy *

phy

)

Print the negotiated link parameters of every deframer link.

Reports what the device ended up with rather than what was requested, so it can be compared against the peer side.

Parameters

phy	- The device structure.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_inspect_jtx_link_all()

int ad9088_inspect_jtx_link_all

(

struct ad9088_phy *

phy

)

Print the negotiated link parameters of every framer link.

Reports what the device ended up with rather than what was requested, so it can be compared against the peer side.

Parameters

phy	- The device structure.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_jesd_rx_link_status_print()

int ad9088_jesd_rx_link_status_print	(	struct ad9088_phy *	phy,
		struct jesd204_link *	lnk,
		int	retry )

Poll a deframer link until it reports good, then print its status.

Which status bits have to be set depends on the JESD204 version and, for subclass 1, additionally on the SYSREF phase having locked. Per-lane state is printed alongside the link state so a single bad lane is visible.

Parameters

phy	- The device structure.
lnk	- The JESD204 link.
retry	- Number of extra attempts before giving up.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_jesd_tx_link_status_print()

int ad9088_jesd_tx_link_status_print	(	struct ad9088_phy *	phy,
		struct jesd204_link *	lnk,
		int	retry )

Poll a framer link until it reports good, then print its status.

Which status bits have to be set depends on the JESD204 version in use. The status is only printed once settled, or on the final attempt, so a link that comes up normally logs a single line.

Parameters

phy	- The device structure.
lnk	- The JESD204 link.
retry	- Number of extra attempts before giving up.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_log_write()

int32_t ad9088_log_write	(	void *	user_data,
		int32_t	log_type,
		const char *	message,
		va_list	argp )

Vendor API callback: emit a log message.

Maps the vendor severity onto the local log levels. Register-level tracing is dropped before formatting, since it is high volume and the format cost would be paid even when the message is discarded.

Parameters

user_data	- The device structure, unused.
log_type	- Vendor log severity.
message	- Format string.
argp	- Arguments for the format string.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_print_link_phase()

void ad9088_print_link_phase	(	struct ad9088_phy *	phy,
		struct jesd204_link *	lnk )

Print the deframer phase difference for one link.

Parameters

phy	- The device structure.
lnk	- The JESD204 link.

ad9088_print_sysref_phase()

void ad9088_print_sysref_phase

(

struct ad9088_phy *

phy

)

Print the captured SYSREF phase several times over.

The value is a signed count of device clock periods between the external and internal SYSREF edges. It is sampled repeatedly because a phase that moves between reads means the capture is not deterministic, which a single read would hide.

Parameters

phy	- The device structure.

ad9088_remove()

int ad9088_remove

(

struct ad9088_phy *

phy

)

Free the resources allocated by ad9088_init().

Parameters

phy	- The device structure.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_set_cnco_freq()

int ad9088_set_cnco_freq	(	struct ad9088_phy *	phy,
		adi_apollo_terminal_e	terminal,
		uint8_t	side,
		uint8_t	cddc_num,
		int64_t	freq_hz )

Set the coarse NCO frequency shift.

Parameters

phy	- The device structure.
terminal	- Selects the transmit or receive datapath.
side	- Datapath side index.
cddc_num	- Coarse datapath index within the side.
freq_hz	- Signed frequency shift, in Hz.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_set_fnco_freq()

int ad9088_set_fnco_freq	(	struct ad9088_phy *	phy,
		adi_apollo_terminal_e	terminal,
		uint8_t	side,
		uint8_t	fddc_num,
		int64_t	freq_hz )

Set the fine NCO frequency shift.

Parameters

phy	- The device structure.
terminal	- Selects the transmit or receive datapath.
side	- Datapath side index.
fddc_num	- Fine datapath index within the side.
freq_hz	- Signed frequency shift, in Hz.

Returns

- 0 in case of success, negative error code otherwise.

ad9088_to_link()

uint8_t ad9088_to_link

(

uint8_t

linkid

)

Map a state-machine link identifier onto a device link identifier.

The state machine numbers the transmit and receive links in one sequence, while the device numbers each direction from zero, so the two halves of the range fold onto the same device identifiers.

Parameters

linkid

- State-machine link identifier.

Returns

- The corresponding device link identifier.

adi_ad9088_calc_nco_freq()

int adi_ad9088_calc_nco_freq	(	struct ad9088_phy *	phy,
		uint64_t	freq,
		uint64_t	ftw,
		uint32_t	a,
		uint32_t	b,
		uint32_t	bits,
		int64_t *	nco_shift )

Convert a frequency tuning word back into a frequency shift.

The inverse of adi_ad9088_calc_nco_ftw(). Tuning words in the upper half of the accumulator range encode a negative shift.

Parameters

phy	- The device structure.
freq	- NCO clock rate, in Hz.
ftw	- Integer frequency tuning word.
a	- Numerator of the fractional part.
b	- Denominator of the fractional part.
bits	- Accumulator width of the source NCO, in bits.
nco_shift	- Decoded signed frequency shift, in Hz.

Returns

- 0 in case of success, negative error code otherwise.

adi_ad9088_calc_nco_ftw()

int adi_ad9088_calc_nco_ftw	(	struct ad9088_phy *	phy,
		uint64_t	freq,
		int64_t	nco_shift,
		uint32_t	div,
		uint32_t	bits,
		uint64_t *	ftw,
		uint64_t *	frac_a,
		uint64_t *	frac_b )

Convert an NCO frequency shift into a frequency tuning word.

The tuning word is the shift expressed as a fraction of the NCO clock, scaled to the accumulator width. Whatever the integer word cannot express is returned as the fraction frac_a / frac_b, which the dual-modulus modes use to reach an exact shift.

Parameters

phy	- The device structure.
freq	- Converter sample rate, in Hz.
nco_shift	- Signed frequency shift to encode, in Hz.
div	- Decimation or interpolation ratio between the converter and the NCO, so that freq / div is the NCO clock.
bits	- Accumulator width of the target NCO, in bits.
ftw	- Integer frequency tuning word.
frac_a	- Numerator of the leftover fraction.
frac_b	- Denominator of the leftover fraction.

Returns

- 0 in case of success, negative error code otherwise.

Variable Documentation

ad9088_fsm_links_to_str

const char* const ad9088_fsm_links_to_str[]

Initial value:

= {
    [DEFRAMER_LINK_A0_TX] = "JESD TX (JRX Deframer Link A0)",
    [DEFRAMER_LINK_A1_TX] = "JESD TX (JRX Deframer Link A1)",
    [DEFRAMER_LINK_B0_TX] = "JESD TX (JRX Deframer Link B0)",
    [DEFRAMER_LINK_B1_TX] = "JESD TX (JRX Deframer Link B1)",
    [FRAMER_LINK_A0_RX] = "JESD RX (JTX Framer Link A0)",
    [FRAMER_LINK_A1_RX] = "JESD RX (JTX Framer Link A1)",
    [FRAMER_LINK_B0_RX] = "JESD RX (JTX Framer Link B0)",
    [FRAMER_LINK_B1_RX] = "JESD RX (JTX Framer Link B1)",
}