#ifndef hal_phy_phy_h #define hal_phy_phy_h /* Cesar project {{{ * * Copyright (C) 2007 Spidcom * * <<>> * * }}} */ /** * \file hal/phy/phy.h * \brief HAL Phy public interface. * \ingroup hal_phy * * \todo Sound TX and RX. */ #include "hal/phy/access.h" #include "hal/phy/pbdma.h" #include "hal/phy/defs.h" /** * ACCESS CONFIRM event callback. * \param user user data * \return true if a DSR is requested */ typedef bool (*phy_access_conf_cb_t) (void *user); /** * RX FC event callback. * \param user user data * \param rx_date start of preamble date * \param fc_av frame control, or NULL if FCCS error * \return true if a DSR is requested */ typedef bool (*phy_rx_fc_cb_t) (void *user, u32 rx_date, const u32 *fc_av); /** * TX FALSE ALARM event callback. * \param user user data * \return true if a DSR is requested */ typedef bool (*phy_tx_false_alarm_cb_t) (void *user); /** * Zero-cross event callback. * \param user user data * \return true if a DSR is requested * * Zero-cross event happens every 20 ms (or 16,67 ms). */ typedef bool (*phy_zero_cross_cb_t) (void *user, const u32 zero_cross_date); /** * If a DSR was requested, this callback is called. * \param user user data */ typedef void (*phy_deferred_cb_t) (void *user); /** * Extra timer callback. * \param user user data * \return true if a DSR is requested */ typedef bool (*phy_extra_timer_cb_t) (void *user); BEGIN_DECLS /** * Initialise the HAL Phy. * \param user_data user data passed to any callback * \param rx_fc_cb RX FC event callback * \param access_cb ACCESS event callback * \param access_conf_cb ACCESS CONFIRM event callback * \param pbdma_cb PB DMA callback * \param tx_false_alarm_cb TX FALSE ALARM callback * \param deferred_cb DSR callback * \return the newly created context */ phy_t * phy_init (void *user_data, phy_rx_fc_cb_t rx_fc_cb, phy_access_cb_t access_cb, phy_access_conf_cb_t access_conf_cb, phy_pbdma_cb_t pbdma_cb, phy_tx_false_alarm_cb_t tx_false_alarm_cb, phy_deferred_cb_t deferred_cb); /** * Set the tone mask and its related parameters, this is a kind of * initialisation second step. * \param ctx phy context * \param tonemask tonemask data * \param carrier_nb number of active carriers in the given tone mask * * This also set ROBO modes parameters, HP1.0 mask and other tone mask related * registers. */ void phy_set_tonemask (phy_t *ctx, u32 *tonemask, uint carrier_nb); /** * Reset and uninitialise the HAL Phy. * \param ctx phy context */ void phy_uninit (phy_t *ctx); /** * Reset the hardware to a known sane state. * \param ctx phy context * * This does not reset tone mask and related parameters. */ void phy_reset (phy_t *ctx); /** * Get current date. * \param ctx phy context * \return current date */ u32 phy_date (phy_t *ctx); /** * Retrieve uncorrected current date. * \param ctx phy context * \return current uncorrected date */ u32 phy_sysdate (phy_t *ctx); /** * Set the clock correction. * \param ctx phy context * \param numerator clock correction */ void phy_clock_set_numerator (phy_t *ctx, uint numerator); /** * Get date of last zero-cross. * \param ctx phy context * \return last zero-cross date */ u32 phy_clock_get_zero_cross_captured_date (phy_t *ctx); /** * Retrieve uncorrected date of last zero-cross. * \param ctx phy context * \return last zero-cross uncorrected date */ u32 phy_clock_get_zero_cross_captured_sysdate (phy_t *ctx); /** * Transfer tone map to hardware using the TM DMA. * \param ctx phy context * \param tonemap_index tonemap index where to store tonemap * \param tonemap tonemap blocks first descriptor * * The tonemap uses two blocks. */ void phy_set_tonemap (phy_t *ctx, uint tonemap_index, blk_t *tonemap); /** * Store the STA SYS clock frequency error value relative to CCo clock in ppm, * useful for interpolation block in the DSP. * \param ctx phy context * \param rho_ppm frequency error */ void phy_sysclock_set_freqerror (phy_t *ctx, double rho_ppm); /** * Start Homeplug 1.0 frame control encoding. * \param ctx phy context * \param fc_10 Homeplug 1.0 frame control */ void phy_tx_fc10 (phy_t *ctx, u32 fc_10); /** * Set TX parameters. * \param ctx phy context * \param fc_mode frame control mode * \param short_ppdu true if no data symbols will be sent * \param mod modulation type * \param fecrate TCC rate * \param pb_size PB size * \param gil guard interval for third symbol and following symbols * \param tonemap_index tone map index * * For short PPDU, following arguments are ignored. * * When modulation type is a ROBO mode, following arguments are ignored. */ void phy_tx_param (phy_t *ctx, phy_fc_mode_t fc_mode, bool short_ppdu, phy_mod_t mod, phy_fecrate_t fecrate, phy_pb_size_t pb_size, phy_gil_t gil, uint tonemap_index); /** * Set TX parameters, shortcut for short_ppdu. * \param ctx phy context * \param fc_mode frame control mode */ extern inline void phy_tx_param_short (phy_t *ctx, phy_fc_mode_t fc_mode) { phy_tx_param (ctx, fc_mode, true, PHY_MOD_NONE, PHY_FEC_RATE_NONE, PHY_PB_SIZE_NONE, PHY_GIL_NB, 0); } /** * Schedule a TX start. * \param ctx phy context * \param date hardware date when the transmission should begin * \param want_conf request an ACCESS CONF interrupt * \param stop_tx_on_prp_lost abort TX if PRP was lost * \param fc_av frame control */ void phy_tx_frame (phy_t *ctx, u32 date, bool want_conf, bool stop_tx_on_prp_lost, const u32 fc_av[4]); /** * Set RX parameters. * \param ctx phy context * \param fc_mode frame control mode * * The new mode is used immediately. */ void phy_rx_param (phy_t *ctx, phy_fc_mode_t fc_mode); /** * Activate or deactivate preamble detection. * \param ctx phy context * \param now if true, date is ignored and change is made immediately * \param date activation date * \param flag true to activate * * A pending interrupt is not cancelled. */ void phy_rx_activate (phy_t *ctx, bool now, u32 date, bool flag); /** * Set parameter for frame payload reception. * \param ctx phy context * \param short_ppdu true if no data symbols will be received * \param mod modulation type * \param fecrate TCC rate * \param pb_size PB size * \param gil guard interval for third symbol and following symbols * \param tonemap_index tone map index * \param symbol_nb number of expected symbols * * This call signals hardware that it can continue to process the incoming * data. */ void phy_rx_prepare (phy_t *ctx, bool short_ppdu, phy_mod_t mod, phy_fecrate_t fecrate, phy_pb_size_t pb_size, phy_gil_t gil, uint tonemap_index, uint symbol_nb); /** * Set parameter for frame payload reception, shortcut for short PPDU. * \param ctx phy context * * This call signals hardware that it can continue to process the incoming * data. In the short PPDU case, it actually stops any further processing. */ extern inline void phy_rx_prepare_short (phy_t *ctx) { phy_rx_prepare (ctx, true, PHY_MOD_NONE, PHY_FEC_RATE_NONE, PHY_PB_SIZE_NONE, PHY_GIL_NB, 0, 0); } /** * Retrieve Homeplug 1.0 frame control. * \param ctx phy context * \return received Homeplug 1.0 frame control or (u32)-1 on CRC error */ u32 phy_rx_fc10 (phy_t *ctx); /** * Retrieve uncorrected date of last start of preamble. * \param ctx phy context * \return last start of preamble uncorrected date */ u32 phy_rx_sysdate (phy_t *ctx); /** * Initialise extra timer callback. * \param ctx phy context * \param extra_timer_user_data user data passed to the callback * \param extra_timer_cb extra timer callback */ void phy_extra_timer_init (phy_t *ctx, void *extra_timer_user_data, phy_extra_timer_cb_t extra_timer_cb); /** * Program the extra timer to the given date. * \param ctx phy context * \param date timer expiration date */ void phy_extra_timer_program (phy_t *ctx, u32 date); /** * Cancel the extra timer. * \param ctx phy context */ void phy_extra_timer_cancel (phy_t *ctx); /** * Initialise zero-cross callback. * \param ctx phy context * \param zero_cross_cb zero-cross callback */ void phy_zero_cross_init (phy_t *ctx, phy_zero_cross_cb_t zero_cross_cb); END_DECLS #endif /* hal_phy_phy_h */