TheRock/rocm-systems/projects/amdsmi/include/ualoe_lib/ualoe_lib.h

/*
 * Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */

#ifndef UALOE_LIB_H
#define UALOE_LIB_H

#include <stdbool.h>
#include <stdint.h>
#include <time.h>

#include "ifoe_telemetry_hostapp.h"
#include "ualoe_mcdi_defs.h"

/* UALoE library source compatibility version. This is incremented
 * whenever a definition is added, removed or changed such that a
 * client might need to guard its use with a compile-time check.
 */
#define UALOE_LIB_VERSION_MAJOR 0
#define UALOE_LIB_VERSION_MINOR 1
#define UALOE_LIB_VERSION_PATCH 0

/* ----------------- */
/* Types and Defines */
/* ----------------- */

/** Handle of an UALoE driver instance */
typedef int ualoe_handle_t;

/** Size of an IFoE textual label */
#define UALOE_LABEL_SIZE (32)

/** Maximum number of Network Ports per IFoE Station */
#define UALOE_MAX_NETPORTS_PER_IFOE_STATION (4)

/** Defines size of a crypto key */
#define UALOE_CRYPTO_KEY_SIZE (8)

/** Size of a MAC address */
#define UALOE_MAC_ADDRESS_SIZE (6)

/** Maximum number of pings supported per path for the L2Ping mechanism */
#define UALOE_L2PING_MAX_PINGS (255)

/** Enum defining different configuration phases for UALoE. Note that UALoE
 * enforces a strict order of phases
 *
 *        System -> Provider -> Tenant -> Showtime
 *                    \
 *                     \-> Diagnostics
 *
 * The only transitions permitted are to the next phase via an explicit
 * call to ualoe_next_config_phase() or by an entity reset which will
 * reset back to the Provider or Tenant configuration phase, depending
 * on whether a handle to the PF or VF is being used
 *
 * Additionally a diagnostics mode is supported to allow offline diagnostics
 * tests to be carried out e.g. Network Port PRBS. A PF FLR or entity reset
 * will reset back to the Provider configuration phase.
 *
 * System
 * ------
 * After the UALoE firmware boots, it will enter this phase waiting for the
 * UALoE station and network configuration. This configuration is provided by the
 * SoC before the host OS boots to allow IFoE to bring up and train the Network
 * Ports and therefore the host driver should not expect to ever see IFoE in
 * this state.
 *
 * Provider
 * --------
 * After the System configuration completes the firmware is in this state
 * waiting for the Provider to configure the IFoE datapath. This configuration
 * is provided from the AI Fabric Manager via the host kernel driver.
 * Configuration that the Provider should perform via the PF...
 *   ualoe_set_identity()
 *   ualoe_set_accelerator_config()
 *   ualoe_set_ifoe_config()
 *   ifoe_netport_set_accelerator_addr_map()
 *   ifoe_netport_set_addr()
 *
 * Tenant
 * ------
 * After the core Provider configuration is complete, the firmware enters this
 * state waiting to receive the Tenant configuration. Configuration that the
 * Tenant should perform via the VF in virtualized mode of via the PF in Bare
 * Metal mode...
 *   ualoe_config_crypto()
 *   ualoe_enable_accelerators()
 *
 * Showtime
 * --------
 * Configuration is complete and the UALoE datapath is active.
 *
 * Diagnostics
 * -----
 * Offline diagnostics mode
 */
typedef enum ualoe_config_phase {
  UALOE_CONFIG_PHASE_SYSTEM,
  UALOE_CONFIG_PHASE_PROVIDER,
  UALOE_CONFIG_PHASE_TENANT,
  UALOE_CONFIG_PHASE_SHOWTIME,
  UALOE_CONFIG_PHASE_DIAGNOSTICS
} ualoe_config_phase_e;

/** For the client there are 2 roles defined: Provider and Tenant.
 * The Provider is responsible for configuring the IFoE datapath, including
 * setting the set of the accelerators in the vpod, which of these is local
 * and configuring various global settings. The Tenant is responsible for
 * configuring encryption (if required), validating the Provider configuration,
 * enabling communications with remote accelerators and transitioning the
 * datapath to showtime.
 *
 * ifoe_virt_mode_e defines the virtualization mode in which IFoE is operating.
 * This controls whether IFoE is operating with a host hypervisor (PF) and
 * guest (VM) or in baremetal mode using the PF only.
 * In virtualized mode, the PF has the role of Provider and VF has the role of
 * Tenant. In bare-metal mode, the PF has both the role of Provider and Tenant
 * and the VF is not used.
 */
typedef enum ifoe_virt_mode {
  IFOE_VIRT_MODE_VIRTUALIZED,
  IFOE_VIRT_MODE_BARE_METAL
} ifoe_virt_mode_e;

/** Enum defining the encapsulation mode that will be used for IFoE traffic */
typedef enum ifoe_encap_type {
  IFOE_ENCAP_TYPE_ETHERNET,
  IFOE_ENCAP_TYPE_TF1,
  IFOE_ENCAP_TYPE_IP
} ifoe_encap_type_e;

/** Enum defining the failover mode that should be used
 *
 * When failover is disabled and a retransmission timeout occurs for an IFoE
 * stream, the stream will be paused and the caller notified. It is the
 * responsibility of the client to take action before the failed memory
 * transaction times out.
 *
 * When failover is enabled and a retransmission timeout occurs for an IFoE
 * stream, the firmware will remap the path for the failed stream to a
 * different network port (if possible) and notify the caller that a failover
 * has occurred. If a remap is not possible, for example because the device is
 * operating in 800G port mode, then the caller will simply be notified that
 * a stream has failed.
 */
typedef enum ifoe_failover_mode {
  IFOE_FAILOVER_DISABLED,
  IFOE_FAILOVER_ENABLED
} ifoe_failover_mode_e;

/** Enum defining the loopback modes for IFoE */
typedef enum ifoe_loopback_mode {
  IFOE_LOOPBACK_OFF,
  IFOE_LOOPBACK_IFOE,
  IFOE_LOOPBACK_IFOE_PRE_MAC
} ifoe_loopback_mode_e;

/** Enum defining the encryption mode to be used for UALoE traffic */
typedef enum ualoe_crypto_mode {
  UALOE_CRYPTO_MODE_OFF,
  UALOE_CRYPTO_MODE_AES_GCM_256
} ualoe_crypto_mode_e;

/** Enum used to specify the encryption key ID used for UALoE traffic */
typedef enum ualoe_crypto_key_id {
  UALOE_CRYPTO_KEY_ID_0,
  UALOE_CRYPTO_KEY_ID_1
} ualoe_crypto_key_id_e;

/** Enum defining the state of an IFoE Station */
typedef enum ifoe_station_state {
  /** In this state a station is disabled and Network Ports owned by the IFoE
   * station will be powered off */
  IFOE_STATION_DISABLED,
  /** In this state, the IFoE station is in a state where the datapath is not
   * not active and traffic originating from both SDP and the network will be
   * dropped. */
  IFOE_STATION_STOPPED,
  /** In this state, the IFoE datapath is enabled with traffic flow enabled
   * in both directions */
  IFOE_STATION_ACTIVE
} ifoe_station_state_e;

