otailinecard.h

/**
 * Copyright (c) 2021 Alibaba Group.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License"); you may
 *    not use this file except in compliance with the License. You may obtain
 *    a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 *
 *    THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR
 *    CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT
 *    LIMITATION ANY IMPLIED WARRANTIES OR CONDITIONS OF TITLE, FITNESS
 *    FOR A PARTICULAR PURPOSE, MERCHANTABILITY OR NON-INFRINGEMENT.
 *
 *    See the Apache Version 2.0 License for specific language governing
 *    permissions and limitations under the License.
 *
 * @file    otailinecard.h
 *
 * @brief   This module defines OTAI Linecard interface
 */

#if !defined (__OTAILINECARD_H_)
#define __OTAILINECARD_H_

#include <otaitypes.h>

/**
 * @defgroup OTAILINECARD OTAI - Linecard specific API definitions
 *
 * @{
 */

/**
 * @brief Power admin state of the linecard
 */
typedef enum _otai_linecard_power_admin_state_t
{
    OTAI_LINECARD_POWER_ADMIN_STATE_ENABLED,
    OTAI_LINECARD_POWER_ADMIN_STATE_DISABLED,
    OTAI_LINECARD_POWER_ADMIN_STATE_MAX,
} otai_linecard_power_admin_state_t;

/**
 * @brief The reset type of the linecard
 */
typedef enum _otai_linecard_reset_t
{
    OTAI_LINECARD_RESET_WARM,
    OTAI_LINECARD_RESET_COLD,
    OTAI_LINECARD_RESET_FORCE,
    OTAI_LINECARD_RESET_MAX,
} otai_linecard_reset_t;

/**
 * @brief Linecard upgrade state
 */
typedef enum _otai_linecard_upgrade_state_t
{
    OTAI_LINECARD_UPGRADE_STATE_IDLE,
    OTAI_LINECARD_UPGRADE_STATE_DOWNLOADING,
    OTAI_LINECARD_UPGRADE_STATE_DOWNLOAD_FINISH,
    OTAI_LINECARD_UPGRADE_STATE_COMMITING,
    OTAI_LINECARD_UPGRADE_STATE_COMMIT_FINISH,
    OTAI_LINECARD_UPGRADE_STATE_REBOOTING,
    OTAI_LINECARD_UPGRADE_STATE_COMMIT_PAUSE,
    OTAI_LINECARD_UPGRADE_STATE_ROLLBACKING,
    OTAI_LINECARD_UPGRADE_STATE_COMMIT_ERROR,
    OTAI_LINECARD_UPGRADE_STATE_REBOOT_ERROR,
    OTAI_LINECARD_UPGRADE_STATE_COMMIT_STOP,
    OTAI_LINECARD_UPGRADE_STATE_MAX,

} otai_linecard_upgrade_state_t;

/**
 * @brief Linecard baud rate
 */
typedef enum _otai_linecard_baud_rate_t
{
    OTAI_LINECARD_BAUD_RATE_9600,
    OTAI_LINECARD_BAUD_RATE_19200,
    OTAI_LINECARD_BAUD_RATE_38400,
    OTAI_LINECARD_BAUD_RATE_57600,
    OTAI_LINECARD_BAUD_RATE_115200,
} otai_linecard_baud_rate_t;

/**
 * @brief Linecard operational state change notification
 *
 * @param[in] linecard_id Linecard Id
 * @param[in] linecard_oper_status New linecard operational state
 */
typedef void (*otai_linecard_state_change_notification_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ otai_oper_status_t linecard_oper_status);

/**
 * @brief Linecard alarm notification
 *
 * @param[in] linecard_id Linecard Id
 * @param[in] alarm_type Alarm type
 * @param[in] alarm_info Alarm info
 */
typedef void (*otai_linecard_alarm_notification_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ otai_alarm_type_t alarm_type,
        _In_ otai_alarm_info_t alarm_info);

/**
 * @brief Linecard OCM spectrum power notification
 *
 * @param[in] linecard_id Linecard Id
 * @param[in] ocm_id OCM Id
 * @param[in] ocm_result OCM Result
 */
typedef void (*otai_linecard_ocm_spectrum_power_notification_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ otai_object_id_t ocm_id,
        _In_ otai_spectrum_power_list_t ocm_result);

