mirror of
https://github.com/VectorCamp/vectorscan.git
synced 2025-06-28 16:41:01 +03:00
943f198ebf
The generated documentation continues to refer to Hyperscan despite the project now being VectorScan. Lets replace many of the Hyperscan references with Vectorscan. At the same time, lets resync the documentation here with the vectorscan readme. This updates the supported platforms/compilers and build options. Signed-off-by: Jeremy Linton <jeremy.linton@arm.com>
68 lines
2.8 KiB
ReStructuredText
68 lines
2.8 KiB
ReStructuredText
.. _serialization:
|
|
|
|
#############
|
|
Serialization
|
|
#############
|
|
|
|
For some applications, compiling Vectorscan 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.
|
|
|
|
Vectorscan 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, Vectorscan
|
|
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:: Vectorscan 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 Vectorscan
|
|
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 Vectorscan library (``libhs``) contains both the compiler and runtime
|
|
portions of the library. This means that in order to support the Vectorscan
|
|
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
|
|
Vectorscan 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 Vectorscan library, called ``libhs_runtime``, is also
|
|
distributed. This library does not depend on the C++ standard library and
|
|
provides all Vectorscan functions other that those used to compile databases.
|