/** Enum defining the state of a Network Port */
typedef enum ifoe_netport_state {
  /** In this state the network port is disabled and powered off */
  IFOE_NETPORT_POWEROFF,
  /** In this state, the Network Port is in an idle state, powered on
   * but not being used for IFoE traffic flow */
  IFOE_NETPORT_IDLE,
  /** In this state, the network port is enabled for IFoE traffic */
  IFOE_NETPORT_ENABLED
} ifoe_netport_state_e;

/** Structure defining an UALoE version. Follows semantic versioning. */
typedef struct ualoe_version_s {
  uint32_t major;
  uint32_t minor;
  uint32_t patch;
} ualoe_version_t;

/** Structure defining a textual label. Labels must be null terminated */
typedef struct ualoe_label_s {
  char text[UALOE_LABEL_SIZE];
} ualoe_label_t;

/** Structure defining UALoE device capabilities */
typedef struct ualoe_capabilities_s {
  /** Number of IFoE Stations configured for use */
  unsigned num_configured_stations;
  /** Number of accelerators supported by the device */
  unsigned max_accelerators;
  /** Number of Network Ports configured for each IFoE Station */
  unsigned num_netports_per_station;
  /** Number of IFoE Paths configured for each IFoE station */
  unsigned num_paths_per_station;
} ualoe_capabilities_t;

/** Structure to hold an encryption/decryption key */
typedef struct ualoe_crypto_key_s {
  uint32_t key[UALOE_CRYPTO_KEY_SIZE];
} ualoe_crypto_key_t;

/** Flags indicating items that have been configured by a client (as opposed
 * to being at the firmware default)
 */
#define IFOE_ACCELERATOR_ID_CONFIGURED (1 << 0)
#define IFOE_VIRT_MODE_CONFIGURED (1 << 2)
#define IFOE_ENCAP_MODE_CONFIGURED (1 << 3)
#define IFOE_FAILOVER_MODE_CONFIGURED (1 << 4)
#define IFOE_CRYPTO_MODE_CONFIGURED (1 << 5)
#define IFOE_LOOPBACK_MODE_CONFIGURED (1 << 6)
#define IFOE_ACTIVE_ACCELERATORS_CONFIGURED (1 << 7)
#define IFOE_LOCAL_ACCELERATORS_CONFIGURED (1 << 8)
#define IFOE_ENABLED_ACCELERATORS_CONFIGURED (1 << 9)

/** Structure defining the global IFoE configuration */
typedef struct ifoe_config_s {
  /** Status flags indicating what has been configured by a client. If clear,
   * this means that the configuration is currently the firmware default. Note
   * that if an item has been configured by a client, whether this was by the
   * Provider or by the Tenant, the flag will be set even if the configuration
   * item matches the firmware default. */
  unsigned configured_flags;
  /** The GPU accelerator ID of the GPU connected to this IFoE system. The
   * firmware default when unconfigured and/or following a PF FLR is 0. */
  unsigned accelerator_id;
  /** Current IFoE configuration phase. When unconfigured and/or following
   * a PF FLR, this will be UALOE_CONFIG_PHASE_PROVIDER. */
  ualoe_config_phase_e current_phase;
  /** Virtualization mode. When unconfigured and/or following a PF FLR,
   * this will be IFOE_VIRT_MODE_VIRTUALIZED. */
  ifoe_virt_mode_e virt_mode;
  /** Encapsulation mode. When unconfigured and/or following a PF FLR, this
   * will be IFOE_ENCAP_TYPE_ETHERNET. */
  ifoe_encap_type_e encap_mode;
  /** Failover mode. When unconfigured and/or following a PF FLR, this will
   * be IFOE_FAILOVER_ENABLED. */
  ifoe_failover_mode_e failover_mode;
  /** Encryption mode. When unconfigured and/or following a PF FLR, this
   * will be UALOE_CRYPTO_MODE_OFF. */
  ualoe_crypto_mode_e crypto_mode;
  /** Loopback mode */
  ifoe_loopback_mode_e loopback_mode;
} ifoe_config_t;

/** Structure defining an IFoE Station descriptor */
typedef struct ifoe_station_desc_s {
  /** Label of IFoE station */
  ualoe_label_t name;
  /** Logical index of the IFoE Station within the device. Logical indices are
   * numbered sequentially from zero. */
  unsigned logical_idx;
  /** Physical index of the IFoE Station within the device */
  unsigned physical_idx;
} ifoe_station_desc_t;

/** Structure defining the state of an IFoE Station
 *
 * The set of IFoE Stations is configured in the BIOS and will be set before
 * IFoE transitions to the Provider configuration phase. The initial state of
 * each IFoE Station at the start of the Provider phase is as follows:
 *   .state = IFOE_STATION_ACTIVE
 *   .dx_isolated = FALSE
 *   .netports[].fault = FALSE
 *   .netports[].streams_failover = 0
 *   .netports[].streams_paused = 0
 * The value of other fields depends on the station instance and the state of
 * the underlying network ports.
 */
typedef struct ifoe_station_state_s {
  /** IFoE Station state */
  ifoe_station_state_e state;
  /** An IFoE Station Logical Link represents the network link provided by the
   * set of underlying physical network ports. This boolean indicates that the
   * logical link is down. It will only be true if _all_ the underlying network
   * ports are down and traffic flow to the ethernet network is not possible. */
  bool link_down;
  /** Boolean indicating that that datapath interface between IFoE and data
   * fabric is isolated i.e. no data flow is disabled in both directions. */
  bool dx_isolated;
  /** Bandwidth of the IFoE logical link in Gbits/s. If the logical link
   * is degraded due to an issue with one of the underlying Network Ports,
   * this bandwidth will be reduced. */
  unsigned bandwidth;
  /** Logical index of the IFoE Station within the device. Logical indices are
   * numbered sequentially from zero. */
  unsigned logical_idx;
  /** Physical index of the IFoE Station within the device */
  unsigned physical_idx;
  /** Number of Network Port structures populated */
  unsigned netport_count;
  /** Array of Network Port information */
  struct {
    /** Logical index of the network port */
    unsigned logical_idx;
    /** When true, indicates that there is a fault on the network port. */
    bool fault;
    /** Count of number of streams currently in a failover state which have been
     * remapped to an alternative Network Port. */
    unsigned streams_failover;
    /** Count of number of streams currently in a paused state due to a
     * retransmission timeout where failover was either not possible or
     * disabled. */
    unsigned streams_paused;
  } netports[UALOE_MAX_NETPORTS_PER_IFOE_STATION];
} ifoe_station_state_t;

/** Structure defining Network Port properties */
typedef struct ualoe_netport_properties_s {
  /** Bitmask of ethernet technologies supported (see UALOE_ETH_TECH_MASK) */
  __uint128_t eth_tech_mask;
  /** Bitmask of FEC modes supported (see UALOE_FEC_MODE_MASK) */
  uint32_t fec_modes;
  /** Number of serdes lanes used in the configured port mode */
  unsigned num_lanes;
  /** Bitmask of loopback modes supported (see UALOE_NETPORT_LOOPBACK_MASK) */
  uint64_t loopback_modes;
  /** Maximum frame length supported */
  unsigned max_frame_len;
} ualoe_netport_properties_t;

