rte_regexdev.h

Go to the documentation of this file.

/* SPDX-License-Identifier: BSD-3-Clause
 * Copyright(C) 2019 Marvell International Ltd.
 * Copyright 2020 Mellanox Technologies, Ltd
 * Copyright(c) 2020 Intel Corporation
 */

#ifndef _RTE_REGEXDEV_H_
#define _RTE_REGEXDEV_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <rte_common.h>
#include <rte_config.h>
#include <rte_dev.h>
#include <rte_errno.h>
#include <rte_mbuf.h>
#include <rte_memory.h>

#define RTE_REGEXDEV_NAME_MAX_LEN RTE_DEV_NAME_MAX_LEN

extern int rte_regexdev_logtype;

#define RTE_REGEXDEV_LOG(level, ...) \
    rte_log(RTE_LOG_ ## level, rte_regexdev_logtype, "" __VA_ARGS__)

/* Macros to check for valid port */
#define RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, retval) do { \
    if (!rte_regexdev_is_valid_dev(dev_id)) { \
        RTE_REGEXDEV_LOG(ERR, "Invalid dev_id=%u\n", dev_id); \
        return retval; \
    } \
} while (0)

#define RTE_REGEXDEV_VALID_DEV_ID_OR_RET(dev_id) do { \
    if (!rte_regexdev_is_valid_dev(dev_id)) { \
        RTE_REGEXDEV_LOG(ERR, "Invalid dev_id=%u\n", dev_id); \
        return; \
    } \
} while (0)

int rte_regexdev_is_valid_dev(uint16_t dev_id);

__rte_experimental
uint8_t
rte_regexdev_count(void);

__rte_experimental
int
rte_regexdev_get_dev_id(const char *name);

/* Enumerates RegEx device capabilities */
#define RTE_REGEXDEV_CAPA_RUNTIME_COMPILATION_F (1ULL << 0)

#define RTE_REGEXDEV_CAPA_SUPP_PCRE_START_ANCHOR_F (1ULL << 1)

#define RTE_REGEXDEV_CAPA_SUPP_PCRE_ATOMIC_GROUPING_F (1ULL << 2)

#define RTE_REGEXDEV_SUPP_PCRE_BACKTRACKING_CTRL_F (1ULL << 3)

#define RTE_REGEXDEV_SUPP_PCRE_CALLOUTS_F (1ULL << 4)

#define RTE_REGEXDEV_SUPP_PCRE_BACKREFERENCE_F (1ULL << 5)

#define RTE_REGEXDEV_SUPP_PCRE_GREEDY_F (1ULL << 6)

#define RTE_REGEXDEV_SUPP_PCRE_MATCH_ALL_F (1ULL << 7)

#define RTE_REGEXDEV_SUPP_PCRE_LOOKAROUND_ASRT_F (1ULL << 8)

#define RTE_REGEXDEV_SUPP_PCRE_MATCH_POINT_RST_F (1ULL << 9)

#define RTE_REGEXDEV_SUPP_NEWLINE_CONVENTIONS_F (1ULL << 10)

#define RTE_REGEXDEV_SUPP_PCRE_NEWLINE_SEQ_F (1ULL << 11)

#define RTE_REGEXDEV_SUPP_PCRE_POSSESSIVE_QUALIFIERS_F (1ULL << 12)

#define RTE_REGEXDEV_SUPP_PCRE_SUBROUTINE_REFERENCES_F (1ULL << 13)

#define RTE_REGEXDEV_SUPP_PCRE_UTF_8_F (1ULL << 14)

#define RTE_REGEXDEV_SUPP_PCRE_UTF_16_F (1ULL << 15)

#define RTE_REGEXDEV_SUPP_PCRE_UTF_32_F (1ULL << 16)

#define RTE_REGEXDEV_SUPP_PCRE_WORD_BOUNDARY_F (1ULL << 17)

#define RTE_REGEXDEV_SUPP_PCRE_FORWARD_REFERENCES_F (1ULL << 18)

#define RTE_REGEXDEV_SUPP_MATCH_AS_END_F (1ULL << 19)

#define RTE_REGEXDEV_SUPP_CROSS_BUFFER_F (1ULL << 20)

#define RTE_REGEXDEV_SUPP_MATCH_ALL_F (1ULL << 21)

#define RTE_REGEXDEV_CAPA_QUEUE_PAIR_OOS_F (1ULL << 22)

/* Enumerates PCRE rule flags */
#define RTE_REGEX_PCRE_RULE_ALLOW_EMPTY_F (1ULL << 0)

#define RTE_REGEX_PCRE_RULE_ANCHORED_F (1ULL << 1)

#define RTE_REGEX_PCRE_RULE_CASELESS_F (1ULL << 2)

#define RTE_REGEX_PCRE_RULE_DOTALL_F (1ULL << 3)

#define RTE_REGEX_PCRE_RULE_DUPNAMES_F (1ULL << 4)

