[meta] Proposal to support custom vendor headers

azure-pipelines.yml

@@ -42,6 +42,13 @@ stages:
         cd meta
         make
       displayName: "Metadata check"
+    - script: |
+        set -ex
+        export ANSI_COLORS_DISABLED=1
+        cp doc/custom-headers/sai*.h custom/
+        cd meta
+        make
+      displayName: "Metadata check with custom"
     - script: |
         set -ex
         export ANSI_COLORS_DISABLED=1

custom/README.md

@@ -0,0 +1,9 @@
+SAI Custom Headers Directory
+==============================================
+
+This directory should contains vendor specific custom headers
+that are considered vendor internal and should not be available
+to public, but they still can have metadata generated for them
+for vendor internal use.
+
+For more information reffer to doc/custom-headers

doc/custom-headers/README.md

@@ -0,0 +1,22 @@
+Proposal for SAI Custom Headers Directory
+==============================================
+
+SAI/custom is designed to hold custom headers provided by vendors.
+
+By default this directory is empty, and no custom headers are present.  If
+vendor want to provide custom headers, it can just simply copy custom headers
+to that directory, and automatically that directory will be used by meta parser
+to generate metadata for custom headers as well.
+
+There is requirement that custom headers must still follow style convention
+as regular headers.
+
+This directory SAI/doc/custom-headers contains sample custom headers and how
+they should look like. Base file is saicustom.h file which must be present if
+vendor wants to add custom headers.
+
+Custom headers, can extend existing object type, api, stats, attributes and
+provide new apis and totally new enums.
+
+Examing provided examples in this directory. If there will be problem with
+custom headers, meta parser will provide error/warning message.

doc/custom-headers/saicustom.h

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2024 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    saicustom.h
+ *
+ * @brief   This module defines custom of the Switch Abstraction Interface (SAI)
+ */
+
+#ifndef __SAICUSTOM_H_
+#define __SAICUSTOM_H_
+
+#include <sai.h>
+#include <saitypes.h>
+
+/* existing enum custom */
+#include "saitypescustom.h"
+#include "saiswitchcustom.h"
+#include "saiportcustom.h"
+
+/* new custom object type includes */
+#include "saicustomone.h"
+
+/**
+ * @brief Custom SAI APIs
+ *
+ * @flags free
+ */
+typedef enum _sai_api_custom_t
+{
+    SAI_API_CUSTOM_RANGE_START = SAI_API_CUSTOM_RANGE_BASE,
+
+    SAI_API_ONE = SAI_API_CUSTOM_RANGE_START,
+
+    /* Add new custom APIs above this line */
+
+    SAI_API_CUSTOM_RANGE_END
+
+} sai_api_custom_t;
+
+#endif /* __SAICUSTOM_H_ */

doc/custom-headers/saicustomone.h