/** Structure defining an Network Port descriptor */
typedef struct ifoe_netport_desc_s {
  /** Label of Network Port */
  ualoe_label_t name;
  /** Logical index of the Network Port */
  unsigned logical_idx;
  /** IFoE Station that Network Port is part of */
  ualoe_label_t station_name;
  /** Logical index of the IFoE Station */
  unsigned station_idx;
  /** Station-relative index for this Network Port. Within each IFoE station
   * Network Ports are numbered sequentially from zero. */
  unsigned station_rel_netport_idx;
} ifoe_netport_desc_t;

/** Structure containing the state of a Network Port
 *
 * The set of Network Ports is configured in the BIOS based on the port mode
 * and the number of configured IFoE stations and will be set before IFoE
 * transitions to the Provider configuration phase. The initial state of each
 * Network Port at the start of the Provider phase is as follows:
 *   .state = IFOE_NETPORT_ENABLED
 *   .autoneg_enabled = TRUE
 *   .parallel_detect_enabled = TRUE
 *   .loopback_mode = UALOE_NETPORT_LOOPBACK_NONE
 * The value of other fields depends on the network port link status and
 * the link technology and FEC mode negotiated with the link partner.
 */
typedef struct ifoe_netport_state_s {
  /** Network Port state */
  ifoe_netport_state_e state;
  /** Boolean indicating whether Auto-Negotiation is enabled */
  bool autoneg_enabled;
  /** Boolean indicating whether Parallel-Detect is enabled */
  bool parallel_detect_enabled;
  /** Network Port link status flags. For the definition of the flags, refer
   * to the defines UALOE_NETPORT_STATUS_FLAG_* in ualoe_mcdi_defs.h. */
  uint64_t link_flags;
  /** Configured link technology */
  ualoe_eth_tech_e link_technology;
  /** FEC mode in use */
  ualoe_fec_mode_e fec_mode;
  /** Loopback mode */
  ualoe_netport_loopback_mode_e loopback_mode;
  /** MAC address configured for IFoE traffic */
  uint8_t ifoe_mac_addr[UALOE_MAC_ADDRESS_SIZE];
  /** Permanent MAC address assigned to this Network Port. This can be used for
   * non-IFoE traffic. */
  uint8_t permanent_mac_addr[UALOE_MAC_ADDRESS_SIZE];
} ifoe_netport_state_t;

/** Enum defining the type of used network address */
typedef enum ifoe_network_addr_type {
  IFOE_NETWORK_ADDR_TYPE_MAC,
  IFOE_NETWORK_ADDR_TYPE_IP,
  IFOE_NETWORK_ADDR_TYPE_MAC_IP,
} ifoe_network_addr_type_e;

/** Structure defining a mapping from accelerator ID to destination address */
typedef struct ifoe_accelerator_addr_map_s {
  /** Accelerator ID */
  unsigned accelerator_id;
  /** MAC address */
  uint8_t mac_addr[UALOE_MAC_ADDRESS_SIZE];
  /** IP address (in Network byte order) */
  uint32_t ip_addr;
} ifoe_accelerator_addr_map_t;

/** Enum defining the different categories of telemetry */
typedef enum ualoe_telemetry_category {
  UALOE_TELEMETRY_CATEGORY_IFOE,
  UALOE_TELEMETRY_CATEGORY_SWITCH,
  UALOE_TELEMETRY_CATEGORY_CRYPTO,
  UALOE_TELEMETRY_CATEGORY_PFC,
  UALOE_TELEMETRY_CATEGORY_NETPORT,
  UALOE_TELEMETRY_CATEGORY_DERIVED_IFOE,
  UALOE_TELEMETRY_CATEGORY_DERIVED_NETPORT,
  UALOE_TELEMETRY_CATEGORY_MAX
} ualoe_telemetry_category_e;

/** Define used to construct a bitmask for selected Telemetry categories */
#define UALOE_TELEMETRY_CATEGORY_MASK(cat) (1U << UALOE_TELEMETRY_CATEGORY_##cat)

/** Definition of an item of telemetry */
typedef struct ualoe_telemetry_item_s {
  /** Identifier of the telemetry item */
  uint64_t id;
  /** Value of the telemetry item */
  uint64_t value;
} ualoe_telemetry_item_t;

/** Collection of telemetry data items for an instance of a cateogory of telemetry */
typedef struct ualoe_telemetry_instance_s {
  /** Name for this instance */
  ualoe_label_t name;
  /** Logical index for this instance */
  unsigned logical_idx;
  /** Number of telemetry items in the set */
  unsigned item_count;
  /** Set of telemetry items */
  ualoe_telemetry_item_t* items;
} ualoe_telemetry_instance_t;

/** Definition of a Telemetry dataset. This contains the all telemetry for one
 * category.
 */
typedef struct ualoe_telemetry_dataset_s {
  /** Telemetry category */
  ualoe_telemetry_category_e category;
  /** Sequence number incremented each time that the telemetry data is written */
  uint64_t generation_count;
  /** Timestamp at which the telemetry was captured. This is the UTC time */
  struct timespec timestamp;
  /** Number of instances of telemetry data for this category */
  unsigned instance_count;
  /** Array of instances of data */
  ualoe_telemetry_instance_t* instances;
} ualoe_telemetry_dataset_t;

/** Top level structure defining the telemetry data for IFoE. Telemetry data
 * is organised into datasets, one for each category of telemetry. This allows
 * a subset of the overall telemetry to be delivered to a client, according to
 * what the client requests and also what is permitted- the Tenant is only
 * allowed to receive the derived telemetry for IFoE Stations and Network
 * Ports. In the top level telemetry data structure, ualoe_telemetry_t, the
 * 'datasets' array is indexed by ualoe_telemetry_category_e. Where a category
 * is not available or has not been requested by the client, the array entry
 * will be Null.
 *
 * For each category, the data is organized into a dataset contains data for
 * each instance of the hardware. Instances are either per-IFoE station or
 * per-network ports, depending on the category of telemetry.
 * Each dataset includes:
 *   - A generation count which is incremented each time that the dataset is
 *     updated
 *   - A timestamp of when the dataset was last updated
 *   - The number of instances in the dataset
 *   - An array of pointers to the data for each instance
 * Each instance includes:
 *   - The textual label of the instance (this will match the equivalent sysfs name),
 *   - The logical index of the instance (either the IFoE Station or Network Port)
 *   - An array of telemetry items consisting of a unique ID and the current value
 *
 * The telemetry IDs are defined in YML which is then used to generate the header
 * file ifoe_telemetry.h provided in the same directory as this API.
 *
 * Almost all telemetry items are counters. The only exceptions are the items:
 *   IFOE_TELEM_ID_IFOE_LOGICAL_LINK_STATUS
 *   IFOE_TELEM_ID_NETPORT_LINK_STATUS
 * in the datasets for derived telemetry for IFoE Stations and Network Ports.
 * These two items are sets of flags defining the status. Refer to
 *   IFOE_TELEM_LINK_STATUS_*
 *   IFOE_TELEM_NETPORT_STATUS_*
 * for the definitions of the individual flags.
 */
