ethdev: add security context API documentation
[dpdk.git] / lib / librte_ether / rte_ethdev.h
index b10e2a9..2729e2b 100644 (file)
@@ -152,6 +152,7 @@ extern "C" {
 #include <rte_devargs.h>
 #include <rte_errno.h>
 #include <rte_common.h>
+#include <rte_config.h>
 
 #include "rte_ether.h"
 #include "rte_eth_ctrl.h"
@@ -233,17 +234,17 @@ __extension__
 struct rte_eth_link {
        uint32_t link_speed;        /**< ETH_SPEED_NUM_ */
        uint16_t link_duplex  : 1;  /**< ETH_LINK_[HALF/FULL]_DUPLEX */
-       uint16_t link_autoneg : 1;  /**< ETH_LINK_SPEED_[AUTONEG/FIXED] */
+       uint16_t link_autoneg : 1;  /**< ETH_LINK_[AUTONEG/FIXED] */
        uint16_t link_status  : 1;  /**< ETH_LINK_[DOWN/UP] */
 } __attribute__((aligned(8)));      /**< aligned for atomic64 read/write */
 
 /* Utility constants */
-#define ETH_LINK_HALF_DUPLEX    0 /**< Half-duplex connection. */
-#define ETH_LINK_FULL_DUPLEX    1 /**< Full-duplex connection. */
-#define ETH_LINK_DOWN           0 /**< Link is down. */
-#define ETH_LINK_UP             1 /**< Link is up. */
-#define ETH_LINK_FIXED          0 /**< No autonegotiation. */
-#define ETH_LINK_AUTONEG        1 /**< Autonegotiated. */
+#define ETH_LINK_HALF_DUPLEX 0 /**< Half-duplex connection (see link_duplex). */
+#define ETH_LINK_FULL_DUPLEX 1 /**< Full-duplex connection (see link_duplex). */
+#define ETH_LINK_DOWN        0 /**< Link is down (see link_status). */
+#define ETH_LINK_UP          1 /**< Link is up (see link_status). */
+#define ETH_LINK_FIXED       0 /**< No autonegotiation (see link_autoneg). */
+#define ETH_LINK_AUTONEG     1 /**< Autonegotiated (see link_autoneg). */
 
 /**
  * A structure used to configure the ring threshold registers of an RX/TX
@@ -945,6 +946,11 @@ struct rte_eth_conf {
                             DEV_RX_OFFLOAD_VLAN_FILTER | \
                             DEV_RX_OFFLOAD_VLAN_EXTEND)
 
+/*
+ * If new Rx offload capabilities are defined, they also must be
+ * mentioned in rte_rx_offload_names in rte_ethdev.c file.
+ */
+
 /**
  * TX offload capabilities of a device.
  */
@@ -975,6 +981,11 @@ struct rte_eth_conf {
  */
 #define DEV_TX_OFFLOAD_SECURITY         0x00020000
 
+/*
+ * If new Tx offload capabilities are defined, they also must be
+ * mentioned in rte_tx_offload_names in rte_ethdev.c file.
+ */
+
 struct rte_pci_device;
 
 /**
@@ -1108,6 +1119,8 @@ struct rte_eth_dcb_info {
 
 struct rte_eth_dev;
 
+#define RTE_ETH_ALL RTE_MAX_ETHPORTS
+
 struct rte_eth_dev_callback;
 /** @internal Structure to keep track of registered callbacks */
 TAILQ_HEAD(rte_eth_dev_cb_list, rte_eth_dev_callback);
@@ -1718,9 +1731,6 @@ struct rte_eth_dev {
        void *security_ctx; /**< Context for security ops */
 } __rte_cache_aligned;
 
-void *
-rte_eth_dev_get_sec_ctx(uint8_t port_id);
-
 struct rte_eth_dev_sriov {
        uint8_t active;               /**< SRIOV is active with 16, 32 or 64 pools */
        uint8_t nb_q_per_pool;        /**< rx queue number per pool */
@@ -1919,6 +1929,32 @@ int rte_eth_dev_detach(uint16_t port_id, char *devname);
  */
 uint32_t rte_eth_speed_bitflag(uint32_t speed, int duplex);
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Get DEV_RX_OFFLOAD_* flag name.
+ *
+ * @param offload
+ *   Offload flag.
+ * @return
+ *   Offload name or 'UNKNOWN' if the flag cannot be recognised.
+ */
+const char *rte_eth_dev_rx_offload_name(uint64_t offload);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Get DEV_TX_OFFLOAD_* flag name.
+ *
+ * @param offload
+ *   Offload flag.
+ * @return
+ *   Offload name or 'UNKNOWN' if the flag cannot be recognised.
+ */
+const char *rte_eth_dev_tx_offload_name(uint64_t offload);
+
 /**
  * Configure an Ethernet device.
  * This function must be invoked first before any other function in the
@@ -2030,7 +2066,7 @@ int rte_eth_rx_queue_setup(uint16_t port_id, uint16_t rx_queue_id,
  *   the DMA memory allocated for the transmit descriptors of the ring.
  * @param tx_conf
  *   The pointer to the configuration data to be used for the transmit queue.
- *   NULL value is allowed, in which case default RX configuration
+ *   NULL value is allowed, in which case default TX configuration
  *   will be used.
  *   The *tx_conf* structure contains the following data:
  *   - The *tx_thresh* structure with the values of the Prefetch, Host, and
@@ -3497,6 +3533,8 @@ enum rte_eth_event_type {
        RTE_ETH_EVENT_VF_MBOX,  /**< message from the VF received by PF */
        RTE_ETH_EVENT_MACSEC,   /**< MACsec offload related event */
        RTE_ETH_EVENT_INTR_RMV, /**< device removal event */
+       RTE_ETH_EVENT_NEW,      /**< port is probed */
+       RTE_ETH_EVENT_DESTROY,  /**< port is released */
        RTE_ETH_EVENT_MAX       /**< max value of this enum */
 };
 
@@ -3507,10 +3545,11 @@ typedef int (*rte_eth_dev_cb_fn)(uint16_t port_id,
 
 
 /**
- * Register a callback function for specific port id.
+ * Register a callback function for port event.
  *
  * @param port_id
  *  Port id.
+ *  RTE_ETH_ALL means register the event for all port ids.
  * @param event
  *  Event interested.
  * @param cb_fn
@@ -3527,10 +3566,11 @@ int rte_eth_dev_callback_register(uint16_t port_id,
                rte_eth_dev_cb_fn cb_fn, void *cb_arg);
 
 /**
- * Unregister a callback function for specific port id.
+ * Unregister a callback function for port event.
  *
  * @param port_id
  *  Port id.
+ *  RTE_ETH_ALL means unregister the event for all port ids.
  * @param event
  *  Event interested.
  * @param cb_fn
@@ -3556,8 +3596,6 @@ int rte_eth_dev_callback_unregister(uint16_t port_id,
  *  Pointer to struct rte_eth_dev.
  * @param event
  *  Eth device interrupt event type.
- * @param cb_arg
- *  callback parameter.
  * @param ret_param
  *  To pass data back to user application.
  *  This allows the user application to decide if a particular function
@@ -3567,7 +3605,7 @@ int rte_eth_dev_callback_unregister(uint16_t port_id,
  *  int
  */
 int _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
-               enum rte_eth_event_type event, void *cb_arg, void *ret_param);
+               enum rte_eth_event_type event, void *ret_param);
 
 /**
  * When there is no rx packet coming in Rx Queue for a long time, we can
@@ -4577,6 +4615,18 @@ int rte_eth_dev_adjust_nb_rx_tx_desc(uint16_t port_id,
 int
 rte_eth_dev_pool_ops_supported(uint16_t port_id, const char *pool);
 
+/**
+ * Get the security context for the Ethernet device.
+ *
+ * @param port_id
+ *   Port identifier of the Ethernet device
+ * @return
+ *   - NULL on error.
+ *   - pointer to security context on success.
+ */
+void *
+rte_eth_dev_get_sec_ctx(uint8_t port_id);
+
 #ifdef __cplusplus
 }
 #endif