sys/contrib/alpine-hal/eth/al_hal_eth_kr.h

   1 /*-
   2 *******************************************************************************
   3 Copyright (C) 2015 Annapurna Labs Ltd.
   4
   5 This file may be licensed under the terms of the Annapurna Labs Commercial
   6 License Agreement.
   7
   8 Alternatively, this file can be distributed under the terms of the GNU General
   9 Public License V2 as published by the Free Software Foundation and can be
  10 found at http://www.gnu.org/licenses/gpl-2.0.html
  11
  12 Alternatively, redistribution and use in source and binary forms, with or
  13 without modification, are permitted provided that the following conditions are
  14 met:
  15
  16     *     Redistributions of source code must retain the above copyright notice,
  17 this list of conditions and the following disclaimer.
  18
  19     *     Redistributions in binary form must reproduce the above copyright
  20 notice, this list of conditions and the following disclaimer in
  21 the documentation and/or other materials provided with the
  22 distribution.
  23
  24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  25 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  26 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  27 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
  28 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  29 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  30 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  31 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  32 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34
  35 *******************************************************************************/
  36 /**
  37  * @defgroup group_eth_kr_api API
  38  * Ethernet KR auto-neg and link-training driver API
  39  * @ingroup group_eth
  40  * @{
  41  * @file   al_hal_eth_kr.h
  42  *
  43  * @brief Header file for KR driver
  44  *
  45  *
  46  */
  47
  48 #ifndef __AL_HAL_ETH_KR_H__
  49 #define __AL_HAL_ETH_KR_H__
  50
  51 #include "al_hal_eth.h"
  52
  53 /* *INDENT-OFF* */
  54 #ifdef __cplusplus
  55 extern "C" {
  56 #endif
  57 /* *INDENT-ON* */
  58
  59 /* AN (Auto-negotiation) Advertisement Registers */
  60 struct al_eth_an_adv {
  61         /* constant value defining 802.3ap support.
  62          * The suggested value is 0x01.*/
  63         uint8_t   selector_field;
  64         /* Contains arbitrary data. */
  65         uint8_t   echoed_nonce;
  66         /* pause capability. */
  67         uint8_t   capability;
  68         /* Set to 1 to indicate a Remote Fault condition.
  69          * Set to 0 to indicate normal operation.*/
  70         uint8_t   remote_fault;
  71         /* Should always be set to 0. */
  72         uint8_t   acknowledge;
  73         /* Set to 1 to indicate that the device has next pages to send.
  74          * Set to 0 to indicate that that device has no next pages to send. */
  75         uint8_t   next_page;
  76         /* Must be set to an arbitrary value.
  77          * Two devices must have a different nonce for autonegotiation to
  78          * operate (a loopback will not allow autonegotiation to complete). */
  79         uint8_t   transmitted_nonce;
  80         uint32_t  technology;
  81 #define AL_ETH_AN_TECH_1000BASE_KX  AL_BIT(0)
  82 #define AL_ETH_AN_TECH_10GBASE_KX4  AL_BIT(1)
  83 #define AL_ETH_AN_TECH_10GBASE_KR   AL_BIT(2)
  84 #define AL_ETH_AN_TECH_40GBASE_KR4  AL_BIT(3)
  85 #define AL_ETH_AN_TECH_40GBASE_CR4  AL_BIT(4)
  86 #define AL_ETH_AN_TECH_100GBASE_CR  AL_BIT(5)
  87         uint8_t   fec_capability;
  88 };
  89
  90 /* AN next page fields */
  91 struct al_eth_an_np {
  92         /* These bits can be used as message code field or unformatted code field.
  93          * When msg_page is true, these bits represent message code field.
  94          * Predefined message code field Code Field should be used as specified in the standard
  95          * 802.3ap.
  96          * For the null message code the value is 0x01.
  97          */
  98         uint16_t        unformatted_code_field;
  99         /* Flag to keep track of the state of the local device's Toggle bit.
 100          * Initial value is taken from base page. Set to 0.
 101          */
 102         al_bool         toggle;
 103         /* Acknowledge 2 is used to indicate that the receiver is able to act on the information
 104          * (or perform the task) defined in the message.
 105          */
 106         al_bool         ack2;
 107         al_bool         msg_page;
 108         /* If the device does not have any more Next Pages to send, set to AL_FALSE */
 109         al_bool         next_page;
 110         uint16_t        unformatted_code_field1;
 111         uint16_t        unformatted_code_field2;
 112 };
 113
 114 enum al_eth_kr_cl72_cstate {
 115         C72_CSTATE_NOT_UPDATED = 0,
 116         C72_CSTATE_UPDATED = 1,
 117         C72_CSTATE_MIN = 2,
 118         C72_CSTATE_MAX = 3,
 119 };
 120
 121 enum al_eth_kr_cl72_coef_op {
 122         AL_PHY_KR_COEF_UP_HOLD = 0,
 123         AL_PHY_KR_COEF_UP_INC = 1,
 124         AL_PHY_KR_COEF_UP_DEC = 2,
 125         AL_PHY_KR_COEF_UP_RESERVED = 3
 126 };
 127
 128 struct al_eth_kr_coef_up_data {
 129         enum al_eth_kr_cl72_coef_op c_zero;
 130         enum al_eth_kr_cl72_coef_op c_plus;
 131         enum al_eth_kr_cl72_coef_op c_minus;
 132         al_bool preset;
 133         al_bool initialize;
 134 };
 135
 136 struct al_eth_kr_status_report_data {
 137         enum al_eth_kr_cl72_cstate c_zero;
 138         enum al_eth_kr_cl72_cstate c_plus;
 139         enum al_eth_kr_cl72_cstate c_minus;
 140         al_bool receiver_ready;
 141 };
 142
 143 enum al_eth_an_lt_lane {
 144         AL_ETH_AN__LT_LANE_0,
 145         AL_ETH_AN__LT_LANE_1,
 146         AL_ETH_AN__LT_LANE_2,
 147         AL_ETH_AN__LT_LANE_3,
 148 };
 149
 150 /**
 151  * get the last received coefficient update message from the link partner
 152  *
 153  * @param adapter pointer to the private structure
 154  * @param lane lane number
 155  * @param lpcoeff coeff update received
 156  *
 157  */
 158 void al_eth_lp_coeff_up_get(
 159                         struct al_hal_eth_adapter *adapter,
 160                         enum al_eth_an_lt_lane lane,
 161                         struct al_eth_kr_coef_up_data *lpcoeff);
 162
 163 /**
 164  * get the last received status report message from the link partner
 165  *
 166  * @param adapter pointer to the private structure
 167  * @param lane lane number
 168  * @param status status report received
 169  *
 170  */
 171 void al_eth_lp_status_report_get(
 172                         struct al_hal_eth_adapter *adapter,
 173                         enum al_eth_an_lt_lane lane,
 174                         struct al_eth_kr_status_report_data *status);
 175
 176 /**
 177  * set the coefficient data for the next message that will be sent to lp
 178  *
 179  * @param adapter pointer to the private structure
 180  * @param lane lane number
 181  * @param ldcoeff coeff update to send
 182  *
 183  */
 184 void al_eth_ld_coeff_up_set(
 185                         struct al_hal_eth_adapter *adapter,
 186                         enum al_eth_an_lt_lane lane,
 187                         struct al_eth_kr_coef_up_data *ldcoeff);
 188
 189 /**
 190  * set the status report message for the next message that will be sent to lp
 191  *
 192  * @param adapter pointer to the private structure
 193  * @param lane lane number
 194  * @param status status report to send
 195  *
 196  */
 197 void al_eth_ld_status_report_set(
 198                         struct al_hal_eth_adapter *adapter,
 199                         enum al_eth_an_lt_lane lane,
 200                         struct al_eth_kr_status_report_data *status);
 201
 202 /**
 203  * get the receiver frame lock status
 204  *
 205  * @param adapter pointer to the private structure
 206  * @param lane lane number
 207  *
 208  * @return true if Training frame delineation is detected, otherwise false.
 209  */
 210 al_bool al_eth_kr_receiver_frame_lock_get(struct al_hal_eth_adapter *adapter,
 211                                           enum al_eth_an_lt_lane lane);
 212
 213 /**
 214  * get the start up protocol progress status
 215  *
 216  * @param adapter pointer to the private structure
 217  * @param lane lane number
 218  *
 219  * @return true if the startup protocol is in progress.
 220  */
 221 al_bool al_eth_kr_startup_proto_prog_get(struct al_hal_eth_adapter *adapter,
 222                                          enum al_eth_an_lt_lane lane);
 223
 224 /**
 225  * indicate the receiver is ready (the link training is completed)
 226  *
 227  * @param adapter pointer to the private structure
 228  * @param lane lane number
 229  *
 230  */
 231 void al_eth_receiver_ready_set(struct al_hal_eth_adapter *adapter,
 232                                enum al_eth_an_lt_lane lane);
 233
 234 /**
 235  * read Training failure status.
 236  *
 237  * @param adapter pointer to the private structure
 238  * @param lane lane number
 239  *
 240  *@return true if Training failure has been detected.
 241  */
 242 al_bool al_eth_kr_training_status_fail_get(struct al_hal_eth_adapter *adapter,
 243                                            enum al_eth_an_lt_lane lane);
 244
 245 /****************************** auto negotiation *******************************/
 246 /**
 247  * Initialize Auto-negotiation
 248  * - Program Ability Registers (Advertisement Registers)
 249  * - Clear Status latches
 250  * @param adapter pointer to the private structure
 251  * @param an_adv pointer to the AN Advertisement Registers structure
 252  *        when NULL, the registers will not be updated.
 253  *
 254  * @return 0 on success. otherwise on failure.
 255  */
 256 int al_eth_kr_an_init(struct al_hal_eth_adapter *adapter,
 257                       struct al_eth_an_adv *an_adv);
 258
 259 /**
 260  * Enable/Restart Auto-negotiation
 261  *
 262  * @param adapter pointer to the private structure
 263  * @param lane lane number
 264  * @param lt_enable initialize link training as well
 265  *
 266  * @return 0 on success. otherwise on failure.
 267  */
 268 int al_eth_kr_an_start(struct al_hal_eth_adapter *adapter,
 269                        enum al_eth_an_lt_lane lane,
 270                        al_bool next_page_enable,
 271                        al_bool lt_enable);
 272
 273
 274 int al_eth_kr_next_page_write(struct al_hal_eth_adapter *adapter,
 275                               struct al_eth_an_np *np);
 276
 277 int al_eth_kr_next_page_read(struct al_hal_eth_adapter *adapter,
 278                              struct al_eth_an_np *np);
 279
 280 /**
 281  * Stop Auto-negotiation
 282  *
 283  * Stopping the auto-negotiation will prevent the mac from sending the last page
 284  * to the link partner in case it start the AN again. It must be called after
 285  * link training is completed or the software will lose sync with the HW state
 286  * machine
 287  *
 288  * @param adapter pointer to the private structure
 289  *
 290  */
 291 void al_eth_kr_an_stop(struct al_hal_eth_adapter *adapter);
 292
 293 /**
 294  *  Check Auto-negotiation event done
 295  *
 296  * @param adapter pointer to the private structure
 297  * @param page_received Set to true if the AN page received indication is set.
 298  *                      Set to false otherwise.
 299  * @param an_completed  Set to true of the AN completed indication is set.
 300  *                      Set to false otherwise.
 301  * @param error Set to true if any error encountered
 302  *
 303  */
 304 void al_eth_kr_an_status_check(struct al_hal_eth_adapter *adapter,
 305                               al_bool *page_received,
 306                               al_bool *an_completed,
 307                               al_bool *error);
 308
 309 /**
 310  *  Read the remote auto-negotiation advertising.
 311  *  This function is safe to called after al_eth_kr_an_status_check returned
 312  *  with page_received set.
 313  *
 314  * @param adapter pointer to the private structure
 315  * @param an_adv pointer to the AN Advertisement Registers structure
 316  *
 317  */
 318 void al_eth_kr_an_read_adv(struct al_hal_eth_adapter *adapter,
 319                            struct al_eth_an_adv *an_adv);
 320
 321 /****************************** link training **********************************/
 322 /**
 323  *  Initialize Link-training.
 324  *  Clear the status register and set the local coefficient update and status
 325  *  to zero.
 326  *
 327  * @param adapter pointer to the private structure
 328  * @param lane lane number
 329  *
 330  */
 331 void al_eth_kr_lt_initialize(struct al_hal_eth_adapter *adapter,
 332                              enum al_eth_an_lt_lane lane);
 333
 334 /**
 335  * Wait for frame lock.
 336  *
 337  * @param adapter pointer to the private structure
 338  * @param lane lane number
 339  * @param timeout timeout in usec.
 340  *
 341  * @return true if frame lock received. false otherwise.
 342  */
 343 al_bool al_eth_kr_lt_frame_lock_wait(struct al_hal_eth_adapter *adapter,
 344                                      enum al_eth_an_lt_lane lane,
 345                                      uint32_t timeout);
 346
 347 /**
 348  * reset the 10GBase- KR startup protocol and begin its operation
 349  *
 350  * @param adapter pointer to the private structure
 351  * @param lane lane number
 352  *
 353  */
 354 void al_eth_kr_lt_restart(struct al_hal_eth_adapter *adapter,
 355                           enum al_eth_an_lt_lane lane);
 356
 357 /**
 358  * reset the 10GBase- KR startup protocol and end its operation
 359  *
 360  * @param adapter pointer to the private structure
 361  * @param lane lane number
 362  *
 363  */
 364 void al_eth_kr_lt_stop(struct al_hal_eth_adapter *adapter,
 365                        enum al_eth_an_lt_lane lane);
 366
 367 #ifdef __cplusplus
 368 }
 369 #endif
 370 /* *INDENT-ON* */
 371 #endif /*__AL_HAL_ETH_KR_H__*/
 372 /** @} end of Ethernet kr group */