typedef struct ualoe_telemetry_s {
  /** Dataset for each category of telemetry */
  ualoe_telemetry_dataset_t* datasets[UALOE_TELEMETRY_CATEGORY_MAX];
} ualoe_telemetry_t;

/** Type for an L2Ping handle. */
typedef unsigned ualoe_ping_handle_t;

/** Structure defining the specification for a L2 ping network connectivity
 * test. */
typedef struct ualoe_ping_spec_s {
  /** When indicates that the network ping check should be carried out on the
   * specified accelerator */
  bool specify_accelerator;
  /** When indicates that the network ping check should be carried out on the
   * specified Network Port */
  bool specify_netport;
  /** Include IFoE Request traffic in the ping test */
  bool include_ifoe_req;
  /** Include IFoE Response traffic in the ping test */
  bool include_ifoe_resp;
  /** Include non-IFoE traffic in the ping test */
  bool include_non_ifoe;
  /** Accelerator ID to target if specify_accelerator is true */
  unsigned accelerator_id;
  /** Network Port to target if specify_netport is true */
  unsigned netport_idx;
  /** Number of pings to perform on each path (max UALOE_L2PING_MAX_PINGS) */
  unsigned num_pings;
} ualoe_ping_spec_t;

/** Structure holding a single ping result for a specific accelerator and
 * netport. */
typedef struct ualoe_ping_netport_results_s {
  /** Count of ping failures on the IFoE Request PFC channel. A value of 0
   * indicates all pings completed successfully. */
  uint8_t req_failures;
  /** Count of ping failures on the IFoE Response PFC channel. A value of 0
   * indicates all pings completed successfully. */
  uint8_t resp_failures;
  /** Count of non-IFOE failures on the non-IFoE traffic PFC channel. A value
   * of 0 indicates all pings completed successfully. */
  uint8_t non_ifoe_failures;
} ualoe_ping_netport_result_t;

/** Structure holding a set of ping results for a specific accelerator. This
 * includes the ping results for all network paths to the accelerator. */
typedef struct ualoe_ping_accel_result_s {
  /** Accelerator ID */
  unsigned id;
  /** Array of network port results. This is either indexed by logical network
   * port index or, if a specific network port was specified for the ping test,
   * a single result for that network port. */
  ualoe_ping_netport_result_t* netports;
} ualoe_ping_accel_result_t;

/** Context for a L2Ping test. */
typedef struct ualoe_ping_s {
  /** Opaque handle for the ping test */
  ualoe_ping_handle_t handle;
  /** Specification of the test */
  ualoe_ping_spec_t spec;
  /** Indicates that the test is complete */
  bool test_complete;
  /** Indication of progress. This field counts up to 'total' */
  unsigned progress;
  /** Indication of progress. The field 'progress' will count up to this value. */
  unsigned total;
  /** Number of accelerators included in the ping test. This provides the size
   * of the accels array. */
  unsigned num_accelerators;
  /** Number of netports included in the ping test. This provides the size of
   * each ualoe_ping_netport_result_t array. */
  unsigned num_netports;
  /** Array of results for each accelerator included in the test. If a specific
   * accelerator was defined in the test spec, this will be an array of 1 entry. */
  ualoe_ping_accel_result_t* accels;
} ualoe_ping_t;

/** Enumeration defining the different UALoE events */
typedef enum {
  /** Notification that a Network Port link state has changed */
  UALOE_EVENT_NETPORT_LINK_CHANGE,
  /** Notification that a IFoE Logical Link state has changed */
  UALOE_EVENT_IFOE_LINK_CHANGE,
  /** Notification that the configuration phase of UALoE has changed */
  UALOE_EVENT_CONFIG_PHASE_CHANGE,
  /** Notification that the current L2 ping test is complete */
  UALOE_EVENT_L2PING_COMPLETE,
} ualoe_event_id_e;

/** Structure defining an UALoE event. This is passed to the caller
 * when an event occurs.
 */
typedef struct ualoe_event_s {
  /** ID of the event that occurred */
  ualoe_event_id_e id;
  /** UTC time for the event */
  struct timespec timestamp;

  /** Union containing event-specific data */
  union {
    /** Data associated with the event UALOE_EVENT_NETPORT_LINK_CHANGE */
    struct {
      /* Label of Network Port that changed link state */
      ualoe_label_t name;
      /** Network Port logical index */
      unsigned logical_idx;
      /* Boolean indicating if link is up or down */
      bool link_down;
    } netport_link_change;

    /** Data associated with the event UALOE_EVENT_IFOE_LINK_CHANGE */
    struct {
      /** IFoE Station name */
      ualoe_label_t name;
      /** IFoE Station logical index */
      unsigned logical_idx;
      /** Boolean indicating that the IFoE Logical Link is down */
      bool link_down;
      /** Boolean indicating that that datapath interface between IFoE and data
       * fabric is isolated i.e. no data flow is disabled in both directions. */
      bool dx_isolated;
      /** Number of Network Port structures populated */
      unsigned netport_count;
      /** Array of Network Port information */
      struct {
        /** Logical index of the network port */
        unsigned logical_idx;
        /** When true, indicates that there is a fault on the network port. */
        bool fault;
        /** Count of number of streams currently in a failover state which have
         * been remapped to an alternative Network Port. */
        unsigned streams_failover;
        /** Count of number of streams currently in a paused state due to a
         * retransmission timeout where failover was either not possible or
         * disabled. */
        unsigned streams_paused;
      } netports[UALOE_MAX_NETPORTS_PER_IFOE_STATION];
    } ifoe_link_change;

    /** Data associated with the event UALOE_EVENT_CONFIG_PHASE_CHANGE */
    struct {
      /** New configuration phase */
      ualoe_config_phase_e phase;
    } config_phase_change;

    /** Data associated with the event UALOE_EVENT_L2PING_COMPLETE */
    struct {
      /** Handle associated with the ping test */
      ualoe_ping_handle_t handle;
    } l2ping_complete;
  } u;
} ualoe_event_t;

/* ------------------- */
/* Function Prototypes */
/* ------------------- */

/**
 * @brief Open a connection to an UALoE driver. The UALoE device exposes
 * a driver instance for each PCI function (one PF and one VF),
 * identified by PCI address.
 *
 * @note This library is statically linked to the application. Multiple
 * clients can connect simultaneously as each has it's own copy of the
 * library code and data.
 *
 * @param pci_addr PCI Address of the UALoE device
 * @param handle Handle to be used for subsequent configuration calls
 * @return 0 on success. errno on failure.
 */
int ualoe_open(const char* pci_addr, ualoe_handle_t* handle);

/**
 * @brief Close a connection to an UALoE driver.
 *
 * @param handle Handle of the UAoE driver
 * @return 0 on success. errno on failure.
 */
int ualoe_close(ualoe_handle_t handle);

