path: root/contrib/libs/hyperscan/src/nfa/nfa_api.h

/* 
 * Copyright (c) 2015-2016, 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. 
 */ 
 
/** \file 
 * \brief Declarations for the main NFA Engine API. 
 * 
 * This file provides the internal API for all runtime engines ("NFAs", even if 
 * they're not strictly NFA implementations). 
 */ 
 
#ifndef NFA_API_H 
#define NFA_API_H 
 
#ifdef __cplusplus 
extern "C" 
{ 
#endif 
 
#include "callback.h" 
#include "ue2common.h" 
 
struct mq; 
struct NFA; 
 
/** 
 * Indicates if an nfa is a zombie. Note: that there were plans for a more 
 * nuanced view of zombiehood but this never eventuated. 
 */ 
enum nfa_zombie_status { 
    NFA_ZOMBIE_NO, /**< nfa is not a zombie and will respond to top events */ 
    NFA_ZOMBIE_ALWAYS_YES /**< nfa is a zombie and will always be a zombie */ 
}; 
 
/** 
 * Compresses an engine's state. 
 * The expanded state (@ref mq::state, @ref mq::streamState) is reduced purely 
 * to a corresponding compressed stream state (@ref mq::streamState). 
 * 
 * @param nfa engine the state belongs to 
 * @param q queue for the engine. The final compressed stream stream is placed 
 *        in the location indicated by @ref mq::streamState 
 * @param loc the location corresponding to the engine's current state 
 */ 
char nfaQueueCompressState(const struct NFA *nfa, const struct mq *q, s64a loc); 
 
/** 
 * Expands an engine's compressed stream state, into its scratch space 
 * representation. This is required before an engine starts operating over its 
 * queue. 
 * 
 * @param nfa engine the state belongs to 
 * @param dest location in scratch for decompressed state 
 * @param src compressed stream state 
 * @param offset the current stream offset. 
 * @param key byte corresponding to the location where the compressed state was 
 *        created. 
 */ 
char nfaExpandState(const struct NFA *nfa, void *dest, const void *src, 
                    u64a offset, u8 key); 
 
/** 
 * Gives us a properly initialised dead state suitable for later @ref 
 * nfaQueueExec calls. 
 */ 
char nfaQueueInitState(const struct NFA *nfa, struct mq *q); 
 
/** 
 * Initialise the state, applying a TOP appropriate for the offset. If the 
 * NFA becomes inactive, return zero. Otherwise, write out its compressed 
 * representation to `state' and return non-zero. 
 * 
 * @param nfa engine the state belongs to 
 * @param offset offset in the stream (relative to start of stream) 
 * @param state pointer indicating where the state is to be written 
 * @param key byte corresponding to the location where the compressed state is 
 *        to be created. 
 */ 
char nfaInitCompressedState(const struct NFA *nfa, u64a offset, void *state, 
                            u8 key); 
 
/** 
 * Process the queued commands on the given NFA. 
 * 
 * @param nfa the NFA to execute 
 * @param q the queued commands. It must start with some variant of start and 
 *        end with some variant of end. The location field of the events must 
 *        be monotonically increasing. 
 * @param end stop processing command queue when we reach this point 
 * 
 * @return non-zero if the nfa is still active, if the nfa is not active the 
 *         state data is undefined 
 * 
 * Note: this function can not process events from the past: the location field 
 * of each event must be >= current offset. 
 */ 
char nfaQueueExec(const struct NFA *nfa, struct mq *q, s64a end); 
 
/**
 * Main execution function that doesn't perform the checks and optimisations of
 * nfaQueueExec() and just dispatches directly to the nfa implementations. It is
 * intended to be used by the Tamarama engine.
 */
char nfaQueueExec_raw(const struct NFA *nfa, struct mq *q, s64a end);

/** Return value indicating that the engine is dead. */
#define MO_DEAD 0

/** Return value indicating that the engine is alive. */ 
#define MO_ALIVE 1 
 
/** Return value from @ref nfaQueueExecToMatch indicating that engine progress 
 * stopped as a match state was reached. */ 
#define MO_MATCHES_PENDING 2 
 
/** 
 * Process the queued commands on the given nfa up to end or the first match. 
 * This function will only fire the callback in response to an report_current 
 * being set and accepts at the starting offset, in all other situations accepts 
 * will result in the queue pausing with a return value of 
 * @ref MO_MATCHES_PENDING. 
 * 
 * @param nfa the NFA to execute 
 * @param q the queued commands. It must start with some variant of start and 
 *        end with some variant of end. The location field of the events must 
 *        be monotonically increasing. If not all the data was processed during 
 *        the call, the queue is updated to reflect the remaining work. 
 * @param end stop processing command queue when we reach this point 
 * 
 * @return @ref MO_ALIVE if the nfa is still active with no matches pending, 
 *         and @ref MO_MATCHES_PENDING if there are matches pending, 0 if not 
 *         alive 
 * 
 * Note: if it can be determined that the stream can never match, the nfa 
 * may be reported as dead even if not all the data was scanned 
 * 
 * Note: if the nfa is not alive the state data is undefined 
 * 
 * Note: this function can not process events from the past: the location field 
 * of each event must be >= current offset. 
 */ 
char nfaQueueExecToMatch(const struct NFA *nfa, struct mq *q, s64a end); 
 
/** 
 * Main execution function that doesn't perform the checks and optimisations of
 * nfaQueueExecToMatch() and just dispatches directly to the nfa
 * implementations. It is intended to be used by the Tamarama engine.
 */
char nfaQueueExec2_raw(const struct NFA *nfa, struct mq *q, s64a end);

/**
 * Report matches at the current queue location. 
 * 
 * @param nfa the NFA to execute 
 * @param q the queued commands. It must start with some variant of start and 
 *         end with some variant of end. The location field of the events must 
 *         be monotonically increasing. 
 * 
 * Note: the queue MUST be located at position where @ref nfaQueueExecToMatch 
 *       returned @ref MO_MATCHES_PENDING. 
 * 
 * Note: the return value of this call is undefined, and should be ignored. 
 */ 
char nfaReportCurrentMatches(const struct NFA *nfa, struct mq *q); 
 
/** 
 * Returns non-zero if the NFA is in an accept state with the given report ID. 
 */ 
char nfaInAcceptState(const struct NFA *nfa, ReportID report, struct mq *q); 
 
/** 
 * Returns non-zero if the NFA is in any accept state regardless of report
 * ID.
 */
char nfaInAnyAcceptState(const struct NFA *nfa, struct mq *q);

/**
 * Process the queued commands on the given NFA up to end or the first match. 
 * 
 * Note: This version is meant for rose prefix/infix NFAs:
 *  - never uses a callback 
 *  - loading of state at a point in history is not special cased 
 * 
 * @param nfa the NFA to execute 
 * @param q the queued commands. It must start with some variant of start and 
 *        end with some variant of end. The location field of the events must 
 *        be monotonically increasing. If not all the data was processed during 
 *        the call, the queue is updated to reflect the remaining work. 
 * @param report we are interested in. If the given report will be raised at
 *        the end location, the function returns @ref MO_MATCHES_PENDING. If no
 *        match information is desired, MO_INVALID_IDX should be passed in.
 * @return @ref MO_ALIVE if the nfa is still active with no matches pending, 
 *         and @ref MO_MATCHES_PENDING if there are matches pending, 0 if not 
 *         alive 
 * 
 * Note: if it can be determined that the stream can never match, the nfa 
 * may be reported as dead even if not all the data was scanned 
 * 
 * Note: if the NFA is not active the state data is undefined. 
 */ 
char nfaQueueExecRose(const struct NFA *nfa, struct mq *q, ReportID report); 
 
/** 
 * Runs an NFA in reverse from (buf + buflen) to buf and then from (hbuf + hlen) 
 * to hbuf (main buffer and history buffer). 
 * 
 * Note: provides the match location as the "end" offset when the callback is
 * called.
 *
 * @param nfa engine to run 
 * @param offset base offset of buf 
 * @param buf main buffer 
 * @param buflen length of buf 
 * @param hbuf history buf 
 * @param hlen length of hbuf 
 * @param callback the callback to call for each match raised 
 * @param context context pointer passed to each callback 
 */ 
char nfaBlockExecReverse(const struct NFA *nfa, u64a offset, const u8 *buf, 
                         size_t buflen, const u8 *hbuf, size_t hlen, 
                         NfaCallback callback, void *context);
 
/** 
 * Check whether the given NFA's state indicates that it is in one or more 
 * final (accept at end of data) state. If so, call the callback for each 
 * match. 
 * 
 * @param nfa the NFA to execute 
 * @param state current state associated with this NFA 
 * @param streamState stream version of the state associated with this NFA 
 *        (including br region) 
 * @param offset the offset to return (via the callback) with each match 
 * @param callback the callback to call for each match raised 
 * @param context context pointer passed to each callback 
 *
 * @return @ref MO_HALT_MATCHING if the user instructed us to halt, otherwise
 *         @ref MO_CONTINUE_MATCHING.
 */ 
char nfaCheckFinalState(const struct NFA *nfa, const char *state, 
                        const char *streamState, u64a offset, 
                        NfaCallback callback, void *context);
 
/** 
 * Indicates if an engine is a zombie. 
 * 
 * @param nfa engine to consider 
 * @param q queue corresponding to the engine 
 * @param loc current location in the buffer for an engine 
 */ 
enum nfa_zombie_status nfaGetZombieStatus(const struct NFA *nfa, struct mq *q, 
                                          s64a loc); 
#ifdef __cplusplus 
}       /* extern "C" */ 
#endif 
 
#endif