/**
 * @brief Linecard OTDR report result
 *
 * @param[in] linecard_id Linecard Id
 * @param[in] otdr_id OTDR Id
 * @param[in] otdr_result OTDR result
 */
typedef void (*otai_linecard_otdr_result_notification_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ otai_object_id_t otdr_id,
        _In_ otai_otdr_result_t otdr_result);

/**
 * @brief Attribute Id in otai_set_linecard_attribute() and
 *        otai_get_linecard_attribute() calls.
 */
typedef enum _otai_linecard_attr_t
{
    /**
     * @brief Start of attributes
     */
    OTAI_LINECARD_ATTR_START,

    /**
     * @brief Linecard type
     *
     * @type char
     * @flags MANDATORY_ON_CREATE | CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_LINECARD_TYPE = OTAI_LINECARD_ATTR_START,

    /**
     * @brief The admin state of the linecard
     *
     * @type otai_admin_state_t
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_ADMIN_STATE,

    /**
     * @brief The board mode of the linecard
     *
     * @type char
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_BOARD_MODE,

    /**
     * @brief The operational state of the linecard
     *
     * @type otai_oper_status_t
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_OPER_STATUS,

    /**
     * @brief Relay
     *
     * @type bool
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_RELAY,

    /**
     * @brief Whether the linecard is present or not
     *
     * @type bool
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_EMPTY,

    /**
     * @brief Whether the linecard is removable
     *
     * @type bool
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_REMOVABLE,

    /**
     * @brief The reset type of the linecard
     *
     * @type otai_linecard_reset_t
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_RESET,

    /**
     * @brief The power admin state of the linecard
     *
     * @type otai_linecard_power_admin_state_t
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_POWER_ADMIN_STATE,

    /**
     * @brief Host name
     *
     * @type char
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_HOSTNAME,

    /**
     * @brief Serial number
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_SERIAL_NO,

    /**
     * @brief Part number
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_PART_NO,

    /**
     * @brief Hardware version
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_HARDWARE_VERSION,

    /**
     * @brief Software version
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_SOFTWARE_VERSION,

    /**
     * @brief CPLD version
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_CPLD_VERSION,

    /**
     * @brief Script version
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_SCRIPT_VERSION,

    /**
     * @brief Manufacture date
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_MFG_DATE,

    /**
     * @brief Manufacture name
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_MFG_NAME,

    /**
     * @brief Set to linecard initialization or connect to linecard.
     *
     * TRUE - Initialize linecard.
     * FALSE - Connect to initialized linecard.
     *
     * @type bool
     * @flags CREATE_ONLY
     */
    OTAI_LINECARD_ATTR_INIT_LINECARD,

    /**
     * @brief Linecard alarm notification
     *
     * @type otai_pointer_t otai_linecard_alarm_notification_fn
     * @flags CREATE_ONLY
     * @default NULL
     */
    OTAI_LINECARD_ATTR_LINECARD_ALARM_NOTIFY,

    /**
     * @brief Spectrum power notification
     *
     * @type otai_pointer_t otai_linecard_ocm_spectrum_power_notification_fn
     * @flags CREATE_ONLY
     * @default NULL
     */
    OTAI_LINECARD_ATTR_LINECARD_OCM_SPECTRUM_POWER_NOTIFY,

    /**
     * @brief OTDR result notification
     *
     * @type otai_pointer_t otai_linecard_otdr_result_notification_fn
     * @flags CREATE_ONLY
     * @default NULL
     */
    OTAI_LINECARD_ATTR_LINECARD_OTDR_RESULT_NOTIFY,

    /**
     * @brief Collect linecard alarm.
     *
     * @type bool
     * @flags SET_ONLY
     */
    OTAI_LINECARD_ATTR_COLLECT_LINECARD_ALARM,

    /**
     * @brief Collect linecard log.
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_COLLECT_LINECARD_LOG,

    /**
     * @brief Linecard operational state change notification
     *
     * @type otai_pointer_t otai_linecard_state_change_notification_fn
     * @flags CREATE_ONLY
     * @default NULL
     */
    OTAI_LINECARD_ATTR_LINECARD_STATE_CHANGE_NOTIFY,

    /**
     * @brief Led mode
     *
     * @type otai_led_mode_t
     * @flags CREATE_AND_SET
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_LED_MODE,

    /**
     * @brief Led flash interval
     *
     * @type otai_uint16_t
     * @flags CREATE_AND_SET
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_LED_FLASH_INTERVAL,

    /**
     * @brief Led color
     *
     * @type otai_led_color_t
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_LED_COLOR,

    /**
     * @brief Baud rate
     *
     * @type otai_linecard_baud_rate_t
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_BAUD_RATE,

    /**
     * @brief Host IPv4 address
     *
     * @type otai_uint32_t
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_HOST_IP,

    /**
     * @brief User name
     *
     * @type char
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_USER_NAME,

    /**
     * @brief User password
     *
     * @type char
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_USER_PASSWORD,

    /**
     * @brief Linecard upgrade file name
     *
     * @type char
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_FILE_NAME,

    /**
     * @brief Linecard upgrade file path
     *
     * @type char
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_FILE_PATH,

    /**
     * @brief Upgrade download
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_DOWNLOAD,

    /**
     * @brief Upgrade commit
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_COMMIT,

    /**
     * @brief Upgrade commit pause
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_COMMIT_PAUSE,

    /**
     * @brief Upgrade commit resume
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_COMMIT_RESUME,

    /**
     * @brief Upgrade rollback
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_ROLLBACK,

    /**
     * @brief Upgrade reboot
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_REBOOT,

    /**
     * @brief Upgrade auto
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_UPGRADE_AUTO,

    /**
     * @brief Upgrade state
     *
     * @type otai_linecard_upgrade_state_t
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_UPGRADE_STATE,

    /**
     * @brief FPGA version
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_FPGA_VERSION,

    /**
     * @brief UCD version
     *
     * @type char
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_UCD_VERSION,

    /**
     * @brief Temperature high alarm threshold
     *
     * @type otai_double_t
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_TEMP_HIGH_ALARM_THRESHOLD,

    /**
     * @brief Temperature high warn threshold
     *
     * @type otai_double_t
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_TEMP_HIGH_WARN_THRESHOLD,

    /**
     * @brief Temperature low alarm threshold
     *
     * @type otai_double_t
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_TEMP_LOW_ALARM_THRESHOLD,

    /**
     * @brief Temperature low warn threshold
     *
     * @type otai_double_t
     * @flags CREATE_AND_SET
     */
    OTAI_LINECARD_ATTR_TEMP_LOW_WARN_THRESHOLD,

    /**
     * @brief Slot id
     *
     * @type otai_int32_t
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_SLOT_ID,

    /**
     * @brief Equipment failure
     *
     * @type bool
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_EQUIPMENT_FAILURE,

    /**
     * @brief Equipment mismatch
     *
     * @type bool
     * @flags READ_ONLY
     */
    OTAI_LINECARD_ATTR_EQUIPMENT_MISMATCH,

    /**
     * @brief Start Pre-configuration
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_START_PRE_CONFIGURATION,

    /**
     * @brief Stop Pre-configuration
     *
     * @type bool
     * @flags SET_ONLY
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_STOP_PRE_CONFIGURATION,

    /**
     * @brief Led name
     *
     * @type char
     * @flags CREATE_AND_SET
     * @isrecoverable false
     */
    OTAI_LINECARD_ATTR_LED_NAME,

    /**
     * @brief End of attributes
     */
    OTAI_LINECARD_ATTR_END,

    /** Custom range base value */
    OTAI_LINECARD_ATTR_CUSTOM_RANGE_START = 0x10000000,

    /** End of custom range base */
    OTAI_LINECARD_ATTR_CUSTOM_RANGE_END

} otai_linecard_attr_t;

