<commit_before>..  BSD LICENSE
    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
    * Neither the name of Intel Corporation nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Packet Classification and Access Control
========================================

The DPDK provides an Access Control library that gives the ability
to classify an input packet based on a set of classification rules.

The ACL library is used to perform an N-tuple search over a set of rules with multiple categories
and find the best match (highest priority) for each category.
The library API provides the following basic operations:

*   Create a new Access Control (AC) context.

*   Add rules into the context.

*   For all rules in the context, build the runtime structures necessary to perform packet classification.

*   Perform input packet classifications.

*   Destroy an AC context and its runtime structures and free the associated memory.

Overview
--------

The current implementation allows the user for each AC context to specify its own rule (set of fields)
over which packet classification will be performed.
To define each field inside an AC rule, the following structure is used:

.. code-block:: c

    struct rte_acl_field_def {
        uint8_t type;         /*< type - ACL_FIELD_TYPE. */
        uint8_t size;         /*< size of field 1,2,4, or 8. */
        uint8_t field_index;  /*< index of field inside the rule. */
        uint8_t input_index;  /*< 0-N input index. */
        uint32_t offset;      /*< offset to start of field. */
    };

*   type
    The field type is one of three choices:

    *   _MASK - for fields such as IP addresses that have a value and a mask defining the number of relevant bits.

    *   _RANGE - for fields such as ports that have a lower and upper value for the field.

    *   _BITMASK - for fields such as protocol identifiers that have a value and a bit mask.

*   size
    The size parameter defines the length of the field in bytes. Allowable values are 1, 2, 4, or 8 bytes.
    Note that due to the grouping of input bytes, 1 or 2 byte fields must be defined as consecutive fields
    that make up 4 consecutive input bytes.
    Also, it is best to define fields of 8 or more bytes as 4 byte fields so that
    the build processes can eliminate fields that are all wild.

*   field_index
    A zero-based value that represents the position of the field inside the rule; 0 to N-1 for N fields.

*   input_index
    For performance reasons, the inner loop of the search function is unrolled to process four input bytes at a time.
    This requires the input to be grouped into sets of 4 consecutive bytes.
    The loop processes the first input byte as part of the setup and then
    subsequent bytes must be in groups of 4 consecutive bytes.
    The input index specifies to which input group that field belongs to.

*   offset
    The offset field defines the offset for the field.
    This is the offset from the beginning of the buffer parameter for the search.

For example, to define classification for the following IPv4 5-tuple structure:

.. code-block:: c

    struct ipv4_5tuple {
        uint8_t proto;
        uint32_t ip_src;
        uint32_t ip_dst;<commit_msg>doc: add restrictions for ACL rule fields<commit_after>..  BSD LICENSE
    Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
    * Neither the name of Intel Corporation nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Packet Classification and Access Control
========================================

The DPDK provides an Access Control library that gives the ability
to classify an input packet based on a set of classification rules.

The ACL library is used to perform an N-tuple search over a set of rules with multiple categories
and find the best match (highest priority) for each category.
The library API provides the following basic operations:

*   Create a new Access Control (AC) context.

*   Add rules into the context.

*   For all rules in the context, build the runtime structures necessary to perform packet classification.

*   Perform input packet classifications.

*   Destroy an AC context and its runtime structures and free the associated memory.

Overview
--------

Rule definition
~~~~~~~~~~~~~~~

The current implementation allows the user for each AC context to specify its own rule (set of fields)
over which packet classification will be performed.
Though there are few restrictions on the rule fields layout:

*  First field in the rule definition has to be one byte long.
*  All subsequent fields has to be grouped into sets of 4 consecutive bytes.

This is done mainly for performance reasons - search function processes the first input byte as part of the flow setup and then the inner loop of the search function is unrolled to process four input bytes at a time.

To define each field inside an AC rule, the following structure is used:

.. code-block:: c

    struct rte_acl_field_def {
        uint8_t type;         /*< type - ACL_FIELD_TYPE. */
        uint8_t size;         /*< size of field 1,2,4, or 8. */
        uint8_t field_index;  /*< index of field inside the rule. */
        uint8_t input_index;  /*< 0-N input index. */
        uint32_t offset;      /*< offset to start of field. */
    };

*   type
    The field type is one of three choices:

    *   _MASK - for fields such as IP addresses that have a value and a mask defining the number of relevant bits.

    *   _RANGE - for fields such as ports that have a lower and upper value for the field.

    *   _BITMASK - for fields such as protocol identifiers that have a value and a bit mask.

*   size
    The size parameter defines the length of the field in bytes. Allowable values are 1, 2, 4, or 8 bytes.
    Note that due to the grouping of input bytes, 1 or 2 byte fields must be defined as consecutive fields
    that make up 4 consecutive input bytes.
    Also, it is best to define fields of 8 or more bytes as 4 byte fields so that
    the build processes can eliminate fields that are all wild.

*   field_index
    A zero-based value that represents the position of the field inside the rule; 0 to N-1 for N fields.

*   input_index
    As mentioned above, all input fields, except the very first one, must be in groups of 4 consecutive bytes.
    The input index specifies to which input group that field belongs to.

*   offset
    The offset field defines the offset for the field.
    This is the offset from the beginning of the buffer parameter for the search.

For example, to define classification for the following IPv4 5-tuple structure:

.. code-block:: c

    struct ipv4_5tuple {
        uint8_t proto;
        uint32_t ip_src;
        uint32_t ip_dst;
{'fraction_non_alphanumeric': 0.04730713245997089, 'fraction_numerical': 0.008525681014763984, 'mean_word_length': 3.2580787959274016, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4038255', 'n_tokens_mistral': 2449, 'n_tokens_neox': 2265, 'n_words': 1401}