/**
 * @brief Get the UALoE firmware and telemetry versions
 * This command is permitted in all configuration phases.
 *
 * @param handle UALoE driver handle
 * @param lib_version Pointer to structure for the UALoE library version
 * @param fw_version Pointer to structure for FW version
 * @param telemetry_version Pointer to structure for Telemetry version
 * @return 0 on success. errno on failure.
 */
int ualoe_get_version(ualoe_handle_t handle, ualoe_version_t* lib_version,
                      ualoe_version_t* fw_version, ualoe_version_t* telemetry_version);

/**
 * @brief Reset the UALoE datapath and configuration. The behaviour of this
 * operation depends on whether the driver instance is associated with the PF
 * or the VF of IFoE.
 * For the PF, this operation will disable the IFoE datapath, reset all
 * stations and return the configuration phase back to the Provider phase. The
 * network ports will remain up and the VF will remain enabled but the crypto
 * keys will be disabled and erased. After a reset, the configuration will be
 * returned to the firmware defaults with the set of active and local
 * accelerators empty. For detail of the defaults for other configuration
 * items, refer to the definition of ifoe_config_t.
 * For the VF, this operation will disable communications with remote GPUs and
 * clear the set of enabled accelerators, clear the crypto keys, disable
 * encryption and return the configuration phase back to Tenant phase.
 * This is a blocking call and will only return when complete.
 *
 * @param handle UALoE driver handle
 * @return 0 on success. errno on failure.
 */
int ualoe_reset(ualoe_handle_t handle);

/**
 * @brief Get the capabilities of this UALoE device. This returns information
 * about the hardware configuration of the device including number of stations,
 * netports per station etc.
 * This command is permitted in all configuration phases.
 *
 * @param handle UALoE driver handle
 * @param capabilities Pointer to capabilities structure to be populated
 * @return 0 on success. errno on failure.
 */
int ualoe_get_capabilities(ualoe_handle_t handle, ualoe_capabilities_t* capabilities);

/**
 * @brief Set an UALoE instance's identity, specifically the ID for the local
 * accelerator.
 * This command is only permitted in the Provider configuration phase.
 *
 * @note This command is not required long-term as this information will be
 * retrieved through a different mechanism.
 *
 * @param handle IFoE driver handle
 * @param accelerator_id The GPU accelerator ID of the GPU connected to this
 * UALoE device
 * @return 0 on success. errno on failure.
 */
int ualoe_set_identity(ualoe_handle_t handle, unsigned accelerator_id);

/**
 * @brief Configure the Accelerator IDs for use in the VPod. The caller should
 * provide one bitmask of the active accelerators in the VPod and a second
 * bitmask that indicates which of these accelerators are local to the host
 * (this applies to any other GPUs that are part of the VPod and also attached
 * to this host processor). For each bit in the bitmask, the bit number
 * corresponds to the accelerator ID.
 * The set of local accelerators must be subset of the active accelerators,
 * noting that a configuration where all accelerators are local is valid.
 * This command is only permitted in the Provider configuration phase.
 *
 * @note This command is not required long-term as this information will be
 * retrieved through a different mechanism.
 *
 * @param handle UALoE driver handle
 * @param bitmask_size Size of the supplied bitmasks in bytes
 * @param active_accelerator_bitmask Bitmask of the active Accelerators in
 * the VPod
 * @param local_accelerator_bitmask Bitmask of the Accelerators local to the device
 * @return 0 on success. errno on failure.
 */
int ualoe_set_accelerator_config(ualoe_handle_t handle, unsigned bitmask_size,
                                 uint32_t active_accelerator_bitmask[],
                                 uint32_t local_accelerator_bitmask[]);

/**
 * @brief Set various IFoE configuration options. These are global settings
 * that apply to all IFoE Stations / Network Ports in the device.
 * This command is only permitted in the Provider configuration phase and
 * if attempted in any other phase, will fail with EBUSY.
 *
 * @param handle UALoE driver handle
 * @param virt_mode Configures IFoE is operating in virtualized or bare-metal mode
 * @param encap_type Specifies the network encapsulation that IFoE traffic will use
 * @param failover_mode Specifies whether failover will be be used
 * @param loopback_mode Network port loopback mode
 */
int ualoe_set_ifoe_config(ualoe_handle_t handle, ifoe_virt_mode_e virt_mode,
                          ifoe_encap_type_e encap_type, ifoe_failover_mode_e failover_mode,
                          ifoe_loopback_mode_e loopback_mode);

/**
 * @brief Get the IFoE configuration. The returned structure includes flags
 * indicating which items have been configured by the client, and consequently
 * which items have not been configured and are the firmware defaults.
 * This command is permitted in all phases.
 *
 * @param handle UALoE driver handle
 * @param config Pointer to structure where configuration should be written
 * @param bitmask_size Size of the supplied bitmasks in bytes
 * @param active_accelerator_bitmask Bitmask of the active Accelerators in
 * the VPod
 * @param local_accelerator_bitmask Bitmask of the Accelerators local to the device
 * @param enabled_accelerator_bitmask Bitmask of the Accelerators enabled for
 * communication
 */
int ualoe_get_ifoe_config(ualoe_handle_t handle, ifoe_config_t* config, unsigned bitmask_size,
                          uint32_t active_accelerator_bitmask[],
                          uint32_t local_accelerator_bitmask[],
                          uint32_t enabled_accelerator_bitmask[]);

/**
 * @brief Transition to the next configuration phase. The caller must specify
 * the next phase to avoid accidentally transitioning to the wrong phase. If
 * this does not match the strict ordering enforced by the firmware, the
 * request will fail with ERANGE. See the UALoE configuration phases definition
 * above for notes on the transition order.
 *
 * @param handle UALoE driver handle
 * @param next_phase Configuration phase to transition to
 * @return 0 on success. errno on failure
 */
int ualoe_next_config_phase(ualoe_handle_t handle, ualoe_config_phase_e next_phase);

/**
 * @brief Get the current configuration phase
 * This command is permitted in all configuration phases.
 *
 * @param handle UALoE driver handle
 * @param phase Pointer to location to return current configuration phase
 * @return 0 on success. errno on failure
 */
int ualoe_get_current_config_phase(ualoe_handle_t handle, ualoe_config_phase_e* phase);

/**
 * @brief Configure the set of accelerator IDs that should be enabled for
 * communication with this accelerator. Specified as a bitmask. This
 * operation is carried out by the tenant and confirms that the tenant has
 * validated that the remote accelerators are trusted, has programmed
 * encryption keys, if necessary, and is ready to enable the reception
 * of traffic. The set of enabled accelerators must be a subset of
 * the configured active accelerators. Note that the local accelerator ID
 * is implicitly active whether or not specified in the set.
 * This command is only permitted in the Tenant configuration phase and
 * if attempted in any other phase, will fail with EBUSY.
 *
 * @param handle UALoE driver handle
 * @param bitmask_size Size of the supplied bitmask in bytes
 * @param enabled_accelerator_bitmask Bitmask of the enabled Accelerators
 * in the VPod
 * @return 0 on success. errno on failure
 */
