Add Direct API documentation

Signed-off-by: Yoan Picchi <yoan.picchi@arm.com>

doc/dev-reference/api_constants.rst

@@ -51,3 +51,10 @@ Compile mode flags
 .. doxygengroup:: HS_MODE_FLAG
    :content-only:
    :no-link:
+
+******************************
+Other Constants
+******************************
+
+.. doxygendefine:: HS_SHORT_PATTERN_THRESHOLD
+   :no-link:

doc/dev-reference/compilation.rst

@@ -123,6 +123,9 @@ Supported flags: :c:member:`HS_FLAG_CASELESS`, :c:member:`HS_FLAG_SINGLEMATCH`,
           The new literal APIs introduced here are designed for rule sets
           containing only pure literal expressions.
 
+In tight loops where performance is critical, some further specialization of the
+literal search exists in the form of :ref:`direct_api`
+
 ***************
 Pattern Support
 ***************

doc/dev-reference/direct_api.rst

@@ -0,0 +1,28 @@
+.. _direct_api:
+
+####################
+Direct API extension
+####################
+
+Even though pure literal searches are fast, there is still some overhead.
+In tight loops where both the pattern and the data are small (say, a
+4-character pattern with a 32-character data buffer), this overhead can
+become noticeable. In such cases, the functions provided by the Direct API
+offer a minimal-overhead alternative, at the cost of a reduced set of
+functionality.
+
+Each type of call is designed for a specific pattern type:
+    - Strings
+    - Pairs of two characters
+    - Single characters
+Each type comes in a ``single`` search and ``set`` search variant, depending
+on whether you need to search for one or multiple patterns.
+
+For each case, compile, search, and free functions are provided.
+
+All search functions are case-sensitive.
+
+The single string search has an additional specialization based on the length
+of the pattern. If the pattern is "short", ie shorter than or equal to
+:c:member:`HS_SHORT_PATTERN_THRESHOLD` characters—then
+:c:func:`hs_compile_short_literal_search` may be used instead.

doc/dev-reference/index.rst

@@ -21,3 +21,4 @@ Vectorscan |version| Developer's Reference Guide
    api_constants
    api_files
    chimera
+   direct_api