@@ -0,0 +1,136 @@
+/**
+ * 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    saicustomone.h
+ *
+ * @brief   This module defines SAI custom for ONE
+ *
+ * @warning This module is a SAI custom module
+ */
+
+#if !defined (__SAICUSTOMONE_H_)
+#define __SAICUSTOMONE_H_
+
+#include <saitypescustom.h>
+
+/**
+ * @defgroup SAICUSTOMONE SAI - Custom ONE specific API definitions
+ *
+ * @{
+ */
+
+/**
+ * @brief Attribute ID for ONE
+ */
+typedef enum _sai_one_attr_t
+{
+    /**
+     * @brief Start of attributes
+     */
+    SAI_ONE_ATTR_START,
+
+    /**
+     * @brief First parameter
+     *
+     * @type sai_uint32_t
+     * @flags CREATE_AND_SET
+     * @default 0
+     */
+    SAI_ONE_ATTR_FIRST = SAI_ONE_ATTR_START,
+
+    /**
+     * @brief End of attributes
+     */
+    SAI_ONE_ATTR_END,
+
+    /* ironic */
+
+    /** Custom range base value */
+    SAI_ONE_ATTR_CUSTOM_RANGE_START = 0x10000000,
+
+    /** End of custom range base */
+    SAI_ONE_ATTR_CUSTOM_RANGE_END,
+
+} sai_one_attr_t;
+
+/**
+ * @brief Create ONE
+ *
+ * @param[out] one_id Entry 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_one_fn)(
+        _Out_ sai_object_id_t *one_id,
+        _In_ sai_object_id_t switch_id,
+        _In_ uint32_t attr_count,
+        _In_ const sai_attribute_t *attr_list);
+
+/**
+ * @brief Remove ONE
+ *
+ * @param[in] one_id Entry id
+ *
+ * @return #SAI_STATUS_SUCCESS on success Failure status code on error
+ */
+typedef sai_status_t (*sai_remove_one_fn)(
+        _In_ sai_object_id_t one_id);
+
+/**
+ * @brief Set attribute for ONE
+ *
+ * @param[in] one_id Entry id
+ * @param[in] attr Attribute
+ *
+ * @return #SAI_STATUS_SUCCESS on success Failure status code on error
+ */
+typedef sai_status_t (*sai_set_one_attribute_fn)(
+        _In_ sai_object_id_t one_id,
+        _In_ const sai_attribute_t *attr);
+
+/**
+ * @brief Get attribute for ONE
+ *
+ * @param[in] one_id Entry 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_one_attribute_fn)(
+        _In_ sai_object_id_t one_id,
+        _In_ uint32_t attr_count,
+        _Inout_ sai_attribute_t *attr_list);
+
+typedef struct _sai_one_api_t
+{
+    sai_create_one_fn           create_one;
+    sai_remove_one_fn           remove_one;
+    sai_set_one_attribute_fn    set_one_attribute;
+    sai_get_one_attribute_fn    get_one_attribute;
+
+} sai_one_api_t;
+
+/**
+ * @}
+ */
+#endif /** __CUSTOMONE_H_ */

doc/custom-headers/saiportcustom.h

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2018 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    saiportcustom.h
+ *
+ * @brief   This module defines port custom of the Switch Abstraction Interface (SAI)
+ */
+
+#ifndef __SAIPORTCUSTOM_H_
+#define __SAIPORTCUSTOM_H_
+
+#include <saiport.h>
+#include <saitypes.h>
+
+/**
+ * @brief SAI port attribute custom.
+ *
+ * @flags free
+ */
+typedef enum _sai_port_attr_custom_t
+{
+    /**
+     * @brief Custom 1
+     *
+     * @type sai_uint32_t
+     * @flags READ_ONLY
+     */
+    SAI_PORT_ATTR_CUSTOM1 = SAI_PORT_ATTR_CUSTOM_RANGE_START,
+
+    /* Add new csutom port attributes above this line */
+
+} sai_port_attr_custom_t;
+
+/**
+ * @brief SAI port stat custom.
+ *
+ * @flags free
+ */
+typedef enum _sai_port_stat_custom_t
+{
+    SAI_PORT_STAT_CUSTOM_RANGE_START = SAI_PORT_STAT_CUSTOM_RANGE_BASE,
+
+    SAI_PORT_STAT_CUSTOM1 = SAI_PORT_STAT_CUSTOM_RANGE_START,
+
+    SAI_PORT_STAT_CUSTOM2,
+
+    SAI_PORT_STAT_CUSTOM_RANGE_END
+
+} sai_port_stat_custom_t;
+
+#endif /* __SAIPORTCUSTOM_H_ */

doc/custom-headers/saiswitchcustom.h

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2018 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    saiswitchcustom.h
+ *
+ * @brief   This module defines switch custom of the Switch Abstraction Interface (SAI)
+ */
+
+#ifndef __SAISWITCHCUSTOM_H_
+#define __SAISWITCHCUSTOM_H_
+
+#include <saiswitch.h>
+#include <saitypescustom.h>
+
+/**
+ * @brief SAI switch attribute custom,
+ *
+ * @flags free
+ */
+typedef enum _sai_switch_attr_custom_t
+{
+    /**
+     * @brief Custom 1
+     *
+     * @type sai_uint32_t
+     * @flags READ_ONLY
+     */
+    SAI_SWITCH_ATTR_CUSTOM1 = SAI_SWITCH_ATTR_CUSTOM_RANGE_START,
+
+    /**
+     * @brief Custom 2
+     *
+     * @type sai_uint32_t
+     * @flags CREATE_AND_SET
+     * @default 0
+     */
+    SAI_SWITCH_ATTR_CUSTOM2,
+
+} sai_switch_attr_custom_t;
+
+#endif /* __SAISWITCHCUSTOM_H_ */