[meta] Proposal to support custom vendor headers

Directory custom should contain 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.

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_ */