text: /* SPDX-License-Identifier: BSD-3-Clause
   * Copyright(c) 2019-2021 Broadcom
   * All rights reserved.
   */
  
  #ifndef _TF_SHADOW_TBL_H_
  #define _TF_SHADOW_TBL_H_
  
  #include "tf_core.h"
  
  /**
   * The Shadow Table module provides shadow DB handling for table based
   * TF types. A shadow DB provides the capability that allows for reuse
   * of TF resources.
   *
   * A Shadow table DB is intended to be used by the Table Type module
   * only.
   */
  
  /**
   * Shadow DB configuration information for a single table type.
   *
   * During Device initialization the HCAPI device specifics are learned
   * and as well as the RM DB creation. From that those initial steps
   * this structure can be populated.
   *
   * NOTE:
   * If used in an array of table types then such array must be ordered
   * by the TF type is represents.
   */
  struct tf_shadow_tbl_cfg_parms {
  	/**
  	 * [in] The number of elements in the alloc_cnt and base_addr
  	 * For now, it should always be equal to TF_TBL_TYPE_MAX
  	 */
  	int num_entries;
  
  	/**
  	 * [in] Resource allocation count array
  	 * This array content originates from the tf_session_resources
  	 * that is passed in on session open
  	 * Array size is TF_TBL_TYPE_MAX
  	 */
  	uint16_t *alloc_cnt;
  	/**
  	 * [in] The base index for each table
  	 */
  	uint16_t base_addr[TF_TBL_TYPE_MAX];
  };
  
  /**
   * Shadow table DB creation parameters
   */
  struct tf_shadow_tbl_create_db_parms {
  	/**
  	 * [in] Receive or transmit direction
  	 */
  	enum tf_dir dir;
  	/**
  	 * [in] Configuration information for the shadow db
  	 */
  	struct tf_shadow_tbl_cfg_parms *cfg;
  	/**
  	 * [out] Shadow table DB handle
  	 */
  	void **shadow_db;
  };
  
  /**
   * Shadow table DB free parameters
   */
  struct tf_shadow_tbl_free_db_parms {
  	/**
  	 * [in] Shadow table DB handle
  	 */
  	void *shadow_db;
  };
  
  /**
   * Shadow table search parameters
   */
  struct tf_shadow_tbl_search_parms {
  	/**
  	 * [in] Shadow table DB handle
  	 */
  	void *shadow_db;
  	/**
  	 * [in,out] The search parms from tf core
  	 */
  	struct tf_tbl_alloc_search_parms *sparms;
  	/**
  	 * [out] Reference count incremented if hit
  	 */
  	uint32_t hb_handle;
  };
  
  /**
   * Shadow Table bind index parameters
   */
  struct tf_shadow_tbl_bind_index_parms {
  	/**
  	 * [in] Shadow tcam DB handle
  	 */
  	void *shadow_db;
  	/**
  	 * [in] receive or transmit direction
  	 */
  	enum tf_dir dir;
  	/**
  	 * [in] TCAM table type
  	 */
  	enum tf_tbl_type type;
  	/**
  	 * [in] index of the entry to program
  	 */
  	uint16_t idx;
  	/**
  	 * [in] struct containing key
  	 */
  	uint8_t *data;
  	/**
  	 * [in] data size in bytes
  	 */
  	uint16_t data_sz_in_bytes;
  	/**
  	 * [in] The hash bucket handled returned from the search
  	 */
  	uint32_t hb_handle;
  };
  
  /**
   * Shadow table insert parameters
   */
  struct tf_shadow_tbl_insert_parms {
  	/**
  	 * [in] Shadow table DB handle
  	 */
  	void *shadow_db;
  	/**
  	 * [in] The insert parms from tf core
  	 */
  	struct tf_tbl_set_parms *sparms;
  };
  
  /**
   * Shadow table remove parameters
   */
  struct tf_shadow_tbl_remove_parms {
  	/**
  	 * [in] Shadow table DB handle
  	 */
  	void *shadow_db;
  	/**
  	 * [in] The free parms from tf core
  	 */
  	struct tf_tbl_free_parms *fparms;
  };
  
  /**
   * @page shadow_tbl Shadow table DB
   *
   * @ref tf_shadow_tbl_create_db
   *
   * @ref tf_shadow_tbl_free_db
   *
   * @reg tf_shadow_tbl_search
   *
   * @reg tf_shadow_tbl_insert
   *
   * @reg tf_shadow_tbl_remove
   */
  
  /**
   * Creates and fills a Shadow table DB. The DB is indexed per the
   * parms structure.
   *
   * [in] parms
   *   Pointer to create db parameters
   *
   * Returns
   *   - (0) if successful.
   *   - (-EINVAL) on failure.
   */
  int tf_shadow_tbl_create_db(struct tf_shadow_tbl_create_db_parms *parms);
  
  /**
   * Closes the Shadow table DB and frees all allocated
   * resources per the associated database.
   *
   * [in] parms
   *   Pointer to the free DB parameters
   *
   * Returns
   *   - (0) if successful.
   *   - (-EINVAL) on failure.
   */
  int tf_shadow_tbl_free_db(struct tf_shadow_tbl_free_db_parms *parms);
  
  /**
   * Search Shadow table db for matching result
   *
   * [in] parms
   *   Pointer to the search parameters
   *
   * Returns
   *   - (0) if successful, element was found.
   *   - (-EINVAL) on failure.
   *
   * If there is a miss, but there is room for insertion, the hb_handle returned
   * is used for insertion during the bind index API
   */
  int tf_shadow_tbl_search(struct tf_shadow_tbl_search_parms *parms);
  
  /**
   * Bind Shadow table db hash and result tables with result from search/alloc
   *
   * [in] parms
   *   Pointer to the search parameters
   *
   * Returns
   *   - (0) if successful
   *   - (-EINVAL) on failure.
   *
   * This is only called after a MISS in the search returns a hb_handle
   */
  int tf_shadow_tbl_bind_index(struct tf_shadow_tbl_bind_index_parms *parms);
  
  /**
   * Inserts an element into the Shadow table DB. Will fail if the
   * elements ref_count is different from 0. Ref_count after insert will
   * be incremented.
   *
   * [in] parms
   *   Pointer to insert parameters
   *
   * Returns
   *   - (0) if successful.
   *   - (-EINVAL) on failure.
   */
  int tf_shadow_tbl_insert(struct tf_shadow_tbl_insert_parms *parms);
  
  /**
   * Removes an element from the Shadow table DB. Will fail if the
   * elements ref_count is 0. Ref_count after removal will be
   * decremented.
   *
   * [in] parms
   *   Pointer to remove parameter
   *
   * Returns
   *   - (0) if successful.
   *   - (-EINVAL) on failure.
   */
  int tf_shadow_tbl_remove(struct tf_shadow_tbl_remove_parms *parms);
  
  #endif /* _TF_SHADOW_TBL_H_ */
  