include/SDL_test_fuzzer.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 18 May 2013 12:48:50 -0700
changeset 7190 11612d544fcd
parent 6885 700f1b25f77f
child 7191 75360622e65f
permissions -rw-r--r--
Added mobile application events, with implementations for iOS and Android
     1 /*
     2   Simple DirectMedia Layer
     3   Copyright (C) 1997-2013 Sam Lantinga <slouken@libsdl.org>
     4 
     5   This software is provided 'as-is', without any express or implied
     6   warranty.  In no event will the authors be held liable for any damages
     7   arising from the use of this software.
     8 
     9   Permission is granted to anyone to use this software for any purpose,
    10   including commercial applications, and to alter it and redistribute it
    11   freely, subject to the following restrictions:
    12 
    13   1. The origin of this software must not be misrepresented; you must not
    14      claim that you wrote the original software. If you use this software
    15      in a product, an acknowledgment in the product documentation would be
    16      appreciated but is not required.
    17   2. Altered source versions must be plainly marked as such, and must not be
    18      misrepresented as being the original software.
    19   3. This notice may not be removed or altered from any source distribution.
    20 */
    21 
    22 /**
    23  *  \file SDL_test_fuzzer.h
    24  *  
    25  *  Include file for SDL test framework.
    26  *
    27  *  This code is a part of the SDL2_test library, not the main SDL library.
    28  */
    29 
    30 /* 
    31 
    32   Data generators for fuzzing test data in a reproducible way.
    33  
    34 */
    35 
    36 #ifndef _SDL_test_fuzzer_h
    37 #define _SDL_test_fuzzer_h
    38 
    39 #include "begin_code.h"
    40 /* Set up for C function definitions, even when using C++ */
    41 #ifdef __cplusplus
    42 /* *INDENT-OFF* */
    43 extern "C" {
    44 /* *INDENT-ON* */
    45 #endif
    46 
    47 
    48 /*
    49   Based on GSOC code by Markus Kauppila <markus.kauppila@gmail.com>
    50 */
    51 
    52 
    53 /**
    54  * \file
    55  * Note: The fuzzer implementation uses a static instance of random context
    56  * internally which makes it thread-UNsafe.
    57  */
    58 
    59 /**
    60  * Initializes the fuzzer for a test
    61  *
    62  * /param execKey Execution "Key" that initializes the random number generator uniquely for the test.
    63  *
    64  */
    65 void SDLTest_FuzzerInit(Uint64 execKey);
    66 
    67 
    68 /**
    69  * Returns a random Uint8
    70  *
    71  * \returns Generated integer
    72  */
    73 Uint8 SDLTest_RandomUint8();
    74 
    75 /**
    76  * Returns a random Sint8
    77  *
    78  * \returns Generated signed integer
    79  */
    80 Sint8 SDLTest_RandomSint8();
    81 
    82 
    83 /**
    84  * Returns a random Uint16
    85  *
    86  * \returns Generated integer
    87  */
    88 Uint16 SDLTest_RandomUint16();
    89 
    90 /**
    91  * Returns a random Sint16
    92  *
    93  * \returns Generated signed integer
    94  */
    95 Sint16 SDLTest_RandomSint16();
    96 
    97 
    98 /**
    99  * Returns a random integer
   100  *
   101  * \returns Generated integer
   102  */
   103 Sint32 SDLTest_RandomSint32();
   104 
   105 
   106 /**
   107  * Returns a random positive integer
   108  *
   109  * \returns Generated integer
   110  */
   111 Uint32 SDLTest_RandomUint32();
   112 
   113 /**
   114  * Returns random Uint64.
   115  *
   116  * \returns Generated integer
   117  */
   118 Uint64 SDLTest_RandomUint64();
   119 
   120 
   121 /**
   122  * Returns random Sint64.
   123  *
   124  * \returns Generated signed integer
   125  */
   126 Sint64 SDLTest_RandomSint64();
   127 
   128 /**
   129  * \returns random float in range [0.0 - 1.0[
   130  */
   131 float SDLTest_RandomUnitFloat();
   132 
   133 /**
   134  * \returns random double in range [0.0 - 1.0[ 
   135  */
   136 double SDLTest_RandomUnitDouble();
   137 
   138 /**
   139  * \returns random float.
   140  *
   141  */
   142 float SDLTest_RandomFloat();
   143 
   144 /**
   145  * \returns random double.
   146  *
   147  */
   148 double SDLTest_RandomDouble();
   149 
   150 /**
   151  * Returns a random boundary value for Uint8 within the given boundaries.
   152  * Boundaries are inclusive, see the usage examples below. If validDomain
   153  * is true, the function will only return valid boundaries, otherwise non-valid
   154  * boundaries are also possible.
   155  * If boundary1 > boundary2, the values are swapped
   156  *
   157  * Usage examples:
   158  * RandomUint8BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20
   159  * RandomUint8BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21
   160  * RandomUint8BoundaryValue(0, 99, SDL_FALSE) returns 100
   161  * RandomUint8BoundaryValue(0, 255, SDL_FALSE) returns 0 (error set)
   162  *
   163  * \param boundary1 Lower boundary limit
   164  * \param boundary2 Upper boundary limit
   165  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
   166  *
   167  * \returns Random boundary value for the given range and domain or 0 with error set
   168  */
   169 Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain);
   170 
   171 /**
   172  * Returns a random boundary value for Uint16 within the given boundaries.
   173  * Boundaries are inclusive, see the usage examples below. If validDomain
   174  * is true, the function will only return valid boundaries, otherwise non-valid
   175  * boundaries are also possible.
   176  * If boundary1 > boundary2, the values are swapped
   177  *
   178  * Usage examples:
   179  * RandomUint16BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20
   180  * RandomUint16BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21
   181  * RandomUint16BoundaryValue(0, 99, SDL_FALSE) returns 100
   182  * RandomUint16BoundaryValue(0, 0xFFFF, SDL_FALSE) returns 0 (error set)
   183  *
   184  * \param boundary1 Lower boundary limit
   185  * \param boundary2 Upper boundary limit
   186  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
   187  *
   188  * \returns Random boundary value for the given range and domain or 0 with error set
   189  */
   190 Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain);
   191 
   192 /**
   193  * Returns a random boundary value for Uint32 within the given boundaries.
   194  * Boundaries are inclusive, see the usage examples below. If validDomain
   195  * is true, the function will only return valid boundaries, otherwise non-valid
   196  * boundaries are also possible.
   197  * If boundary1 > boundary2, the values are swapped
   198  *
   199  * Usage examples:
   200  * RandomUint32BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20
   201  * RandomUint32BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21
   202  * RandomUint32BoundaryValue(0, 99, SDL_FALSE) returns 100
   203  * RandomUint32BoundaryValue(0, 0xFFFFFFFF, SDL_FALSE) returns 0 (with error set)
   204  *
   205  * \param boundary1 Lower boundary limit
   206  * \param boundary2 Upper boundary limit
   207  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
   208  *
   209  * \returns Random boundary value for the given range and domain or 0 with error set
   210  */
   211 Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain);
   212 
   213 /**
   214  * Returns a random boundary value for Uint64 within the given boundaries.
   215  * Boundaries are inclusive, see the usage examples below. If validDomain
   216  * is true, the function will only return valid boundaries, otherwise non-valid
   217  * boundaries are also possible.
   218  * If boundary1 > boundary2, the values are swapped
   219  *
   220  * Usage examples:
   221  * RandomUint64BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20
   222  * RandomUint64BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21
   223  * RandomUint64BoundaryValue(0, 99, SDL_FALSE) returns 100
   224  * RandomUint64BoundaryValue(0, 0xFFFFFFFFFFFFFFFF, SDL_FALSE) returns 0 (with error set)
   225  *
   226  * \param boundary1 Lower boundary limit
   227  * \param boundary2 Upper boundary limit
   228  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
   229  *
   230  * \returns Random boundary value for the given range and domain or 0 with error set
   231  */
   232 Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain);
   233 
   234 /**
   235  * Returns a random boundary value for Sint8 within the given boundaries.
   236  * Boundaries are inclusive, see the usage examples below. If validDomain
   237  * is true, the function will only return valid boundaries, otherwise non-valid
   238  * boundaries are also possible.
   239  * If boundary1 > boundary2, the values are swapped
   240  *
   241  * Usage examples:
   242  * RandomSint8BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20
   243  * RandomSint8BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9
   244  * RandomSint8BoundaryValue(SINT8_MIN, 99, SDL_FALSE) returns 100
   245  * RandomSint8BoundaryValue(SINT8_MIN, SINT8_MAX, SDL_FALSE) returns SINT8_MIN (== error value) with error set
   246  *
   247  * \param boundary1 Lower boundary limit
   248  * \param boundary2 Upper boundary limit
   249  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
   250  *
   251  * \returns Random boundary value for the given range and domain or SINT8_MIN with error set
   252  */
   253 Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain);
   254 
   255 
   256 /**
   257  * Returns a random boundary value for Sint16 within the given boundaries.
   258  * Boundaries are inclusive, see the usage examples below. If validDomain
   259  * is true, the function will only return valid boundaries, otherwise non-valid
   260  * boundaries are also possible.
   261  * If boundary1 > boundary2, the values are swapped
   262  *
   263  * Usage examples:
   264  * RandomSint16BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20
   265  * RandomSint16BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9
   266  * RandomSint16BoundaryValue(SINT16_MIN, 99, SDL_FALSE) returns 100
   267  * RandomSint16BoundaryValue(SINT16_MIN, SINT16_MAX, SDL_FALSE) returns SINT16_MIN (== error value) with error set
   268  *
   269  * \param boundary1 Lower boundary limit
   270  * \param boundary2 Upper boundary limit
   271  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
   272  *
   273  * \returns Random boundary value for the given range and domain or SINT16_MIN with error set
   274  */
   275 Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain);
   276 
   277 /**
   278  * Returns a random boundary value for Sint32 within the given boundaries.
   279  * Boundaries are inclusive, see the usage examples below. If validDomain
   280  * is true, the function will only return valid boundaries, otherwise non-valid
   281  * boundaries are also possible.
   282  * If boundary1 > boundary2, the values are swapped
   283  *
   284  * Usage examples:
   285  * RandomSint32BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20
   286  * RandomSint32BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9
   287  * RandomSint32BoundaryValue(SINT32_MIN, 99, SDL_FALSE) returns 100
   288  * RandomSint32BoundaryValue(SINT32_MIN, SINT32_MAX, SDL_FALSE) returns SINT32_MIN (== error value)
   289  *
   290  * \param boundary1 Lower boundary limit
   291  * \param boundary2 Upper boundary limit
   292  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
   293  *
   294  * \returns Random boundary value for the given range and domain or SINT32_MIN with error set
   295  */
   296 Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain);
   297 
   298 /**
   299  * Returns a random boundary value for Sint64 within the given boundaries.
   300  * Boundaries are inclusive, see the usage examples below. If validDomain
   301  * is true, the function will only return valid boundaries, otherwise non-valid
   302  * boundaries are also possible.
   303  * If boundary1 > boundary2, the values are swapped
   304  *
   305  * Usage examples:
   306  * RandomSint64BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20
   307  * RandomSint64BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9
   308  * RandomSint64BoundaryValue(SINT64_MIN, 99, SDL_FALSE) returns 100
   309  * RandomSint64BoundaryValue(SINT64_MIN, SINT64_MAX, SDL_FALSE) returns SINT64_MIN (== error value) and error set
   310  *
   311  * \param boundary1 Lower boundary limit
   312  * \param boundary2 Upper boundary limit
   313  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
   314  *
   315  * \returns Random boundary value for the given range and domain or SINT64_MIN with error set
   316  */
   317 Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain);
   318 
   319 
   320 /**
   321  * Returns integer in range [min, max] (inclusive).
   322  * Min and max values can be negative values.
   323  * If Max in smaller tham min, then the values are swapped.
   324  * Min and max are the same value, that value will be returned.
   325  *
   326  * \param min Minimum inclusive value of returned random number
   327  * \param max Maximum inclusive value of returned random number
   328  *
   329  * \returns Generated random integer in range
   330  */
   331 Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
   332 
   333 
   334 /**
   335  * Generates random null-terminated string. The minimum length for
   336  * the string is 1 character, maximum length for the string is 255 
   337  * characters and it can contain ASCII characters from 32 to 126.
   338  *
   339  * Note: Returned string needs to be deallocated.
   340  *
   341  * \returns Newly allocated random string; or NULL if length was invalid or string could not be allocated.
   342  */
   343 char * SDLTest_RandomAsciiString();
   344 
   345 
   346 /**
   347  * Generates random null-terminated string. The maximum length for
   348  * the string is defined by the maxLength parameter.
   349  * String can contain ASCII characters from 32 to 126.
   350  *
   351  * Note: Returned string needs to be deallocated.
   352  *
   353  * \param maxLength The maximum length of the generated string.
   354  *
   355  * \returns Newly allocated random string; or NULL if maxLength was invalid or string could not be allocated. 
   356  */
   357 char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
   358 
   359 
   360 /**
   361  * Generates random null-terminated string. The length for
   362  * the string is defined by the size parameter.
   363  * String can contain ASCII characters from 32 to 126.
   364  *
   365  * Note: Returned string needs to be deallocated.
   366  *
   367  * \param size The length of the generated string
   368  *
   369  * \returns Newly allocated random string; or NULL if size was invalid or string could not be allocated.
   370  */
   371 char * SDLTest_RandomAsciiStringOfSize(int size);
   372 
   373 /**
   374  * Returns the invocation count for the fuzzer since last ...FuzzerInit.
   375  */
   376 int SDLTest_GetFuzzerInvocationCount();
   377 
   378 /* Ends C function definitions when using C++ */
   379 #ifdef __cplusplus
   380 /* *INDENT-OFF* */
   381 }
   382 /* *INDENT-ON* */
   383 #endif
   384 #include "close_code.h"
   385 
   386 #endif /* _SDL_test_fuzzer_h */
   387 
   388 /* vi: set ts=4 sw=4 expandtab: */