int ualoe_enable_accelerators(ualoe_handle_t handle, unsigned bitmask_size,
                              uint32_t enabled_accelerator_bitmask[]);

/**
 * @brief Configure the encryption mode for the UALoE datapath. This operation
 * is carried out by the tenant in virtualization mode. In bare-metal mode
 * mode the provider will carry out this operation but may do so only after
 * completing the Provider configuration and transitioning to the tenant
 * configuration phase. Encryption can be disabled or enabled with one of
 * the encryption modes supported by the datapath.
 * This command is only permitted in the Tenant configuration phase and if
 * attempted in any other phase, will fail with EBUSY.
 *
 * @param handle UALoE driver handle
 * @param mode Encryption mode to be used
 * @return 0 on success. errno on failure
 */
int ualoe_config_crypto(ualoe_handle_t handle, ualoe_crypto_mode_e mode);

/**
 * @brief Set the encryption key for UALoE TX / egress datapath. This command
 * is permitted when encryption is enabled and when UALoE is in the Tenant
 * configuration or Showtime phase. If attempted in any other phase, the
 * command will fail with EBUSY. If attempted when encryption is disabled
 * the command will fail with ENODEV.
 *
 * @param handle UALoE driver handle
 * @param key_id Key ID to be used for TX encryption
 * @param key Crypto key to be programmed
 * @return 0 on success. errno on failure
 */
int ualoe_set_tx_crypto_key(ualoe_handle_t handle, ualoe_crypto_key_id_e key_id,
                            ualoe_crypto_key_t* key);

/**
 * @brief Disables the specified key for RX decryption. For the UALoE receive
 * datapath, two keys on the RX datapath to allow the key rotation. This
 * function disables one key ID such that the associated key can no longer
 * be used to decrypt packets.
 * This command is permitted when encryption is enabled and when UALoE is in
 * the Tenant configuration or Showtime phase. If attempted in any other
 * phase, the command will fail with EBUSY. If attempted when encryption is
 * disabled the command will fail with ENODEV.
 *
 * @param handle UALoE driver handle
 * @param key_id Key ID to be used for TX encryption
 * @return 0 on success. errno on failure
 */
int ualoe_disable_rx_crypto_key(ualoe_handle_t handle, ualoe_crypto_key_id_e key_id);

/**
 * @brief Set and enable an encryption key for UALoE RX / ingress datapath.
 * IFoE supports two keys on the RX datapath identified by a key ID. This
 * allows the keys to be rotated without interruption to traffic flow.
 * This command is permitted when encryption is enabled and when IFoE is
 * in the Tenant configuration or showtime phase. If attempted in any other
 * phase, the command will fail with EBUSY. If attempted when encryption is
 * disabled the command will fail with ENODEV.
 *
 * @param handle UALoE driver handle
 * @param key_id Key ID to be used for RX decryption
 * @param key Crypto key to be programmed
 * @return 0 on success. errno on failure
 */
int ualoe_set_rx_crypto_key(ualoe_handle_t handle, ualoe_crypto_key_id_e key_id,
                            ualoe_crypto_key_t* key);

/**
 * @brief Get a set of descriptors for the IFoE Stations in this device. Each
 * descriptor contain information about the station including a textual label
 * and physical and logical indices.
 * This command is permitted in the Provider, Tenant, Showtime and Diagnostics
 * phases.
 *
 * @param handle UALoE driver handle
 * @param desc_count Number of entries in descriptor array provided by the
 * caller. This should match the number of configured IFoE stations- refer to
 * ualoe_get_capabilities().
 * @param descs Array of descriptors. This memory should be allocated by the
 * caller and will be populated by this function.
 * @return 0 on success. errno on failure
 */
int ifoe_get_station_list(ualoe_handle_t handle, unsigned desc_count, ifoe_station_desc_t descs[]);

/**
 * @brief Function to control an IFoE station. This can be used to
 * administratively enable and disable the station as well as placing it
 * in a stopped/drain state.
 * This command is only permitted in the Provider configuration phase.
 *
 * @param handle UALoE driver handle
 * @param station_idx Logical index of IFoE station
 * @param state The state to set the IFoE station into
 * @return 0 on success. errno on failure
 */
int ifoe_station_ctrl(ualoe_handle_t handle, unsigned station_idx, ifoe_station_state_e state);

/**
 * @brief Function to get information about the state of an IFoE Station.
 * This command is permitted in the Provider, Tenant, Showtime and Diagnostics
 * phases.
 *
 * @param handle UALoE driver handle
 * @param station_idx Logical index of IFoE station
 * @param state Pointer to structure to store the station state
 * @return 0 on success. errno on failure
 */
int ifoe_station_get_state(ualoe_handle_t handle, unsigned station_idx,
                           ifoe_station_state_t* state);

/**
 * @brief Set the Path to Port mapping for the IFoE datapath. This can be done
 * globally, per IFoE Station and per Accelerator ID, depending on the selected
 * flags.
 * This command is permitted in the Provider, Tenant and Showtime phases.
 *
 * @param handle UALoE driver handle
 * @param specify_station Boolean indicating if the mapping should be set for a
 * specific IFoE Station
 * @param specify_accelerator Boolean indicating if the mapping should be set
 * for a specific Accelerator.
 * @param reenable_streams Boolean indicating that any disabled streams
 * affected by this mapping request should be re-enabled.
 * @param station_idx Logical index of IFoE station
 * @param accelerator_id Accelerator ID
 * @param path_count Number of entries in paths array provided by the
 * caller. This must match the number IFoE Paths as returned by
 * ualoe_get_capabilities().
 * @param map Array of Network Port logical indices, indexed by the IFoE Path.
 * @return 0 on success. errno on failure
 */
int ifoe_set_path_to_port_map(ualoe_handle_t handle, bool specify_station, bool specify_accelerator,
                              bool reenable_streams, unsigned station_idx, unsigned accelerator_id,
                              unsigned path_count, unsigned map[]);

/**
 * @brief Get the Path to Port mapping for a specified IFoE Station and
 * Accelerator.
 * This command is permitted in the Provider, Tenant and Showtime phases.
 *
 * @param handle UALoE driver handle
 * @param station_idx Logical index of IFoE station
 * @param accelerator_id Accelerator ID
 * @param path_count Number of entries in paths array provided by the
 * caller. This must match the number IFoE Paths as returned by
 * ualoe_get_capabilities().
 * @param map Array of Network Port logical indices, indexed by IFoE Path.
 * @return 0 on success. errno on failure
 */
int ifoe_get_path_to_port_map(ualoe_handle_t handle, unsigned station_idx, unsigned accelerator_id,
                              unsigned path_count, unsigned map[]);

/**
 * @brief Get the Network Port properties. Note that the port properties
 * are common to all IFoE network ports and are fixed for a given port
 * mode.
 * This command is permitted in all configuration phases.
 *
 * @param handle UALoE driver handle
 * @param properties Pointer to location to write port properties
 * @return 0 on success. errno on failure
 */
int ifoe_get_netport_properties(ualoe_handle_t handle, ualoe_netport_properties_t* properties);

