1 | /* |
2 | * Copyright (c) 2015-2016, Intel Corporation |
3 | * |
4 | * Redistribution and use in source and binary forms, with or without |
5 | * modification, are permitted provided that the following conditions are met: |
6 | * |
7 | * * Redistributions of source code must retain the above copyright notice, |
8 | * this list of conditions and the following disclaimer. |
9 | * * Redistributions in binary form must reproduce the above copyright |
10 | * notice, this list of conditions and the following disclaimer in the |
11 | * documentation and/or other materials provided with the distribution. |
12 | * * Neither the name of Intel Corporation nor the names of its contributors |
13 | * may be used to endorse or promote products derived from this software |
14 | * without specific prior written permission. |
15 | * |
16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
26 | * POSSIBILITY OF SUCH DAMAGE. |
27 | */ |
28 | |
29 | /** \file |
30 | * \brief Declarations for the main NFA Engine API. |
31 | * |
32 | * This file provides the internal API for all runtime engines ("NFAs", even if |
33 | * they're not strictly NFA implementations). |
34 | */ |
35 | |
36 | #ifndef NFA_API_H |
37 | #define NFA_API_H |
38 | |
39 | #ifdef __cplusplus |
40 | extern "C" |
41 | { |
42 | #endif |
43 | |
44 | #include "callback.h" |
45 | #include "ue2common.h" |
46 | |
47 | struct mq; |
48 | struct NFA; |
49 | |
50 | /** |
51 | * Indicates if an nfa is a zombie. Note: that there were plans for a more |
52 | * nuanced view of zombiehood but this never eventuated. |
53 | */ |
54 | enum nfa_zombie_status { |
55 | NFA_ZOMBIE_NO, /**< nfa is not a zombie and will respond to top events */ |
56 | NFA_ZOMBIE_ALWAYS_YES /**< nfa is a zombie and will always be a zombie */ |
57 | }; |
58 | |
59 | /** |
60 | * Compresses an engine's state. |
61 | * The expanded state (@ref mq::state, @ref mq::streamState) is reduced purely |
62 | * to a corresponding compressed stream state (@ref mq::streamState). |
63 | * |
64 | * @param nfa engine the state belongs to |
65 | * @param q queue for the engine. The final compressed stream stream is placed |
66 | * in the location indicated by @ref mq::streamState |
67 | * @param loc the location corresponding to the engine's current state |
68 | */ |
69 | char nfaQueueCompressState(const struct NFA *nfa, const struct mq *q, s64a loc); |
70 | |
71 | /** |
72 | * Expands an engine's compressed stream state, into its scratch space |
73 | * representation. This is required before an engine starts operating over its |
74 | * queue. |
75 | * |
76 | * @param nfa engine the state belongs to |
77 | * @param dest location in scratch for decompressed state |
78 | * @param src compressed stream state |
79 | * @param offset the current stream offset. |
80 | * @param key byte corresponding to the location where the compressed state was |
81 | * created. |
82 | */ |
83 | char nfaExpandState(const struct NFA *nfa, void *dest, const void *src, |
84 | u64a offset, u8 key); |
85 | |
86 | /** |
87 | * Gives us a properly initialised dead state suitable for later @ref |
88 | * nfaQueueExec calls. |
89 | */ |
90 | char nfaQueueInitState(const struct NFA *nfa, struct mq *q); |
91 | |
92 | /** |
93 | * Initialise the state, applying a TOP appropriate for the offset. If the |
94 | * NFA becomes inactive, return zero. Otherwise, write out its compressed |
95 | * representation to `state' and return non-zero. |
96 | * |
97 | * @param nfa engine the state belongs to |
98 | * @param offset offset in the stream (relative to start of stream) |
99 | * @param state pointer indicating where the state is to be written |
100 | * @param key byte corresponding to the location where the compressed state is |
101 | * to be created. |
102 | */ |
103 | char nfaInitCompressedState(const struct NFA *nfa, u64a offset, void *state, |
104 | u8 key); |
105 | |
106 | /** |
107 | * Process the queued commands on the given NFA. |
108 | * |
109 | * @param nfa the NFA to execute |
110 | * @param q the queued commands. It must start with some variant of start and |
111 | * end with some variant of end. The location field of the events must |
112 | * be monotonically increasing. |
113 | * @param end stop processing command queue when we reach this point |
114 | * |
115 | * @return non-zero if the nfa is still active, if the nfa is not active the |
116 | * state data is undefined |
117 | * |
118 | * Note: this function can not process events from the past: the location field |
119 | * of each event must be >= current offset. |
120 | */ |
121 | char nfaQueueExec(const struct NFA *nfa, struct mq *q, s64a end); |
122 | |
123 | /** |
124 | * Main execution function that doesn't perform the checks and optimisations of |
125 | * nfaQueueExec() and just dispatches directly to the nfa implementations. It is |
126 | * intended to be used by the Tamarama engine. |
127 | */ |
128 | char nfaQueueExec_raw(const struct NFA *nfa, struct mq *q, s64a end); |
129 | |
130 | /** Return value indicating that the engine is dead. */ |
131 | #define MO_DEAD 0 |
132 | |
133 | /** Return value indicating that the engine is alive. */ |
134 | #define MO_ALIVE 1 |
135 | |
136 | /** Return value from @ref nfaQueueExecToMatch indicating that engine progress |
137 | * stopped as a match state was reached. */ |
138 | #define MO_MATCHES_PENDING 2 |
139 | |
140 | /** |
141 | * Process the queued commands on the given nfa up to end or the first match. |
142 | * This function will only fire the callback in response to an report_current |
143 | * being set and accepts at the starting offset, in all other situations accepts |
144 | * will result in the queue pausing with a return value of |
145 | * @ref MO_MATCHES_PENDING. |
146 | * |
147 | * @param nfa the NFA to execute |
148 | * @param q the queued commands. It must start with some variant of start and |
149 | * end with some variant of end. The location field of the events must |
150 | * be monotonically increasing. If not all the data was processed during |
151 | * the call, the queue is updated to reflect the remaining work. |
152 | * @param end stop processing command queue when we reach this point |
153 | * |
154 | * @return @ref MO_ALIVE if the nfa is still active with no matches pending, |
155 | * and @ref MO_MATCHES_PENDING if there are matches pending, 0 if not |
156 | * alive |
157 | * |
158 | * Note: if it can be determined that the stream can never match, the nfa |
159 | * may be reported as dead even if not all the data was scanned |
160 | * |
161 | * Note: if the nfa is not alive the state data is undefined |
162 | * |
163 | * Note: this function can not process events from the past: the location field |
164 | * of each event must be >= current offset. |
165 | */ |
166 | char nfaQueueExecToMatch(const struct NFA *nfa, struct mq *q, s64a end); |
167 | |
168 | /** |
169 | * Main execution function that doesn't perform the checks and optimisations of |
170 | * nfaQueueExecToMatch() and just dispatches directly to the nfa |
171 | * implementations. It is intended to be used by the Tamarama engine. |
172 | */ |
173 | char nfaQueueExec2_raw(const struct NFA *nfa, struct mq *q, s64a end); |
174 | |
175 | /** |
176 | * Report matches at the current queue location. |
177 | * |
178 | * @param nfa the NFA to execute |
179 | * @param q the queued commands. It must start with some variant of start and |
180 | * end with some variant of end. The location field of the events must |
181 | * be monotonically increasing. |
182 | * |
183 | * Note: the queue MUST be located at position where @ref nfaQueueExecToMatch |
184 | * returned @ref MO_MATCHES_PENDING. |
185 | * |
186 | * Note: the return value of this call is undefined, and should be ignored. |
187 | */ |
188 | char nfaReportCurrentMatches(const struct NFA *nfa, struct mq *q); |
189 | |
190 | /** |
191 | * Returns non-zero if the NFA is in an accept state with the given report ID. |
192 | */ |
193 | char nfaInAcceptState(const struct NFA *nfa, ReportID report, struct mq *q); |
194 | |
195 | /** |
196 | * Returns non-zero if the NFA is in any accept state regardless of report |
197 | * ID. |
198 | */ |
199 | char nfaInAnyAcceptState(const struct NFA *nfa, struct mq *q); |
200 | |
201 | /** |
202 | * Process the queued commands on the given NFA up to end or the first match. |
203 | * |
204 | * Note: This version is meant for rose prefix/infix NFAs: |
205 | * - never uses a callback |
206 | * - loading of state at a point in history is not special cased |
207 | * |
208 | * @param nfa the NFA to execute |
209 | * @param q the queued commands. It must start with some variant of start and |
210 | * end with some variant of end. The location field of the events must |
211 | * be monotonically increasing. If not all the data was processed during |
212 | * the call, the queue is updated to reflect the remaining work. |
213 | * @param report we are interested in. If the given report will be raised at |
214 | * the end location, the function returns @ref MO_MATCHES_PENDING. If no |
215 | * match information is desired, MO_INVALID_IDX should be passed in. |
216 | * @return @ref MO_ALIVE if the nfa is still active with no matches pending, |
217 | * and @ref MO_MATCHES_PENDING if there are matches pending, 0 if not |
218 | * alive |
219 | * |
220 | * Note: if it can be determined that the stream can never match, the nfa |
221 | * may be reported as dead even if not all the data was scanned |
222 | * |
223 | * Note: if the NFA is not active the state data is undefined. |
224 | */ |
225 | char nfaQueueExecRose(const struct NFA *nfa, struct mq *q, ReportID report); |
226 | |
227 | /** |
228 | * Runs an NFA in reverse from (buf + buflen) to buf and then from (hbuf + hlen) |
229 | * to hbuf (main buffer and history buffer). |
230 | * |
231 | * Note: provides the match location as the "end" offset when the callback is |
232 | * called. |
233 | * |
234 | * @param nfa engine to run |
235 | * @param offset base offset of buf |
236 | * @param buf main buffer |
237 | * @param buflen length of buf |
238 | * @param hbuf history buf |
239 | * @param hlen length of hbuf |
240 | * @param callback the callback to call for each match raised |
241 | * @param context context pointer passed to each callback |
242 | */ |
243 | char nfaBlockExecReverse(const struct NFA *nfa, u64a offset, const u8 *buf, |
244 | size_t buflen, const u8 *hbuf, size_t hlen, |
245 | NfaCallback callback, void *context); |
246 | |
247 | /** |
248 | * Check whether the given NFA's state indicates that it is in one or more |
249 | * final (accept at end of data) state. If so, call the callback for each |
250 | * match. |
251 | * |
252 | * @param nfa the NFA to execute |
253 | * @param state current state associated with this NFA |
254 | * @param streamState stream version of the state associated with this NFA |
255 | * (including br region) |
256 | * @param offset the offset to return (via the callback) with each match |
257 | * @param callback the callback to call for each match raised |
258 | * @param context context pointer passed to each callback |
259 | * |
260 | * @return @ref MO_HALT_MATCHING if the user instructed us to halt, otherwise |
261 | * @ref MO_CONTINUE_MATCHING. |
262 | */ |
263 | char nfaCheckFinalState(const struct NFA *nfa, const char *state, |
264 | const char *streamState, u64a offset, |
265 | NfaCallback callback, void *context); |
266 | |
267 | /** |
268 | * Indicates if an engine is a zombie. |
269 | * |
270 | * @param nfa engine to consider |
271 | * @param q queue corresponding to the engine |
272 | * @param loc current location in the buffer for an engine |
273 | */ |
274 | enum nfa_zombie_status nfaGetZombieStatus(const struct NFA *nfa, struct mq *q, |
275 | s64a loc); |
276 | #ifdef __cplusplus |
277 | } /* extern "C" */ |
278 | #endif |
279 | |
280 | #endif |
281 | |