/**
 * @brief Linecard counter IDs in otai_get_linecard_stats() call
 *
 * @flags Contains flags
 */
typedef enum _otai_linecard_stat_t
{
    /**
     * @brief Start of statistics
     */
    OTAI_LINECARD_STAT_START,

    /**
     * @brief Memory available
     *
     * @type otai_uint64_t
     * @iscounter false
     */
    OTAI_LINECARD_STAT_MEMORY_AVAILABLE = OTAI_LINECARD_STAT_START,

    /**
     * @brief Memory utilized
     *
     * @type otai_uint64_t
     * @iscounter false
     */
    OTAI_LINECARD_STAT_MEMORY_UTILIZED,

    /**
     * @brief CPU utilization
     *
     * @type otai_uint32_t
     * @iscounter false
     */
    OTAI_LINECARD_STAT_CPU_UTILIZATION,

    /**
     * @brief Temperature
     *
     * @type otai_double_t
     * @precision precision2
     * @iscounter false
     */
    OTAI_LINECARD_STAT_TEMPERATURE,

    /**
     * @brief End of statistics
     */
    OTAI_LINECARD_STAT_END,

} otai_linecard_stat_t;

/**
 * @brief Create linecard
 *
 * @param[out] linecard_id The Linecard Object ID
 * @param[in] attr_count Number of attributes
 * @param[in] attr_list Array of attributes to set during initialization
 *
 * @return #OTAI_STATUS_SUCCESS on success, failure status code on error
 */