/**
 * @brief Get a set of descriptors for the Network Ports associated with the
 * IFoE device. Each descriptor contain information about the location network
 * port i.e. the IFoE station that it belongs to and it's station-relative
 * index.
 * This command is permitted in the Provider, Tenant, Showtime and Diagnostics
 * phases.
 *
 * @param handle UALoE driver handle
 * @param desc_count Number of entries in descriptor array provided by the
 * caller. This should match the number of configured network ports- refer to
 * ualoe_get_capabilities().
 * @param descs Array of descriptors. This memory should be allocated by the
 * caller and will be populated by this function.
 * @return 0 on success. errno on failure
 */
int ifoe_get_netport_list(ualoe_handle_t handle, unsigned desc_count, ifoe_netport_desc_t descs[]);

/**
 * @brief Function to control a Network Port. This can be used to disable a
 * Network Port and remove it as a part of the logical link of the associated
 * IFoE Station.
 * This command is only permitted in the Provider configuration phase.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param state The state to set the Network Port into
 * @return 0 on success. errno on failure
 */
int ifoe_netport_ctrl(ualoe_handle_t handle, unsigned netport_idx, ifoe_netport_state_e state);

/**
 * @brief Function to configure a Network Port link to use Auto-Negotiation.
 * The caller should supply the set of ethernet technologies supported in
 * as well as the requested FEC mode, noting that a weaker FEC mode may be
 * negotiated depending on the link parter's capabilities. With AN enabled,
 * parallel detect can used in which case the local link will attempt to
 * determine the link configuration being used by the partner.
 * This command is only permitted in the Provider and Diagnostics configuration
 * phases.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param parallel_detect_enable Enable Parallel Detect
 * @param advertised_eth_techs Bitmask of supported ethernet technologies
 * @param requested_fec_mode Requested FEC mode to use
 * @return 0 on success. errno on failure
 */
int ifoe_netport_config_link_auto(ualoe_handle_t handle, unsigned netport_idx,
                                  bool parallel_detect_enable, __uint128_t advertised_eth_techs,
                                  ualoe_fec_mode_e requested_fec_mode);

/**
 * @brief Function to configure a Network Port link with Auto-Negotiation
 * disabled and a fixed link configuration. The caller should specify the
 * ethernet technology, FEC mode and the loopback mode (can be none).
 * This command is only permitted in the Provider and Diagnostics configuration
 * phases.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param eth_tech Ethernet technology to configure
 * @param fec_mode FEC mode to use
 * @param loopback_mode Loopback mode
 * @return 0 on success. errno on failure
 */
int ifoe_netport_config_link_manual(ualoe_handle_t handle, unsigned netport_idx,
                                    ualoe_eth_tech_e eth_tech, ualoe_fec_mode_e fec_mode,
                                    ualoe_netport_loopback_mode_e loopback_mode);

/**
 * @brief Function to configure the MAC and/or IP addresses to use
 * for IFoE traffic.
 * This command is only permitted in the Provider configuration phase.
 *
 * @note The mac_addr and ip_addr parameters are optional. Their presence or
 * absence is determined by the addr_type parameter. A "missing" parameter can
 * take any value, and the parameter's value will be ignored during the call.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param addr_type The type of network address to use for IFoE traffic
 * @param mac_addr The MAC address to use for IFoE traffic
 * @param ip_addr The IP address to use for IFoE traffic in Network byte order
 * @return 0 on success. errno on failure
 *
 * @note addr_type must match the configured encapsulation mode:
 * - IFOE_NETWORK_ADDR_TYPE_MAC can be used only with IFOE_ENCAP_TYPE_ETHERNET;
 * - IFOE_NETWORK_ADDR_TYPE_IP with IFOE_ENCAP_TYPE_TF1;
 * - IFOE_NETWORK_ADDR_TYPE_MAC_IP with IFOE_ENCAP_TYPE_IP.
 *
 * The command will fail with error EINVAL when attempting to pass an address
 * type that is not compatible with the currently used encapsulation mode.
 */
int ifoe_netport_set_addr(ualoe_handle_t handle, unsigned netport_idx,
                          ifoe_network_addr_type_e addr_type, uint8_t mac_addr[], uint32_t ip_addr);

/**
 * @brief Function to set the Accelerator to destination MAC address mapping
 * for a Network Port.
 * This command is only permitted in the Provider configuration phase.
 *
 * @note To be discussed, should this be provided as a more global mapping i.e.
 * a struct containing netport, accelerator ID, dest mac address?
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param map_addr_type The type of network address in map array
 * @param map_count Number of mapping entries provided
 * @param map Array of accelerator to address mappings
 *
 * @note All details about the use of the address type and its values from
 * ifoe_netport_set_addr apply to this function and the address values used
 * in ifoe_accelerator_addr_map_t.
 */
int ifoe_netport_set_accelerator_addr_map(ualoe_handle_t handle, unsigned netport_idx,
                                          ifoe_network_addr_type_e map_addr_type,
                                          unsigned map_count, ifoe_accelerator_addr_map_t map[]);

/**
 * @brief Function to get IFoE-specific state of a Network Port.
 * This command is permitted in the Provider, Tenant, Showtime and Diagnostics
 * phases.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param state Pointer to structure to store the station state
 * @return 0 on success. errno on failure
 */
int ifoe_netport_get_state(ualoe_handle_t handle, unsigned netport_idx,
                           ifoe_netport_state_t* state);

/**
 * @brief Allocate storage for Telemetry. This is called specify a set of
 * telemetry categories for which telemetry should be retrieved and the call
 * will allocate the required storage for the telemetry. The allocated
 * storage can then be reused each time that the caller wants to get an
 * updated snapshot of the data.
 * This functionality can be used by both the Provider and Tenant but the
 * tenant is restricted in the categories that it can receive to the
 * DERIVED_IFOE and DERIVED_NETPORT categories.
 * This command is permitted in Provider, Tenant, Showtime and Diagnostics
 * phases.
 *
 * @param handle UALoE driver handle
 * @param category_mask Bitmask of the Telemetry categories required,
 * constructed using UALOE_telemetry_CATEGORY_MASK(cat)
 * @param telemetry Returned telemetry structure
 * @return 0 on success. errno on failure
 */
int ualoe_telemetry_alloc(ualoe_handle_t handle, unsigned category_mask,
                          ualoe_telemetry_t** telemetry);

/**
 * @brief Get a copy of the latest telemetry data snapshot
 * This command is permitted in Provider, Tenant, Showtime and Diagnostics
 * phases.
 *
 * @param handle UALoE driver handle
 * @param telemetry Storage for telemetry pre-allocated using
 * ualoe_telemetry_alloc()
 * @return 0 on success. errno on failure
 */
int ualoe_telemetry_get(ualoe_handle_t handle, ualoe_telemetry_t* telemetry);

/**
 * @brief Free the storage allocated for the telemetry data
 * This command is permitted in Provider, Tenant, Showtime and Diagnostics
 * phases.
 *
 * @param handle UALoE driver handle
 * @param telemetry Telemetry data to be freed
 * @return 0 on success. errno on failure
 */
int ualoe_telemetry_free(ualoe_handle_t handle, ualoe_telemetry_t* telemetry);

