From 28986c364a514097fbb159f232cf1153b1c8a767 Mon Sep 17 00:00:00 2001
From: Yoan Picchi <yoan.picchi@arm.com>
Date: Thu, 19 Jun 2025 13:55:23 +0000
Subject: [PATCH] Add Direct API documentation

Signed-off-by: Yoan Picchi <yoan.picchi@arm.com>
---
 doc/dev-reference/api_constants.rst |  7 +++++++
 doc/dev-reference/compilation.rst   |  3 +++
 doc/dev-reference/direct_api.rst    | 28 ++++++++++++++++++++++++++++
 doc/dev-reference/index.rst         |  1 +
 4 files changed, 39 insertions(+)
 create mode 100644 doc/dev-reference/direct_api.rst

diff --git a/doc/dev-reference/api_constants.rst b/doc/dev-reference/api_constants.rst
index bbe229de..912c1917 100644
--- a/doc/dev-reference/api_constants.rst
+++ b/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:
diff --git a/doc/dev-reference/compilation.rst b/doc/dev-reference/compilation.rst
index a0ae8c8b..21066c80 100644
--- a/doc/dev-reference/compilation.rst
+++ b/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
 ***************
diff --git a/doc/dev-reference/direct_api.rst b/doc/dev-reference/direct_api.rst
new file mode 100644
index 00000000..8942633a
--- /dev/null
+++ b/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.
diff --git a/doc/dev-reference/index.rst b/doc/dev-reference/index.rst
index 4046a298..5845f9e1 100644
--- a/doc/dev-reference/index.rst
+++ b/doc/dev-reference/index.rst
@@ -21,3 +21,4 @@ Vectorscan |version| Developer's Reference Guide
    api_constants
    api_files
    chimera
+   direct_api