diff --git a/doc/fw/SAI-FW-API.md b/doc/fw/SAI-FW-API.md new file mode 100755 index 000000000..a482e9325 --- /dev/null +++ b/doc/fw/SAI-FW-API.md @@ -0,0 +1,635 @@ +# Firmware Instances SAI Specification +------------------------------------------------------------------------------- + Title | SAI Firmware API +:-------------|:----------------------------------------------------------------- + Authors | Jai Kumar, Broadcom Inc + Status | In review + Type | Standards track + Created | 06/24/2026: Initial Draft + SAI-Version | 1.19 +------------------------------------------------------------------------------- + + +## 1.0 Introduction +Modern switches support one or more embedded controllers for low latency performance sensitive functions. These functions are implemented as embedded software modules aka firmware running on these controllers. There can be one or more set of firmwares running on one or more controllers. This specification introduces set of APIs to manage the firmware running on the controller. + + +## 2.0 Overview +The SAI Firmware API provides a standardized mechanism for managing firmware instances associated with a switch object. The API supports: + +* Firmware object creation +* Firmware lifecycle management including start and stop of firmware operations +* Firmware state monitoring +* Runtime firmware configuration + +The API is exposed through the `sai_fw_api_t` method table, using a new FW object. + +### 2.1 Firmware Object Lifecycle + +There are two life cycles that need to be supported. + +#### 2.1.1 Firmware loaded during switch create +Depending on the functionality provided, a firmware may need to be loaded during the switch creation process itself. + +A create only switch attribute SAI_SWITCH_ATTR_FW_LIST is added to specify the details of firmware during switch create time. + +NOS will specify the list of firmwares in sai_fw_list_t data structure. Each element in a list specifies +- name of the firmware with the fully qualified path +- logfile name with the fully qualified path +- core id on which it is running. IDs are linear integer name space 0, 1,2 and so on +- administrative state of the firmware + +``` + /** + * @brief Firmware list + * + * @type sai_fw_list_t + * @flags CREATE_ONLY + * @default internal + */ + SAI_SWITCH_ATTR_FW_LIST, + + /** + * @brief Firmware enabled on the switch + * + * @type sai_object_list_t + * @flags READ_ONLY + * @objects SAI_OBJECT_TYPE_FW + */ + SAI_SWITCH_ATTR_FW, + + /** + * @brief Maximum number of cores supported + * + * @type sai_uint8_t + * @flags READ_ONLY + */ + SAI_SWITCH_ATTR_MAX_FW_CORES, +``` + +New data type specifies the necessary information for loading and starting the firware. +``` +/** + * @brief SAI firmware administrative state + */ +typedef enum _sai_fw_admin_state_t +{ + /** Firmware admin state is automatic loading and running */ + SAI_FW_ADMIN_STATE_AUTO, + + /** Firmware admin state to start the firmware */ + SAI_FW_ADMIN_STATE_START_FW, + + /** Firmware admin state is stop the firmware */ + SAI_FW_ADMIN_STATE_STOP_FW, + + /** Firmware admin state is load the firmware */ + SAI_FW_ADMIN_STATE_LOAD_FW, + + /** Firmware admin state is unload the firmware */ + SAI_FW_ADMIN_STATE_UNLOAD_FW, +} sai_fw_admin_state_t; + +/** + * @brief Defines a firmware instance + */ +typedef struct _sai_fw_inst_t +{ + /** Firmware path */ + sai_s8_list_t fw_path_name; + + /** Firmware log file path */ + sai_s8_list_t log_path_name; + + /** Firmware core id */ + uint8_t core_id; + + /** Firmware admin state */ + sai_fw_admin_state_t admin_state; +} sai_fw_inst_t; + +/** + * @brief Defines a list of firmware instances + */ +typedef struct _sai_fw_list_t +{ + /** Number of firmware instances */ + uint32_t count; + + /** List of firmware instances */ + sai_fw_inst_t *list; +} sai_fw_list_t; +``` + +Sequence of sets to load and start the firmware during switch create: + +```text +Set SAI_SWITCH_ATTR_FW_LIST attribute + | + v + [sai_s8_list_t fw_path_name] + [sai_s8_list_t log_path_name] + [uint8_t core_id] + [sai_fw_admin_state_t admin_state] + | + v +Set Other Switch Attributes + | + v +Create Switch Object + | + v +SDK Start Firmware based on configured admin state during switch create + | + v ++---------+---------+---------+---------+ +| | | | | +v v v v v +Auto Start Stop Load UnLoad + +``` + +> In this workflow SAI allocates the new instance of SAI_OBJECT_TYPE_FW object, based on the attribute SAI_SWITCH_ATTR_FW_LIST. + +#### 2.1.2 Runtime loading of firmware +This is the case where system is up and running and a firmware need to be loaded on one of the controllers. + +New object type SAI_OBJECT_TYPE_FW is introduced to manage the loading or unloading of firnware instances. NOS must create a SAI_OBJECT_TYPE_FW for each firmware. Based on the admin state configured SAI adapter will either just load the firmware or start it. + +``` +typedef enum _sai_fw_attr_t +{ + /** + * @brief Start of Attributes + */ + SAI_FW_ATTR_START, + + /** + * @brief Firmware Log File and Path Name [char[SAI_FW_NAME_SIZE]] + * + * The maximum number of characters for the name is SAI_FW_NAME_SIZE - 1 since + * it needs the terminating null byte ('\0') at the end. + * + * @type char + * @flags CREATE_AND_SET + * @default "" + */ + SAI_FW_ATTR_LOG_FILE_AND_PATH_NAME = SAI_FW_ATTR_START, + + /** + * @brief Firmware File and Path Name [char[SAI_FW_NAME_SIZE]] + * + * The maximum number of characters for the name is SAI_FW_NAME_SIZE - 1 since + * it needs the terminating null byte ('\0') at the end. + * + * @type char + * @flags CREATE_AND_SET + * @default "" + */ + SAI_FW_ATTR_FW_FILE_AND_PATH_NAME, + + /** + * @brief Firmware to be loaded on the core + * + * @type sai_uint8_t + * @flags CREATE_AND_SET + * @default 0 + */ + SAI_FW_ATTR_CORE_ID, + + /** + * @brief Firmware admin state + * + * @type sai_fw_admin_state_t + * @flags CREATE_AND_SET + * @default SAI_FW_ADMIN_STATE_AUTO + */ + SAI_FW_ATTR_FW_ADMIN_STATE, + + /** + * @brief Firmware operational state + * + * @type sai_fw_op_state_t + * @flags READ_ONLY + */ + SAI_FW_ATTR_FW_OP_STATE, + + /** + * @brief Firmware major version + * + * @type sai_uint32_t + * @flags READ_ONLY + */ + SAI_FW_ATTR_FW_MAJOR_VERSION, + + /** + * @brief Firmware minor version + * + * @type sai_uint32_t + * @flags READ_ONLY + */ + SAI_FW_ATTR_FW_MINOR_VERSION, + + /** + * @brief End of Performance Monitoring attributes + */ + SAI_FW_ATTR_END, + + /** Custom range base value */ + SAI_FW_ATTR_CUSTOM_RANGE_START = 0x10000000, + + /** End of custom range base */ + SAI_FW_ATTR_CUSTOM_RANGE_END + +} sai_fw_attr_t; + +``` +--- + +## 3.0 Firmware States + +### 3.1 Administrative State + +Followin administrative states are defined to manage the life cycle of the firmware. Admin state is specified in the SAI_FW_ATTR_FW_INST attribute which is of data type sai_fw_inst_t. + +Administrative state controls firmware behavior. + +| State | Description | +| --------------------------- | ----------------------------------- | +| SAI_FW_ADMIN_STATE_AUTO | Automatically load and run firmware | +| SAI_FW_ADMIN_STATE_START_FW | Explicitly start firmware | +| SAI_FW_ADMIN_STATE_STOP_FW | Explicitly stop firmware | +| SAI_FW_ADMIN_STATE_LOAD_FW | Only load the firmware | +| SAI_FW_ADMIN_STATE_UNLOAD_FW| Only unload the firmware. | + + +--- + +### 3.2 Operational State + +Once firmware is loaded, NOS need to know its operational state. Operational state is queried using the attribute SAI_FW_ATTR_FW_OP_STATE which is of the data type sai_fw_op_state_t. +Operational state indicates the firmware state. + +| State | Description | +| -------------------------- | ------------------------------- | +| SAI_FW_OP_STATE_LOADED | Firmware loaded but not started | +| SAI_FW_OP_STATE_NOT_LOADED | Firmware unavailable and not loaded| +| SAI_FW_OP_STATE_RUNNING | Firmware loaded and running | +| SAI_FW_OP_STATE_STOPPED | Firmware loaded but stopped | +| SAI_FW_OP_STATE_ERROR | Firmware loaded and encountered an error | + +``` +/** + * @brief SAI firmware operational state + */ +typedef enum _sai_fw_op_state_t +{ + /** Firmware operational state is firmware is loaded but not started */ + SAI_FW_OP_STATE_LOADED, + + /** Firmware operational state is firmware is not loaded */ + SAI_FW_OP_STATE_NOT_LOADED, + + /** Firmware operational state is running */ + SAI_FW_OP_STATE_RUNNING, + + /** Firmware operational state is stop */ + SAI_FW_OP_STATE_STOPPED, + + /** Firmware operational state is in error */ + SAI_FW_OP_STATE_ERROR, +} sai_fw_op_state_t; +``` + +--- + +## 4.0 Example Workflow + +This section describes workflow for various scenarios. + +### 4.1 Workflow for Cold Boot and Start two firmware during switch create +This is the case where firmware is loaded during switch create and switch attributes are specified. + +#### 4.1.1 Configure the switch attribute for loading firmware + +``` +// Specify the TAM event type for packet drops +sai_attr_list[0].id = SAI_SWITCH_ATTR_FW_LIST; +sai_attr_list[0].count = 2; + +sai_attr_list[0].list[0].value.fw_path_name = /mnt/fw/mon-fw.srec; +sai_attr_list[0].list[0].value.log_path_name = /mnt/log/fw/mon-fw.log; +sai_attr_list[0].list[0].value.core_id = 0; +sai_attr_list[0].list[0].value.admin_state = SAI_FW_ADMIN_STATE_AUTO; + +sai_attr_list[0].list[1].value.fw_path_name = /mnt/fw/api-perf-fw.srec;; +sai_attr_list[0].list[1].value.log_path_name = /mnt/log/fw/api-perf-fw.log; +sai_attr_list[0].list[1].value.core_id = 1; +sai_attr_list[0].list[1].value.admin_state = SAI_FW_ADMIN_STATE_AUTO; +``` + +> SAI Adapter will create two oids of type SAI_OBJECT_TYPE_FW e.g. OID-FW-1 and OID-FW-2 + +#### 4.1.2 Read the configured FW objects in the system +NOS will do a get API call for attribute SAI_SWITCH_ATTR_FW. +This will return two OIDs as OID-FW-1 and OID-FW-2. + +``` +sai_attribute_t attr; + +attr.id = SAI_SWITCH_ATTR_FW_LIST; + +status = fw_api->get_switch_attribute( + switchid, + 1, + &attr); + +Result: +attr.count = 2 +attr.list[0] = OID-FW-1 +attr.list[1] = OID-FW-2 +``` + +#### 4.1.3 Read the operational state of the firmware +NOS can get the state and list of FW OIDs using the GET API. + +``` +sai_attribute_t attr; + +attr.id = SAI_FW_ATTR_FW_OP_STATE; + +status = fw_api->get_fw_attribute( + OID-FW-1, + 1, + &attr); +Result: +SAI_FW_OP_STATE_RUNNING + +status = fw_api->get_fw_attribute( + OID-FW-2, + 1, + &attr); +Result: +SAI_FW_OP_STATE_RUNNING +``` +### 4.2 Workflow for Runtime configuration of two firmware +This is the case where firmware is loaded after the switch create is done. This workflow is applicable for frmware function that can be started after the switch create and init is done and have no dependency on switch init state. + +#### 4.1.1 Create SAI_OBJECT_TYPE_FW objects for each firmware + +``` +// Specify the firmware log file name and path +sai_attr_list[0].id = SAI_FW_ATTR_LOG_FILE_AND_PATH_NAME; +sai_attr_list[0].value.char = "/mnt/log/fw/mon-fw.log\0"; + +// Specify the firmware image file name and path +sai_attr_list[1].id = SAI_FW_ATTR_FW_FILE_AND_PATH_NAME; +sai_attr_list[1].value.char = "/mnt/log/fw/mon-fw.srec\0"; + +// Specify the administrative state of the firmware +sai_attr_list[2].id = SAI_FW_ATTR_FW_ADMIN_STATE; +sai_attr_list[2].value.s32 = SAI_FW_ADMIN_STATE_AUTO; + +// Specify the core id +sai_attr_list[3].id = SAI_FW_ATTR_CORE_ID; +sai_attr_list[3].value.u8 = 0; + +// Create firmware object +attr_count = 4; +create_fw( + &sai_mon_fw_obj, + switch_id, + attr_count, + sai_attr_list); + +// Create firmware object for 2nd firmware + +// Specify the firmware log file name and path +sai_attr_list[0].id = SAI_FW_ATTR_LOG_FILE_AND_PATH_NAME; +sai_attr_list[0].value.char = "/mnt/log/fw/api-perf-fw.log\0"; + +// Specify the firmware image file name and path +sai_attr_list[1].id = SAI_FW_ATTR_FW_FILE_AND_PATH_NAME; +sai_attr_list[1].value.char = "/mnt/log/fw/api-perf-fw.srec\0"; + +// Specify the administrative state of the firmware +sai_attr_list[2].id = SAI_FW_ATTR_FW_ADMIN_STATE; +sai_attr_list[2].value.s32 = SAI_FW_ADMIN_STATE_AUTO; + +// Specify the core id +sai_attr_list[3].id = SAI_FW_ATTR_CORE_ID; +sai_attr_list[3].value.u8 = 0; + +// Create firmware object +attr_count = 4; +create_fw( + &sai_api_perf_fw_obj, + switch_id, + attr_count, + sai_attr_list); +``` +#### 4.2.2 Read the operational state and the version of the firmware +NOS will perform a GET for the operational state for each OID. + +``` +sai_attribute_t attr; + +attr[0].id = SAI_FW_ATTR_FW_OP_STATE; +attr[1].id = SAI_FW_ATTR_FW_MAJOR_VERSION; +attr[2].id = SAI_FW_ATTR_FW_MINOR_VERSION; + +status = fw_api->get_fw_attribute( + sai_mon_fw_obj, + 3, + &attr); +Result: +SAI_FW_OP_STATE_RUNNING +1 +12 + +status = fw_api->get_fw_attribute( + sai_mon, + 3, + &attr); +Result: +SAI_FW_OP_STATE_RUNNING +1 +18 +``` + +### 4.3 Workflow for Warmboot transition from no firmware to two firmwares +This is the case where new set of firmware need to be installed after the warmboot. +If the firmware is such that it can be installed after the switch create then no new workflow is required as it will be considered a post warmboot configuration change. But if the requirement is to load the firmware immediately after warmboot then it must be configured as part of swtich create. + +This will follow the same steps as in section 4.1 + +### 4.4 Workflow for Warmboot transition from one firmware to two firmwares +This is the case where another firmware is added after the warmboot. +This is same as section 4.3 where NOS need to retain the previously configured firmware and add another one. + +> Section 4.3 and 4.4 will create new OID post warmboot and any implications of this need to be handled by orchagent. + +### 4.4 Workflow for Warmboot transition from two firmwares of ver1 to two firmwares of ver2 +This is a simpler case where there are no new OIDs are created post warmboot but only the attributes are changed from ver 1 to ver 2 post warmboot. + + +### 4.5 Workflow for Create and Auto-Start Firmware + + +#### 4.5.1 Example + +```c +sai_attribute_t attrs[2]; + +... other attributes are set ... + +attrs[1].id = SAI_FW_ATTR_FW_ADMIN_STATE; +attrs[1].value.s32 = SAI_FW_ADMIN_STATE_AUTO; + +sai_object_id_t fw_id; + +status = fw_api->create_fw( + &fw_id, + switch_id, + 2, + attrs); +``` +#### 4.5.2 Expected Result + +```text +Firmware Object Created +Firmware Loaded +Firmware Running +Operational State = RUNNING +``` + +--- + +### 4.6 Workflow to manage Firmware lifecycle manually + +#### 4.6.1 Create Firmware with admin state as LOAD + +This will only load the firmware. If there is a previously loaded firmware and is not unloaded, this API sequence must return error. + +```c +attrs[1].id = SAI_FW_ATTR_FW_ADMIN_STATE; +attrs[1].value.s32 = SAI_FW_ADMIN_STATE_LOAD_FW; + +fw_api->set_fw_attribute( + fw_id, + &attr); +``` + +#### 4.6.1.1 Result + +```text +Firmware Loaded +Operational State = LOADED +``` + +--- + +#### 4.6.2 Workflow to Start Firmware +This will start running the loaded firmware. If there is no firmware loaded and NOS is strying to set the admin state as START, SAI adapter must return error. + +```c +sai_attribute_t attr; + +attr.id = SAI_FW_ATTR_FW_ADMIN_STATE; +attr.value.s32 = SAI_FW_ADMIN_STATE_START_FW; + +fw_api->set_fw_attribute( + fw_id, + &attr); +``` + +#### 4.6.2.1 Result + +```text +Firmware Running +Operational State = RUNNING +``` + +--- + +### 4.6.3 Workflow to Stop Firmware +This will stop the running firmware but not unload it. If there is no firmware loaded, or the state of firmware of not RUNNING and NOS is strying to set the admin state as STOP, SAI adapter must return error. + +``` +sai_attribute_t attr; + +attr.id = SAI_FW_ATTR_FW_ADMIN_STATE; +attr.value.s32 = SAI_FW_ADMIN_STATE_STOP_FW; + +fw_api->set_fw_attribute( + fw_id, + &attr); +``` +#### 4.6.3.1 Result + +```text +Firmware Running +Operational State = STOPPED +``` +--- +#### 4.6.4 Create Firmware with admin state as UNLOAD + +This will unload the firmware. If there is a no previously loaded firmware, this API sequence must return error. + +```c +attrs[1].id = SAI_FW_ATTR_FW_ADMIN_STATE; +attrs[1].value.s32 = SAI_FW_ADMIN_STATE_UNLOAD_FW; + +fw_api->set_fw_attribute( + fw_id, + &attr); +``` + +#### 4.6.4.1 Result + +```text +Firmware UnLoaded +Operational State = UNLOADED +``` + +--- + +### 4.6.5 Workflow to Query Firmware Status + + +```c +sai_attribute_t attr; + +attr.id = SAI_FW_ATTR_FW_OP_STATE; + +status = fw_api->get_fw_attribute( + fw_id, + 1, + &attr); +``` + +#### 4.6.5.1 Result + +```c +switch(attr.value.s32) +{ + case SAI_FW_OP_STATE_LOADED: + printf("Firmware Loaded\n"); + break; + case SAI_FW_OP_STATE_UNLOADED: + printf("Firmware Unloaded\n"); + break; + case SAI_FW_OP_STATE_RUNNING: + printf("Firmware Running\n"); + break; + + case SAI_FW_OP_STATE_STOPPED: + printf("Firmware Stopped\n"); + break; + + case SAI_FW_OP_STATE_ERROR: + printf("Firmware Error\n"); + break; +} +``` + diff --git a/inc/sai.h b/inc/sai.h index bfeb264fa..862e79a30 100644 --- a/inc/sai.h +++ b/inc/sai.h @@ -32,6 +32,7 @@ #include "saibuffer.h" #include "saicounter.h" #include "saifdb.h" +#include "saifw.h" #include "saihash.h" #include "saihostif.h" #include "saiipmcgroup.h" @@ -157,6 +158,7 @@ typedef enum _sai_api_t SAI_API_SYNCE = 54, /**< sai_synce_api_t */ SAI_API_VIRTUAL_CHANNEL = 55, /**< sai_virtual_channel_api_t */ SAI_API_PERFMON = 56, /**< sai_perfmon_api_t */ + SAI_API_FW = 57, /**< sai_fw_api_t */ SAI_API_MAX, /**< total number of APIs */ /** diff --git a/inc/saifw.h b/inc/saifw.h new file mode 100644 index 000000000..3b7a18960 --- /dev/null +++ b/inc/saifw.h @@ -0,0 +1,217 @@ +/** + * Copyright (c) 2014 Microsoft Open Technologies, Inc. + * + * 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. + * + * Microsoft would like to thank the following companies for their review and + * assistance with these files: Intel Corporation, Mellanox Technologies Ltd, + * Dell Products, L.P., Facebook, Inc., Marvell International Ltd. + * + * @file saifw.h + * + * @brief This module defines SAI Firmware spec + */ + +#if !defined (__SAIFW_H_) +#define __SAIFW_H_ + +#include + +/** + * @defgroup SAIFW SAI - Firmware specific API definitions + * + * @{ + */ + +/** + * @brief SAI firmware operational state + */ +typedef enum _sai_fw_op_state_t +{ + /** Firmware operational state is firmware is loaded but not started */ + SAI_FW_OP_STATE_LOADED, + + /** Firmware operational state is firmware is not loaded */ + SAI_FW_OP_STATE_NOT_LOADED, + + /** Firmware operational state is running */ + SAI_FW_OP_STATE_RUNNING, + + /** Firmware operational state is stop */ + SAI_FW_OP_STATE_STOPPED, + + /** Firmware operational state is in error */ + SAI_FW_OP_STATE_ERROR, +} sai_fw_op_state_t; + +/** + * @brief Defines maximum length of firmware and log file name + */ +#define SAI_FW_NAME_SIZE 64 + +/** + * @brief Firmware Attributes + */ +typedef enum _sai_fw_attr_t +{ + /** + * @brief Start of Attributes + */ + SAI_FW_ATTR_START, + + /** + * @brief Firmware Log File and Path Name [char[SAI_FW_NAME_SIZE]] + * + * The maximum number of characters for the name is SAI_FW_NAME_SIZE - 1 since + * it needs the terminating null byte ('\0') at the end. + * + * @type char + * @flags CREATE_AND_SET + * @default "" + */ + SAI_FW_ATTR_LOG_FILE_AND_PATH_NAME = SAI_FW_ATTR_START, + + /** + * @brief Firmware File and Path Name [char[SAI_FW_NAME_SIZE]] + * + * The maximum number of characters for the name is SAI_FW_NAME_SIZE - 1 since + * it needs the terminating null byte ('\0') at the end. + * + * @type char + * @flags CREATE_AND_SET + * @default "" + */ + SAI_FW_ATTR_FW_FILE_AND_PATH_NAME, + + /** + * @brief Firmware to be loaded on the core + * + * @type sai_uint8_t + * @flags CREATE_AND_SET + * @default 0 + */ + SAI_FW_ATTR_CORE_ID, + + /** + * @brief Firmware admin state + * + * @type sai_fw_admin_state_t + * @flags CREATE_AND_SET + * @default SAI_FW_ADMIN_STATE_AUTO + */ + SAI_FW_ATTR_FW_ADMIN_STATE, + + /** + * @brief Firmware operational state + * + * @type sai_fw_op_state_t + * @flags READ_ONLY + */ + SAI_FW_ATTR_FW_OP_STATE, + + /** + * @brief Firmware major version + * + * @type sai_uint32_t + * @flags READ_ONLY + */ + SAI_FW_ATTR_FW_MAJOR_VERSION, + + /** + * @brief Firmware minor version + * + * @type sai_uint32_t + * @flags READ_ONLY + */ + SAI_FW_ATTR_FW_MINOR_VERSION, + + /** + * @brief End of Performance Monitoring attributes + */ + SAI_FW_ATTR_END, + + /** Custom range base value */ + SAI_FW_ATTR_CUSTOM_RANGE_START = 0x10000000, + + /** End of custom range base */ + SAI_FW_ATTR_CUSTOM_RANGE_END + +} sai_fw_attr_t; + +/** + * @brief Create firmware object + * + * @param[out] fw_id Firmware id + * @param[in] switch_id Switch id + * @param[in] attr_count Number of attributes + * @param[in] attr_list Array of attributes + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_create_fw_fn)( + _Out_ sai_object_id_t *fw_id, + _In_ sai_object_id_t switch_id, + _In_ uint32_t attr_count, + _In_ const sai_attribute_t *attr_list); + +/** + * @brief Remove firmware object + * + * @param[in] fw_id Firmware id + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_remove_fw_fn)( + _In_ sai_object_id_t fw_id); + +/** + * @brief Set firmware attribute + * + * @param[in] fw_id Firmware id + * @param[in] attr Attribute + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_set_fw_attribute_fn)( + _In_ sai_object_id_t fw_id, + _In_ const sai_attribute_t *attr); + +/** + * @brief Get Firmware attribute + * + * @param[in] fw_id Firmware ID + * @param[in] attr_count Number of attributes + * @param[inout] attr_list Array of attributes + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_get_fw_attribute_fn)( + _In_ sai_object_id_t fw_id, + _In_ uint32_t attr_count, + _Inout_ sai_attribute_t *attr_list); + +/** + * @brief Firmware related API methods table retrieved with sai_api_query() + */ +typedef struct _sai_fw_api_t +{ + sai_create_fw_fn create_fw; + sai_remove_fw_fn remove_fw; + sai_set_fw_attribute_fn set_fw_attribute; + sai_get_fw_attribute_fn get_fw_attribute; +} sai_fw_api_t; + +/** + * @} + */ +#endif /** __SAIFW_H_ */ diff --git a/inc/saiswitch.h b/inc/saiswitch.h index d3f8edeb6..70eec5fda 100644 --- a/inc/saiswitch.h +++ b/inc/saiswitch.h @@ -3652,6 +3652,32 @@ typedef enum _sai_switch_attr_t */ SAI_SWITCH_ATTR_TAM_EVENT_LEARN_NOTIFY, + /** + * @brief Firmware list + * + * @type sai_fw_list_t + * @flags CREATE_ONLY + * @default internal + */ + SAI_SWITCH_ATTR_FW_LIST, + + /** + * @brief Firmware enabled on the switch + * + * @type sai_object_list_t + * @flags READ_ONLY + * @objects SAI_OBJECT_TYPE_FW + */ + SAI_SWITCH_ATTR_FW, + + /** + * @brief Maximum number of cores supported + * + * @type sai_uint8_t + * @flags READ_ONLY + */ + SAI_SWITCH_ATTR_MAX_FW_CORES, + /** * @brief End of attributes */ diff --git a/inc/saitypes.h b/inc/saitypes.h index 6e542c46d..f22ad1f87 100644 --- a/inc/saitypes.h +++ b/inc/saitypes.h @@ -308,6 +308,7 @@ typedef enum _sai_object_type_t SAI_OBJECT_TYPE_CBFC_CREDIT_PROFILE = 118, SAI_OBJECT_TYPE_PERFMON = 119, SAI_OBJECT_TYPE_TAM_EVENT_LEARN_ENTRY = 120, + SAI_OBJECT_TYPE_FW = 121, /** Must remain in last position */ SAI_OBJECT_TYPE_MAX, @@ -422,6 +423,57 @@ typedef struct _sai_taps_list_t sai_s32_list_t *list; } sai_taps_list_t; +/** + * @brief SAI firmware administrative state + */ +typedef enum _sai_fw_admin_state_t +{ + /** Firmware admin state is automatic loading and running */ + SAI_FW_ADMIN_STATE_AUTO, + + /** Firmware admin state to start the firmware */ + SAI_FW_ADMIN_STATE_START_FW, + + /** Firmware admin state is stop the firmware */ + SAI_FW_ADMIN_STATE_STOP_FW, + + /** Firmware admin state is load the firmware */ + SAI_FW_ADMIN_STATE_LOAD_FW, + + /** Firmware admin state is unload the firmware */ + SAI_FW_ADMIN_STATE_UNLOAD_FW, +} sai_fw_admin_state_t; + +/** + * @brief Defines a firmware instance + */ +typedef struct _sai_fw_inst_t +{ + /** Firmware path */ + sai_s8_list_t fw_path_name; + + /** Firmware log file path */ + sai_s8_list_t log_path_name; + + /** Firmware core id */ + uint8_t core_id; + + /** Firmware admin state */ + sai_fw_admin_state_t admin_state; +} sai_fw_inst_t; + +/** + * @brief Defines a list of firmware instances + */ +typedef struct _sai_fw_list_t +{ + /** Number of firmware instances */ + uint32_t count; + + /** List of firmware instances */ + sai_fw_inst_t *list; +} sai_fw_list_t; + typedef enum _sai_ip_addr_family_t { SAI_IP_ADDR_FAMILY_IPV4, @@ -1844,6 +1896,12 @@ typedef union _sai_attribute_value_t /** @validonly meta->attrvaluetype == SAI_ATTR_VALUE_TYPE_UINT64_RANGE_LIST */ sai_u64_range_list_t u64rangelist; + /** @validonly meta->attrvaluetype == SAI_ATTR_VALUE_TYPE_FW_INST */ + sai_fw_inst_t fwinst; + + /** @validonly meta->attrvaluetype == SAI_ATTR_VALUE_TYPE_FW_LIST */ + sai_fw_list_t fwlist; + /** @validonly meta->attrvaluetype == SAI_ATTR_VALUE_TYPE_PORT_ILT_LANE_TRAINING_STATUS_LIST */ sai_port_ilt_lane_training_status_list_t port_ilt_lane_training_status_list; diff --git a/meta/parse.pl b/meta/parse.pl index 9386df890..dd184905a 100755 --- a/meta/parse.pl +++ b/meta/parse.pl @@ -1751,6 +1751,10 @@ sub ProcessDefaultValue { WriteSource "$val = { .chardata = { 0 } };"; } + elsif ($default =~ /^0$/ and $type =~ /^(sai_fw_inst_t)/) + { + WriteSource "$val = { 0 };"; + } elsif ($default =~ /^0\.0\.0\.0$/ and $type =~ /^(sai_ip4_t)/) { WriteSource "$val = { 0 };"; diff --git a/meta/saimetadatatypes.h b/meta/saimetadatatypes.h index 27b0d05c7..51450f17a 100644 --- a/meta/saimetadatatypes.h +++ b/meta/saimetadatatypes.h @@ -544,7 +544,17 @@ typedef enum _sai_attr_value_type_t /** * @brief Attribute value is 64 bit unsigned integer range list. */ - SAI_ATTR_VALUE_TYPE_UINT64_RANGE_LIST + SAI_ATTR_VALUE_TYPE_UINT64_RANGE_LIST, + + /** + * @brief Attribute value is firmware instance. + */ + SAI_ATTR_VALUE_TYPE_FW_INST, + + /** + * @brief Attribute value is firmware list. + */ + SAI_ATTR_VALUE_TYPE_FW_LIST, } sai_attr_value_type_t; /** diff --git a/meta/saisanitycheck.c b/meta/saisanitycheck.c index dbeeb8962..5710354de 100644 --- a/meta/saisanitycheck.c +++ b/meta/saisanitycheck.c @@ -852,6 +852,8 @@ void check_attr_object_type_provided( case SAI_ATTR_VALUE_TYPE_ACL_CHAIN_LIST: case SAI_ATTR_VALUE_TYPE_POE_PORT_POWER_CONSUMPTION: case SAI_ATTR_VALUE_TYPE_TAPS_LIST: + case SAI_ATTR_VALUE_TYPE_FW_INST: + case SAI_ATTR_VALUE_TYPE_FW_LIST: case SAI_ATTR_VALUE_TYPE_PRBS_PER_LANE_RX_STATUS_LIST: case SAI_ATTR_VALUE_TYPE_PRBS_PER_LANE_RX_STATE_LIST: case SAI_ATTR_VALUE_TYPE_PRBS_BIT_ERROR_RATE: @@ -1083,6 +1085,7 @@ void check_attr_default_required( case SAI_ATTR_VALUE_TYPE_IPV4: case SAI_ATTR_VALUE_TYPE_SYSTEM_PORT_CONFIG: case SAI_ATTR_VALUE_TYPE_IPV6: + case SAI_ATTR_VALUE_TYPE_FW_INST: break; case SAI_ATTR_VALUE_TYPE_CHARDATA: @@ -1124,9 +1127,9 @@ void check_attr_default_required( case SAI_ATTR_VALUE_TYPE_IP_PREFIX_LIST: case SAI_ATTR_VALUE_TYPE_ACL_CHAIN_LIST: case SAI_ATTR_VALUE_TYPE_TAPS_LIST: + case SAI_ATTR_VALUE_TYPE_FW_LIST: - if (((md->objecttype == SAI_OBJECT_TYPE_PORT) || (md->objecttype == SAI_OBJECT_TYPE_PORT_SERDES)) - && md->defaultvaluetype == SAI_DEFAULT_VALUE_TYPE_SWITCH_INTERNAL) + if (((md->objecttype == SAI_OBJECT_TYPE_PORT) || (md->objecttype == SAI_OBJECT_TYPE_PORT_SERDES) || (md->objecttype == SAI_OBJECT_TYPE_SWITCH)) && md->defaultvaluetype == SAI_DEFAULT_VALUE_TYPE_SWITCH_INTERNAL) { /* * Allow non object lists on PORT to be set to internal default value. @@ -1381,6 +1384,7 @@ void check_attr_default_value_type( case SAI_DEFAULT_VALUE_TYPE_SWITCH_INTERNAL: if ((md->objecttype == SAI_OBJECT_TYPE_PORT) || + (md->objecttype == SAI_OBJECT_TYPE_SWITCH) || (md->objecttype == SAI_OBJECT_TYPE_PORT_SERDES) || (md->objecttype == SAI_OBJECT_TYPE_SAMPLEPACKET) || (md->objecttype == SAI_OBJECT_TYPE_NEIGHBOR_ENTRY)) @@ -3004,6 +3008,7 @@ void check_attr_is_primitive( case SAI_ATTR_VALUE_TYPE_IP_PREFIX_LIST: case SAI_ATTR_VALUE_TYPE_ACL_CHAIN_LIST: case SAI_ATTR_VALUE_TYPE_TAPS_LIST: + case SAI_ATTR_VALUE_TYPE_FW_LIST: case SAI_ATTR_VALUE_TYPE_PRBS_PER_LANE_RX_STATUS_LIST: case SAI_ATTR_VALUE_TYPE_PRBS_PER_LANE_RX_STATE_LIST: case SAI_ATTR_VALUE_TYPE_PRBS_PER_LANE_BIT_ERROR_RATE_LIST: @@ -3072,6 +3077,7 @@ void check_attr_is_primitive( case SAI_ATTR_VALUE_TYPE_LATCH_STATUS: case SAI_ATTR_VALUE_TYPE_POE_PORT_POWER_CONSUMPTION: case SAI_ATTR_VALUE_TYPE_PRBS_BIT_ERROR_RATE: + case SAI_ATTR_VALUE_TYPE_FW_INST: if (!md->isprimitive) { @@ -5558,6 +5564,19 @@ void check_graph_connected() continue; } + if (SAI_OBJECT_TYPE_FW == idx2ot(i)) + { + /* + * Allow firmware object to be disconnected from main graph + * as use case is by querying base object stats and not by direct reference + */ + + META_LOG_WARN("firmware object %s is disconnected from graph", + sai_metadata_all_object_type_infos[i]->objecttypename); + + continue; + } + if (SAI_OBJECT_TYPE_DEBUG_COUNTER == idx2ot(i)) { /* @@ -6429,6 +6448,7 @@ void check_struct_and_union_size() CHECK_STRUCT_SIZE(sai_prbs_bit_error_rate_t, 16); CHECK_STRUCT_SIZE(sai_prbs_per_lane_bit_error_rate_list_t, 16); CHECK_STRUCT_SIZE(sai_tam_event_learn_notification_data_t, 24); + CHECK_STRUCT_SIZE(sai_fw_list_t, 16) } #pragma GCC diagnostic pop