#define RTE_REGEX_PCRE_RULE_EXTENDED_F (1ULL << 5)

#define RTE_REGEX_PCRE_RULE_MATCH_UNSET_BACKREF_F (1ULL << 6)

#define RTE_REGEX_PCRE_RULE_MULTILINE_F (1ULL << 7)

#define RTE_REGEX_PCRE_RULE_NO_AUTO_CAPTURE_F (1ULL << 8)

#define RTE_REGEX_PCRE_RULE_UCP_F (1ULL << 9)

#define RTE_REGEX_PCRE_RULE_UNGREEDY_F (1ULL << 10)

#define RTE_REGEX_PCRE_RULE_UTF_F (1ULL << 11)

#define RTE_REGEX_PCRE_RULE_NEVER_BACKSLASH_C_F (1ULL << 12)

struct rte_regexdev_info {
    const char *driver_name; 
    struct rte_device *dev; 
    uint16_t max_matches;
    uint16_t max_queue_pairs;
    uint16_t max_payload_size;
    uint32_t max_rules_per_group;
    uint16_t max_groups;
    uint32_t regexdev_capa;
    uint64_t rule_flags;
};

__rte_experimental
int
rte_regexdev_info_get(uint8_t dev_id, struct rte_regexdev_info *dev_info);

/* Enumerates RegEx device configuration flags */
#define RTE_REGEXDEV_CFG_CROSS_BUFFER_SCAN_F (1ULL << 0)

#define RTE_REGEXDEV_CFG_MATCH_AS_END_F (1ULL << 1)

#define RTE_REGEXDEV_CFG_MATCH_ALL_F (1ULL << 2)

struct rte_regexdev_config {
    uint16_t nb_max_matches;
    uint16_t nb_queue_pairs;
    uint32_t nb_rules_per_group;
    uint16_t nb_groups;
    const char *rule_db;
    uint32_t rule_db_len;
    uint32_t dev_cfg_flags;
};

__rte_experimental
int
rte_regexdev_configure(uint8_t dev_id, const struct rte_regexdev_config *cfg);

/* Enumerates RegEx queue pair configuration flags */
#define RTE_REGEX_QUEUE_PAIR_CFG_OOS_F (1ULL << 0)

struct rte_regex_ops;
typedef void (*regexdev_stop_flush_t)(uint8_t dev_id, uint16_t qp_id,
                      struct rte_regex_ops *op);
struct rte_regexdev_qp_conf {
    uint32_t qp_conf_flags;
    uint16_t nb_desc;
    regexdev_stop_flush_t cb;
};

__rte_experimental
int
rte_regexdev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
                  const struct rte_regexdev_qp_conf *qp_conf);

__rte_experimental
int
rte_regexdev_start(uint8_t dev_id);

__rte_experimental
int
rte_regexdev_stop(uint8_t dev_id);

__rte_experimental
int
rte_regexdev_close(uint8_t dev_id);

/* Device get/set attributes */

enum rte_regexdev_attr_id {
    RTE_REGEXDEV_ATTR_SOCKET_ID,
    RTE_REGEXDEV_ATTR_MAX_MATCHES,
    RTE_REGEXDEV_ATTR_MAX_SCAN_TIMEOUT,
    RTE_REGEXDEV_ATTR_MAX_PREFIX,
};

__rte_experimental
int
rte_regexdev_attr_get(uint8_t dev_id, enum rte_regexdev_attr_id attr_id,
              void *attr_value);

__rte_experimental
int
rte_regexdev_attr_set(uint8_t dev_id, enum rte_regexdev_attr_id attr_id,
              const void *attr_value);

/* Rule related APIs */
enum rte_regexdev_rule_op {
    RTE_REGEX_RULE_OP_ADD,
    RTE_REGEX_RULE_OP_REMOVE
};

struct rte_regexdev_rule {
    enum rte_regexdev_rule_op op;
    uint16_t group_id;
    uint32_t rule_id;
    const char *pcre_rule;
    uint16_t pcre_rule_len;
    uint64_t rule_flags;
    /* PCRE rule flags. Supported device specific PCRE rules enumerated
     * in struct rte_regexdev_info::rule_flags. For successful rule
     * database update, application needs to provide only supported
     * rule flags.
     * @See RTE_REGEX_PCRE_RULE_*, struct rte_regexdev_info::rule_flags
     */
};

__rte_experimental
int
rte_regexdev_rule_db_update(uint8_t dev_id,
                const struct rte_regexdev_rule *rules,
                uint32_t nb_rules);

__rte_experimental
int
rte_regexdev_rule_db_compile_activate(uint8_t dev_id);

__rte_experimental
int
rte_regexdev_rule_db_import(uint8_t dev_id, const char *rule_db,
                uint32_t rule_db_len);

__rte_experimental
int
rte_regexdev_rule_db_export(uint8_t dev_id, char *rule_db);

/* Extended statistics */
#define RTE_REGEXDEV_XSTATS_NAME_SIZE 64