typedef otai_status_t (*otai_create_linecard_fn)(
        _Out_ otai_object_id_t *linecard_id,
        _In_ uint32_t attr_count,
        _In_ const otai_attribute_t *attr_list);

/**
 * @brief Remove/disconnect Linecard
 *
 * Release all resources associated with a currently created linecard
 *
 * @param[in] linecard_id The Linecard id
 *
 * @return #OTAI_STATUS_SUCCESS on success, failure status code on error
 */
typedef otai_status_t (*otai_remove_linecard_fn)(
        _In_ otai_object_id_t linecard_id);

/**
 * @brief Set linecard attribute value
 *
 * @param[in] linecard_id Linecard id
 * @param[in] attr Linecard attribute
 *
 * @return #OTAI_STATUS_SUCCESS on success, failure status code on error
 */
typedef otai_status_t (*otai_set_linecard_attribute_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ const otai_attribute_t *attr);

/**
 * @brief Get linecard attribute value
 *
 * @param[in] linecard_id Linecard id
 * @param[in] attr_count Number of attributes
 * @param[inout] attr_list Array of linecard attributes
 *
 * @return #OTAI_STATUS_SUCCESS on success, failure status code on error
 */
typedef otai_status_t (*otai_get_linecard_attribute_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ uint32_t attr_count,
        _Inout_ otai_attribute_t *attr_list);

/**
 * @brief Get linecard counters. Deprecated for backward compatibility.
 *
 * @param[in] linecard_id Linecard id
 * @param[in] number_of_counters Number of counters in the array
 * @param[in] counter_ids Specifies the array of counter ids
 * @param[out] counters Array of resulting counter values.
 *
 * @return #OTAI_STATUS_SUCCESS on success, failure status code on error
 */
typedef otai_status_t (*otai_get_linecard_stats_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ uint32_t number_of_counters,
        _In_ const otai_stat_id_t *counter_ids,
        _Out_ otai_stat_value_t *counters);

/**
 * @brief Get linecard statistics counters extended.
 *
 * @param[in] linecard_id Linecard id
 * @param[in] number_of_counters Number of counters in the array
 * @param[in] counter_ids Specifies the array of counter ids
 * @param[in] mode Statistics mode
 * @param[out] counters Array of resulting counter values.
 *
 * @return #OTAI_STATUS_SUCCESS on success, failure status code on error
 */
typedef otai_status_t (*otai_get_linecard_stats_ext_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ uint32_t number_of_counters,
        _In_ const otai_stat_id_t *counter_ids,
        _In_ otai_stats_mode_t mode,
        _Out_ otai_stat_value_t *counters);

/**
 * @brief Clear linecard statistics counters.
 *
 * @param[in] linecard_id Linecard id
 * @param[in] number_of_counters Number of counters in the array
 * @param[in] counter_ids Specifies the array of counter ids
 *
 * @return #OTAI_STATUS_SUCCESS on success, failure status code on error
 */
typedef otai_status_t (*otai_clear_linecard_stats_fn)(
        _In_ otai_object_id_t linecard_id,
        _In_ uint32_t number_of_counters,
        _In_ const otai_stat_id_t *counter_ids);

/**
 * @brief Linecard method table retrieved with otai_api_query()
 */
typedef struct _otai_linecard_api_t
{
    otai_create_linecard_fn            create_linecard;
    otai_remove_linecard_fn            remove_linecard;
    otai_set_linecard_attribute_fn     set_linecard_attribute;
    otai_get_linecard_attribute_fn     get_linecard_attribute;
    otai_get_linecard_stats_fn         get_linecard_stats;
    otai_get_linecard_stats_ext_fn     get_linecard_stats_ext;
    otai_clear_linecard_stats_fn       clear_linecard_stats;
} otai_linecard_api_t;

/**
 * @}
 */
#endif /** __OTAILINECARD_H_ */