/**
 * @brief Configure an L2 Ping test, allocate the context for the test and
 * memory required to hold the results before starting the test. The test will
 * take some time and continue in the background. When the test is complete,
 * the notification UALOE_EVENT_L2PING_COMPLETE will be sent.
 * ualoe_l2ping_update() can be called during the ping test to get an update
 * on progress and to retrieve the full results at the end of the test.
 * ualoe_l2ping_free() must be called at the end of the test to free the
 * allocated resources.
 * This command is only permitted in Showtime and Diagnostics phases.
 *
 * @param handle UALoE driver handle
 * @param spec Specification for the ping test
 * @param ping Pointer to the ping context which will be allocated for the test
 * @return 0 on success. errno on failure
 */
int ualoe_l2ping_start(ualoe_handle_t handle, ualoe_ping_spec_t* spec, ualoe_ping_t** ping);

/**
 * @brief Update the ping context with the status and progress. If the ping
 * test is complete the context will be marked as such and the full results
 * populated.
 * This command is only permitted in Showtime and Diagnostics phases.
 *
 * @param handle UALoE driver handle
 * @param ping Pointer to the context for the ping currently in progress
 * @return 0 on success. errno on failure
 */
int ualoe_l2ping_update(ualoe_handle_t handle, ualoe_ping_t* ping);

/**
 * @brief Stop the current ping test if not already finished and free the
 * resources allocated for the test.
 * This command is allowed in all phases.
 *
 * @param handle UALoE driver handle
 * @param ping Pointer to the ping context to be freed
 * @return 0 on success. errno on failure
 */
int ualoe_l2ping_fini(ualoe_handle_t handle, ualoe_ping_t* ping);

/**
 * @brief Prototype of callback function to notify the client that
 * an event has occurred
 *
 * @param user_context Context supplied by the user when the callback
 * was subscribed to
 * @param handle UALoE driver handle
 * @param event Structure containing the event
 */
typedef void (*ualoe_event_callback_t)(void* user_context, ualoe_handle_t handle,
                                       ualoe_event_t event);

/**
 * @brief Register a callback to be notified of UALoE events
 * This command is permitted in all configuration phases.
 *
 * @param handle UALoE driver handle
 * @param callback Callback function
 * @param user_context Context that will be passed back in callbacks
 * @return 0 on success. errno on failure
 */
int ualoe_register_event_callback(ualoe_handle_t handle, ualoe_event_callback_t callback,
                                  void* user_context);

/** Functions for diagnostics operations */

/** Structure used to hold PRBS test results */
typedef struct ualoe_prbs_results {
  /** Indicates whether the PRBS results are valid */
  bool valid;
  /** Indicates that the requested RX EQ operation was successful */
  bool rxeq_success;
  /** Indicates whether CDR is locked */
  bool cdr_lock;
  /** Indicates that the specified PRBS pattern is detected. If false,
   * indicates that there has been no detection of the pattern. */
  bool pattern_lock;
  /** Indicates that the error count has overflowed since the previous
   * time that the results were retrieved. */
  bool overflow;
  /** Interval since the last call to collect the results (or since PRBS
   * RX was enabled if this is the first call to retrieve results) */
  struct timespec interval;
  /** Number of bit errors detected */
  uint64_t error_count;
} ualoe_prbs_results_t;

/**
 * @brief Configure a network port PMA differential lane in preparation for
 * PRBS (pseudo-randon binary sequence) testing.
 * This operation can only be performed in Diagnostics mode.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param lane_idx Netport relative index of the serdes lane to configure
 * @param enable Controls if PMA lane should be enabled or powered down
 * @param pma_rate Specifies the PMA rate
 * @param loopback_mode Specifies loopback mode
 * @param tx_polarity Specifies polarity of TX lane
 * @param rx_polarity Specifies polarity of RX lane
 * @return 0 on success. errno on failure
 */
int ualoe_diag_config_pma_lane(ualoe_handle_t handle, unsigned netport_idx, unsigned lane_idx,
                               bool enable, ualoe_pma_rate_e pma_rate,
                               ualoe_netport_loopback_mode_e loopback_mode,
                               ualoe_pma_polarity_e tx_polarity, ualoe_pma_polarity_e rx_polarity);

/**
 * @brief Configure PRBS TX on a network port serdes lane. This operation will
 * configure the PMA to start transmitting the selected PRBS sequence. Before
 * enabling PRBS, the lane should be configured using the function
 * ualoe_diag_config_pma_lane(). To stop PRBS, the function can be called
 * again with enable false, whereby the PMA will be reconfigured to the
 * normal state where it processes transitions from the PCS.
 * This operation can only be performed in Diagnostics mode.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param lane_idx Netport relative index of the serdes lane to configure
 * @param enable Boolean indicating whether to enable/disable PRBS
 * @param pattern PRBS pattern to emit
 * @param user_pattern User supplied pattern if pattern is set to user defined
 * @return 0 on success. errno on failure
 */
int ualoe_diag_config_prbs_tx(ualoe_handle_t handle, unsigned netport_idx, unsigned lane_idx,
                              bool enable, ualoe_prbs_pattern_e pattern, __uint128_t user_pattern);

/**
 * @brief Start PRBS RX on a network port serdes lane. This operation will
 * configure the PMA to listen for the specified PRBS sequence. Before enabling
 * PRBS, the lane should be configured using the function
 * ualoe_diag_config_pma_lane(). When enabling PRBS RX, a preliminary RX
 * equalization using the resync flag. After enabling PRBS, IFoE will continue
 * to collect results until PRBS is disabled by a subsequent call with enable
 * set to false. While running, results can be fetched using the function
 * ualoe_diag_get_prbs_results().
 * This operation can only be performed in Diagnostics mode.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param lane_idx Netport relative index of the serdes lane to configure
 * @param enable Boolean indicating whether to enable/disable PRBS
 * @param resync If true, perform an RX equalization operation on the lane
 * before starting PRBS RX.
 * @param pattern PRBS pattern to emit
 * @param user_pattern User supplied pattern if pattern is set to user defined
 * @return 0 on success. errno on failure
 */
int ualoe_diag_config_prbs_rx(ualoe_handle_t handle, unsigned netport_idx, unsigned lane_idx,
                              bool enable, bool resync, ualoe_prbs_pattern_e pattern,
                              __uint128_t user_pattern);

/**
 * @brief When PRBS RX is enabled, this operation gets a snapshot of the
 * results. Note that taking a snapshot of the results will clear the
 * counters in the firmware to minimize the possibility of overflow.
 * Therefore, if cumulative results are required this is the responsibility
 * of the client.
 * This operation can only be performed in Diagnostics mode.
 *
 * @param handle UALoE driver handle
 * @param netport_idx Logical index of the Network Port
 * @param lane_idx Netport relative index of the serdes lane to configure
 * @param results Pointer to structure where results will be written.
 * @return 0 on success. errno on failure
 */
int ualoe_diag_get_prbs_results(ualoe_handle_t handle, unsigned netport_idx, unsigned lane_idx,
                                ualoe_prbs_results_t* results);

#endif  // UALOE_LIB_H