struct rte_regexdev_xstats_map {
    uint16_t id;
    char name[RTE_REGEXDEV_XSTATS_NAME_SIZE];
};

__rte_experimental
int
rte_regexdev_xstats_names_get(uint8_t dev_id,
                  struct rte_regexdev_xstats_map *xstats_map);

__rte_experimental
int
rte_regexdev_xstats_get(uint8_t dev_id, const uint16_t *ids,
            uint64_t *values, uint16_t nb_values);

__rte_experimental
int
rte_regexdev_xstats_by_name_get(uint8_t dev_id, const char *name,
                uint16_t *id, uint64_t *value);

__rte_experimental
int
rte_regexdev_xstats_reset(uint8_t dev_id, const uint16_t *ids,
              uint16_t nb_ids);

__rte_experimental
int
rte_regexdev_selftest(uint8_t dev_id);

__rte_experimental
int
rte_regexdev_dump(uint8_t dev_id, FILE *f);

/* Fast path APIs */

struct rte_regexdev_match {
    RTE_STD_C11
    union {
        uint64_t u64;
        struct {
            uint32_t rule_id:20;
            uint32_t group_id:12;
            uint16_t start_offset;
            RTE_STD_C11
            union {
                uint16_t len;
                uint16_t end_offset;
            };
        };
    };
};

/* Enumerates RegEx request flags. */
#define RTE_REGEX_OPS_REQ_GROUP_ID0_VALID_F (1 << 0)

#define RTE_REGEX_OPS_REQ_GROUP_ID1_VALID_F (1 << 1)

#define RTE_REGEX_OPS_REQ_GROUP_ID2_VALID_F (1 << 2)

#define RTE_REGEX_OPS_REQ_GROUP_ID3_VALID_F (1 << 3)

#define RTE_REGEX_OPS_REQ_STOP_ON_MATCH_F (1 << 4)

#define RTE_REGEX_OPS_REQ_MATCH_HIGH_PRIORITY_F (1 << 5)

/* Enumerates RegEx response flags. */
#define RTE_REGEX_OPS_RSP_PMI_SOJ_F (1 << 0)

#define RTE_REGEX_OPS_RSP_PMI_EOJ_F (1 << 1)

#define RTE_REGEX_OPS_RSP_MAX_SCAN_TIMEOUT_F (1 << 2)

#define RTE_REGEX_OPS_RSP_MAX_MATCH_F (1 << 3)

#define RTE_REGEX_OPS_RSP_MAX_PREFIX_F (1 << 4)

struct rte_regex_ops {
    /* W0 */
    uint16_t req_flags;
    uint16_t rsp_flags;
    uint16_t nb_actual_matches;
    uint16_t nb_matches;
    /* W1 */
    struct rte_mbuf *mbuf; 
    /* W2 */
    uint16_t group_id0;
    uint16_t group_id1;
    uint16_t group_id2;
    uint16_t group_id3;
    /* W3 */
    RTE_STD_C11
    union {
        uint64_t user_id;
        void *user_ptr;
    };

    /* W4 */
    RTE_STD_C11
    union {
        uint64_t cross_buf_id;
        void *cross_buf_ptr;
    };

    /* W5 */
    struct rte_regexdev_match matches[];
};

#include "rte_regexdev_core.h"

__rte_experimental
static inline uint16_t
rte_regexdev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
               struct rte_regex_ops **ops, uint16_t nb_ops)
{
    struct rte_regexdev *dev = &rte_regex_devices[dev_id];
#ifdef RTE_LIBRTE_REGEXDEV_DEBUG
    RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, -EINVAL);
    RTE_FUNC_PTR_OR_ERR_RET(*dev->enqueue, -ENOTSUP);
    if (qp_id >= dev->data->dev_conf.nb_queue_pairs) {
        RTE_REGEXDEV_LOG(ERR, "Invalid queue %d\n", qp_id);
        return -EINVAL;
    }
#endif
    return (*dev->enqueue)(dev, qp_id, ops, nb_ops);
}

__rte_experimental
static inline uint16_t
rte_regexdev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
               struct rte_regex_ops **ops, uint16_t nb_ops)
{
    struct rte_regexdev *dev = &rte_regex_devices[dev_id];
#ifdef RTE_LIBRTE_REGEXDEV_DEBUG
    RTE_REGEXDEV_VALID_DEV_ID_OR_ERR_RET(dev_id, -EINVAL);
    RTE_FUNC_PTR_OR_ERR_RET(*dev->dequeue, -ENOTSUP);
    if (qp_id >= dev->data->dev_conf.nb_queue_pairs) {
        RTE_REGEXDEV_LOG(ERR, "Invalid queue %d\n", qp_id);
        return -EINVAL;
    }
#endif
    return (*dev->dequeue)(dev, qp_id, ops, nb_ops);
}

#ifdef __cplusplus
}
#endif

#endif /* _RTE_REGEXDEV_H_ */