path: root/contrib/libs/hyperscan/runtime_avx512/hs_runtime.h

/* 
 * Copyright (c) 2015-2018, Intel Corporation 
 * 
 * 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. 
 */ 
 
#ifndef HS_AVX512_RUNTIME_H 
#define HS_AVX512_RUNTIME_H 
 
#include <stdlib.h> 
 
/** 
 * @file 
 * @brief The Hyperscan runtime API definition. 
 * 
 * Hyperscan is a high speed regular expression engine. 
 * 
 * This header contains functions for using compiled Hyperscan databases for 
 * scanning data at runtime. 
 */ 
 
#include "hs_common.h" 
 
#ifdef __cplusplus 
extern "C" 
{ 
#endif 
 
/** 
 * Definition of the stream identifier type. 
 */ 
struct hs_stream; 
 
/** 
 * The stream identifier returned by @ref hs_open_stream(). 
 */ 
typedef struct hs_stream hs_stream_t; 
 
struct hs_scratch; 
 
/** 
 * A Hyperscan scratch space. 
 */ 
typedef struct hs_scratch hs_scratch_t; 
 
/** 
 * Definition of the match event callback function type. 
 * 
 * A callback function matching the defined type must be provided by the 
 * application calling the @ref hs_scan(), @ref hs_scan_vector() or @ref 
 * hs_scan_stream() functions (or other streaming calls which can produce 
 * matches). 
 * 
 * This callback function will be invoked whenever a match is located in the 
 * target data during the execution of a scan. The details of the match are 
 * passed in as parameters to the callback function, and the callback function 
 * should return a value indicating whether or not matching should continue on 
 * the target data. If no callbacks are desired from a scan call, NULL may be 
 * provided in order to suppress match production. 
 * 
 * This callback function should not attempt to call Hyperscan API functions on 
 * the same stream nor should it attempt to reuse the scratch space allocated 
 * for the API calls that caused it to be triggered. Making another call to the 
 * Hyperscan library with completely independent parameters should work (for 
 * example, scanning a different database in a new stream and with new scratch 
 * space), but reusing data structures like stream state and/or scratch space 
 * will produce undefined behavior. 
 * 
 * @param id 
 *      The ID number of the expression that matched. If the expression was a 
 *      single expression compiled with @ref hs_compile(), this value will be 
 *      zero. 
 * 
 * @param from 
 *      - If a start of match flag is enabled for the current pattern, this 
 *        argument will be set to the start of match for the pattern assuming 
 *        that that start of match value lies within the current 'start of match 
 *        horizon' chosen by one of the SOM_HORIZON mode flags. 
 
 *      - If the start of match value lies outside this horizon (possible only 
 *        when the SOM_HORIZON value is not @ref HS_MODE_SOM_HORIZON_LARGE), 
 *        the @p from value will be set to @ref HS_OFFSET_PAST_HORIZON. 
 
 *      - This argument will be set to zero if the Start of Match flag is not 
 *        enabled for the given pattern. 
 * 
 * @param to 
 *      The offset after the last byte that matches the expression. 
 * 
 * @param flags 
 *      This is provided for future use and is unused at present. 
 * 
 * @param context 
 *      The pointer supplied by the user to the @ref hs_scan(), @ref 
 *      hs_scan_vector() or @ref hs_scan_stream() function. 
 * 
 * @return 
 *      Non-zero if the matching should cease, else zero. If scanning is 
 *      performed in streaming mode and a non-zero value is returned, any 
 *      subsequent calls to @ref hs_scan_stream() for that stream will 
 *      immediately return with @ref HS_SCAN_TERMINATED. 
 */ 
typedef int (HS_CDECL *match_event_handler)(unsigned int id, 
                                            unsigned long long from, 
                                            unsigned long long to, 
                                            unsigned int flags, 
                                            void *context); 
 
/** 
 * Open and initialise a stream. 
 * 
 * @param db 
 *      A compiled pattern database. 
 * 
 * @param flags 
 *      Flags modifying the behaviour of the stream. This parameter is provided 
 *      for future use and is unused at present. 
 * 
 * @param stream 
 *      On success, a pointer to the generated @ref hs_stream_t will be 
 *      returned; NULL on failure. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_open_stream(const hs_database_t *db, unsigned int flags, 
                                   hs_stream_t **stream); 
 
/** 
 * Write data to be scanned to the opened stream. 
 * 
 * This is the function call in which the actual pattern matching takes place 
 * as data is written to the stream. Matches will be returned via the @ref 
 * match_event_handler callback supplied. 
 * 
 * @param id 
 *      The stream ID (returned by @ref hs_open_stream()) to which the data 
 *      will be written. 
 * 
 * @param data 
 *      Pointer to the data to be scanned. 
 * 
 * @param length 
 *      The number of bytes to scan. 
 * 
 * @param flags 
 *      Flags modifying the behaviour of the stream. This parameter is provided 
 *      for future use and is unused at present. 
 * 
 * @param scratch 
 *      A per-thread scratch space allocated by @ref hs_alloc_scratch(). 
 * 
 * @param onEvent 
 *      Pointer to a match event callback function. If a NULL pointer is given, 
 *      no matches will be returned. 
 * 
 * @param ctxt 
 *      The user defined pointer which will be passed to the callback function 
 *      when a match occurs. 
 * 
 * @return 
 *      Returns @ref HS_SUCCESS on success; @ref HS_SCAN_TERMINATED if the 
 *      match callback indicated that scanning should stop; other values on 
 *      error. 
 */ 
hs_error_t avx512_hs_scan_stream(hs_stream_t *id, const char *data, 
                                   unsigned int length, unsigned int flags, 
                                   hs_scratch_t *scratch, 
                                   match_event_handler onEvent, void *ctxt); 
 
/** 
 * Close a stream. 
 * 
 * This function completes matching on the given stream and frees the memory 
 * associated with the stream state. After this call, the stream pointed to by 
 * @p id is invalid and can no longer be used. To reuse the stream state after 
 * completion, rather than closing it, the @ref hs_reset_stream function can be 
 * used. 
 * 
 * This function must be called for any stream created with @ref 
 * hs_open_stream(), even if scanning has been terminated by a non-zero return 
 * from the match callback function. 
 * 
 * Note: This operation may result in matches being returned (via calls to the 
 * match event callback) for expressions anchored to the end of the data stream 
 * (for example, via the use of the `$` meta-character). If these matches are 
 * not desired, NULL may be provided as the @ref match_event_handler callback. 
 * 
 * If NULL is provided as the @ref match_event_handler callback, it is 
 * permissible to provide a NULL scratch. 
 * 
 * @param id 
 *      The stream ID returned by @ref hs_open_stream(). 
 * 
 * @param scratch 
 *      A per-thread scratch space allocated by @ref hs_alloc_scratch(). This is 
 *      allowed to be NULL only if the @p onEvent callback is also NULL. 
 * 
 * @param onEvent 
 *      Pointer to a match event callback function. If a NULL pointer is given, 
 *      no matches will be returned. 
 * 
 * @param ctxt 
 *      The user defined pointer which will be passed to the callback function 
 *      when a match occurs. 
 * 
 * @return 
 *      Returns @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_close_stream(hs_stream_t *id, hs_scratch_t *scratch, 
                                    match_event_handler onEvent, void *ctxt); 
 
/** 
 * Reset a stream to an initial state. 
 * 
 * Conceptually, this is equivalent to performing @ref hs_close_stream() on the 
 * given stream, followed by a @ref hs_open_stream(). This new stream replaces 
 * the original stream in memory, avoiding the overhead of freeing the old 
 * stream and allocating the new one. 
 * 
 * Note: This operation may result in matches being returned (via calls to the 
 * match event callback) for expressions anchored to the end of the original 
 * data stream (for example, via the use of the `$` meta-character). If these 
 * matches are not desired, NULL may be provided as the @ref match_event_handler 
 * callback. 
 * 
 * Note: the stream will also be tied to the same database. 
 * 
 * @param id 
 *      The stream (as created by @ref hs_open_stream()) to be replaced. 
 * 
 * @param flags 
 *      Flags modifying the behaviour of the stream. This parameter is provided 
 *      for future use and is unused at present. 
 * 
 * @param scratch 
 *      A per-thread scratch space allocated by @ref hs_alloc_scratch(). This is 
 *      allowed to be NULL only if the @p onEvent callback is also NULL. 
 * 
 * @param onEvent 
 *      Pointer to a match event callback function. If a NULL pointer is given, 
 *      no matches will be returned. 
 * 
 * @param context 
 *      The user defined pointer which will be passed to the callback function 
 *      when a match occurs. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_reset_stream(hs_stream_t *id, unsigned int flags, 
                                    hs_scratch_t *scratch, 
                                    match_event_handler onEvent, void *context); 
 
/** 
 * Duplicate the given stream. The new stream will have the same state as the 
 * original including the current stream offset. 
 * 
 * @param to_id 
 *      On success, a pointer to the new, copied @ref hs_stream_t will be 
 *      returned; NULL on failure. 
 * 
 * @param from_id 
 *      The stream (as created by @ref hs_open_stream()) to be copied. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_copy_stream(hs_stream_t **to_id, 
                                   const hs_stream_t *from_id); 
 
/** 
 * Duplicate the given 'from' stream state onto the 'to' stream. The 'to' stream 
 * will first be reset (reporting any EOD matches if a non-NULL @p onEvent 
 * callback handler is provided). 
 * 
 * Note: the 'to' stream and the 'from' stream must be open against the same 
 * database. 
 * 
 * @param to_id 
 *      On success, a pointer to the new, copied @ref hs_stream_t will be 
 *      returned; NULL on failure. 
 * 
 * @param from_id 
 *      The stream (as created by @ref hs_open_stream()) to be copied. 
 * 
 * @param scratch 
 *      A per-thread scratch space allocated by @ref hs_alloc_scratch(). This is 
 *      allowed to be NULL only if the @p onEvent callback is also NULL. 
 * 
 * @param onEvent 
 *      Pointer to a match event callback function. If a NULL pointer is given, 
 *      no matches will be returned. 
 * 
 * @param context 
 *      The user defined pointer which will be passed to the callback function 
 *      when a match occurs. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_reset_and_copy_stream(hs_stream_t *to_id, 
                                             const hs_stream_t *from_id, 
                                             hs_scratch_t *scratch, 
                                             match_event_handler onEvent, 
                                             void *context); 
 
/** 
 * Creates a compressed representation of the provided stream in the buffer 
 * provided. This compressed representation can be converted back into a stream 
 * state by using @ref hs_expand_stream() or @ref hs_reset_and_expand_stream(). 
 * The size of the compressed representation will be placed into @p used_space. 
 * 
 * If there is not sufficient space in the buffer to hold the compressed 
 * representation, @ref HS_INSUFFICIENT_SPACE will be returned and @p used_space 
 * will be populated with the amount of space required. 
 * 
 * Note: this function does not close the provided stream, you may continue to 
 * use the stream or to free it with @ref hs_close_stream(). 
 * 
 * @param stream 
 *      The stream (as created by @ref hs_open_stream()) to be compressed. 
 * 
 * @param buf 
 *      Buffer to write the compressed representation into. Note: if the call is 
 *      just being used to determine the amount of space required, it is allowed 
 *      to pass NULL here and @p buf_space as 0. 
 * 
 * @param buf_space 
 *      The number of bytes in @p buf. If buf_space is too small, the call will 
 *      fail with @ref HS_INSUFFICIENT_SPACE. 
 * 
 * @param used_space 
 *      Pointer to where the amount of used space will be written to. The used 
 *      buffer space is always less than or equal to @p buf_space. If the call 
 *      fails with @ref HS_INSUFFICIENT_SPACE, this pointer will be used to 
 *      write out the amount of buffer space required. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, @ref HS_INSUFFICIENT_SPACE if the provided 
 *      buffer is too small. 
 */ 
hs_error_t avx512_hs_compress_stream(const hs_stream_t *stream, char *buf, 
                                       size_t buf_space, size_t *used_space); 
 
/** 
 * Decompresses a compressed representation created by @ref hs_compress_stream() 
 * into a new stream. 
 * 
 * Note: @p buf must correspond to a complete compressed representation created 
 * by @ref hs_compress_stream() of a stream that was opened against @p db. It is 
 * not always possible to detect misuse of this API and behaviour is undefined 
 * if these properties are not satisfied. 
 * 
 * @param db 
 *      The compiled pattern database that the compressed stream was opened 
 *      against. 
 * 
 * @param stream 
 *      On success, a pointer to the expanded @ref hs_stream_t will be 
 *      returned; NULL on failure. 
 * 
 * @param buf 
 *      A compressed representation of a stream. These compressed forms are 
 *      created by @ref hs_compress_stream(). 
 * 
 * @param buf_size 
 *      The size in bytes of the compressed representation. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_expand_stream(const hs_database_t *db, 
                                     hs_stream_t **stream, const char *buf, 
                                     size_t buf_size); 
 
/** 
 * Decompresses a compressed representation created by @ref hs_compress_stream() 
 * on top of the 'to' stream. The 'to' stream will first be reset (reporting 
 * any EOD matches if a non-NULL @p onEvent callback handler is provided). 
 * 
 * Note: the 'to' stream must be opened against the same database as the 
 * compressed stream. 
 * 
 * Note: @p buf must correspond to a complete compressed representation created 
 * by @ref hs_compress_stream() of a stream that was opened against @p db. It is 
 * not always possible to detect misuse of this API and behaviour is undefined 
 * if these properties are not satisfied. 
 * 
 * @param to_stream 
 *      A pointer to a valid stream state. A pointer to the expanded @ref 
 *      hs_stream_t will be returned; NULL on failure. 
 * 
 * @param buf 
 *      A compressed representation of a stream. These compressed forms are 
 *      created by @ref hs_compress_stream(). 
 * 
 * @param buf_size 
 *      The size in bytes of the compressed representation. 
 * 
 * @param scratch 
 *      A per-thread scratch space allocated by @ref hs_alloc_scratch(). This is 
 *      allowed to be NULL only if the @p onEvent callback is also NULL. 
 * 
 * @param onEvent 
 *      Pointer to a match event callback function. If a NULL pointer is given, 
 *      no matches will be returned. 
 * 
 * @param context 
 *      The user defined pointer which will be passed to the callback function 
 *      when a match occurs. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_reset_and_expand_stream(hs_stream_t *to_stream, 
                                               const char *buf, size_t buf_size, 
                                               hs_scratch_t *scratch, 
                                               match_event_handler onEvent, 
                                               void *context); 
 
/** 
 * The block (non-streaming) regular expression scanner. 
 * 
 * This is the function call in which the actual pattern matching takes place 
 * for block-mode pattern databases. 
 * 
 * @param db 
 *      A compiled pattern database. 
 * 
 * @param data 
 *      Pointer to the data to be scanned. 
 * 
 * @param length 
 *      The number of bytes to scan. 
 * 
 * @param flags 
 *      Flags modifying the behaviour of this function. This parameter is 
 *      provided for future use and is unused at present. 
 * 
 * @param scratch 
 *      A per-thread scratch space allocated by @ref hs_alloc_scratch() for this 
 *      database. 
 * 
 * @param onEvent 
 *      Pointer to a match event callback function. If a NULL pointer is given, 
 *      no matches will be returned. 
 * 
 * @param context 
 *      The user defined pointer which will be passed to the callback function. 
 * 
 * @return 
 *      Returns @ref HS_SUCCESS on success; @ref HS_SCAN_TERMINATED if the 
 *      match callback indicated that scanning should stop; other values on 
 *      error. 
 */ 
hs_error_t avx512_hs_scan(const hs_database_t *db, const char *data, 
                            unsigned int length, unsigned int flags, 
                            hs_scratch_t *scratch, match_event_handler onEvent, 
                            void *context); 
 
/** 
 * The vectored regular expression scanner. 
 * 
 * This is the function call in which the actual pattern matching takes place 
 * for vectoring-mode pattern databases. 
 * 
 * @param db 
 *      A compiled pattern database. 
 * 
 * @param data 
 *      An array of pointers to the data blocks to be scanned. 
 * 
 * @param length 
 *      An array of lengths (in bytes) of each data block to scan. 
 * 
 * @param count 
 *      Number of data blocks to scan. This should correspond to the size of 
 *      of the @p data and @p length arrays. 
 * 
 * @param flags 
 *      Flags modifying the behaviour of this function. This parameter is 
 *      provided for future use and is unused at present. 
 * 
 * @param scratch 
 *      A per-thread scratch space allocated by @ref hs_alloc_scratch() for 
 *      this database. 
 * 
 * @param onEvent 
 *      Pointer to a match event callback function. If a NULL pointer is given, 
 *      no matches will be returned. 
 * 
 * @param context 
 *      The user defined pointer which will be passed to the callback function. 
 * 
 * @return 
 *      Returns @ref HS_SUCCESS on success; @ref HS_SCAN_TERMINATED if the match 
 *      callback indicated that scanning should stop; other values on error. 
 */ 
hs_error_t avx512_hs_scan_vector(const hs_database_t *db, 
                                   const char *const *data, 
                                   const unsigned int *length, 
                                   unsigned int count, unsigned int flags, 
                                   hs_scratch_t *scratch, 
                                   match_event_handler onEvent, void *context); 
 
/** 
 * Allocate a "scratch" space for use by Hyperscan. 
 * 
 * This is required for runtime use, and one scratch space per thread, or 
 * concurrent caller, is required. Any allocator callback set by @ref 
 * hs_set_scratch_allocator() or @ref hs_set_allocator() will be used by this 
 * function. 
 * 
 * @param db 
 *      The database, as produced by @ref hs_compile(). 
 * 
 * @param scratch 
 *      On first allocation, a pointer to NULL should be provided so a new 
 *      scratch can be allocated. If a scratch block has been previously 
 *      allocated, then a pointer to it should be passed back in to see if it 
 *      is valid for this database block. If a new scratch block is required, 
 *      the original will be freed and the new one returned, otherwise the 
 *      previous scratch block will be returned. On success, the scratch block 
 *      will be suitable for use with the provided database in addition to any 
 *      databases that original scratch space was suitable for. 
 * 
 * @return 
 *      @ref HS_SUCCESS on successful allocation; @ref HS_NOMEM if the 
 *      allocation fails.  Other errors may be returned if invalid parameters 
 *      are specified. 
 */ 
hs_error_t avx512_hs_alloc_scratch(const hs_database_t *db, 
                                     hs_scratch_t **scratch); 
 
/** 
 * Allocate a scratch space that is a clone of an existing scratch space. 
 * 
 * This is useful when multiple concurrent threads will be using the same set 
 * of compiled databases, and another scratch space is required. Any allocator 
 * callback set by @ref hs_set_scratch_allocator() or @ref hs_set_allocator() 
 * will be used by this function. 
 * 
 * @param src 
 *      The existing @ref hs_scratch_t to be cloned. 
 * 
 * @param dest 
 *      A pointer to the new scratch space will be returned here. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success; @ref HS_NOMEM if the allocation fails. 
 *      Other errors may be returned if invalid parameters are specified. 
 */ 
hs_error_t avx512_hs_clone_scratch(const hs_scratch_t *src, 
                                     hs_scratch_t **dest); 
 
/** 
 * Provides the size of the given scratch space. 
 * 
 * @param scratch 
 *      A per-thread scratch space allocated by @ref hs_alloc_scratch() or @ref 
 *      hs_clone_scratch(). 
 * 
 * @param scratch_size 
 *      On success, the size of the scratch space in bytes is placed in this 
 *      parameter. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_scratch_size(const hs_scratch_t *scratch, 
                                    size_t *scratch_size); 
 
/** 
 * Free a scratch block previously allocated by @ref hs_alloc_scratch() or @ref 
 * hs_clone_scratch(). 
 * 
 * The free callback set by @ref hs_set_scratch_allocator() or @ref 
 * hs_set_allocator() will be used by this function. 
 * 
 * @param scratch 
 *      The scratch block to be freed. NULL may also be safely provided. 
 * 
 * @return 
 *      @ref HS_SUCCESS on success, other values on failure. 
 */ 
hs_error_t avx512_hs_free_scratch(hs_scratch_t *scratch); 
 
/** 
 * Callback 'from' return value, indicating that the start of this match was 
 * too early to be tracked with the requested SOM_HORIZON precision. 
 */ 
#define HS_OFFSET_PAST_HORIZON    (~0ULL) 
 
#ifdef __cplusplus 
} /* extern "C" */ 
#endif 
 
#endif /* HS_AVX512_RUNTIME_H */