doc/guides/prog_guide/regexdev.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright 2020 Mellanox Technologies, Ltd
   3
   4 RegEx Device Library
   5 ====================
   6
   7 The RegEx library provides a RegEx device framework for management and
   8 provisioning of hardware and software RegEx poll mode drivers, defining generic
   9 APIs which support a number of different RegEx operations.
  10
  11
  12 Design Principles
  13 -----------------
  14
  15 The RegEx library follows the same basic principles as those used in DPDK's
  16 Ethernet Device framework and the Crypto framework. The RegEx framework provides
  17 a generic Crypto device framework which supports both physical (hardware)
  18 and virtual (software) RegEx devices as well as a generic RegEx API which allows
  19 RegEx devices to be managed and configured and supports RegEx operations to be
  20 provisioned on RegEx poll mode driver.
  21
  22
  23 Device Management
  24 -----------------
  25
  26 Device Creation
  27 ~~~~~~~~~~~~~~~
  28
  29 Physical RegEx devices are discovered during the PCI probe/enumeration of the
  30 EAL function which is executed at DPDK initialization, based on
  31 their PCI device identifier, each unique PCI BDF (bus/bridge, device,
  32 function). Specific physical ReEx devices, like other physical devices in DPDK
  33 can be white-listed or black-listed using the EAL command line options.
  34
  35
  36 Device Identification
  37 ~~~~~~~~~~~~~~~~~~~~~
  38
  39 Each device, whether virtual or physical is uniquely designated by two
  40 identifiers:
  41
  42 - A unique device index used to designate the RegEx device in all functions
  43   exported by the regexdev API.
  44
  45 - A device name used to designate the RegEx device in console messages, for
  46   administration or debugging purposes.
  47
  48
  49 Device Configuration
  50 ~~~~~~~~~~~~~~~~~~~~
  51
  52 The configuration of each RegEx device includes the following operations:
  53
  54 - Allocation of resources, including hardware resources if a physical device.
  55 - Resetting the device into a well-known default state.
  56 - Initialization of statistics counters.
  57
  58 The rte_regexdev_configure API is used to configure a RegEx device.
  59
  60 .. code-block:: c
  61
  62    int rte_regexdev_configure(uint8_t dev_id,
  63                               const struct rte_regexdev_config *cfg);
  64
  65 The ``rte_regexdev_config`` structure is used to pass the configuration
  66 parameters for the RegEx device for example  number of queue pairs, number of
  67 groups, max number of matches and so on.
  68
  69 .. code-block:: c
  70
  71    struct rte_regexdev_config {
  72         uint16_t nb_max_matches;
  73         /**< Maximum matches per scan configured on this device.
  74          * This value cannot exceed the *max_matches*
  75          * which previously provided in rte_regexdev_info_get().
  76          * The value 0 is allowed, in which case, value 1 used.
  77          * @see struct rte_regexdev_info::max_matches
  78          */
  79         uint16_t nb_queue_pairs;
  80         /**< Number of RegEx queue pairs to configure on this device.
  81          * This value cannot exceed the *max_queue_pairs* which previously
  82          * provided in rte_regexdev_info_get().
  83          * @see struct rte_regexdev_info::max_queue_pairs
  84          */
  85         uint32_t nb_rules_per_group;
  86         /**< Number of rules per group to configure on this device.
  87          * This value cannot exceed the *max_rules_per_group*
  88          * which previously provided in rte_regexdev_info_get().
  89          * The value 0 is allowed, in which case,
  90          * struct rte_regexdev_info::max_rules_per_group used.
  91          * @see struct rte_regexdev_info::max_rules_per_group
  92          */
  93         uint16_t nb_groups;
  94         /**< Number of groups to configure on this device.
  95          * This value cannot exceed the *max_groups*
  96          * which previously provided in rte_regexdev_info_get().
  97          * @see struct rte_regexdev_info::max_groups
  98          */
  99         const char *rule_db;
 100         /**< Import initial set of prebuilt rule database on this device.
 101          * The value NULL is allowed, in which case, the device will not
 102          * be configured prebuilt rule database. Application may use
 103          * rte_regexdev_rule_db_update() or rte_regexdev_rule_db_import() API
 104          * to update or import rule database after the
 105          * rte_regexdev_configure().
 106          * @see rte_regexdev_rule_db_update(), rte_regexdev_rule_db_import()
 107          */
 108         uint32_t rule_db_len;
 109         /**< Length of *rule_db* buffer. */
 110         uint32_t dev_cfg_flags;
 111         /**< RegEx device configuration flags, See RTE_REGEXDEV_CFG_*  */
 112     };
 113
 114
 115 Configuration of Rules Database
 116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 117
 118 Each Regex device should be configured with the rule database.
 119 There are two modes of setting the rule database, online or offline.
 120 The online mode means, that the rule database in being compiled by the
 121 RegEx PMD while in the offline mode the rule database is compiled by external
 122 compiler, and is being loaded to the PMD as a buffer.
 123 The configuration mode is depended on the PMD capabilities.
 124
 125 Online rule configuration is done using the following API functions:
 126 ``rte_regexdev_rule_db_update`` which add / remove rules from the rules
 127 precomplied list, and ``rte_regexdev_rule_db_compile_activate``
 128 which compile the rules and loads them to the RegEx HW.
 129
 130 Offline rule configuration can be done by adding a pointer to the compiled
 131 rule database in the configuration step, or by using
 132 ``rte_regexdev_rule_db_import`` API.
 133
 134
 135 Configuration of Queue Pairs
 136 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 137
 138 Each RegEx device can be configured with number of queue pairs.
 139 Each queue pair is configured using ``rte_regexdev_queue_pair_setup``
 140
 141
 142 Logical Cores, Memory and Queues Pair Relationships
 143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145 Multiple logical cores should never share the same queue pair for enqueuing
 146 operations or dequeuing operations on the same RegEx device since this would
 147 require global locks and hinder performance.
 148
 149
 150 Device Features and Capabilities
 151 ---------------------------------
 152
 153 RegEx devices may support different feature set.
 154 In order to get the supported PMD feature ``rte_regexdev_info_get``
 155 API which return the info of the device and it's supported features.
 156
 157
 158 Enqueue / Dequeue Burst APIs
 159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 160
 161 The burst enqueue API uses a RegEx device identifier and a queue pair
 162 identifier to specify the device queue pair to schedule the processing on.
 163 The ``nb_ops`` parameter is the number of operations to process which are
 164 supplied in the ``ops`` array of ``rte_regex_ops`` structures.
 165 The enqueue function returns the number of operations it actually enqueued for
 166 processing, a return value equal to ``nb_ops`` means that all packets have been
 167 enqueued.
 168
 169 Data pointed in each op, should not be released until the dequeue of for that
 170 op.
 171
 172 The dequeue API uses the same format as the enqueue API of processed but
 173 the ``nb_ops`` and ``ops`` parameters are now used to specify the max processed
 174 operations the user wishes to retrieve and the location in which to store them.
 175 The API call returns the actual number of processed operations returned, this
 176 can never be larger than ``nb_ops``.
 177