doc: add description of serialization, runtime lib

diff --git a/doc/dev-reference/index.rst b/doc/dev-reference/index.rst
index ddc523f0812c4ba88230eef0f5485bcc8d525fa3..df4f8916108a96d17e7f4b8fc76be1b1953c5282 100644 (file)
--- a/doc/dev-reference/index.rst
+++ b/doc/dev-reference/index.rst
@@ -15,6 +15,7 @@ Hyperscan |version| Developer's Reference Guide
    getting_started
    compilation
    runtime
+   serialization
    performance
    api_constants
    api_files

diff --git a/doc/dev-reference/serialization.rst b/doc/dev-reference/serialization.rst
new file mode 100644 (file)
index 0000000..4f884c7
--- /dev/null
+++ b/doc/dev-reference/serialization.rst
@@ -0,0 +1,67 @@
+.. _serialization:
+
+#############
+Serialization
+#############
+
+For some applications, compiling Hyperscan pattern databases immediately prior
+to use is not an appropriate design. Some users may wish to:
+
+* Compile pattern databases on a different host;
+
+* Persist compiled databases to storage and only re-compile pattern databases
+  when the patterns change;
+
+* Control the region of memory in which the compiled database is located.
+
+Hyperscan pattern databases are not completely flat in memory: they contain
+pointers and have specific alignment requirements. Therefore, they cannot be
+copied (or otherwise relocated) directly. To enable these use cases, Hyperscan
+provides functionality for serializing and deserializing compiled pattern
+databases.
+
+The API provides the following functions:
+
+#. :c:func:`hs_serialize_database`: serializes a pattern database into a
+   flat relocatable buffer of bytes.
+
+#. :c:func:`hs_deserialize_database`: reconstructs a newly allocated pattern
+   database from the output of :c:func:`hs_serialize_database`.
+
+#. :c:func:`hs_deserialize_database_at`: reconstructs a pattern
+   database at a given memory location from the output of
+   :c:func:`hs_serialize_database`.
+
+#. :c:func:`hs_serialized_database_size`: given a serialized pattern database,
+   returns the size of the memory block required by the database when
+   deserialized.
+
+#. :c:func:`hs_serialized_database_info`: given a serialized pattern database,
+   returns a string containing information about the database. This call is
+   analogous to :c:func:`hs_database_info`.
+
+.. note:: Hyperscan performs both version and platform compatibility checks
+   upon deserialization. The :c:func:`hs_deserialize_database` and
+   :c:func:`hs_deserialize_database_at` functions will only permit the
+   deserialization of databases compiled with (a) the same version of Hyperscan
+   and (b) platform features supported by the current host platform. See
+   :ref:`instr_specialization` for more information on platform specialization.
+
+===================
+The Runtime Library
+===================
+
+The main Hyperscan library (``libhs``) contains both the compiler and runtime
+portions of the library. This means that in order to support the Hyperscan
+compiler, which is written in C++, it requires C++ linkage and has a
+dependency on the C++ standard library.
+
+Many embedded applications require only the scanning ("runtime") portion of the
+Hyperscan library. In these cases, pattern compilation generally takes place on
+another host, and serialized pattern databases are delivered to the application
+for use.
+
+To support these applications without requiring the C++ dependency, a
+runtime-only version of the Hyperscan library, called ``libhs_runtime``, is also
+distributed. This library does not depend on the C++ standard library and
+provides all Hyperscan functions other that those used to compile databases.