├── .gitignore
├── .travis.yml
├── CHANGELOG.md
├── COPYING
├── Doxyfile
├── Makefile
├── README.md
├── example.c
├── ringfs.c
├── ringfs.h
└── tests
    ├── flashsim.c
    ├── flashsim.h
    ├── fuzzer.py
    ├── pyflashsim.py
    ├── pyringfs.py
    ├── sharedlibrary.py
    └── tests.c


/.gitignore:
--------------------------------------------------------------------------------
 1 | *.o
 2 | *.so
 3 | *.pyc
 4 | *.pyo
 5 | *~
 6 | *.bak
 7 | *.diff
 8 | .*.swp
 9 | ringfs
10 | tests/tests
11 | example
12 | tags
13 | html/
14 | *.sim
15 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
 1 | language: c
 2 | compiler:
 3 |     - gcc
 4 |     - clang
 5 | before_install:
 6 |     - if [ "$CC" == "gcc" ]; then
 7 |           sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test;
 8 |           sudo apt-get update -qq;
 9 |       fi
10 | install:
11 |     - if [ "$CC" == "gcc" ]; then
12 |           sudo apt-get install -qq gcc-4.8;
13 |           export CC="gcc-4.8";
14 |       fi
15 |     - sudo apt-get install check
16 | script: make test
17 | notifications:
18 |   email:
19 |     on_success: change
20 |     on_failure: change
21 |   hipchat:
22 |     format: html
23 |     template:
24 |       - "<a href='https://github.com/%{repository}'>%{repository}</a>#<a href='%{build_url}'>%{build_number}</a>: <code><a href='%{compare_url}'>%{commit}</a></code> on <code>%{branch}</code> by %{author} has <a href='%{build_url}'>%{result}</a>."
25 |     rooms:
26 |       secure: YCtUInhx74toFNey9E4V/5tbR1kGZqIBmn16l+Gmz5U+xba52pRPunegAqXZ1Ew8zA5+ppJb/BNugCiNtRWN/tZh/Er/hTV4zRwXJre3+gbHjzTS8QnALrl7fWPFKe5C1QMHdRHv6crBQ471YZLxUO4Imu5bvTW5BFOnJhVEuuI=
27 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # RingFS changelog
 2 | 
 3 | ## 0.2.0, released 2014/05/07
 4 | 
 5 | * BUGFIX: used_seen was not updated in ringfs_scan(), causing corruption.
 6 | * Improved tests.
 7 | * Basic Python bindings.
 8 | * Basic fuzzing support.
 9 | 
10 | ## 0.1.0, released 2014/04/28
11 | 
12 | First "full" release. Entire API is implemented but subject to change.
13 | Tests cover most common cases.
14 | 


--------------------------------------------------------------------------------
/COPYING:
--------------------------------------------------------------------------------
 1 |         DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
 2 |                     Version 2, December 2004
 3 | 
 4 |  Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
 5 | 
 6 |  Everyone is permitted to copy and distribute verbatim or modified
 7 |  copies of this license document, and changing it is allowed as long
 8 |  as the name is changed.
 9 | 
10 |             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
11 |    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
12 | 
13 |   0. You just DO WHAT THE FUCK YOU WANT TO.
14 | 


--------------------------------------------------------------------------------
/Doxyfile:
--------------------------------------------------------------------------------
   1 | # Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
   2 | # This program is free software. It comes without any warranty, to the extent
   3 | # permitted by applicable law. You can redistribute it and/or modify it under
   4 | # the terms of the Do What The Fuck You Want To Public License, Version 2, as
   5 | # published by Sam Hocevar. See the COPYING file for more details.
   6 | 
   7 | # Doxyfile 1.8.6
   8 | 
   9 | # This file describes the settings to be used by the documentation system
  10 | # doxygen (www.doxygen.org) for a project.
  11 | #
  12 | # All text after a double hash (##) is considered a comment and is placed in
  13 | # front of the TAG it is preceding.
  14 | #
  15 | # All text after a single hash (#) is considered a comment and will be ignored.
  16 | # The format is:
  17 | # TAG = value [value, ...]
  18 | # For lists, items can also be appended using:
  19 | # TAG += value [value, ...]
  20 | # Values that contain spaces should be placed between quotes (\" \").
  21 | 
  22 | #---------------------------------------------------------------------------
  23 | # Project related configuration options
  24 | #---------------------------------------------------------------------------
  25 | 
  26 | # This tag specifies the encoding used for all characters in the config file
  27 | # that follow. The default is UTF-8 which is also the encoding used for all text
  28 | # before the first occurrence of this tag. Doxygen uses libiconv (or the iconv
  29 | # built into libc) for the transcoding. See http://www.gnu.org/software/libiconv
  30 | # for the list of possible encodings.
  31 | # The default value is: UTF-8.
  32 | 
  33 | DOXYFILE_ENCODING      = UTF-8
  34 | 
  35 | # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
  36 | # double-quotes, unless you are using Doxywizard) that should identify the
  37 | # project for which the documentation is generated. This name is used in the
  38 | # title of most generated pages and in a few other places.
  39 | # The default value is: My Project.
  40 | 
  41 | PROJECT_NAME           = "ringfs"
  42 | 
  43 | # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
  44 | # could be handy for archiving the generated documentation or if some version
  45 | # control system is used.
  46 | 
  47 | PROJECT_NUMBER         =
  48 | 
  49 | # Using the PROJECT_BRIEF tag one can provide an optional one line description
  50 | # for a project that appears at the top of each page and should give viewer a
  51 | # quick idea about the purpose of the project. Keep the description short.
  52 | 
  53 | PROJECT_BRIEF          =
  54 | 
  55 | # With the PROJECT_LOGO tag one can specify an logo or icon that is included in
  56 | # the documentation. The maximum height of the logo should not exceed 55 pixels
  57 | # and the maximum width should not exceed 200 pixels. Doxygen will copy the logo
  58 | # to the output directory.
  59 | 
  60 | PROJECT_LOGO           =
  61 | 
  62 | # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
  63 | # into which the generated documentation will be written. If a relative path is
  64 | # entered, it will be relative to the location where doxygen was started. If
  65 | # left blank the current directory will be used.
  66 | 
  67 | OUTPUT_DIRECTORY       =
  68 | 
  69 | # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub-
  70 | # directories (in 2 levels) under the output directory of each output format and
  71 | # will distribute the generated files over these directories. Enabling this
  72 | # option can be useful when feeding doxygen a huge amount of source files, where
  73 | # putting all generated files in the same directory would otherwise causes
  74 | # performance problems for the file system.
  75 | # The default value is: NO.
  76 | 
  77 | CREATE_SUBDIRS         = NO
  78 | 
  79 | # The OUTPUT_LANGUAGE tag is used to specify the language in which all
  80 | # documentation generated by doxygen is written. Doxygen will use this
  81 | # information to generate all constant output in the proper language.
  82 | # Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese,
  83 | # Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States),
  84 | # Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian,
  85 | # Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages),
  86 | # Korean, Korean-en (Korean with English messages), Latvian, Lithuanian,
  87 | # Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian,
  88 | # Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish,
  89 | # Ukrainian and Vietnamese.
  90 | # The default value is: English.
  91 | 
  92 | OUTPUT_LANGUAGE        = English
  93 | 
  94 | # If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member
  95 | # descriptions after the members that are listed in the file and class
  96 | # documentation (similar to Javadoc). Set to NO to disable this.
  97 | # The default value is: YES.
  98 | 
  99 | BRIEF_MEMBER_DESC      = YES
 100 | 
 101 | # If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief
 102 | # description of a member or function before the detailed description
 103 | #
 104 | # Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
 105 | # brief descriptions will be completely suppressed.
 106 | # The default value is: YES.
 107 | 
 108 | REPEAT_BRIEF           = YES
 109 | 
 110 | # This tag implements a quasi-intelligent brief description abbreviator that is
 111 | # used to form the text in various listings. Each string in this list, if found
 112 | # as the leading text of the brief description, will be stripped from the text
 113 | # and the result, after processing the whole list, is used as the annotated
 114 | # text. Otherwise, the brief description is used as-is. If left blank, the
 115 | # following values are used ($name is automatically replaced with the name of
 116 | # the entity):The $name class, The $name widget, The $name file, is, provides,
 117 | # specifies, contains, represents, a, an and the.
 118 | 
 119 | ABBREVIATE_BRIEF       =
 120 | 
 121 | # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
 122 | # doxygen will generate a detailed section even if there is only a brief
 123 | # description.
 124 | # The default value is: NO.
 125 | 
 126 | ALWAYS_DETAILED_SEC    = NO
 127 | 
 128 | # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
 129 | # inherited members of a class in the documentation of that class as if those
 130 | # members were ordinary class members. Constructors, destructors and assignment
 131 | # operators of the base classes will not be shown.
 132 | # The default value is: NO.
 133 | 
 134 | INLINE_INHERITED_MEMB  = NO
 135 | 
 136 | # If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path
 137 | # before files name in the file list and in the header files. If set to NO the
 138 | # shortest path that makes the file name unique will be used
 139 | # The default value is: YES.
 140 | 
 141 | FULL_PATH_NAMES        = YES
 142 | 
 143 | # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
 144 | # Stripping is only done if one of the specified strings matches the left-hand
 145 | # part of the path. The tag can be used to show relative paths in the file list.
 146 | # If left blank the directory from which doxygen is run is used as the path to
 147 | # strip.
 148 | #
 149 | # Note that you can specify absolute paths here, but also relative paths, which
 150 | # will be relative from the directory where doxygen is started.
 151 | # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 152 | 
 153 | STRIP_FROM_PATH        =
 154 | 
 155 | # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 156 | # path mentioned in the documentation of a class, which tells the reader which
 157 | # header file to include in order to use a class. If left blank only the name of
 158 | # the header file containing the class definition is used. Otherwise one should
 159 | # specify the list of include paths that are normally passed to the compiler
 160 | # using the -I flag.
 161 | 
 162 | STRIP_FROM_INC_PATH    =
 163 | 
 164 | # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 165 | # less readable) file names. This can be useful is your file systems doesn't
 166 | # support long names like on DOS, Mac, or CD-ROM.
 167 | # The default value is: NO.
 168 | 
 169 | SHORT_NAMES            = NO
 170 | 
 171 | # If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the
 172 | # first line (until the first dot) of a Javadoc-style comment as the brief
 173 | # description. If set to NO, the Javadoc-style will behave just like regular Qt-
 174 | # style comments (thus requiring an explicit @brief command for a brief
 175 | # description.)
 176 | # The default value is: NO.
 177 | 
 178 | JAVADOC_AUTOBRIEF      = YES
 179 | 
 180 | # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
 181 | # line (until the first dot) of a Qt-style comment as the brief description. If
 182 | # set to NO, the Qt-style will behave just like regular Qt-style comments (thus
 183 | # requiring an explicit \brief command for a brief description.)
 184 | # The default value is: NO.
 185 | 
 186 | QT_AUTOBRIEF           = YES
 187 | 
 188 | # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a
 189 | # multi-line C++ special comment block (i.e. a block of //! or /// comments) as
 190 | # a brief description. This used to be the default behavior. The new default is
 191 | # to treat a multi-line C++ comment block as a detailed description. Set this
 192 | # tag to YES if you prefer the old behavior instead.
 193 | #
 194 | # Note that setting this tag to YES also means that rational rose comments are
 195 | # not recognized any more.
 196 | # The default value is: NO.
 197 | 
 198 | MULTILINE_CPP_IS_BRIEF = NO
 199 | 
 200 | # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the
 201 | # documentation from any documented member that it re-implements.
 202 | # The default value is: YES.
 203 | 
 204 | INHERIT_DOCS           = YES
 205 | 
 206 | # If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a
 207 | # new page for each member. If set to NO, the documentation of a member will be
 208 | # part of the file/class/namespace that contains it.
 209 | # The default value is: NO.
 210 | 
 211 | SEPARATE_MEMBER_PAGES  = NO
 212 | 
 213 | # The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen
 214 | # uses this value to replace tabs by spaces in code fragments.
 215 | # Minimum value: 1, maximum value: 16, default value: 4.
 216 | 
 217 | TAB_SIZE               = 4
 218 | 
 219 | # This tag can be used to specify a number of aliases that act as commands in
 220 | # the documentation. An alias has the form:
 221 | # name=value
 222 | # For example adding
 223 | # "sideeffect=@par Side Effects:\n"
 224 | # will allow you to put the command \sideeffect (or @sideeffect) in the
 225 | # documentation, which will result in a user-defined paragraph with heading
 226 | # "Side Effects:". You can put \n's in the value part of an alias to insert
 227 | # newlines.
 228 | 
 229 | ALIASES                =
 230 | 
 231 | # This tag can be used to specify a number of word-keyword mappings (TCL only).
 232 | # A mapping has the form "name=value". For example adding "class=itcl::class"
 233 | # will allow you to use the command class in the itcl::class meaning.
 234 | 
 235 | TCL_SUBST              =
 236 | 
 237 | # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 238 | # only. Doxygen will then generate output that is more tailored for C. For
 239 | # instance, some of the names that are used will be different. The list of all
 240 | # members will be omitted, etc.
 241 | # The default value is: NO.
 242 | 
 243 | OPTIMIZE_OUTPUT_FOR_C  = YES
 244 | 
 245 | # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
 246 | # Python sources only. Doxygen will then generate output that is more tailored
 247 | # for that language. For instance, namespaces will be presented as packages,
 248 | # qualified scopes will look different, etc.
 249 | # The default value is: NO.
 250 | 
 251 | OPTIMIZE_OUTPUT_JAVA   = NO
 252 | 
 253 | # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran
 254 | # sources. Doxygen will then generate output that is tailored for Fortran.
 255 | # The default value is: NO.
 256 | 
 257 | OPTIMIZE_FOR_FORTRAN   = NO
 258 | 
 259 | # Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL
 260 | # sources. Doxygen will then generate output that is tailored for VHDL.
 261 | # The default value is: NO.
 262 | 
 263 | OPTIMIZE_OUTPUT_VHDL   = NO
 264 | 
 265 | # Doxygen selects the parser to use depending on the extension of the files it
 266 | # parses. With this tag you can assign which parser to use for a given
 267 | # extension. Doxygen has a built-in mapping, but you can override or extend it
 268 | # using this tag. The format is ext=language, where ext is a file extension, and
 269 | # language is one of the parsers supported by doxygen: IDL, Java, Javascript,
 270 | # C#, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL. For instance to make
 271 | # doxygen treat .inc files as Fortran files (default is PHP), and .f files as C
 272 | # (default is Fortran), use: inc=Fortran f=C.
 273 | #
 274 | # Note For files without extension you can use no_extension as a placeholder.
 275 | #
 276 | # Note that for custom extensions you also need to set FILE_PATTERNS otherwise
 277 | # the files are not read by doxygen.
 278 | 
 279 | EXTENSION_MAPPING      =
 280 | 
 281 | # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 282 | # according to the Markdown format, which allows for more readable
 283 | # documentation. See http://daringfireball.net/projects/markdown/ for details.
 284 | # The output of markdown processing is further processed by doxygen, so you can
 285 | # mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in
 286 | # case of backward compatibilities issues.
 287 | # The default value is: YES.
 288 | 
 289 | MARKDOWN_SUPPORT       = YES
 290 | 
 291 | # When enabled doxygen tries to link words that correspond to documented
 292 | # classes, or namespaces to their corresponding documentation. Such a link can
 293 | # be prevented in individual cases by by putting a % sign in front of the word
 294 | # or globally by setting AUTOLINK_SUPPORT to NO.
 295 | # The default value is: YES.
 296 | 
 297 | AUTOLINK_SUPPORT       = YES
 298 | 
 299 | # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
 300 | # to include (a tag file for) the STL sources as input, then you should set this
 301 | # tag to YES in order to let doxygen match functions declarations and
 302 | # definitions whose arguments contain STL classes (e.g. func(std::string);
 303 | # versus func(std::string) {}). This also make the inheritance and collaboration
 304 | # diagrams that involve STL classes more complete and accurate.
 305 | # The default value is: NO.
 306 | 
 307 | BUILTIN_STL_SUPPORT    = NO
 308 | 
 309 | # If you use Microsoft's C++/CLI language, you should set this option to YES to
 310 | # enable parsing support.
 311 | # The default value is: NO.
 312 | 
 313 | CPP_CLI_SUPPORT        = NO
 314 | 
 315 | # Set the SIP_SUPPORT tag to YES if your project consists of sip (see:
 316 | # http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen
 317 | # will parse them like normal C++ but will assume all classes use public instead
 318 | # of private inheritance when no explicit protection keyword is present.
 319 | # The default value is: NO.
 320 | 
 321 | SIP_SUPPORT            = NO
 322 | 
 323 | # For Microsoft's IDL there are propget and propput attributes to indicate
 324 | # getter and setter methods for a property. Setting this option to YES will make
 325 | # doxygen to replace the get and set methods by a property in the documentation.
 326 | # This will only work if the methods are indeed getting or setting a simple
 327 | # type. If this is not the case, or you want to show the methods anyway, you
 328 | # should set this option to NO.
 329 | # The default value is: YES.
 330 | 
 331 | IDL_PROPERTY_SUPPORT   = YES
 332 | 
 333 | # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
 334 | # tag is set to YES, then doxygen will reuse the documentation of the first
 335 | # member in the group (if any) for the other members of the group. By default
 336 | # all members of a group must be documented explicitly.
 337 | # The default value is: NO.
 338 | 
 339 | DISTRIBUTE_GROUP_DOC   = NO
 340 | 
 341 | # Set the SUBGROUPING tag to YES to allow class member groups of the same type
 342 | # (for instance a group of public functions) to be put as a subgroup of that
 343 | # type (e.g. under the Public Functions section). Set it to NO to prevent
 344 | # subgrouping. Alternatively, this can be done per class using the
 345 | # \nosubgrouping command.
 346 | # The default value is: YES.
 347 | 
 348 | SUBGROUPING            = YES
 349 | 
 350 | # When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions
 351 | # are shown inside the group in which they are included (e.g. using \ingroup)
 352 | # instead of on a separate page (for HTML and Man pages) or section (for LaTeX
 353 | # and RTF).
 354 | #
 355 | # Note that this feature does not work in combination with
 356 | # SEPARATE_MEMBER_PAGES.
 357 | # The default value is: NO.
 358 | 
 359 | INLINE_GROUPED_CLASSES = NO
 360 | 
 361 | # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions
 362 | # with only public data fields or simple typedef fields will be shown inline in
 363 | # the documentation of the scope in which they are defined (i.e. file,
 364 | # namespace, or group documentation), provided this scope is documented. If set
 365 | # to NO, structs, classes, and unions are shown on a separate page (for HTML and
 366 | # Man pages) or section (for LaTeX and RTF).
 367 | # The default value is: NO.
 368 | 
 369 | INLINE_SIMPLE_STRUCTS  = YES
 370 | 
 371 | # When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or
 372 | # enum is documented as struct, union, or enum with the name of the typedef. So
 373 | # typedef struct TypeS {} TypeT, will appear in the documentation as a struct
 374 | # with name TypeT. When disabled the typedef will appear as a member of a file,
 375 | # namespace, or class. And the struct will be named TypeS. This can typically be
 376 | # useful for C code in case the coding convention dictates that all compound
 377 | # types are typedef'ed and only the typedef is referenced, never the tag name.
 378 | # The default value is: NO.
 379 | 
 380 | TYPEDEF_HIDES_STRUCT   = NO
 381 | 
 382 | # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
 383 | # cache is used to resolve symbols given their name and scope. Since this can be
 384 | # an expensive process and often the same symbol appears multiple times in the
 385 | # code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small
 386 | # doxygen will become slower. If the cache is too large, memory is wasted. The
 387 | # cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range
 388 | # is 0..9, the default is 0, corresponding to a cache size of 2^16=65536
 389 | # symbols. At the end of a run doxygen will report the cache usage and suggest
 390 | # the optimal cache size from a speed point of view.
 391 | # Minimum value: 0, maximum value: 9, default value: 0.
 392 | 
 393 | LOOKUP_CACHE_SIZE      = 0
 394 | 
 395 | #---------------------------------------------------------------------------
 396 | # Build related configuration options
 397 | #---------------------------------------------------------------------------
 398 | 
 399 | # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 400 | # documentation are documented, even if no documentation was available. Private
 401 | # class members and static file members will be hidden unless the
 402 | # EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
 403 | # Note: This will also disable the warnings about undocumented members that are
 404 | # normally produced when WARNINGS is set to YES.
 405 | # The default value is: NO.
 406 | 
 407 | EXTRACT_ALL            = YES
 408 | 
 409 | # If the EXTRACT_PRIVATE tag is set to YES all private members of a class will
 410 | # be included in the documentation.
 411 | # The default value is: NO.
 412 | 
 413 | EXTRACT_PRIVATE        = NO
 414 | 
 415 | # If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
 416 | # scope will be included in the documentation.
 417 | # The default value is: NO.
 418 | 
 419 | EXTRACT_PACKAGE        = NO
 420 | 
 421 | # If the EXTRACT_STATIC tag is set to YES all static members of a file will be
 422 | # included in the documentation.
 423 | # The default value is: NO.
 424 | 
 425 | EXTRACT_STATIC         = YES
 426 | 
 427 | # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined
 428 | # locally in source files will be included in the documentation. If set to NO
 429 | # only classes defined in header files are included. Does not have any effect
 430 | # for Java sources.
 431 | # The default value is: YES.
 432 | 
 433 | EXTRACT_LOCAL_CLASSES  = YES
 434 | 
 435 | # This flag is only useful for Objective-C code. When set to YES local methods,
 436 | # which are defined in the implementation section but not in the interface are
 437 | # included in the documentation. If set to NO only methods in the interface are
 438 | # included.
 439 | # The default value is: NO.
 440 | 
 441 | EXTRACT_LOCAL_METHODS  = NO
 442 | 
 443 | # If this flag is set to YES, the members of anonymous namespaces will be
 444 | # extracted and appear in the documentation as a namespace called
 445 | # 'anonymous_namespace{file}', where file will be replaced with the base name of
 446 | # the file that contains the anonymous namespace. By default anonymous namespace
 447 | # are hidden.
 448 | # The default value is: NO.
 449 | 
 450 | EXTRACT_ANON_NSPACES   = NO
 451 | 
 452 | # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
 453 | # undocumented members inside documented classes or files. If set to NO these
 454 | # members will be included in the various overviews, but no documentation
 455 | # section is generated. This option has no effect if EXTRACT_ALL is enabled.
 456 | # The default value is: NO.
 457 | 
 458 | HIDE_UNDOC_MEMBERS     = NO
 459 | 
 460 | # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
 461 | # undocumented classes that are normally visible in the class hierarchy. If set
 462 | # to NO these classes will be included in the various overviews. This option has
 463 | # no effect if EXTRACT_ALL is enabled.
 464 | # The default value is: NO.
 465 | 
 466 | HIDE_UNDOC_CLASSES     = NO
 467 | 
 468 | # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
 469 | # (class|struct|union) declarations. If set to NO these declarations will be
 470 | # included in the documentation.
 471 | # The default value is: NO.
 472 | 
 473 | HIDE_FRIEND_COMPOUNDS  = NO
 474 | 
 475 | # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
 476 | # documentation blocks found inside the body of a function. If set to NO these
 477 | # blocks will be appended to the function's detailed documentation block.
 478 | # The default value is: NO.
 479 | 
 480 | HIDE_IN_BODY_DOCS      = NO
 481 | 
 482 | # The INTERNAL_DOCS tag determines if documentation that is typed after a
 483 | # \internal command is included. If the tag is set to NO then the documentation
 484 | # will be excluded. Set it to YES to include the internal documentation.
 485 | # The default value is: NO.
 486 | 
 487 | INTERNAL_DOCS          = NO
 488 | 
 489 | # If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file
 490 | # names in lower-case letters. If set to YES upper-case letters are also
 491 | # allowed. This is useful if you have classes or files whose names only differ
 492 | # in case and if your file system supports case sensitive file names. Windows
 493 | # and Mac users are advised to set this option to NO.
 494 | # The default value is: system dependent.
 495 | 
 496 | CASE_SENSE_NAMES       = NO
 497 | 
 498 | # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
 499 | # their full class and namespace scopes in the documentation. If set to YES the
 500 | # scope will be hidden.
 501 | # The default value is: NO.
 502 | 
 503 | HIDE_SCOPE_NAMES       = NO
 504 | 
 505 | # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
 506 | # the files that are included by a file in the documentation of that file.
 507 | # The default value is: YES.
 508 | 
 509 | SHOW_INCLUDE_FILES     = YES
 510 | 
 511 | # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
 512 | # grouped member an include statement to the documentation, telling the reader
 513 | # which file to include in order to use the member.
 514 | # The default value is: NO.
 515 | 
 516 | SHOW_GROUPED_MEMB_INC  = NO
 517 | 
 518 | # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
 519 | # files with double quotes in the documentation rather than with sharp brackets.
 520 | # The default value is: NO.
 521 | 
 522 | FORCE_LOCAL_INCLUDES   = NO
 523 | 
 524 | # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the
 525 | # documentation for inline members.
 526 | # The default value is: YES.
 527 | 
 528 | INLINE_INFO            = YES
 529 | 
 530 | # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
 531 | # (detailed) documentation of file and class members alphabetically by member
 532 | # name. If set to NO the members will appear in declaration order.
 533 | # The default value is: YES.
 534 | 
 535 | SORT_MEMBER_DOCS       = YES
 536 | 
 537 | # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
 538 | # descriptions of file, namespace and class members alphabetically by member
 539 | # name. If set to NO the members will appear in declaration order. Note that
 540 | # this will also influence the order of the classes in the class list.
 541 | # The default value is: NO.
 542 | 
 543 | SORT_BRIEF_DOCS        = NO
 544 | 
 545 | # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
 546 | # (brief and detailed) documentation of class members so that constructors and
 547 | # destructors are listed first. If set to NO the constructors will appear in the
 548 | # respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.
 549 | # Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief
 550 | # member documentation.
 551 | # Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting
 552 | # detailed member documentation.
 553 | # The default value is: NO.
 554 | 
 555 | SORT_MEMBERS_CTORS_1ST = NO
 556 | 
 557 | # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
 558 | # of group names into alphabetical order. If set to NO the group names will
 559 | # appear in their defined order.
 560 | # The default value is: NO.
 561 | 
 562 | SORT_GROUP_NAMES       = NO
 563 | 
 564 | # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
 565 | # fully-qualified names, including namespaces. If set to NO, the class list will
 566 | # be sorted only by class name, not including the namespace part.
 567 | # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
 568 | # Note: This option applies only to the class list, not to the alphabetical
 569 | # list.
 570 | # The default value is: NO.
 571 | 
 572 | SORT_BY_SCOPE_NAME     = NO
 573 | 
 574 | # If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper
 575 | # type resolution of all parameters of a function it will reject a match between
 576 | # the prototype and the implementation of a member function even if there is
 577 | # only one candidate or it is obvious which candidate to choose by doing a
 578 | # simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still
 579 | # accept a match between prototype and implementation in such cases.
 580 | # The default value is: NO.
 581 | 
 582 | STRICT_PROTO_MATCHING  = NO
 583 | 
 584 | # The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the
 585 | # todo list. This list is created by putting \todo commands in the
 586 | # documentation.
 587 | # The default value is: YES.
 588 | 
 589 | GENERATE_TODOLIST      = YES
 590 | 
 591 | # The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the
 592 | # test list. This list is created by putting \test commands in the
 593 | # documentation.
 594 | # The default value is: YES.
 595 | 
 596 | GENERATE_TESTLIST      = YES
 597 | 
 598 | # The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug
 599 | # list. This list is created by putting \bug commands in the documentation.
 600 | # The default value is: YES.
 601 | 
 602 | GENERATE_BUGLIST       = YES
 603 | 
 604 | # The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO)
 605 | # the deprecated list. This list is created by putting \deprecated commands in
 606 | # the documentation.
 607 | # The default value is: YES.
 608 | 
 609 | GENERATE_DEPRECATEDLIST= YES
 610 | 
 611 | # The ENABLED_SECTIONS tag can be used to enable conditional documentation
 612 | # sections, marked by \if <section_label> ... \endif and \cond <section_label>
 613 | # ... \endcond blocks.
 614 | 
 615 | ENABLED_SECTIONS       =
 616 | 
 617 | # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
 618 | # initial value of a variable or macro / define can have for it to appear in the
 619 | # documentation. If the initializer consists of more lines than specified here
 620 | # it will be hidden. Use a value of 0 to hide initializers completely. The
 621 | # appearance of the value of individual variables and macros / defines can be
 622 | # controlled using \showinitializer or \hideinitializer command in the
 623 | # documentation regardless of this setting.
 624 | # Minimum value: 0, maximum value: 10000, default value: 30.
 625 | 
 626 | MAX_INITIALIZER_LINES  = 30
 627 | 
 628 | # Set the SHOW_USED_FILES tag to NO to disable the list of files generated at
 629 | # the bottom of the documentation of classes and structs. If set to YES the list
 630 | # will mention the files that were used to generate the documentation.
 631 | # The default value is: YES.
 632 | 
 633 | SHOW_USED_FILES        = YES
 634 | 
 635 | # Set the SHOW_FILES tag to NO to disable the generation of the Files page. This
 636 | # will remove the Files entry from the Quick Index and from the Folder Tree View
 637 | # (if specified).
 638 | # The default value is: YES.
 639 | 
 640 | SHOW_FILES             = YES
 641 | 
 642 | # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces
 643 | # page. This will remove the Namespaces entry from the Quick Index and from the
 644 | # Folder Tree View (if specified).
 645 | # The default value is: YES.
 646 | 
 647 | SHOW_NAMESPACES        = YES
 648 | 
 649 | # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 650 | # doxygen should invoke to get the current version for each file (typically from
 651 | # the version control system). Doxygen will invoke the program by executing (via
 652 | # popen()) the command command input-file, where command is the value of the
 653 | # FILE_VERSION_FILTER tag, and input-file is the name of an input file provided
 654 | # by doxygen. Whatever the program writes to standard output is used as the file
 655 | # version. For an example see the documentation.
 656 | 
 657 | FILE_VERSION_FILTER    =
 658 | 
 659 | # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
 660 | # by doxygen. The layout file controls the global structure of the generated
 661 | # output files in an output format independent way. To create the layout file
 662 | # that represents doxygen's defaults, run doxygen with the -l option. You can
 663 | # optionally specify a file name after the option, if omitted DoxygenLayout.xml
 664 | # will be used as the name of the layout file.
 665 | #
 666 | # Note that if you run doxygen from a directory containing a file called
 667 | # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 668 | # tag is left empty.
 669 | 
 670 | LAYOUT_FILE            =
 671 | 
 672 | # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 673 | # the reference definitions. This must be a list of .bib files. The .bib
 674 | # extension is automatically appended if omitted. This requires the bibtex tool
 675 | # to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info.
 676 | # For LaTeX the style of the bibliography can be controlled using
 677 | # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the
 678 | # search path. Do not use file names with spaces, bibtex cannot handle them. See
 679 | # also \cite for info how to create references.
 680 | 
 681 | CITE_BIB_FILES         =
 682 | 
 683 | #---------------------------------------------------------------------------
 684 | # Configuration options related to warning and progress messages
 685 | #---------------------------------------------------------------------------
 686 | 
 687 | # The QUIET tag can be used to turn on/off the messages that are generated to
 688 | # standard output by doxygen. If QUIET is set to YES this implies that the
 689 | # messages are off.
 690 | # The default value is: NO.
 691 | 
 692 | QUIET                  = NO
 693 | 
 694 | # The WARNINGS tag can be used to turn on/off the warning messages that are
 695 | # generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES
 696 | # this implies that the warnings are on.
 697 | #
 698 | # Tip: Turn warnings on while writing the documentation.
 699 | # The default value is: YES.
 700 | 
 701 | WARNINGS               = YES
 702 | 
 703 | # If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate
 704 | # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
 705 | # will automatically be disabled.
 706 | # The default value is: YES.
 707 | 
 708 | WARN_IF_UNDOCUMENTED   = YES
 709 | 
 710 | # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 711 | # potential errors in the documentation, such as not documenting some parameters
 712 | # in a documented function, or documenting parameters that don't exist or using
 713 | # markup commands wrongly.
 714 | # The default value is: YES.
 715 | 
 716 | WARN_IF_DOC_ERROR      = YES
 717 | 
 718 | # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
 719 | # are documented, but have no documentation for their parameters or return
 720 | # value. If set to NO doxygen will only warn about wrong or incomplete parameter
 721 | # documentation, but not about the absence of documentation.
 722 | # The default value is: NO.
 723 | 
 724 | WARN_NO_PARAMDOC       = NO
 725 | 
 726 | # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 727 | # can produce. The string should contain the $file, $line, and $text tags, which
 728 | # will be replaced by the file and line number from which the warning originated
 729 | # and the warning text. Optionally the format may contain $version, which will
 730 | # be replaced by the version of the file (if it could be obtained via
 731 | # FILE_VERSION_FILTER)
 732 | # The default value is: $file:$line: $text.
 733 | 
 734 | WARN_FORMAT            = "$file:$line: $text"
 735 | 
 736 | # The WARN_LOGFILE tag can be used to specify a file to which warning and error
 737 | # messages should be written. If left blank the output is written to standard
 738 | # error (stderr).
 739 | 
 740 | WARN_LOGFILE           =
 741 | 
 742 | #---------------------------------------------------------------------------
 743 | # Configuration options related to the input files
 744 | #---------------------------------------------------------------------------
 745 | 
 746 | # The INPUT tag is used to specify the files and/or directories that contain
 747 | # documented source files. You may enter file names like myfile.cpp or
 748 | # directories like /usr/src/myproject. Separate the files or directories with
 749 | # spaces.
 750 | # Note: If this tag is empty the current directory is searched.
 751 | 
 752 | INPUT                  =
 753 | 
 754 | # This tag can be used to specify the character encoding of the source files
 755 | # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
 756 | # libiconv (or the iconv built into libc) for the transcoding. See the libiconv
 757 | # documentation (see: http://www.gnu.org/software/libiconv) for the list of
 758 | # possible encodings.
 759 | # The default value is: UTF-8.
 760 | 
 761 | INPUT_ENCODING         = UTF-8
 762 | 
 763 | # If the value of the INPUT tag contains directories, you can use the
 764 | # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and
 765 | # *.h) to filter out the source-files in the directories. If left blank the
 766 | # following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii,
 767 | # *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp,
 768 | # *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown,
 769 | # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 770 | # *.qsf, *.as and *.js.
 771 | 
 772 | FILE_PATTERNS          =
 773 | 
 774 | # The RECURSIVE tag can be used to specify whether or not subdirectories should
 775 | # be searched for input files as well.
 776 | # The default value is: NO.
 777 | 
 778 | RECURSIVE              = NO
 779 | 
 780 | # The EXCLUDE tag can be used to specify files and/or directories that should be
 781 | # excluded from the INPUT source files. This way you can easily exclude a
 782 | # subdirectory from a directory tree whose root is specified with the INPUT tag.
 783 | #
 784 | # Note that relative paths are relative to the directory from which doxygen is
 785 | # run.
 786 | 
 787 | EXCLUDE                =
 788 | 
 789 | # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 790 | # directories that are symbolic links (a Unix file system feature) are excluded
 791 | # from the input.
 792 | # The default value is: NO.
 793 | 
 794 | EXCLUDE_SYMLINKS       = NO
 795 | 
 796 | # If the value of the INPUT tag contains directories, you can use the
 797 | # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
 798 | # certain files from those directories.
 799 | #
 800 | # Note that the wildcards are matched against the file with absolute path, so to
 801 | # exclude all test directories for example use the pattern */test/*
 802 | 
 803 | EXCLUDE_PATTERNS       =
 804 | 
 805 | # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 806 | # (namespaces, classes, functions, etc.) that should be excluded from the
 807 | # output. The symbol name can be a fully qualified name, a word, or if the
 808 | # wildcard * is used, a substring. Examples: ANamespace, AClass,
 809 | # AClass::ANamespace, ANamespace::*Test
 810 | #
 811 | # Note that the wildcards are matched against the file with absolute path, so to
 812 | # exclude all test directories use the pattern */test/*
 813 | 
 814 | EXCLUDE_SYMBOLS        =
 815 | 
 816 | # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 817 | # that contain example code fragments that are included (see the \include
 818 | # command).
 819 | 
 820 | EXAMPLE_PATH           =
 821 | 
 822 | # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 823 | # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
 824 | # *.h) to filter out the source-files in the directories. If left blank all
 825 | # files are included.
 826 | 
 827 | EXAMPLE_PATTERNS       =
 828 | 
 829 | # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
 830 | # searched for input files to be used with the \include or \dontinclude commands
 831 | # irrespective of the value of the RECURSIVE tag.
 832 | # The default value is: NO.
 833 | 
 834 | EXAMPLE_RECURSIVE      = NO
 835 | 
 836 | # The IMAGE_PATH tag can be used to specify one or more files or directories
 837 | # that contain images that are to be included in the documentation (see the
 838 | # \image command).
 839 | 
 840 | IMAGE_PATH             =
 841 | 
 842 | # The INPUT_FILTER tag can be used to specify a program that doxygen should
 843 | # invoke to filter for each input file. Doxygen will invoke the filter program
 844 | # by executing (via popen()) the command:
 845 | #
 846 | # <filter> <input-file>
 847 | #
 848 | # where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the
 849 | # name of an input file. Doxygen will then use the output that the filter
 850 | # program writes to standard output. If FILTER_PATTERNS is specified, this tag
 851 | # will be ignored.
 852 | #
 853 | # Note that the filter must not add or remove lines; it is applied before the
 854 | # code is scanned, but not when the output code is generated. If lines are added
 855 | # or removed, the anchors will not be placed correctly.
 856 | 
 857 | INPUT_FILTER           =
 858 | 
 859 | # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 860 | # basis. Doxygen will compare the file name with each pattern and apply the
 861 | # filter if there is a match. The filters are a list of the form: pattern=filter
 862 | # (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how
 863 | # filters are used. If the FILTER_PATTERNS tag is empty or if none of the
 864 | # patterns match the file name, INPUT_FILTER is applied.
 865 | 
 866 | FILTER_PATTERNS        =
 867 | 
 868 | # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
 869 | # INPUT_FILTER ) will also be used to filter the input files that are used for
 870 | # producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES).
 871 | # The default value is: NO.
 872 | 
 873 | FILTER_SOURCE_FILES    = NO
 874 | 
 875 | # The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file
 876 | # pattern. A pattern will override the setting for FILTER_PATTERN (if any) and
 877 | # it is also possible to disable source filtering for a specific pattern using
 878 | # *.ext= (so without naming a filter).
 879 | # This tag requires that the tag FILTER_SOURCE_FILES is set to YES.
 880 | 
 881 | FILTER_SOURCE_PATTERNS =
 882 | 
 883 | # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that
 884 | # is part of the input, its contents will be placed on the main page
 885 | # (index.html). This can be useful if you have a project on for instance GitHub
 886 | # and want to reuse the introduction page also for the doxygen output.
 887 | 
 888 | USE_MDFILE_AS_MAINPAGE = README.md
 889 | 
 890 | #---------------------------------------------------------------------------
 891 | # Configuration options related to source browsing
 892 | #---------------------------------------------------------------------------
 893 | 
 894 | # If the SOURCE_BROWSER tag is set to YES then a list of source files will be
 895 | # generated. Documented entities will be cross-referenced with these sources.
 896 | #
 897 | # Note: To get rid of all source code in the generated output, make sure that
 898 | # also VERBATIM_HEADERS is set to NO.
 899 | # The default value is: NO.
 900 | 
 901 | SOURCE_BROWSER         = YES
 902 | 
 903 | # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 904 | # classes and enums directly into the documentation.
 905 | # The default value is: NO.
 906 | 
 907 | INLINE_SOURCES         = NO
 908 | 
 909 | # Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any
 910 | # special comment blocks from generated source code fragments. Normal C, C++ and
 911 | # Fortran comments will always remain visible.
 912 | # The default value is: YES.
 913 | 
 914 | STRIP_CODE_COMMENTS    = YES
 915 | 
 916 | # If the REFERENCED_BY_RELATION tag is set to YES then for each documented
 917 | # function all documented functions referencing it will be listed.
 918 | # The default value is: NO.
 919 | 
 920 | REFERENCED_BY_RELATION = NO
 921 | 
 922 | # If the REFERENCES_RELATION tag is set to YES then for each documented function
 923 | # all documented entities called/used by that function will be listed.
 924 | # The default value is: NO.
 925 | 
 926 | REFERENCES_RELATION    = NO
 927 | 
 928 | # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set
 929 | # to YES, then the hyperlinks from functions in REFERENCES_RELATION and
 930 | # REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will
 931 | # link to the documentation.
 932 | # The default value is: YES.
 933 | 
 934 | REFERENCES_LINK_SOURCE = YES
 935 | 
 936 | # If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the
 937 | # source code will show a tooltip with additional information such as prototype,
 938 | # brief description and links to the definition and documentation. Since this
 939 | # will make the HTML file larger and loading of large files a bit slower, you
 940 | # can opt to disable this feature.
 941 | # The default value is: YES.
 942 | # This tag requires that the tag SOURCE_BROWSER is set to YES.
 943 | 
 944 | SOURCE_TOOLTIPS        = YES
 945 | 
 946 | # If the USE_HTAGS tag is set to YES then the references to source code will
 947 | # point to the HTML generated by the htags(1) tool instead of doxygen built-in
 948 | # source browser. The htags tool is part of GNU's global source tagging system
 949 | # (see http://www.gnu.org/software/global/global.html). You will need version
 950 | # 4.8.6 or higher.
 951 | #
 952 | # To use it do the following:
 953 | # - Install the latest version of global
 954 | # - Enable SOURCE_BROWSER and USE_HTAGS in the config file
 955 | # - Make sure the INPUT points to the root of the source tree
 956 | # - Run doxygen as normal
 957 | #
 958 | # Doxygen will invoke htags (and that will in turn invoke gtags), so these
 959 | # tools must be available from the command line (i.e. in the search path).
 960 | #
 961 | # The result: instead of the source browser generated by doxygen, the links to
 962 | # source code will now point to the output of htags.
 963 | # The default value is: NO.
 964 | # This tag requires that the tag SOURCE_BROWSER is set to YES.
 965 | 
 966 | USE_HTAGS              = NO
 967 | 
 968 | # If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a
 969 | # verbatim copy of the header file for each class for which an include is
 970 | # specified. Set to NO to disable this.
 971 | # See also: Section \class.
 972 | # The default value is: YES.
 973 | 
 974 | VERBATIM_HEADERS       = YES
 975 | 
 976 | #---------------------------------------------------------------------------
 977 | # Configuration options related to the alphabetical class index
 978 | #---------------------------------------------------------------------------
 979 | 
 980 | # If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all
 981 | # compounds will be generated. Enable this if the project contains a lot of
 982 | # classes, structs, unions or interfaces.
 983 | # The default value is: YES.
 984 | 
 985 | ALPHABETICAL_INDEX     = YES
 986 | 
 987 | # The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in
 988 | # which the alphabetical index list will be split.
 989 | # Minimum value: 1, maximum value: 20, default value: 5.
 990 | # This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
 991 | 
 992 | COLS_IN_ALPHA_INDEX    = 5
 993 | 
 994 | # In case all classes in a project start with a common prefix, all classes will
 995 | # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
 996 | # can be used to specify a prefix (or a list of prefixes) that should be ignored
 997 | # while generating the index headers.
 998 | # This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
 999 | 
1000 | IGNORE_PREFIX          =
1001 | 
1002 | #---------------------------------------------------------------------------
1003 | # Configuration options related to the HTML output
1004 | #---------------------------------------------------------------------------
1005 | 
1006 | # If the GENERATE_HTML tag is set to YES doxygen will generate HTML output
1007 | # The default value is: YES.
1008 | 
1009 | GENERATE_HTML          = YES
1010 | 
1011 | # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
1012 | # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
1013 | # it.
1014 | # The default directory is: html.
1015 | # This tag requires that the tag GENERATE_HTML is set to YES.
1016 | 
1017 | HTML_OUTPUT            = html
1018 | 
1019 | # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
1020 | # generated HTML page (for example: .htm, .php, .asp).
1021 | # The default value is: .html.
1022 | # This tag requires that the tag GENERATE_HTML is set to YES.
1023 | 
1024 | HTML_FILE_EXTENSION    = .html
1025 | 
1026 | # The HTML_HEADER tag can be used to specify a user-defined HTML header file for
1027 | # each generated HTML page. If the tag is left blank doxygen will generate a
1028 | # standard header.
1029 | #
1030 | # To get valid HTML the header file that includes any scripts and style sheets
1031 | # that doxygen needs, which is dependent on the configuration options used (e.g.
1032 | # the setting GENERATE_TREEVIEW). It is highly recommended to start with a
1033 | # default header using
1034 | # doxygen -w html new_header.html new_footer.html new_stylesheet.css
1035 | # YourConfigFile
1036 | # and then modify the file new_header.html. See also section "Doxygen usage"
1037 | # for information on how to generate the default header that doxygen normally
1038 | # uses.
1039 | # Note: The header is subject to change so you typically have to regenerate the
1040 | # default header when upgrading to a newer version of doxygen. For a description
1041 | # of the possible markers and block names see the documentation.
1042 | # This tag requires that the tag GENERATE_HTML is set to YES.
1043 | 
1044 | HTML_HEADER            =
1045 | 
1046 | # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
1047 | # generated HTML page. If the tag is left blank doxygen will generate a standard
1048 | # footer. See HTML_HEADER for more information on how to generate a default
1049 | # footer and what special commands can be used inside the footer. See also
1050 | # section "Doxygen usage" for information on how to generate the default footer
1051 | # that doxygen normally uses.
1052 | # This tag requires that the tag GENERATE_HTML is set to YES.
1053 | 
1054 | HTML_FOOTER            =
1055 | 
1056 | # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
1057 | # sheet that is used by each HTML page. It can be used to fine-tune the look of
1058 | # the HTML output. If left blank doxygen will generate a default style sheet.
1059 | # See also section "Doxygen usage" for information on how to generate the style
1060 | # sheet that doxygen normally uses.
1061 | # Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as
1062 | # it is more robust and this tag (HTML_STYLESHEET) will in the future become
1063 | # obsolete.
1064 | # This tag requires that the tag GENERATE_HTML is set to YES.
1065 | 
1066 | HTML_STYLESHEET        =
1067 | 
1068 | # The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user-
1069 | # defined cascading style sheet that is included after the standard style sheets
1070 | # created by doxygen. Using this option one can overrule certain style aspects.
1071 | # This is preferred over using HTML_STYLESHEET since it does not replace the
1072 | # standard style sheet and is therefor more robust against future updates.
1073 | # Doxygen will copy the style sheet file to the output directory. For an example
1074 | # see the documentation.
1075 | # This tag requires that the tag GENERATE_HTML is set to YES.
1076 | 
1077 | HTML_EXTRA_STYLESHEET  =
1078 | 
1079 | # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
1080 | # other source files which should be copied to the HTML output directory. Note
1081 | # that these files will be copied to the base HTML output directory. Use the
1082 | # $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these
1083 | # files. In the HTML_STYLESHEET file, use the file name only. Also note that the
1084 | # files will be copied as-is; there are no commands or markers available.
1085 | # This tag requires that the tag GENERATE_HTML is set to YES.
1086 | 
1087 | HTML_EXTRA_FILES       =
1088 | 
1089 | # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
1090 | # will adjust the colors in the stylesheet and background images according to
1091 | # this color. Hue is specified as an angle on a colorwheel, see
1092 | # http://en.wikipedia.org/wiki/Hue for more information. For instance the value
1093 | # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300
1094 | # purple, and 360 is red again.
1095 | # Minimum value: 0, maximum value: 359, default value: 220.
1096 | # This tag requires that the tag GENERATE_HTML is set to YES.
1097 | 
1098 | HTML_COLORSTYLE_HUE    = 220
1099 | 
1100 | # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors
1101 | # in the HTML output. For a value of 0 the output will use grayscales only. A
1102 | # value of 255 will produce the most vivid colors.
1103 | # Minimum value: 0, maximum value: 255, default value: 100.
1104 | # This tag requires that the tag GENERATE_HTML is set to YES.
1105 | 
1106 | HTML_COLORSTYLE_SAT    = 100
1107 | 
1108 | # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the
1109 | # luminance component of the colors in the HTML output. Values below 100
1110 | # gradually make the output lighter, whereas values above 100 make the output
1111 | # darker. The value divided by 100 is the actual gamma applied, so 80 represents
1112 | # a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not
1113 | # change the gamma.
1114 | # Minimum value: 40, maximum value: 240, default value: 80.
1115 | # This tag requires that the tag GENERATE_HTML is set to YES.
1116 | 
1117 | HTML_COLORSTYLE_GAMMA  = 80
1118 | 
1119 | # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
1120 | # page will contain the date and time when the page was generated. Setting this
1121 | # to NO can help when comparing the output of multiple runs.
1122 | # The default value is: YES.
1123 | # This tag requires that the tag GENERATE_HTML is set to YES.
1124 | 
1125 | HTML_TIMESTAMP         = YES
1126 | 
1127 | # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
1128 | # documentation will contain sections that can be hidden and shown after the
1129 | # page has loaded.
1130 | # The default value is: NO.
1131 | # This tag requires that the tag GENERATE_HTML is set to YES.
1132 | 
1133 | HTML_DYNAMIC_SECTIONS  = NO
1134 | 
1135 | # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries
1136 | # shown in the various tree structured indices initially; the user can expand
1137 | # and collapse entries dynamically later on. Doxygen will expand the tree to
1138 | # such a level that at most the specified number of entries are visible (unless
1139 | # a fully collapsed tree already exceeds this amount). So setting the number of
1140 | # entries 1 will produce a full collapsed tree by default. 0 is a special value
1141 | # representing an infinite number of entries and will result in a full expanded
1142 | # tree by default.
1143 | # Minimum value: 0, maximum value: 9999, default value: 100.
1144 | # This tag requires that the tag GENERATE_HTML is set to YES.
1145 | 
1146 | HTML_INDEX_NUM_ENTRIES = 100
1147 | 
1148 | # If the GENERATE_DOCSET tag is set to YES, additional index files will be
1149 | # generated that can be used as input for Apple's Xcode 3 integrated development
1150 | # environment (see: http://developer.apple.com/tools/xcode/), introduced with
1151 | # OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a
1152 | # Makefile in the HTML output directory. Running make will produce the docset in
1153 | # that directory and running make install will install the docset in
1154 | # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at
1155 | # startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html
1156 | # for more information.
1157 | # The default value is: NO.
1158 | # This tag requires that the tag GENERATE_HTML is set to YES.
1159 | 
1160 | GENERATE_DOCSET        = NO
1161 | 
1162 | # This tag determines the name of the docset feed. A documentation feed provides
1163 | # an umbrella under which multiple documentation sets from a single provider
1164 | # (such as a company or product suite) can be grouped.
1165 | # The default value is: Doxygen generated docs.
1166 | # This tag requires that the tag GENERATE_DOCSET is set to YES.
1167 | 
1168 | DOCSET_FEEDNAME        = "Doxygen generated docs"
1169 | 
1170 | # This tag specifies a string that should uniquely identify the documentation
1171 | # set bundle. This should be a reverse domain-name style string, e.g.
1172 | # com.mycompany.MyDocSet. Doxygen will append .docset to the name.
1173 | # The default value is: org.doxygen.Project.
1174 | # This tag requires that the tag GENERATE_DOCSET is set to YES.
1175 | 
1176 | DOCSET_BUNDLE_ID       = org.doxygen.Project
1177 | 
1178 | # The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify
1179 | # the documentation publisher. This should be a reverse domain-name style
1180 | # string, e.g. com.mycompany.MyDocSet.documentation.
1181 | # The default value is: org.doxygen.Publisher.
1182 | # This tag requires that the tag GENERATE_DOCSET is set to YES.
1183 | 
1184 | DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
1185 | 
1186 | # The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.
1187 | # The default value is: Publisher.
1188 | # This tag requires that the tag GENERATE_DOCSET is set to YES.
1189 | 
1190 | DOCSET_PUBLISHER_NAME  = Publisher
1191 | 
1192 | # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three
1193 | # additional HTML index files: index.hhp, index.hhc, and index.hhk. The
1194 | # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop
1195 | # (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on
1196 | # Windows.
1197 | #
1198 | # The HTML Help Workshop contains a compiler that can convert all HTML output
1199 | # generated by doxygen into a single compiled HTML file (.chm). Compiled HTML
1200 | # files are now used as the Windows 98 help format, and will replace the old
1201 | # Windows help format (.hlp) on all Windows platforms in the future. Compressed
1202 | # HTML files also contain an index, a table of contents, and you can search for
1203 | # words in the documentation. The HTML workshop also contains a viewer for
1204 | # compressed HTML files.
1205 | # The default value is: NO.
1206 | # This tag requires that the tag GENERATE_HTML is set to YES.
1207 | 
1208 | GENERATE_HTMLHELP      = NO
1209 | 
1210 | # The CHM_FILE tag can be used to specify the file name of the resulting .chm
1211 | # file. You can add a path in front of the file if the result should not be
1212 | # written to the html output directory.
1213 | # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
1214 | 
1215 | CHM_FILE               =
1216 | 
1217 | # The HHC_LOCATION tag can be used to specify the location (absolute path
1218 | # including file name) of the HTML help compiler ( hhc.exe). If non-empty
1219 | # doxygen will try to run the HTML help compiler on the generated index.hhp.
1220 | # The file has to be specified with full path.
1221 | # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
1222 | 
1223 | HHC_LOCATION           =
1224 | 
1225 | # The GENERATE_CHI flag controls if a separate .chi index file is generated (
1226 | # YES) or that it should be included in the master .chm file ( NO).
1227 | # The default value is: NO.
1228 | # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
1229 | 
1230 | GENERATE_CHI           = NO
1231 | 
1232 | # The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc)
1233 | # and project file content.
1234 | # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
1235 | 
1236 | CHM_INDEX_ENCODING     =
1237 | 
1238 | # The BINARY_TOC flag controls whether a binary table of contents is generated (
1239 | # YES) or a normal table of contents ( NO) in the .chm file.
1240 | # The default value is: NO.
1241 | # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
1242 | 
1243 | BINARY_TOC             = NO
1244 | 
1245 | # The TOC_EXPAND flag can be set to YES to add extra items for group members to
1246 | # the table of contents of the HTML help documentation and to the tree view.
1247 | # The default value is: NO.
1248 | # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
1249 | 
1250 | TOC_EXPAND             = NO
1251 | 
1252 | # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
1253 | # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that
1254 | # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help
1255 | # (.qch) of the generated HTML documentation.
1256 | # The default value is: NO.
1257 | # This tag requires that the tag GENERATE_HTML is set to YES.
1258 | 
1259 | GENERATE_QHP           = NO
1260 | 
1261 | # If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify
1262 | # the file name of the resulting .qch file. The path specified is relative to
1263 | # the HTML output folder.
1264 | # This tag requires that the tag GENERATE_QHP is set to YES.
1265 | 
1266 | QCH_FILE               =
1267 | 
1268 | # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help
1269 | # Project output. For more information please see Qt Help Project / Namespace
1270 | # (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace).
1271 | # The default value is: org.doxygen.Project.
1272 | # This tag requires that the tag GENERATE_QHP is set to YES.
1273 | 
1274 | QHP_NAMESPACE          = org.doxygen.Project
1275 | 
1276 | # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt
1277 | # Help Project output. For more information please see Qt Help Project / Virtual
1278 | # Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual-
1279 | # folders).
1280 | # The default value is: doc.
1281 | # This tag requires that the tag GENERATE_QHP is set to YES.
1282 | 
1283 | QHP_VIRTUAL_FOLDER     = doc
1284 | 
1285 | # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom
1286 | # filter to add. For more information please see Qt Help Project / Custom
1287 | # Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-
1288 | # filters).
1289 | # This tag requires that the tag GENERATE_QHP is set to YES.
1290 | 
1291 | QHP_CUST_FILTER_NAME   =
1292 | 
1293 | # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the
1294 | # custom filter to add. For more information please see Qt Help Project / Custom
1295 | # Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-
1296 | # filters).
1297 | # This tag requires that the tag GENERATE_QHP is set to YES.
1298 | 
1299 | QHP_CUST_FILTER_ATTRS  =
1300 | 
1301 | # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this
1302 | # project's filter section matches. Qt Help Project / Filter Attributes (see:
1303 | # http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes).
1304 | # This tag requires that the tag GENERATE_QHP is set to YES.
1305 | 
1306 | QHP_SECT_FILTER_ATTRS  =
1307 | 
1308 | # The QHG_LOCATION tag can be used to specify the location of Qt's
1309 | # qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the
1310 | # generated .qhp file.
1311 | # This tag requires that the tag GENERATE_QHP is set to YES.
1312 | 
1313 | QHG_LOCATION           =
1314 | 
1315 | # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be
1316 | # generated, together with the HTML files, they form an Eclipse help plugin. To
1317 | # install this plugin and make it available under the help contents menu in
1318 | # Eclipse, the contents of the directory containing the HTML and XML files needs
1319 | # to be copied into the plugins directory of eclipse. The name of the directory
1320 | # within the plugins directory should be the same as the ECLIPSE_DOC_ID value.
1321 | # After copying Eclipse needs to be restarted before the help appears.
1322 | # The default value is: NO.
1323 | # This tag requires that the tag GENERATE_HTML is set to YES.
1324 | 
1325 | GENERATE_ECLIPSEHELP   = NO
1326 | 
1327 | # A unique identifier for the Eclipse help plugin. When installing the plugin
1328 | # the directory name containing the HTML and XML files should also have this
1329 | # name. Each documentation set should have its own identifier.
1330 | # The default value is: org.doxygen.Project.
1331 | # This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES.
1332 | 
1333 | ECLIPSE_DOC_ID         = org.doxygen.Project
1334 | 
1335 | # If you want full control over the layout of the generated HTML pages it might
1336 | # be necessary to disable the index and replace it with your own. The
1337 | # DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top
1338 | # of each HTML page. A value of NO enables the index and the value YES disables
1339 | # it. Since the tabs in the index contain the same information as the navigation
1340 | # tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES.
1341 | # The default value is: NO.
1342 | # This tag requires that the tag GENERATE_HTML is set to YES.
1343 | 
1344 | DISABLE_INDEX          = NO
1345 | 
1346 | # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
1347 | # structure should be generated to display hierarchical information. If the tag
1348 | # value is set to YES, a side panel will be generated containing a tree-like
1349 | # index structure (just like the one that is generated for HTML Help). For this
1350 | # to work a browser that supports JavaScript, DHTML, CSS and frames is required
1351 | # (i.e. any modern browser). Windows users are probably better off using the
1352 | # HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can
1353 | # further fine-tune the look of the index. As an example, the default style
1354 | # sheet generated by doxygen has an example that shows how to put an image at
1355 | # the root of the tree instead of the PROJECT_NAME. Since the tree basically has
1356 | # the same information as the tab index, you could consider setting
1357 | # DISABLE_INDEX to YES when enabling this option.
1358 | # The default value is: NO.
1359 | # This tag requires that the tag GENERATE_HTML is set to YES.
1360 | 
1361 | GENERATE_TREEVIEW      = NO
1362 | 
1363 | # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
1364 | # doxygen will group on one line in the generated HTML documentation.
1365 | #
1366 | # Note that a value of 0 will completely suppress the enum values from appearing
1367 | # in the overview section.
1368 | # Minimum value: 0, maximum value: 20, default value: 4.
1369 | # This tag requires that the tag GENERATE_HTML is set to YES.
1370 | 
1371 | ENUM_VALUES_PER_LINE   = 4
1372 | 
1373 | # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used
1374 | # to set the initial width (in pixels) of the frame in which the tree is shown.
1375 | # Minimum value: 0, maximum value: 1500, default value: 250.
1376 | # This tag requires that the tag GENERATE_HTML is set to YES.
1377 | 
1378 | TREEVIEW_WIDTH         = 250
1379 | 
1380 | # When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to
1381 | # external symbols imported via tag files in a separate window.
1382 | # The default value is: NO.
1383 | # This tag requires that the tag GENERATE_HTML is set to YES.
1384 | 
1385 | EXT_LINKS_IN_WINDOW    = NO
1386 | 
1387 | # Use this tag to change the font size of LaTeX formulas included as images in
1388 | # the HTML documentation. When you change the font size after a successful
1389 | # doxygen run you need to manually remove any form_*.png images from the HTML
1390 | # output directory to force them to be regenerated.
1391 | # Minimum value: 8, maximum value: 50, default value: 10.
1392 | # This tag requires that the tag GENERATE_HTML is set to YES.
1393 | 
1394 | FORMULA_FONTSIZE       = 10
1395 | 
1396 | # Use the FORMULA_TRANPARENT tag to determine whether or not the images
1397 | # generated for formulas are transparent PNGs. Transparent PNGs are not
1398 | # supported properly for IE 6.0, but are supported on all modern browsers.
1399 | #
1400 | # Note that when changing this option you need to delete any form_*.png files in
1401 | # the HTML output directory before the changes have effect.
1402 | # The default value is: YES.
1403 | # This tag requires that the tag GENERATE_HTML is set to YES.
1404 | 
1405 | FORMULA_TRANSPARENT    = YES
1406 | 
1407 | # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see
1408 | # http://www.mathjax.org) which uses client side Javascript for the rendering
1409 | # instead of using prerendered bitmaps. Use this if you do not have LaTeX
1410 | # installed or if you want to formulas look prettier in the HTML output. When
1411 | # enabled you may also need to install MathJax separately and configure the path
1412 | # to it using the MATHJAX_RELPATH option.
1413 | # The default value is: NO.
1414 | # This tag requires that the tag GENERATE_HTML is set to YES.
1415 | 
1416 | USE_MATHJAX            = NO
1417 | 
1418 | # When MathJax is enabled you can set the default output format to be used for
1419 | # the MathJax output. See the MathJax site (see:
1420 | # http://docs.mathjax.org/en/latest/output.html) for more details.
1421 | # Possible values are: HTML-CSS (which is slower, but has the best
1422 | # compatibility), NativeMML (i.e. MathML) and SVG.
1423 | # The default value is: HTML-CSS.
1424 | # This tag requires that the tag USE_MATHJAX is set to YES.
1425 | 
1426 | MATHJAX_FORMAT         = HTML-CSS
1427 | 
1428 | # When MathJax is enabled you need to specify the location relative to the HTML
1429 | # output directory using the MATHJAX_RELPATH option. The destination directory
1430 | # should contain the MathJax.js script. For instance, if the mathjax directory
1431 | # is located at the same level as the HTML output directory, then
1432 | # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax
1433 | # Content Delivery Network so you can quickly see the result without installing
1434 | # MathJax. However, it is strongly recommended to install a local copy of
1435 | # MathJax from http://www.mathjax.org before deployment.
1436 | # The default value is: http://cdn.mathjax.org/mathjax/latest.
1437 | # This tag requires that the tag USE_MATHJAX is set to YES.
1438 | 
1439 | MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
1440 | 
1441 | # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax
1442 | # extension names that should be enabled during MathJax rendering. For example
1443 | # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
1444 | # This tag requires that the tag USE_MATHJAX is set to YES.
1445 | 
1446 | MATHJAX_EXTENSIONS     =
1447 | 
1448 | # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces
1449 | # of code that will be used on startup of the MathJax code. See the MathJax site
1450 | # (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an
1451 | # example see the documentation.
1452 | # This tag requires that the tag USE_MATHJAX is set to YES.
1453 | 
1454 | MATHJAX_CODEFILE       =
1455 | 
1456 | # When the SEARCHENGINE tag is enabled doxygen will generate a search box for
1457 | # the HTML output. The underlying search engine uses javascript and DHTML and
1458 | # should work on any modern browser. Note that when using HTML help
1459 | # (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET)
1460 | # there is already a search function so this one should typically be disabled.
1461 | # For large projects the javascript based search engine can be slow, then
1462 | # enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to
1463 | # search using the keyboard; to jump to the search box use <access key> + S
1464 | # (what the <access key> is depends on the OS and browser, but it is typically
1465 | # <CTRL>, <ALT>/<option>, or both). Inside the search box use the <cursor down
1466 | # key> to jump into the search results window, the results can be navigated
1467 | # using the <cursor keys>. Press <Enter> to select an item or <escape> to cancel
1468 | # the search. The filter options can be selected when the cursor is inside the
1469 | # search box by pressing <Shift>+<cursor down>. Also here use the <cursor keys>
1470 | # to select a filter and <Enter> or <escape> to activate or cancel the filter
1471 | # option.
1472 | # The default value is: YES.
1473 | # This tag requires that the tag GENERATE_HTML is set to YES.
1474 | 
1475 | SEARCHENGINE           = YES
1476 | 
1477 | # When the SERVER_BASED_SEARCH tag is enabled the search engine will be
1478 | # implemented using a web server instead of a web client using Javascript. There
1479 | # are two flavours of web server based searching depending on the
1480 | # EXTERNAL_SEARCH setting. When disabled, doxygen will generate a PHP script for
1481 | # searching and an index file used by the script. When EXTERNAL_SEARCH is
1482 | # enabled the indexing and searching needs to be provided by external tools. See
1483 | # the section "External Indexing and Searching" for details.
1484 | # The default value is: NO.
1485 | # This tag requires that the tag SEARCHENGINE is set to YES.
1486 | 
1487 | SERVER_BASED_SEARCH    = NO
1488 | 
1489 | # When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP
1490 | # script for searching. Instead the search results are written to an XML file
1491 | # which needs to be processed by an external indexer. Doxygen will invoke an
1492 | # external search engine pointed to by the SEARCHENGINE_URL option to obtain the
1493 | # search results.
1494 | #
1495 | # Doxygen ships with an example indexer ( doxyindexer) and search engine
1496 | # (doxysearch.cgi) which are based on the open source search engine library
1497 | # Xapian (see: http://xapian.org/).
1498 | #
1499 | # See the section "External Indexing and Searching" for details.
1500 | # The default value is: NO.
1501 | # This tag requires that the tag SEARCHENGINE is set to YES.
1502 | 
1503 | EXTERNAL_SEARCH        = NO
1504 | 
1505 | # The SEARCHENGINE_URL should point to a search engine hosted by a web server
1506 | # which will return the search results when EXTERNAL_SEARCH is enabled.
1507 | #
1508 | # Doxygen ships with an example indexer ( doxyindexer) and search engine
1509 | # (doxysearch.cgi) which are based on the open source search engine library
1510 | # Xapian (see: http://xapian.org/). See the section "External Indexing and
1511 | # Searching" for details.
1512 | # This tag requires that the tag SEARCHENGINE is set to YES.
1513 | 
1514 | SEARCHENGINE_URL       =
1515 | 
1516 | # When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed
1517 | # search data is written to a file for indexing by an external tool. With the
1518 | # SEARCHDATA_FILE tag the name of this file can be specified.
1519 | # The default file is: searchdata.xml.
1520 | # This tag requires that the tag SEARCHENGINE is set to YES.
1521 | 
1522 | SEARCHDATA_FILE        = searchdata.xml
1523 | 
1524 | # When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the
1525 | # EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is
1526 | # useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple
1527 | # projects and redirect the results back to the right project.
1528 | # This tag requires that the tag SEARCHENGINE is set to YES.
1529 | 
1530 | EXTERNAL_SEARCH_ID     =
1531 | 
1532 | # The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen
1533 | # projects other than the one defined by this configuration file, but that are
1534 | # all added to the same external search index. Each project needs to have a
1535 | # unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of
1536 | # to a relative location where the documentation can be found. The format is:
1537 | # EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ...
1538 | # This tag requires that the tag SEARCHENGINE is set to YES.
1539 | 
1540 | EXTRA_SEARCH_MAPPINGS  =
1541 | 
1542 | #---------------------------------------------------------------------------
1543 | # Configuration options related to the LaTeX output
1544 | #---------------------------------------------------------------------------
1545 | 
1546 | # If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output.
1547 | # The default value is: YES.
1548 | 
1549 | GENERATE_LATEX         = NO
1550 | 
1551 | # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
1552 | # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
1553 | # it.
1554 | # The default directory is: latex.
1555 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1556 | 
1557 | LATEX_OUTPUT           = latex
1558 | 
1559 | # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
1560 | # invoked.
1561 | #
1562 | # Note that when enabling USE_PDFLATEX this option is only used for generating
1563 | # bitmaps for formulas in the HTML output, but not in the Makefile that is
1564 | # written to the output directory.
1565 | # The default file is: latex.
1566 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1567 | 
1568 | LATEX_CMD_NAME         = latex
1569 | 
1570 | # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate
1571 | # index for LaTeX.
1572 | # The default file is: makeindex.
1573 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1574 | 
1575 | MAKEINDEX_CMD_NAME     = makeindex
1576 | 
1577 | # If the COMPACT_LATEX tag is set to YES doxygen generates more compact LaTeX
1578 | # documents. This may be useful for small projects and may help to save some
1579 | # trees in general.
1580 | # The default value is: NO.
1581 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1582 | 
1583 | COMPACT_LATEX          = NO
1584 | 
1585 | # The PAPER_TYPE tag can be used to set the paper type that is used by the
1586 | # printer.
1587 | # Possible values are: a4 (210 x 297 mm), letter (8.5 x 11 inches), legal (8.5 x
1588 | # 14 inches) and executive (7.25 x 10.5 inches).
1589 | # The default value is: a4.
1590 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1591 | 
1592 | PAPER_TYPE             = a4
1593 | 
1594 | # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
1595 | # that should be included in the LaTeX output. To get the times font for
1596 | # instance you can specify
1597 | # EXTRA_PACKAGES=times
1598 | # If left blank no extra packages will be included.
1599 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1600 | 
1601 | EXTRA_PACKAGES         =
1602 | 
1603 | # The LATEX_HEADER tag can be used to specify a personal LaTeX header for the
1604 | # generated LaTeX document. The header should contain everything until the first
1605 | # chapter. If it is left blank doxygen will generate a standard header. See
1606 | # section "Doxygen usage" for information on how to let doxygen write the
1607 | # default header to a separate file.
1608 | #
1609 | # Note: Only use a user-defined header if you know what you are doing! The
1610 | # following commands have a special meaning inside the header: $title,
1611 | # $datetime, $date, $doxygenversion, $projectname, $projectnumber. Doxygen will
1612 | # replace them by respectively the title of the page, the current date and time,
1613 | # only the current date, the version number of doxygen, the project name (see
1614 | # PROJECT_NAME), or the project number (see PROJECT_NUMBER).
1615 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1616 | 
1617 | LATEX_HEADER           =
1618 | 
1619 | # The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the
1620 | # generated LaTeX document. The footer should contain everything after the last
1621 | # chapter. If it is left blank doxygen will generate a standard footer.
1622 | #
1623 | # Note: Only use a user-defined footer if you know what you are doing!
1624 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1625 | 
1626 | LATEX_FOOTER           =
1627 | 
1628 | # The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or
1629 | # other source files which should be copied to the LATEX_OUTPUT output
1630 | # directory. Note that the files will be copied as-is; there are no commands or
1631 | # markers available.
1632 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1633 | 
1634 | LATEX_EXTRA_FILES      =
1635 | 
1636 | # If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is
1637 | # prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will
1638 | # contain links (just like the HTML output) instead of page references. This
1639 | # makes the output suitable for online browsing using a PDF viewer.
1640 | # The default value is: YES.
1641 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1642 | 
1643 | PDF_HYPERLINKS         = YES
1644 | 
1645 | # If the LATEX_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate
1646 | # the PDF file directly from the LaTeX files. Set this option to YES to get a
1647 | # higher quality PDF documentation.
1648 | # The default value is: YES.
1649 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1650 | 
1651 | USE_PDFLATEX           = YES
1652 | 
1653 | # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode
1654 | # command to the generated LaTeX files. This will instruct LaTeX to keep running
1655 | # if errors occur, instead of asking the user for help. This option is also used
1656 | # when generating formulas in HTML.
1657 | # The default value is: NO.
1658 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1659 | 
1660 | LATEX_BATCHMODE        = NO
1661 | 
1662 | # If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the
1663 | # index chapters (such as File Index, Compound Index, etc.) in the output.
1664 | # The default value is: NO.
1665 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1666 | 
1667 | LATEX_HIDE_INDICES     = NO
1668 | 
1669 | # If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source
1670 | # code with syntax highlighting in the LaTeX output.
1671 | #
1672 | # Note that which sources are shown also depends on other settings such as
1673 | # SOURCE_BROWSER.
1674 | # The default value is: NO.
1675 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1676 | 
1677 | LATEX_SOURCE_CODE      = NO
1678 | 
1679 | # The LATEX_BIB_STYLE tag can be used to specify the style to use for the
1680 | # bibliography, e.g. plainnat, or ieeetr. See
1681 | # http://en.wikipedia.org/wiki/BibTeX and \cite for more info.
1682 | # The default value is: plain.
1683 | # This tag requires that the tag GENERATE_LATEX is set to YES.
1684 | 
1685 | LATEX_BIB_STYLE        = plain
1686 | 
1687 | #---------------------------------------------------------------------------
1688 | # Configuration options related to the RTF output
1689 | #---------------------------------------------------------------------------
1690 | 
1691 | # If the GENERATE_RTF tag is set to YES doxygen will generate RTF output. The
1692 | # RTF output is optimized for Word 97 and may not look too pretty with other RTF
1693 | # readers/editors.
1694 | # The default value is: NO.
1695 | 
1696 | GENERATE_RTF           = NO
1697 | 
1698 | # The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a
1699 | # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
1700 | # it.
1701 | # The default directory is: rtf.
1702 | # This tag requires that the tag GENERATE_RTF is set to YES.
1703 | 
1704 | RTF_OUTPUT             = rtf
1705 | 
1706 | # If the COMPACT_RTF tag is set to YES doxygen generates more compact RTF
1707 | # documents. This may be useful for small projects and may help to save some
1708 | # trees in general.
1709 | # The default value is: NO.
1710 | # This tag requires that the tag GENERATE_RTF is set to YES.
1711 | 
1712 | COMPACT_RTF            = NO
1713 | 
1714 | # If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will
1715 | # contain hyperlink fields. The RTF file will contain links (just like the HTML
1716 | # output) instead of page references. This makes the output suitable for online
1717 | # browsing using Word or some other Word compatible readers that support those
1718 | # fields.
1719 | #
1720 | # Note: WordPad (write) and others do not support links.
1721 | # The default value is: NO.
1722 | # This tag requires that the tag GENERATE_RTF is set to YES.
1723 | 
1724 | RTF_HYPERLINKS         = NO
1725 | 
1726 | # Load stylesheet definitions from file. Syntax is similar to doxygen's config
1727 | # file, i.e. a series of assignments. You only have to provide replacements,
1728 | # missing definitions are set to their default value.
1729 | #
1730 | # See also section "Doxygen usage" for information on how to generate the
1731 | # default style sheet that doxygen normally uses.
1732 | # This tag requires that the tag GENERATE_RTF is set to YES.
1733 | 
1734 | RTF_STYLESHEET_FILE    =
1735 | 
1736 | # Set optional variables used in the generation of an RTF document. Syntax is
1737 | # similar to doxygen's config file. A template extensions file can be generated
1738 | # using doxygen -e rtf extensionFile.
1739 | # This tag requires that the tag GENERATE_RTF is set to YES.
1740 | 
1741 | RTF_EXTENSIONS_FILE    =
1742 | 
1743 | #---------------------------------------------------------------------------
1744 | # Configuration options related to the man page output
1745 | #---------------------------------------------------------------------------
1746 | 
1747 | # If the GENERATE_MAN tag is set to YES doxygen will generate man pages for
1748 | # classes and files.
1749 | # The default value is: NO.
1750 | 
1751 | GENERATE_MAN           = NO
1752 | 
1753 | # The MAN_OUTPUT tag is used to specify where the man pages will be put. If a
1754 | # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
1755 | # it. A directory man3 will be created inside the directory specified by
1756 | # MAN_OUTPUT.
1757 | # The default directory is: man.
1758 | # This tag requires that the tag GENERATE_MAN is set to YES.
1759 | 
1760 | MAN_OUTPUT             = man
1761 | 
1762 | # The MAN_EXTENSION tag determines the extension that is added to the generated
1763 | # man pages. In case the manual section does not start with a number, the number
1764 | # 3 is prepended. The dot (.) at the beginning of the MAN_EXTENSION tag is
1765 | # optional.
1766 | # The default value is: .3.
1767 | # This tag requires that the tag GENERATE_MAN is set to YES.
1768 | 
1769 | MAN_EXTENSION          = .3
1770 | 
1771 | # If the MAN_LINKS tag is set to YES and doxygen generates man output, then it
1772 | # will generate one additional man file for each entity documented in the real
1773 | # man page(s). These additional files only source the real man page, but without
1774 | # them the man command would be unable to find the correct page.
1775 | # The default value is: NO.
1776 | # This tag requires that the tag GENERATE_MAN is set to YES.
1777 | 
1778 | MAN_LINKS              = NO
1779 | 
1780 | #---------------------------------------------------------------------------
1781 | # Configuration options related to the XML output
1782 | #---------------------------------------------------------------------------
1783 | 
1784 | # If the GENERATE_XML tag is set to YES doxygen will generate an XML file that
1785 | # captures the structure of the code including all documentation.
1786 | # The default value is: NO.
1787 | 
1788 | GENERATE_XML           = NO
1789 | 
1790 | # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
1791 | # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
1792 | # it.
1793 | # The default directory is: xml.
1794 | # This tag requires that the tag GENERATE_XML is set to YES.
1795 | 
1796 | XML_OUTPUT             = xml
1797 | 
1798 | # The XML_SCHEMA tag can be used to specify a XML schema, which can be used by a
1799 | # validating XML parser to check the syntax of the XML files.
1800 | # This tag requires that the tag GENERATE_XML is set to YES.
1801 | 
1802 | XML_SCHEMA             =
1803 | 
1804 | # The XML_DTD tag can be used to specify a XML DTD, which can be used by a
1805 | # validating XML parser to check the syntax of the XML files.
1806 | # This tag requires that the tag GENERATE_XML is set to YES.
1807 | 
1808 | XML_DTD                =
1809 | 
1810 | # If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program
1811 | # listings (including syntax highlighting and cross-referencing information) to
1812 | # the XML output. Note that enabling this will significantly increase the size
1813 | # of the XML output.
1814 | # The default value is: YES.
1815 | # This tag requires that the tag GENERATE_XML is set to YES.
1816 | 
1817 | XML_PROGRAMLISTING     = YES
1818 | 
1819 | #---------------------------------------------------------------------------
1820 | # Configuration options related to the DOCBOOK output
1821 | #---------------------------------------------------------------------------
1822 | 
1823 | # If the GENERATE_DOCBOOK tag is set to YES doxygen will generate Docbook files
1824 | # that can be used to generate PDF.
1825 | # The default value is: NO.
1826 | 
1827 | GENERATE_DOCBOOK       = NO
1828 | 
1829 | # The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put.
1830 | # If a relative path is entered the value of OUTPUT_DIRECTORY will be put in
1831 | # front of it.
1832 | # The default directory is: docbook.
1833 | # This tag requires that the tag GENERATE_DOCBOOK is set to YES.
1834 | 
1835 | DOCBOOK_OUTPUT         = docbook
1836 | 
1837 | #---------------------------------------------------------------------------
1838 | # Configuration options for the AutoGen Definitions output
1839 | #---------------------------------------------------------------------------
1840 | 
1841 | # If the GENERATE_AUTOGEN_DEF tag is set to YES doxygen will generate an AutoGen
1842 | # Definitions (see http://autogen.sf.net) file that captures the structure of
1843 | # the code including all documentation. Note that this feature is still
1844 | # experimental and incomplete at the moment.
1845 | # The default value is: NO.
1846 | 
1847 | GENERATE_AUTOGEN_DEF   = NO
1848 | 
1849 | #---------------------------------------------------------------------------
1850 | # Configuration options related to the Perl module output
1851 | #---------------------------------------------------------------------------
1852 | 
1853 | # If the GENERATE_PERLMOD tag is set to YES doxygen will generate a Perl module
1854 | # file that captures the structure of the code including all documentation.
1855 | #
1856 | # Note that this feature is still experimental and incomplete at the moment.
1857 | # The default value is: NO.
1858 | 
1859 | GENERATE_PERLMOD       = NO
1860 | 
1861 | # If the PERLMOD_LATEX tag is set to YES doxygen will generate the necessary
1862 | # Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI
1863 | # output from the Perl module output.
1864 | # The default value is: NO.
1865 | # This tag requires that the tag GENERATE_PERLMOD is set to YES.
1866 | 
1867 | PERLMOD_LATEX          = NO
1868 | 
1869 | # If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely
1870 | # formatted so it can be parsed by a human reader. This is useful if you want to
1871 | # understand what is going on. On the other hand, if this tag is set to NO the
1872 | # size of the Perl module output will be much smaller and Perl will parse it
1873 | # just the same.
1874 | # The default value is: YES.
1875 | # This tag requires that the tag GENERATE_PERLMOD is set to YES.
1876 | 
1877 | PERLMOD_PRETTY         = YES
1878 | 
1879 | # The names of the make variables in the generated doxyrules.make file are
1880 | # prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. This is useful
1881 | # so different doxyrules.make files included by the same Makefile don't
1882 | # overwrite each other's variables.
1883 | # This tag requires that the tag GENERATE_PERLMOD is set to YES.
1884 | 
1885 | PERLMOD_MAKEVAR_PREFIX =
1886 | 
1887 | #---------------------------------------------------------------------------
1888 | # Configuration options related to the preprocessor
1889 | #---------------------------------------------------------------------------
1890 | 
1891 | # If the ENABLE_PREPROCESSING tag is set to YES doxygen will evaluate all
1892 | # C-preprocessor directives found in the sources and include files.
1893 | # The default value is: YES.
1894 | 
1895 | ENABLE_PREPROCESSING   = YES
1896 | 
1897 | # If the MACRO_EXPANSION tag is set to YES doxygen will expand all macro names
1898 | # in the source code. If set to NO only conditional compilation will be
1899 | # performed. Macro expansion can be done in a controlled way by setting
1900 | # EXPAND_ONLY_PREDEF to YES.
1901 | # The default value is: NO.
1902 | # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
1903 | 
1904 | MACRO_EXPANSION        = NO
1905 | 
1906 | # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
1907 | # the macro expansion is limited to the macros specified with the PREDEFINED and
1908 | # EXPAND_AS_DEFINED tags.
1909 | # The default value is: NO.
1910 | # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
1911 | 
1912 | EXPAND_ONLY_PREDEF     = NO
1913 | 
1914 | # If the SEARCH_INCLUDES tag is set to YES the includes files in the
1915 | # INCLUDE_PATH will be searched if a #include is found.
1916 | # The default value is: YES.
1917 | # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
1918 | 
1919 | SEARCH_INCLUDES        = YES
1920 | 
1921 | # The INCLUDE_PATH tag can be used to specify one or more directories that
1922 | # contain include files that are not input files but should be processed by the
1923 | # preprocessor.
1924 | # This tag requires that the tag SEARCH_INCLUDES is set to YES.
1925 | 
1926 | INCLUDE_PATH           =
1927 | 
1928 | # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
1929 | # patterns (like *.h and *.hpp) to filter out the header-files in the
1930 | # directories. If left blank, the patterns specified with FILE_PATTERNS will be
1931 | # used.
1932 | # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
1933 | 
1934 | INCLUDE_FILE_PATTERNS  =
1935 | 
1936 | # The PREDEFINED tag can be used to specify one or more macro names that are
1937 | # defined before the preprocessor is started (similar to the -D option of e.g.
1938 | # gcc). The argument of the tag is a list of macros of the form: name or
1939 | # name=definition (no spaces). If the definition and the "=" are omitted, "=1"
1940 | # is assumed. To prevent a macro definition from being undefined via #undef or
1941 | # recursively expanded use the := operator instead of the = operator.
1942 | # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
1943 | 
1944 | PREDEFINED             =
1945 | 
1946 | # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
1947 | # tag can be used to specify a list of macro names that should be expanded. The
1948 | # macro definition that is found in the sources will be used. Use the PREDEFINED
1949 | # tag if you want to use a different macro definition that overrules the
1950 | # definition found in the source code.
1951 | # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
1952 | 
1953 | EXPAND_AS_DEFINED      =
1954 | 
1955 | # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
1956 | # remove all refrences to function-like macros that are alone on a line, have an
1957 | # all uppercase name, and do not end with a semicolon. Such function macros are
1958 | # typically used for boiler-plate code, and will confuse the parser if not
1959 | # removed.
1960 | # The default value is: YES.
1961 | # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
1962 | 
1963 | SKIP_FUNCTION_MACROS   = YES
1964 | 
1965 | #---------------------------------------------------------------------------
1966 | # Configuration options related to external references
1967 | #---------------------------------------------------------------------------
1968 | 
1969 | # The TAGFILES tag can be used to specify one or more tag files. For each tag
1970 | # file the location of the external documentation should be added. The format of
1971 | # a tag file without this location is as follows:
1972 | # TAGFILES = file1 file2 ...
1973 | # Adding location for the tag files is done as follows:
1974 | # TAGFILES = file1=loc1 "file2 = loc2" ...
1975 | # where loc1 and loc2 can be relative or absolute paths or URLs. See the
1976 | # section "Linking to external documentation" for more information about the use
1977 | # of tag files.
1978 | # Note: Each tag file must have an unique name (where the name does NOT include
1979 | # the path). If a tag file is not located in the directory in which doxygen is
1980 | # run, you must also specify the path to the tagfile here.
1981 | 
1982 | TAGFILES               =
1983 | 
1984 | # When a file name is specified after GENERATE_TAGFILE, doxygen will create a
1985 | # tag file that is based on the input files it reads. See section "Linking to
1986 | # external documentation" for more information about the usage of tag files.
1987 | 
1988 | GENERATE_TAGFILE       =
1989 | 
1990 | # If the ALLEXTERNALS tag is set to YES all external class will be listed in the
1991 | # class index. If set to NO only the inherited external classes will be listed.
1992 | # The default value is: NO.
1993 | 
1994 | ALLEXTERNALS           = NO
1995 | 
1996 | # If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed in
1997 | # the modules index. If set to NO, only the current project's groups will be
1998 | # listed.
1999 | # The default value is: YES.
2000 | 
2001 | EXTERNAL_GROUPS        = YES
2002 | 
2003 | # If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in
2004 | # the related pages index. If set to NO, only the current project's pages will
2005 | # be listed.
2006 | # The default value is: YES.
2007 | 
2008 | EXTERNAL_PAGES         = YES
2009 | 
2010 | # The PERL_PATH should be the absolute path and name of the perl script
2011 | # interpreter (i.e. the result of 'which perl').
2012 | # The default file (with absolute path) is: /usr/bin/perl.
2013 | 
2014 | PERL_PATH              = /usr/bin/perl
2015 | 
2016 | #---------------------------------------------------------------------------
2017 | # Configuration options related to the dot tool
2018 | #---------------------------------------------------------------------------
2019 | 
2020 | # If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram
2021 | # (in HTML and LaTeX) for classes with base or super classes. Setting the tag to
2022 | # NO turns the diagrams off. Note that this option also works with HAVE_DOT
2023 | # disabled, but it is recommended to install and use dot, since it yields more
2024 | # powerful graphs.
2025 | # The default value is: YES.
2026 | 
2027 | CLASS_DIAGRAMS         = YES
2028 | 
2029 | # You can define message sequence charts within doxygen comments using the \msc
2030 | # command. Doxygen will then run the mscgen tool (see:
2031 | # http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the
2032 | # documentation. The MSCGEN_PATH tag allows you to specify the directory where
2033 | # the mscgen tool resides. If left empty the tool is assumed to be found in the
2034 | # default search path.
2035 | 
2036 | MSCGEN_PATH            =
2037 | 
2038 | # You can include diagrams made with dia in doxygen documentation. Doxygen will
2039 | # then run dia to produce the diagram and insert it in the documentation. The
2040 | # DIA_PATH tag allows you to specify the directory where the dia binary resides.
2041 | # If left empty dia is assumed to be found in the default search path.
2042 | 
2043 | DIA_PATH               =
2044 | 
2045 | # If set to YES, the inheritance and collaboration graphs will hide inheritance
2046 | # and usage relations if the target is undocumented or is not a class.
2047 | # The default value is: YES.
2048 | 
2049 | HIDE_UNDOC_RELATIONS   = YES
2050 | 
2051 | # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
2052 | # available from the path. This tool is part of Graphviz (see:
2053 | # http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent
2054 | # Bell Labs. The other options in this section have no effect if this option is
2055 | # set to NO
2056 | # The default value is: NO.
2057 | 
2058 | HAVE_DOT               = NO
2059 | 
2060 | # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
2061 | # to run in parallel. When set to 0 doxygen will base this on the number of
2062 | # processors available in the system. You can set it explicitly to a value
2063 | # larger than 0 to get control over the balance between CPU load and processing
2064 | # speed.
2065 | # Minimum value: 0, maximum value: 32, default value: 0.
2066 | # This tag requires that the tag HAVE_DOT is set to YES.
2067 | 
2068 | DOT_NUM_THREADS        = 0
2069 | 
2070 | # When you want a differently looking font n the dot files that doxygen
2071 | # generates you can specify the font name using DOT_FONTNAME. You need to make
2072 | # sure dot is able to find the font, which can be done by putting it in a
2073 | # standard location or by setting the DOTFONTPATH environment variable or by
2074 | # setting DOT_FONTPATH to the directory containing the font.
2075 | # The default value is: Helvetica.
2076 | # This tag requires that the tag HAVE_DOT is set to YES.
2077 | 
2078 | DOT_FONTNAME           = Helvetica
2079 | 
2080 | # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
2081 | # dot graphs.
2082 | # Minimum value: 4, maximum value: 24, default value: 10.
2083 | # This tag requires that the tag HAVE_DOT is set to YES.
2084 | 
2085 | DOT_FONTSIZE           = 10
2086 | 
2087 | # By default doxygen will tell dot to use the default font as specified with
2088 | # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set
2089 | # the path where dot can find it using this tag.
2090 | # This tag requires that the tag HAVE_DOT is set to YES.
2091 | 
2092 | DOT_FONTPATH           =
2093 | 
2094 | # If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for
2095 | # each documented class showing the direct and indirect inheritance relations.
2096 | # Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO.
2097 | # The default value is: YES.
2098 | # This tag requires that the tag HAVE_DOT is set to YES.
2099 | 
2100 | CLASS_GRAPH            = YES
2101 | 
2102 | # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a
2103 | # graph for each documented class showing the direct and indirect implementation
2104 | # dependencies (inheritance, containment, and class references variables) of the
2105 | # class with other documented classes.
2106 | # The default value is: YES.
2107 | # This tag requires that the tag HAVE_DOT is set to YES.
2108 | 
2109 | COLLABORATION_GRAPH    = YES
2110 | 
2111 | # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for
2112 | # groups, showing the direct groups dependencies.
2113 | # The default value is: YES.
2114 | # This tag requires that the tag HAVE_DOT is set to YES.
2115 | 
2116 | GROUP_GRAPHS           = YES
2117 | 
2118 | # If the UML_LOOK tag is set to YES doxygen will generate inheritance and
2119 | # collaboration diagrams in a style similar to the OMG's Unified Modeling
2120 | # Language.
2121 | # The default value is: NO.
2122 | # This tag requires that the tag HAVE_DOT is set to YES.
2123 | 
2124 | UML_LOOK               = NO
2125 | 
2126 | # If the UML_LOOK tag is enabled, the fields and methods are shown inside the
2127 | # class node. If there are many fields or methods and many nodes the graph may
2128 | # become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the
2129 | # number of items for each type to make the size more manageable. Set this to 0
2130 | # for no limit. Note that the threshold may be exceeded by 50% before the limit
2131 | # is enforced. So when you set the threshold to 10, up to 15 fields may appear,
2132 | # but if the number exceeds 15, the total amount of fields shown is limited to
2133 | # 10.
2134 | # Minimum value: 0, maximum value: 100, default value: 10.
2135 | # This tag requires that the tag HAVE_DOT is set to YES.
2136 | 
2137 | UML_LIMIT_NUM_FIELDS   = 10
2138 | 
2139 | # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and
2140 | # collaboration graphs will show the relations between templates and their
2141 | # instances.
2142 | # The default value is: NO.
2143 | # This tag requires that the tag HAVE_DOT is set to YES.
2144 | 
2145 | TEMPLATE_RELATIONS     = NO
2146 | 
2147 | # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to
2148 | # YES then doxygen will generate a graph for each documented file showing the
2149 | # direct and indirect include dependencies of the file with other documented
2150 | # files.
2151 | # The default value is: YES.
2152 | # This tag requires that the tag HAVE_DOT is set to YES.
2153 | 
2154 | INCLUDE_GRAPH          = YES
2155 | 
2156 | # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are
2157 | # set to YES then doxygen will generate a graph for each documented file showing
2158 | # the direct and indirect include dependencies of the file with other documented
2159 | # files.
2160 | # The default value is: YES.
2161 | # This tag requires that the tag HAVE_DOT is set to YES.
2162 | 
2163 | INCLUDED_BY_GRAPH      = YES
2164 | 
2165 | # If the CALL_GRAPH tag is set to YES then doxygen will generate a call
2166 | # dependency graph for every global function or class method.
2167 | #
2168 | # Note that enabling this option will significantly increase the time of a run.
2169 | # So in most cases it will be better to enable call graphs for selected
2170 | # functions only using the \callgraph command.
2171 | # The default value is: NO.
2172 | # This tag requires that the tag HAVE_DOT is set to YES.
2173 | 
2174 | CALL_GRAPH             = NO
2175 | 
2176 | # If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller
2177 | # dependency graph for every global function or class method.
2178 | #
2179 | # Note that enabling this option will significantly increase the time of a run.
2180 | # So in most cases it will be better to enable caller graphs for selected
2181 | # functions only using the \callergraph command.
2182 | # The default value is: NO.
2183 | # This tag requires that the tag HAVE_DOT is set to YES.
2184 | 
2185 | CALLER_GRAPH           = NO
2186 | 
2187 | # If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical
2188 | # hierarchy of all classes instead of a textual one.
2189 | # The default value is: YES.
2190 | # This tag requires that the tag HAVE_DOT is set to YES.
2191 | 
2192 | GRAPHICAL_HIERARCHY    = YES
2193 | 
2194 | # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the
2195 | # dependencies a directory has on other directories in a graphical way. The
2196 | # dependency relations are determined by the #include relations between the
2197 | # files in the directories.
2198 | # The default value is: YES.
2199 | # This tag requires that the tag HAVE_DOT is set to YES.
2200 | 
2201 | DIRECTORY_GRAPH        = YES
2202 | 
2203 | # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
2204 | # generated by dot.
2205 | # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order
2206 | # to make the SVG files visible in IE 9+ (other browsers do not have this
2207 | # requirement).
2208 | # Possible values are: png, jpg, gif and svg.
2209 | # The default value is: png.
2210 | # This tag requires that the tag HAVE_DOT is set to YES.
2211 | 
2212 | DOT_IMAGE_FORMAT       = png
2213 | 
2214 | # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
2215 | # enable generation of interactive SVG images that allow zooming and panning.
2216 | #
2217 | # Note that this requires a modern browser other than Internet Explorer. Tested
2218 | # and working are Firefox, Chrome, Safari, and Opera.
2219 | # Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make
2220 | # the SVG files visible. Older versions of IE do not have SVG support.
2221 | # The default value is: NO.
2222 | # This tag requires that the tag HAVE_DOT is set to YES.
2223 | 
2224 | INTERACTIVE_SVG        = NO
2225 | 
2226 | # The DOT_PATH tag can be used to specify the path where the dot tool can be
2227 | # found. If left blank, it is assumed the dot tool can be found in the path.
2228 | # This tag requires that the tag HAVE_DOT is set to YES.
2229 | 
2230 | DOT_PATH               =
2231 | 
2232 | # The DOTFILE_DIRS tag can be used to specify one or more directories that
2233 | # contain dot files that are included in the documentation (see the \dotfile
2234 | # command).
2235 | # This tag requires that the tag HAVE_DOT is set to YES.
2236 | 
2237 | DOTFILE_DIRS           =
2238 | 
2239 | # The MSCFILE_DIRS tag can be used to specify one or more directories that
2240 | # contain msc files that are included in the documentation (see the \mscfile
2241 | # command).
2242 | 
2243 | MSCFILE_DIRS           =
2244 | 
2245 | # The DIAFILE_DIRS tag can be used to specify one or more directories that
2246 | # contain dia files that are included in the documentation (see the \diafile
2247 | # command).
2248 | 
2249 | DIAFILE_DIRS           =
2250 | 
2251 | # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes
2252 | # that will be shown in the graph. If the number of nodes in a graph becomes
2253 | # larger than this value, doxygen will truncate the graph, which is visualized
2254 | # by representing a node as a red box. Note that doxygen if the number of direct
2255 | # children of the root node in a graph is already larger than
2256 | # DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that
2257 | # the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.
2258 | # Minimum value: 0, maximum value: 10000, default value: 50.
2259 | # This tag requires that the tag HAVE_DOT is set to YES.
2260 | 
2261 | DOT_GRAPH_MAX_NODES    = 50
2262 | 
2263 | # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
2264 | # generated by dot. A depth value of 3 means that only nodes reachable from the
2265 | # root by following a path via at most 3 edges will be shown. Nodes that lay
2266 | # further from the root node will be omitted. Note that setting this option to 1
2267 | # or 2 may greatly reduce the computation time needed for large code bases. Also
2268 | # note that the size of a graph can be further restricted by
2269 | # DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction.
2270 | # Minimum value: 0, maximum value: 1000, default value: 0.
2271 | # This tag requires that the tag HAVE_DOT is set to YES.
2272 | 
2273 | MAX_DOT_GRAPH_DEPTH    = 0
2274 | 
2275 | # Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
2276 | # background. This is disabled by default, because dot on Windows does not seem
2277 | # to support this out of the box.
2278 | #
2279 | # Warning: Depending on the platform used, enabling this option may lead to
2280 | # badly anti-aliased labels on the edges of a graph (i.e. they become hard to
2281 | # read).
2282 | # The default value is: NO.
2283 | # This tag requires that the tag HAVE_DOT is set to YES.
2284 | 
2285 | DOT_TRANSPARENT        = NO
2286 | 
2287 | # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
2288 | # files in one run (i.e. multiple -o and -T options on the command line). This
2289 | # makes dot run faster, but since only newer versions of dot (>1.8.10) support
2290 | # this, this feature is disabled by default.
2291 | # The default value is: NO.
2292 | # This tag requires that the tag HAVE_DOT is set to YES.
2293 | 
2294 | DOT_MULTI_TARGETS      = NO
2295 | 
2296 | # If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page
2297 | # explaining the meaning of the various boxes and arrows in the dot generated
2298 | # graphs.
2299 | # The default value is: YES.
2300 | # This tag requires that the tag HAVE_DOT is set to YES.
2301 | 
2302 | GENERATE_LEGEND        = YES
2303 | 
2304 | # If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot
2305 | # files that are used to generate the various graphs.
2306 | # The default value is: YES.
2307 | # This tag requires that the tag HAVE_DOT is set to YES.
2308 | 
2309 | DOT_CLEANUP            = YES
2310 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
 1 | # Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
 2 | # This program is free software. It comes without any warranty, to the extent
 3 | # permitted by applicable law. You can redistribute it and/or modify it under
 4 | # the terms of the Do What The Fuck You Want To Public License, Version 2, as
 5 | # published by Sam Hocevar. See the COPYING file for more details.
 6 | 
 7 | CFLAGS = -g -Wall -Wextra -Werror -std=c99 -I. -Itests
 8 | CFLAGS += -D_GNU_SOURCE
 9 | CFLAGS += -fPIC # needed due to our shared library shenanigans
10 | LDLIBS = -lcheck -lm -lpthread -lrt
11 | 
12 | all: scan-build test example
13 | 	@echo "+++ All good."""
14 | 
15 | test: unit fuzz
16 | 
17 | unit: tests/tests
18 | 	@echo "+++ Running Check test suite..."
19 | 	tests/tests
20 | 
21 | fuzz: ringfs.so tests/flashsim.so tests/fuzzer.py
22 | 	@echo "+++ Running fuzzer..."
23 | 	tests/fuzzer.py
24 | 
25 | scan-build: clean
26 | 	@echo "+++ Running Clang Static Analyzer..."
27 | 	scan-build $(MAKE) tests
28 | 
29 | docs:
30 | 	doxygen
31 | 
32 | clean:
33 | 	$(RM) *.o tests/*.o tests/tests html/ *.sim tags example
34 | 
35 | %.so: %.o
36 | 	$(LINK.o) -shared $^ $(LOADLIBES) $(LDLIBS) -o $@
37 | 
38 | ringfs.o: ringfs.c ringfs.h
39 | 
40 | example: example.o ringfs.o tests/flashsim.o
41 | example.o: example.c ringfs.h tests/flashsim.h
42 | 
43 | tests/tests: ringfs.o tests/tests.o tests/flashsim.o
44 | tests/tests.o: tests/tests.c ringfs.h
45 | 
46 | tests/tests: ringfs.o tests/tests.o tests/flashsim.o
47 | tests/tests.o: tests/tests.c ringfs.h
48 | tests/flashsim.o: tests/flashsim.c tests/flashsim.h
49 | 
50 | ringfs.so: ringfs.o
51 | tests/flashsim.so: tests/flashsim.o
52 | 
53 | .PHONY: all test unit fuzz scan-build clean docs
54 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # RingFS, a small Flash-based ring buffer.
 2 | 
 3 | [![Build Status](https://travis-ci.org/cloudyourcar/ringfs.svg)](https://travis-ci.org/cloudyourcar/ringfs)
 4 | 
 5 | RingFS is a persistent, Flash-based ring buffer designed for embedded software.
 6 | It's aimed at storing non-critical data that can be expunged on the FIFO basis
 7 | as needed. Typical uses include:
 8 | 
 9 | * telemetry data,
10 | * debug logs,
11 | * stack traces.
12 | 
13 | RingFS has been designed to run on NOR Flash memory, which exhibits the following
14 | semantics:
15 | 
16 | 1. Bits are programmed by flipping them from 1 to 0 with byte granularity.
17 | 2. Bits are erased by flipping them from 0 to 1 with sector granularity.
18 | 
19 | ## Features
20 | 
21 | * Designed and optimized for NOR Flash memory.
22 | * Stores fixed-size objects in a FIFO buffer.
23 | * Written in ISO C99.
24 | * No dynamic memory allocation.
25 | * Basic robustness features for error recovery.
26 | 
27 | ## Usage
28 | 
29 | 1. Add ``ringfs.c`` and ``ringfs.h`` to your project.
30 | 2. Implement the required Flash ops (``sector_erase``, ``program``, ``read``).
31 | 3. Glue your Flash ops with ringfs using ``struct ringfs_flash_partition``.
32 | 
33 | See ``example.c`` if this sounds complicated.
34 | 
35 | ## Documentation
36 | 
37 | See Doxygen-generated documentation at http://cloudyourcar.github.io/ringfs/.
38 | 
39 | ## Non-Features
40 | 
41 | The ring buffer has been designed to be as simple as possible. Therefore, the
42 | following are non-features that will *not* be implemented:
43 | 
44 | * Variable object sizes (makes things much more complicated).
45 | * Complicated error recovery (we can lose data in edge cases).
46 | * Upgrades (complex, also unnecessary in our use cases).
47 | 
48 | Actually, on the second thought, I may consider adding support for variable
49 | object sizes some day.
50 | 
51 | ## License
52 | 
53 | > Copyright © 2014 Kosma Moczek \<kosma@cloudyourcar.com\>
54 | > 
55 | > This program is free software. It comes without any warranty, to the extent
56 | > permitted by applicable law. You can redistribute it and/or modify it under
57 | > the terms of the Do What The Fuck You Want To Public License, Version 2, as
58 | > published by Sam Hocevar. See the COPYING file for more details.
59 | 


--------------------------------------------------------------------------------
/example.c:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
  3 |  * This program is free software. It comes without any warranty, to the extent
  4 |  * permitted by applicable law. You can redistribute it and/or modify it under
  5 |  * the terms of the Do What The Fuck You Want To Public License, Version 2, as
  6 |  * published by Sam Hocevar. See the COPYING file for more details.
  7 |  */
  8 | 
  9 | #include <stdio.h>
 10 | #include <assert.h>
 11 | 
 12 | #include "ringfs.h"
 13 | #include "flashsim.h"
 14 | 
 15 | 
 16 | /* Flash implementation & ops. */
 17 | 
 18 | #define FLASH_SECTOR_SIZE       1024
 19 | #define FLASH_TOTAL_SECTORS     16
 20 | #define FLASH_PARTITION_OFFSET  8
 21 | #define FLASH_PARTITION_SIZE    4
 22 | 
 23 | static struct flashsim *sim;
 24 | 
 25 | static void init_flash_driver(void)
 26 | {
 27 |     sim = flashsim_open("example.sim",
 28 |             FLASH_TOTAL_SECTORS*FLASH_SECTOR_SIZE,
 29 |             FLASH_SECTOR_SIZE);
 30 | }
 31 | 
 32 | static int op_sector_erase(struct ringfs_flash_partition *flash, int address)
 33 | {
 34 |     (void) flash;
 35 |     flashsim_sector_erase(sim, address);
 36 |     return 0;
 37 | }
 38 | 
 39 | static ssize_t op_program(struct ringfs_flash_partition *flash, int address, const void *data, size_t size)
 40 | {
 41 |     (void) flash;
 42 |     flashsim_program(sim, address, data, size);
 43 |     return size;
 44 | }
 45 | 
 46 | static ssize_t op_read(struct ringfs_flash_partition *flash, int address, void *data, size_t size)
 47 | {
 48 |     (void) flash;
 49 |     flashsim_read(sim, address, data, size);
 50 |     return size;
 51 | }
 52 | 
 53 | static struct ringfs_flash_partition flash = {
 54 |     .sector_size = FLASH_SECTOR_SIZE,
 55 |     .sector_offset = FLASH_PARTITION_OFFSET,
 56 |     .sector_count = FLASH_PARTITION_SIZE,
 57 | 
 58 |     .sector_erase = op_sector_erase,
 59 |     .program = op_program,
 60 |     .read = op_read,
 61 | };
 62 | 
 63 | 
 64 | /* Data record format. */
 65 | struct log_entry {
 66 |     int level;
 67 |     char message[16];
 68 | };
 69 | #define LOG_ENTRY_VERSION 1
 70 | 
 71 | 
 72 | /* Let's roll! */
 73 | int main()
 74 | {
 75 |     /* Initialize your Flash driver before using the filesystem. */
 76 |     init_flash_driver();
 77 | 
 78 |     /* Always call ringfs_init first. */
 79 |     struct ringfs fs;
 80 |     ringfs_init(&fs, &flash, LOG_ENTRY_VERSION, sizeof(struct log_entry));
 81 | 
 82 |     /* Scan and/or format before any data operations. */
 83 |     printf("# scanning for filesystem...\n");
 84 |     if (ringfs_scan(&fs) == 0) {
 85 |         printf("# found existing filesystem, usage: %d/%d\n",
 86 |                 ringfs_count_estimate(&fs),
 87 |                 ringfs_capacity(&fs));
 88 |     } else {
 89 |         printf("# no valid filesystem found, formatting.\n");
 90 |         ringfs_format(&fs);
 91 |     }
 92 | 
 93 |     /* Append data using ringfs_append. Oldest data is removed as needed. */
 94 |     printf("# inserting some objects\n");
 95 |     ringfs_append(&fs, &(struct log_entry) { 1, "foo" });
 96 |     ringfs_append(&fs, &(struct log_entry) { 2, "bar" });
 97 |     ringfs_append(&fs, &(struct log_entry) { 3, "baz" });
 98 |     ringfs_append(&fs, &(struct log_entry) { 4, "xyzzy" });
 99 |     ringfs_append(&fs, &(struct log_entry) { 5, "test" });
100 |     ringfs_append(&fs, &(struct log_entry) { 6, "hello" });
101 | 
102 |     /* Objects are retrieved using ringfs_fetch. They are not physically removed
103 |      * until you call ringfs_discard. This is useful, for example, when transmitting
104 |      * queued objects over the network: you don't physically remove the objects
105 |      * from the ring buffer until you receive an ACK. */
106 |     printf("# reading 2 objects\n");
107 |     for (int i=0; i<2; i++) {
108 |         struct log_entry entry;
109 |         assert(ringfs_fetch(&fs, &entry) == 0);
110 |         printf("## level=%d message=%.16s\n", entry.level, entry.message);
111 |     }
112 |     printf("# discarding read objects\n");
113 |     ringfs_discard(&fs);
114 | 
115 |     /* If you decide you can't remove the objects yet, just call ringfs_rewind() and
116 |      * they will be available again for subsequent reads. */
117 |     printf("# reading 2 objects\n");
118 |     for (int i=0; i<2; i++) {
119 |         struct log_entry entry;
120 |         assert(ringfs_fetch(&fs, &entry) == 0);
121 |         printf("## level=%d message=%.16s\n", entry.level, entry.message);
122 |     }
123 |     printf("# rewinding read head back\n");
124 |     ringfs_rewind(&fs);
125 | 
126 |     /* ...and here they are again. */
127 |     printf("# reading 2 objects\n");
128 |     for (int i=0; i<2; i++) {
129 |         struct log_entry entry;
130 |         assert(ringfs_fetch(&fs, &entry) == 0);
131 |         printf("## level=%d message=%.16s\n", entry.level, entry.message);
132 |     }
133 | 
134 |     return 0;
135 | }
136 | 
137 | /* vim: set ts=4 sw=4 et: */
138 | 


--------------------------------------------------------------------------------
/ringfs.c:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
  3 |  * This program is free software. It comes without any warranty, to the extent
  4 |  * permitted by applicable law. You can redistribute it and/or modify it under
  5 |  * the terms of the Do What The Fuck You Want To Public License, Version 2, as
  6 |  * published by Sam Hocevar. See the COPYING file for more details.
  7 |  */
  8 | 
  9 | /**
 10 |  * @defgroup ringfs_impl RingFS implementation
 11 |  * @details
 12 |  *
 13 |  * @{
 14 |  */
 15 | 
 16 | #include <ringfs.h>
 17 | 
 18 | #include <inttypes.h>
 19 | #include <stdbool.h>
 20 | #include <stddef.h>
 21 | 
 22 | 
 23 | /**
 24 |  * @defgroup sector
 25 |  * @{
 26 |  */
 27 | 
 28 | enum sector_status {
 29 |     SECTOR_ERASED     = 0xFFFFFFFF, /**< Default state after NOR flash erase. */
 30 |     SECTOR_FREE       = 0xFFFFFF00, /**< Sector erased. */
 31 |     SECTOR_IN_USE     = 0xFFFF0000, /**< Sector contains valid data. */
 32 |     SECTOR_ERASING    = 0xFF000000, /**< Sector should be erased. */
 33 |     SECTOR_FORMATTING = 0x00000000, /**< The entire partition is being formatted. */
 34 | };
 35 | 
 36 | struct sector_header {
 37 |     uint32_t status;
 38 |     uint32_t version;
 39 | };
 40 | 
 41 | static int _sector_address(struct ringfs *fs, int sector_offset)
 42 | {
 43 |     return (fs->flash->sector_offset + sector_offset) * fs->flash->sector_size;
 44 | }
 45 | 
 46 | static int _sector_get_status(struct ringfs *fs, int sector, uint32_t *status)
 47 | {
 48 |     return fs->flash->read(fs->flash,
 49 |             _sector_address(fs, sector) + offsetof(struct sector_header, status),
 50 |             status, sizeof(*status));
 51 | }
 52 | 
 53 | static int _sector_set_status(struct ringfs *fs, int sector, uint32_t status)
 54 | {
 55 |     return fs->flash->program(fs->flash,
 56 |             _sector_address(fs, sector) + offsetof(struct sector_header, status),
 57 |             &status, sizeof(status));
 58 | }
 59 | 
 60 | static int _sector_free(struct ringfs *fs, int sector)
 61 | {
 62 |     int sector_addr = _sector_address(fs, sector);
 63 |     _sector_set_status(fs, sector, SECTOR_ERASING);
 64 |     fs->flash->sector_erase(fs->flash, sector_addr);
 65 |     fs->flash->program(fs->flash,
 66 |             sector_addr + offsetof(struct sector_header, version),
 67 |             &fs->version, sizeof(fs->version));
 68 |     _sector_set_status(fs, sector, SECTOR_FREE);
 69 |     return 0;
 70 | }
 71 | 
 72 | /**
 73 |  * @}
 74 |  * @defgroup slot
 75 |  * @{
 76 |  */
 77 | 
 78 | enum slot_status {
 79 |     SLOT_ERASED   = 0xFFFFFFFF, /**< Default state after NOR flash erase. */
 80 |     SLOT_RESERVED = 0xFFFFFF00, /**< Write started but not yet committed. */
 81 |     SLOT_VALID    = 0xFFFF0000, /**< Write committed, slot contains valid data. */
 82 |     SLOT_GARBAGE  = 0xFF000000, /**< Slot contents discarded and no longer valid. */
 83 | };
 84 | 
 85 | struct slot_header {
 86 |     uint32_t status;
 87 | };
 88 | 
 89 | static int _slot_address(struct ringfs *fs, struct ringfs_loc *loc)
 90 | {
 91 |     return _sector_address(fs, loc->sector) +
 92 |            sizeof(struct sector_header) +
 93 |            (sizeof(struct slot_header) + fs->object_size) * loc->slot;
 94 | }
 95 | 
 96 | static int _slot_get_status(struct ringfs *fs, struct ringfs_loc *loc, uint32_t *status)
 97 | {
 98 |     return fs->flash->read(fs->flash,
 99 |             _slot_address(fs, loc) + offsetof(struct slot_header, status),
100 |             status, sizeof(*status));
101 | }
102 | 
103 | static int _slot_set_status(struct ringfs *fs, struct ringfs_loc *loc, uint32_t status)
104 | {
105 |     return fs->flash->program(fs->flash, 
106 |             _slot_address(fs, loc) + offsetof(struct slot_header, status),
107 |             &status, sizeof(status));
108 | }
109 | 
110 | /**
111 |  * @}
112 |  * @defgroup loc
113 |  * @{
114 |  */
115 | 
116 | static bool _loc_equal(struct ringfs_loc *a, struct ringfs_loc *b)
117 | {
118 |     return (a->sector == b->sector) && (a->slot == b->slot);
119 | }
120 | 
121 | /** Advance a location to the beginning of the next sector. */
122 | static void _loc_advance_sector(struct ringfs *fs, struct ringfs_loc *loc)
123 | {
124 |     loc->slot = 0;
125 |     loc->sector++;
126 |     if (loc->sector >= fs->flash->sector_count)
127 |         loc->sector = 0;
128 | }
129 | 
130 | /** Advance a location to the next slot, advancing the sector too if needed. */
131 | static void _loc_advance_slot(struct ringfs *fs, struct ringfs_loc *loc)
132 | {
133 |     loc->slot++;
134 |     if (loc->slot >= fs->slots_per_sector)
135 |         _loc_advance_sector(fs, loc);
136 | }
137 | 
138 | /**
139 |  * @}
140 |  */
141 | 
142 | /* And here we go. */
143 | 
144 | int ringfs_init(struct ringfs *fs, struct ringfs_flash_partition *flash, uint32_t version, int object_size)
145 | {
146 |     /* Copy arguments to instance. */
147 |     fs->flash = flash;
148 |     fs->version = version;
149 |     fs->object_size = object_size;
150 | 
151 |     /* Precalculate commonly used values. */
152 |     fs->slots_per_sector = (fs->flash->sector_size - sizeof(struct sector_header)) /
153 |                            (sizeof(struct slot_header) + fs->object_size);
154 | 
155 |     return 0;
156 | }
157 | 
158 | int ringfs_format(struct ringfs *fs)
159 | {
160 |     /* Mark all sectors to prevent half-erased filesystems. */
161 |     for (int sector=0; sector<fs->flash->sector_count; sector++)
162 |         _sector_set_status(fs, sector, SECTOR_FORMATTING);
163 | 
164 |     /* Erase, update version, mark as free. */
165 |     for (int sector=0; sector<fs->flash->sector_count; sector++)
166 |         _sector_free(fs, sector);
167 | 
168 |     /* Start reading & writing at the first sector. */
169 |     fs->read.sector = 0;
170 |     fs->read.slot = 0;
171 |     fs->write.sector = 0;
172 |     fs->write.slot = 0;
173 |     fs->cursor.sector = 0;
174 |     fs->cursor.slot = 0;
175 | 
176 |     return 0;
177 | }
178 | 
179 | int ringfs_scan(struct ringfs *fs)
180 | {
181 |     uint32_t previous_sector_status = SECTOR_FREE;
182 |     /* The read sector is the first IN_USE sector *after* a FREE sector
183 |      * (or the first one). */
184 |     int read_sector = 0;
185 |     /* The write sector is the last IN_USE sector *before* a FREE sector
186 |      * (or the last one). */
187 |     int write_sector = fs->flash->sector_count - 1;
188 |     /* There must be at least one FREE sector available at all times. */
189 |     bool free_seen = false;
190 |     /* If there's no IN_USE sector, we start at the first one. */
191 |     bool used_seen = false;
192 | 
193 |     /* Iterate over sectors. */
194 |     for (int sector=0; sector<fs->flash->sector_count; sector++) {
195 |         int addr = _sector_address(fs, sector);
196 | 
197 |         /* Read sector header. */
198 |         struct sector_header header;
199 |         fs->flash->read(fs->flash, addr, &header, sizeof(header));
200 | 
201 |         /* Detect partially-formatted partitions. */
202 |         if (header.status == SECTOR_FORMATTING) {
203 |             printf("ringfs_scan: partially formatted partition\r\n");
204 |             return -1;
205 |         }
206 | 
207 |         /* Detect and fix partially erased sectors. */
208 |         if (header.status == SECTOR_ERASING || header.status == SECTOR_ERASED) {
209 |             _sector_free(fs, sector);
210 |             header.status = SECTOR_FREE;
211 |         }
212 | 
213 |         /* Detect corrupted sectors. */
214 |         if (header.status != SECTOR_FREE && header.status != SECTOR_IN_USE) {
215 |             printf("ringfs_scan: corrupted sector %d\r\n", sector);
216 |             return -1;
217 |         }
218 | 
219 |         /* Detect obsolete versions. We can't do this earlier because the version
220 |          * could have been invalid due to a partial erase. */
221 |         if (header.version != fs->version) {
222 |             printf("ringfs_scan: incompatible version 0x%08"PRIx32"\r\n", header.version);
223 |             return -1;
224 |         }
225 | 
226 |         /* Record the presence of a FREE sector. */
227 |         if (header.status == SECTOR_FREE)
228 |             free_seen = true;
229 | 
230 |         /* Record the presence of a IN_USE sector. */
231 |         if (header.status == SECTOR_IN_USE)
232 |             used_seen = true;
233 | 
234 |         /* Update read & write sectors according to the above rules. */
235 |         if (header.status == SECTOR_IN_USE && previous_sector_status == SECTOR_FREE)
236 |             read_sector = sector;
237 |         if (header.status == SECTOR_FREE && previous_sector_status == SECTOR_IN_USE)
238 |             write_sector = sector-1;
239 | 
240 |         previous_sector_status = header.status;
241 |     }
242 | 
243 |     /* Detect the lack of a FREE sector. */
244 |     if (!free_seen) {
245 |         printf("ringfs_scan: invariant violated: no FREE sector found\r\n");
246 |         return -1;
247 |     }
248 | 
249 |     /* Start writing at the first sector if the filesystem is empty. */
250 |     if (!used_seen) {
251 |         write_sector = 0;
252 |     }
253 | 
254 |     /* Scan the write sector and skip all occupied slots at the beginning. */
255 |     fs->write.sector = write_sector;
256 |     fs->write.slot = 0;
257 |     while (fs->write.sector == write_sector) {
258 |         uint32_t status;
259 |         _slot_get_status(fs, &fs->write, &status);
260 |         if (status == SLOT_ERASED)
261 |             break;
262 | 
263 |         _loc_advance_slot(fs, &fs->write);
264 |     }
265 |     /* If the sector was full, we're at the beginning of a FREE sector now. */
266 | 
267 |     /* Position the read head at the start of the first IN_USE sector, then skip
268 |      * over garbage/invalid slots until something of value is found or we reach
269 |      * the write head which means there's no data. */
270 |     fs->read.sector = read_sector;
271 |     fs->read.slot = 0;
272 |     while (!_loc_equal(&fs->read, &fs->write)) {
273 |         uint32_t status;
274 |         _slot_get_status(fs, &fs->read, &status);
275 |         if (status == SLOT_VALID)
276 |             break;
277 | 
278 |         _loc_advance_slot(fs, &fs->read);
279 |     }
280 | 
281 |     /* Move the read cursor to the read head position. */
282 |     fs->cursor = fs->read;
283 | 
284 |     return 0;
285 | }
286 | 
287 | int ringfs_capacity(struct ringfs *fs)
288 | {
289 |     return fs->slots_per_sector * (fs->flash->sector_count - 1);
290 | }
291 | 
292 | int ringfs_count_estimate(struct ringfs *fs)
293 | {
294 |     int sector_diff = (fs->write.sector - fs->read.sector + fs->flash->sector_count) %
295 |         fs->flash->sector_count;
296 | 
297 |     return sector_diff * fs->slots_per_sector + fs->write.slot - fs->read.slot;
298 | }
299 | 
300 | int ringfs_count_exact(struct ringfs *fs)
301 | {
302 |     int count = 0;
303 | 
304 |     /* Use a temporary loc for iteration. */
305 |     struct ringfs_loc loc = fs->read;
306 |     while (!_loc_equal(&loc, &fs->write)) {
307 |         uint32_t status;
308 |         _slot_get_status(fs, &loc, &status);
309 |         
310 |         if (status == SLOT_VALID)
311 |             count++;
312 | 
313 |         _loc_advance_slot(fs, &loc);
314 |     }
315 | 
316 |     return count;
317 | }
318 | 
319 | int ringfs_append(struct ringfs *fs, const void *object)
320 | {
321 |     uint32_t status;
322 | 
323 |     /*
324 |      * There are three sectors involved in appending a value:
325 |      * - the sector where the append happens: it has to be writable
326 |      * - the next sector: it must be free (invariant)
327 |      * - the next-next sector: read & cursor heads are moved there if needed
328 |      */
329 | 
330 |     /* Make sure the next sector is free. */
331 |     int next_sector = (fs->write.sector+1) % fs->flash->sector_count;
332 |     _sector_get_status(fs, next_sector, &status);
333 |     if (status != SECTOR_FREE) {
334 |         /* Next sector must be freed. But first... */
335 | 
336 |         /* Move the read & cursor heads out of the way. */
337 |         if (fs->read.sector == next_sector)
338 |             _loc_advance_sector(fs, &fs->read);
339 |         if (fs->cursor.sector == next_sector)
340 |             _loc_advance_sector(fs, &fs->cursor);
341 | 
342 |         /* Free the next sector. */
343 |         _sector_free(fs, next_sector);
344 |     }
345 | 
346 |     /* Now we can make sure the current write sector is writable. */
347 |     _sector_get_status(fs, fs->write.sector, &status);
348 |     if (status == SECTOR_FREE) {
349 |         /* Free sector. Mark as used. */
350 |         _sector_set_status(fs, fs->write.sector, SECTOR_IN_USE);
351 |     } else if (status != SECTOR_IN_USE) {
352 |         printf("ringfs_append: corrupted filesystem\r\n");
353 |         return -1;
354 |     }
355 | 
356 |     /* Preallocate slot. */
357 |     _slot_set_status(fs, &fs->write, SLOT_RESERVED);
358 | 
359 |     /* Write object. */
360 |     fs->flash->program(fs->flash,
361 |             _slot_address(fs, &fs->write) + sizeof(struct slot_header),
362 |             object, fs->object_size);
363 | 
364 |     /* Commit write. */
365 |     _slot_set_status(fs, &fs->write, SLOT_VALID);
366 | 
367 |     /* Advance the write head. */
368 |     _loc_advance_slot(fs, &fs->write);
369 | 
370 |     return 0;
371 | }
372 | 
373 | int ringfs_fetch(struct ringfs *fs, void *object)
374 | {
375 |     /* Advance forward in search of a valid slot. */
376 |     while (!_loc_equal(&fs->cursor, &fs->write)) {
377 |         uint32_t status;
378 | 
379 |         _slot_get_status(fs, &fs->cursor, &status);
380 | 
381 |         if (status == SLOT_VALID) {
382 |             fs->flash->read(fs->flash,
383 |                     _slot_address(fs, &fs->cursor) + sizeof(struct slot_header),
384 |                     object, fs->object_size);
385 |             _loc_advance_slot(fs, &fs->cursor);
386 |             return 0;
387 |         }
388 | 
389 |         _loc_advance_slot(fs, &fs->cursor);
390 |     }
391 | 
392 |     return -1;
393 | }
394 | 
395 | int ringfs_discard(struct ringfs *fs)
396 | {
397 |     while (!_loc_equal(&fs->read, &fs->cursor)) {
398 |         _slot_set_status(fs, &fs->read, SLOT_GARBAGE);
399 |         _loc_advance_slot(fs, &fs->read);
400 |     }
401 | 
402 |     return 0;
403 | }
404 | 
405 | int ringfs_item_discard(struct ringfs *fs)
406 | {
407 |         _slot_set_status(fs, &fs->read, SLOT_GARBAGE);
408 |         _loc_advance_slot(fs, &fs->read);
409 | 
410 |     return 0;
411 | }
412 | 
413 | int ringfs_rewind(struct ringfs *fs)
414 | {
415 |     fs->cursor = fs->read;
416 |     return 0;
417 | }
418 | 
419 | void ringfs_dump(FILE *stream, struct ringfs *fs)
420 | {
421 |     const char *description;
422 | 
423 |     fprintf(stream, "RingFS read: {%d,%d} cursor: {%d,%d} write: {%d,%d}\n",
424 |             fs->read.sector, fs->read.slot,
425 |             fs->cursor.sector, fs->cursor.slot,
426 |             fs->write.sector, fs->write.slot);
427 | 
428 |     for (int sector=0; sector<fs->flash->sector_count; sector++) {
429 |         int addr = _sector_address(fs, sector);
430 | 
431 |         /* Read sector header. */
432 |         struct sector_header header;
433 |         fs->flash->read(fs->flash, addr, &header, sizeof(header));
434 | 
435 |         switch (header.status) {
436 |             case SECTOR_ERASED: description = "ERASED"; break;
437 |             case SECTOR_FREE: description = "FREE"; break;
438 |             case SECTOR_IN_USE: description = "IN_USE"; break;
439 |             case SECTOR_ERASING: description = "ERASING"; break;
440 |             case SECTOR_FORMATTING: description = "FORMATTING"; break;
441 |             default: description = "UNKNOWN"; break;
442 |         }
443 | 
444 |         fprintf(stream, "[%04d] [v=0x%08"PRIx32"] [%-10s] ",
445 |                 sector, header.version, description);
446 | 
447 |         for (int slot=0; slot<fs->slots_per_sector; slot++) {
448 |             struct ringfs_loc loc = { sector, slot };
449 |             uint32_t status;
450 |             _slot_get_status(fs, &loc, &status);
451 | 
452 |             switch (status) {
453 |                 case SLOT_ERASED: description = "E"; break;
454 |                 case SLOT_RESERVED: description = "R"; break;
455 |                 case SLOT_VALID: description = "V"; break;
456 |                 case SLOT_GARBAGE: description = "G"; break;
457 |                 default: description = "?"; break;
458 |             }
459 | 
460 |             fprintf(stream, "%s", description);
461 |         }
462 | 
463 |         fprintf(stream, "\n");
464 |     }
465 | 
466 |     fflush(stream);
467 | }
468 | 
469 | /**
470 |  * @}
471 |  */
472 | 
473 | /* vim: set ts=4 sw=4 et: */
474 | 


--------------------------------------------------------------------------------
/ringfs.h:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
  3 |  * This program is free software. It comes without any warranty, to the extent
  4 |  * permitted by applicable law. You can redistribute it and/or modify it under
  5 |  * the terms of the Do What The Fuck You Want To Public License, Version 2, as
  6 |  * published by Sam Hocevar. See the COPYING file for more details.
  7 |  */
  8 | 
  9 | #ifndef RINGFS_H
 10 | #define RINGFS_H
 11 | 
 12 | /**
 13 |  * @defgroup ringfs_api RingFS API
 14 |  * @{
 15 |  */
 16 | 
 17 | #include <stdint.h>
 18 | #include <stdio.h>
 19 | #include <unistd.h>
 20 | 
 21 | /**
 22 |  * Flash memory+parition descriptor.
 23 |  */
 24 | struct ringfs_flash_partition
 25 | {
 26 |     int sector_size;            /**< Sector size, in bytes. */
 27 |     int sector_offset;          /**< Partition offset, in sectors. */
 28 |     int sector_count;           /**< Partition size, in sectors. */
 29 | 
 30 |     /**
 31 |      * Erase a sector.
 32 |      * @param address Any address inside the sector.
 33 |      * @returns Zero on success, -1 on failure.
 34 |      */
 35 |     int (*sector_erase)(struct ringfs_flash_partition *flash, int address);
 36 |     /**
 37 |      * Program flash memory bits by toggling them from 1 to 0.
 38 |      * @param address Start address, in bytes.
 39 |      * @param data Data to program.
 40 |      * @param size Size of data.
 41 |      * @returns size on success, -1 on failure.
 42 |      */
 43 |     ssize_t (*program)(struct ringfs_flash_partition *flash, int address, const void *data, size_t size);
 44 |     /**
 45 |      * Read flash memory.
 46 |      * @param address Start address, in bytes.
 47 |      * @param data Buffer to store read data.
 48 |      * @param size Size of data.
 49 |      * @returns size on success, -1 on failure.
 50 |      */
 51 |     ssize_t (*read)(struct ringfs_flash_partition *flash, int address, void *data, size_t size);
 52 | };
 53 | 
 54 | /** @private */
 55 | struct ringfs_loc {
 56 |     int sector;
 57 |     int slot;
 58 | };
 59 | 
 60 | /**
 61 |  * RingFS instance. Should be initialized with ringfs_init() befure use.
 62 |  * Structure fields should not be accessed directly.
 63 |  * */
 64 | struct ringfs {
 65 |     /* Constant values, set once at ringfs_init(). */
 66 |     struct ringfs_flash_partition *flash;
 67 |     uint32_t version;
 68 |     int object_size;
 69 |     /* Cached values. */
 70 |     int slots_per_sector;
 71 | 
 72 |     /* Read/write pointers. Modified as needed. */
 73 |     struct ringfs_loc read;
 74 |     struct ringfs_loc write;
 75 |     struct ringfs_loc cursor;
 76 | };
 77 | 
 78 | /**
 79 |  * Initialize a RingFS instance. Must be called before the instance can be used
 80 |  * with the other ringfs_* functions.
 81 |  *
 82 |  * @param fs RingFS instance to be initialized.
 83 |  * @param flash Flash memory interface. Must be implemented externally.
 84 |  * @param version Object version. Should be incremented whenever the object's
 85 |  *                semantics or size change in a backwards-incompatible way.
 86 |  * @param object_size Size of one stored object, in bytes.
 87 |  * @returns Zero on success, -1 on failure.
 88 |  */
 89 | int ringfs_init(struct ringfs *fs, struct ringfs_flash_partition *flash, uint32_t version, int object_size);
 90 | 
 91 | /**
 92 |  * Format the flash memory.
 93 |  *
 94 |  * @param fs Initialized RingFS instance.
 95 |  * @returns Zero on success, -1 on failure.
 96 |  */
 97 | int ringfs_format(struct ringfs *fs);
 98 | 
 99 | /**
100 |  * Scan the flash memory for a valid filesystem.
101 |  *
102 |  * @param fs Initialized RingFS instance.
103 |  * @returns Zero on success, -1 on failure.
104 |  */
105 | int ringfs_scan(struct ringfs *fs);
106 | 
107 | /**
108 |  * Calculate maximum RingFS capacity.
109 |  *
110 |  * @param fs Initialized RingFS instance.
111 |  * @returns Maximum capacity on success, -1 on failure.
112 |  */
113 | int ringfs_capacity(struct ringfs *fs);
114 | 
115 | /**
116 |  * Calculate approximate object count.
117 |  * Runs in O(1).
118 |  *
119 |  * @param fs Initialized RingFS instance.
120 |  * @returns Estimated object count on success, -1 on failure.
121 |  */
122 | int ringfs_count_estimate(struct ringfs *fs);
123 | 
124 | /**
125 |  * Calculate exact object count.
126 |  * Runs in O(n).
127 |  *
128 |  * @param fs Initialized RingFS instance.
129 |  * @returns Exact object count on success, -1 on failure.
130 |  */
131 | int ringfs_count_exact(struct ringfs *fs);
132 | 
133 | /**
134 |  * Append an object at the end of the ring. Deletes oldest objects as needed.
135 |  *
136 |  * @param fs Initialized RingFS instance.
137 |  * @param object Object to be stored.
138 |  * @returns Zero on success, -1 on failure.
139 |  */
140 | int ringfs_append(struct ringfs *fs, const void *object);
141 | 
142 | /**
143 |  * Fetch next object from the ring, oldest-first. Advances read cursor.
144 |  *
145 |  * @param fs Initialized RingFS instance.
146 |  * @param object Buffer to store retrieved object.
147 |  * @returns Zero on success, -1 on failure.
148 |  */
149 | int ringfs_fetch(struct ringfs *fs, void *object);
150 | 
151 | /**
152 |  * Discard all fetched objects up to the read cursor.
153 |  *
154 |  * @param fs Initialized RingFS instance.
155 |  * @returns Zero on success, -1 on failure.
156 |  */
157 | int ringfs_discard(struct ringfs *fs);
158 | 
159 | int ringfs_item_discard(struct ringfs *fs);
160 | 
161 | /**
162 |  * Rewind the read cursor back to the oldest object.
163 |  *
164 |  * @param fs Initialized RingFS instance.
165 |  * @returns Zero on success, -1 on failure.
166 |  */
167 | int ringfs_rewind(struct ringfs *fs);
168 | 
169 | /**
170 |  * Dump filesystem metadata. For debugging purposes.
171 |  * @param stream File stream to write to.
172 |  * @param fs Initialized RingFS instance.
173 |  */
174 | void ringfs_dump(FILE *stream, struct ringfs *fs);
175 | 
176 | /**
177 |  * @}
178 |  */
179 | 
180 | #endif
181 | 
182 | /* vim: set ts=4 sw=4 et: */
183 | 


--------------------------------------------------------------------------------
/tests/flashsim.c:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
  3 |  * This program is free software. It comes without any warranty, to the extent
  4 |  * permitted by applicable law. You can redistribute it and/or modify it under
  5 |  * the terms of the Do What The Fuck You Want To Public License, Version 2, as
  6 |  * published by Sam Hocevar. See the COPYING file for more details.
  7 |  */
  8 | 
  9 | #include "flashsim.h"
 10 | 
 11 | #include <stdio.h>
 12 | #include <string.h>
 13 | #include <unistd.h>
 14 | #include <stdlib.h>
 15 | #include <assert.h>
 16 | 
 17 | #ifdef FLASHSIM_LOG
 18 | #define logprintf(args...) printf(args)
 19 | #else
 20 | #define logprintf(args...) do {} while (0)
 21 | #endif
 22 | 
 23 | struct flashsim {
 24 |     int size;
 25 |     int sector_size;
 26 | 
 27 |     FILE *fh;
 28 | };
 29 | 
 30 | struct flashsim *flashsim_open(const char *name, int size, int sector_size)
 31 | {
 32 |     struct flashsim *sim = malloc(sizeof(struct flashsim));
 33 | 
 34 |     sim->size = size;
 35 |     sim->sector_size = sector_size;
 36 |     sim->fh = fopen(name, "w+");
 37 |     assert(sim->fh != NULL);
 38 |     assert(ftruncate(fileno(sim->fh), size) == 0);
 39 | 
 40 |     return sim;
 41 | }
 42 | 
 43 | void flashsim_close(struct flashsim *sim)
 44 | {
 45 |     fclose(sim->fh);
 46 |     free(sim);
 47 | }
 48 | 
 49 | void flashsim_sector_erase(struct flashsim *sim, int addr)
 50 | {
 51 |     int sector_start = addr - (addr % sim->sector_size);
 52 |     logprintf("flashsim_erase  (0x%08x) * erasing sector at 0x%08x\n", addr, sector_start);
 53 | 
 54 |     void *empty = malloc(sim->sector_size);
 55 |     memset(empty, 0xff, sim->sector_size);
 56 | 
 57 |     assert(fseek(sim->fh, sector_start, SEEK_SET) == 0);
 58 |     assert(fwrite(empty, 1, sim->sector_size, sim->fh) == (size_t) sim->sector_size);
 59 | 
 60 |     free(empty);
 61 | }
 62 | 
 63 | void flashsim_read(struct flashsim *sim, int addr, uint8_t *buf, int len)
 64 | {
 65 |     assert(fseek(sim->fh, addr, SEEK_SET) == 0);
 66 |     assert(fread(buf, 1, len, sim->fh) == (size_t) len);
 67 | 
 68 |     logprintf("flashsim_read   (0x%08x) = %d bytes [ ", addr, len);
 69 |     for (int i=0; i<len; i++) {
 70 |         logprintf("%02x ", buf[i]);
 71 |         if (i == 15) {
 72 |             logprintf("... ");
 73 |             break;
 74 |         }
 75 |     }
 76 |     logprintf("]\n");
 77 | }
 78 | 
 79 | void flashsim_program(struct flashsim *sim, int addr, const uint8_t *buf, int len)
 80 | {
 81 |     logprintf("flashsim_program(0x%08x) + %d bytes [ ", addr, len);
 82 |     for (int i=0; i<len; i++) {
 83 |         logprintf("%02x ", buf[i]);
 84 |         if (i == 15) {
 85 |             logprintf("... ");
 86 |             break;
 87 |         }
 88 |     }
 89 |     logprintf("]\n");
 90 | 
 91 |     uint8_t *data = malloc(len);
 92 | 
 93 |     assert(fseek(sim->fh, addr, SEEK_SET) == 0);
 94 |     assert(fread(data, 1, len, sim->fh) == (size_t) len);
 95 | 
 96 |     for (int i=0; i<(int) len; i++)
 97 |         data[i] &= buf[i];
 98 | 
 99 |     assert(fseek(sim->fh, addr, SEEK_SET) == 0);
100 |     assert(fwrite(data, 1, len, sim->fh) == (size_t) len);
101 | 
102 |     free(data);
103 | }
104 | 
105 | /* vim: set ts=4 sw=4 et: */
106 | 


--------------------------------------------------------------------------------
/tests/flashsim.h:
--------------------------------------------------------------------------------
 1 | /*
 2 |  * Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
 3 |  * This program is free software. It comes without any warranty, to the extent
 4 |  * permitted by applicable law. You can redistribute it and/or modify it under
 5 |  * the terms of the Do What The Fuck You Want To Public License, Version 2, as
 6 |  * published by Sam Hocevar. See the COPYING file for more details.
 7 |  */
 8 | 
 9 | #ifndef FLASHSIM_H
10 | #define FLASHSIM_H
11 | 
12 | #include <stdint.h>
13 | #include <unistd.h>
14 | 
15 | struct flashsim;
16 | 
17 | struct flashsim *flashsim_open(const char *name, int size, int sector_size);
18 | void flashsim_close(struct flashsim *sim);
19 | 
20 | void flashsim_sector_erase(struct flashsim *sim, int addr);
21 | void flashsim_read(struct flashsim *sim, int addr, uint8_t *buf, int len);
22 | void flashsim_program(struct flashsim *sim, int addr, const uint8_t *buf, int len);
23 | 
24 | #endif
25 | 
26 | /* vim: set ts=4 sw=4 et: */
27 | 


--------------------------------------------------------------------------------
/tests/fuzzer.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | # -*- coding: utf-8 -*-
 3 | 
 4 | import random
 5 | 
 6 | from pyflashsim import FlashSim
 7 | from pyringfs import RingFSFlashPartition, RingFS
 8 | 
 9 | 
10 | def compare(a, b):
11 |     if a != b:
12 |         print ">>> %s != %s" % (a, b)
13 |     return a == b
14 | 
15 | 
16 | class FuzzRun(object):
17 | 
18 |     def __init__(self, name, version, object_size, sector_size, total_sectors, sector_offset, sector_count):
19 | 
20 |         print "FuzzRun[%s]: v=%08x os=%d ss=%d ts=%d so=%d sc=%d" % (name, version, object_size, sector_size,
21 |                 total_sectors, sector_offset, sector_count)
22 | 
23 |         sim = FlashSim(name, total_sectors*sector_size, sector_size)
24 | 
25 |         def op_sector_erase(flash, address):
26 |             sim.sector_erase(address)
27 |             return 0
28 | 
29 |         def op_program(flash, address, data):
30 |             sim.program(address, data)
31 |             return len(data)
32 | 
33 |         def op_read(flash, address, size):
34 |             return sim.read(address, size)
35 | 
36 |         self.version = version
37 |         self.object_size = object_size
38 | 
39 |         self.flash = RingFSFlashPartition(sector_size, sector_offset, sector_count,
40 |                 op_sector_erase, op_program, op_read)
41 |         self.fs = RingFS(self.flash, self.version, self.object_size)
42 | 
43 |     def run(self):
44 | 
45 |         self.fs.format()
46 |         self.fs.dump()
47 | 
48 |         def do_append():
49 |             self.fs.append('x'*self.object_size)
50 | 
51 |         def do_fetch():
52 |             self.fs.fetch()
53 | 
54 |         def do_rewind():
55 |             self.fs.rewind()
56 | 
57 |         def do_discard():
58 |             self.fs.discard()
59 | 
60 |         for i in xrange(1000):
61 |             fun = random.choice([do_append]*100 + [do_fetch]*100 + [do_rewind]*10 + [do_discard]*10)
62 |             print i, fun.__name__
63 |             fun()
64 | 
65 |             # consistency check
66 |             newfs = RingFS(self.flash, self.version, self.object_size)
67 |             try:
68 |                 assert newfs.scan() == 0
69 |                 assert compare(newfs.ringfs.read.sector, self.fs.ringfs.read.sector)
70 |                 assert compare(newfs.ringfs.read.slot, self.fs.ringfs.read.slot)
71 |                 assert compare(newfs.ringfs.write.sector, self.fs.ringfs.write.sector)
72 |                 assert compare(newfs.ringfs.write.slot, self.fs.ringfs.write.slot)
73 |             except AssertionError:
74 |                 print "self.fs:"
75 |                 self.fs.dump()
76 |                 print "newfs:"
77 |                 newfs.dump()
78 |                 raise
79 | 
80 | 
81 | sector_size = random.randint(16, 256)
82 | total_sectors = random.randint(2, 8)
83 | sector_offset = random.randint(0, total_sectors-2)
84 | sector_count = random.randint(2, total_sectors-sector_offset)
85 | version = random.randint(0, 0xffffffff)
86 | object_size = random.randint(1, sector_size-8)
87 | 
88 | f = FuzzRun('tests/fuzzer.sim', version, object_size, sector_size, total_sectors, sector_offset, sector_count)
89 | f.run()
90 | 


--------------------------------------------------------------------------------
/tests/pyflashsim.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | # -*- coding: utf-8 -*-
 3 | 
 4 | import os
 5 | import sys
 6 | from sharedlibrary import GenericLibrary
 7 | from ctypes import *
 8 | 
 9 | 
10 | class libflashsim(GenericLibrary):
11 |     dllname = 'tests/flashsim.so'
12 |     functions = [
13 |         ['flashsim_open', [c_char_p, c_int, c_int], c_void_p],
14 |         ['flashsim_sector_erase', [c_void_p, c_int], None],
15 |         ['flashsim_read', [c_void_p, c_int, c_void_p, c_int], None],
16 |         ['flashsim_program', [c_void_p, c_int, c_void_p, c_int], None],
17 |         ['flashsim_close', [c_void_p], None],
18 |     ]
19 | 
20 | 
21 | class FlashSim(object):
22 | 
23 |     def __init__(self, name, size, sector_size):
24 |         self.libflashsim = libflashsim()
25 |         self.sim = self.libflashsim.flashsim_open(name ,size, sector_size)
26 | 
27 |     def sector_erase(self, addr):
28 |         self.libflashsim.flashsim_sector_erase(self.sim, addr)
29 | 
30 |     def read(self, addr, size):
31 |         buf = create_string_buffer(size)
32 |         self.libflashsim.flashsim_read(self.sim, addr, buf, size)
33 |         return buf.raw
34 | 
35 |     def program(self, addr, data):
36 |         self.libflashsim.flashsim_program(self.sim, addr, data, len(data))
37 | 
38 |     def __del__(self):
39 |         self.libflashsim.flashsim_close(self.sim)
40 | 


--------------------------------------------------------------------------------
/tests/pyringfs.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python
  2 | # -*- coding: utf-8 -*-
  3 | 
  4 | import os
  5 | import sys
  6 | from sharedlibrary import GenericLibrary
  7 | from ctypes import *
  8 | 
  9 | 
 10 | # forward declaration
 11 | class StructRingFSFlashPartition(Structure):
 12 |     pass
 13 | 
 14 | op_sector_erase_t = CFUNCTYPE(c_int, POINTER(StructRingFSFlashPartition), c_int)
 15 | op_program_t = CFUNCTYPE(c_ssize_t, POINTER(StructRingFSFlashPartition), c_int, c_void_p, c_size_t)
 16 | op_read_t = CFUNCTYPE(c_ssize_t, POINTER(StructRingFSFlashPartition), c_int, c_void_p, c_size_t)
 17 | 
 18 | StructRingFSFlashPartition._fields_ = [
 19 |     ('sector_size', c_int),
 20 |     ('sector_offset', c_int),
 21 |     ('sector_count', c_int),
 22 | 
 23 |     ('sector_erase', op_sector_erase_t),
 24 |     ('program', op_program_t),
 25 |     ('read', op_read_t),
 26 | ]
 27 | 
 28 | class StructRingFSLoc(Structure):
 29 |     _fields_ = [
 30 |         ('sector', c_int),
 31 |         ('slot', c_int),
 32 |     ]
 33 | 
 34 | class StructRingFS(Structure):
 35 |     _fields_ = [
 36 |         ('flash', POINTER(StructRingFSFlashPartition)),
 37 |         ('version', c_uint32),
 38 |         ('object_size', c_int),
 39 |         ('slots_per_sector', c_int),
 40 | 
 41 |         ('read', StructRingFSLoc),
 42 |         ('write', StructRingFSLoc),
 43 |         ('cursor', StructRingFSLoc),
 44 |     ]
 45 | 
 46 | 
 47 | class libringfs(GenericLibrary):
 48 |     dllname = './ringfs.so'
 49 |     functions = [
 50 |         ['ringfs_init', [POINTER(StructRingFS), POINTER(StructRingFSFlashPartition), c_uint32, c_int], c_int],
 51 |         ['ringfs_format', [POINTER(StructRingFS)], c_int],
 52 |         ['ringfs_scan', [POINTER(StructRingFS)], c_int],
 53 |         ['ringfs_capacity', [POINTER(StructRingFS)], c_int],
 54 |         ['ringfs_count_estimate', [POINTER(StructRingFS)], c_int],
 55 |         ['ringfs_count_exact', [POINTER(StructRingFS)], c_int],
 56 |         ['ringfs_append', [POINTER(StructRingFS), c_void_p], c_int],
 57 |         ['ringfs_fetch', [POINTER(StructRingFS), c_void_p], c_int],
 58 |         ['ringfs_discard', [POINTER(StructRingFS)], c_int],
 59 |         ['ringfs_rewind', [POINTER(StructRingFS)], c_int],
 60 |         ['ringfs_dump', [c_void_p, POINTER(StructRingFS)], None],
 61 |     ]
 62 | 
 63 | 
 64 | class RingFSFlashPartition(object):
 65 | 
 66 |     def __init__(self, sector_size, sector_offset, sector_count, sector_erase, program, read):
 67 | 
 68 |         def op_sector_erase(flash, address):
 69 |             sector_erase(flash, address)
 70 |             return 0
 71 | 
 72 |         def op_program(flash, address, data, size):
 73 |             program(flash, address, string_at(data, size))
 74 |             return size
 75 | 
 76 |         def op_read(flash, address, buf, size):
 77 |             data = read(flash, address, size)
 78 |             memmove(buf, data, size)
 79 |             return size
 80 | 
 81 |         self.struct = StructRingFSFlashPartition(sector_size, sector_offset, sector_count,
 82 |                 op_sector_erase_t(op_sector_erase),
 83 |                 op_program_t(op_program),
 84 |                 op_read_t(op_read))
 85 | 
 86 | 
 87 | class RingFS(object):
 88 | 
 89 |     def __init__(self, flash, version, object_size):
 90 |         self.libringfs = libringfs()
 91 |         self.ringfs = StructRingFS()
 92 |         self.flash = flash.struct
 93 |         self.libringfs.ringfs_init(byref(self.ringfs), byref(self.flash), version, object_size)
 94 |         self.object_size = object_size
 95 | 
 96 |     def format(self):
 97 |         self.libringfs.ringfs_format(byref(self.ringfs))
 98 | 
 99 |     def scan(self):
100 |         return self.libringfs.ringfs_scan(byref(self.ringfs))
101 | 
102 |     def capacity(self):
103 |         return self.libringfs.ringfs_capacity(byref(self.ringfs))
104 | 
105 |     def count_estimate(self):
106 |         return self.libringfs.ringfs_count_estimate(byref(self.ringfs))
107 | 
108 |     def count_exact(self):
109 |         return self.libringfs.ringfs_count_exact(byref(self.ringfs))
110 | 
111 |     def append(self, obj):
112 |         self.libringfs.ringfs_append(byref(self.ringfs), obj)
113 | 
114 |     def fetch(self):
115 |         obj = create_string_buffer(self.object_size)
116 |         self.libringfs.ringfs_append(byref(self.ringfs), obj)
117 |         return obj.raw
118 | 
119 |     def discard(self):
120 |         self.libringfs.ringfs_discard(byref(self.ringfs))
121 | 
122 |     def rewind(self):
123 |         self.libringfs.ringfs_rewind(byref(self.ringfs))
124 | 
125 |     def dump(self):
126 |         import ctypes
127 |         ctypes.pythonapi.PyFile_AsFile.argtypes= [ ctypes.py_object ]
128 |         ctypes.pythonapi.PyFile_AsFile.restype= ctypes.c_void_p
129 |         cstdout = ctypes.pythonapi.PyFile_AsFile(sys.stdout)
130 |         self.libringfs.ringfs_dump(cstdout, byref(self.ringfs))
131 | 
132 | __all__ = [
133 |     'StructRingFSFlashPartition',
134 |     'RingFS',
135 | ]
136 | 


--------------------------------------------------------------------------------
/tests/sharedlibrary.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | # -*- coding: utf-8 -*-
 3 | 
 4 | from ctypes import CDLL
 5 | 
 6 | class GenericLibrary(CDLL):
 7 | 
 8 |     def __init__(self, *args, **kwargs):
 9 |         super(GenericLibrary, self).__init__(self.dllname, *args, **kwargs)
10 | 
11 |         for name, argtypes, restype in self.functions:
12 |             getattr(self, name).argtypes = argtypes
13 |             getattr(self, name).restype = restype
14 | 


--------------------------------------------------------------------------------
/tests/tests.c:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
  3 |  * This program is free software. It comes without any warranty, to the extent
  4 |  * permitted by applicable law. You can redistribute it and/or modify it under
  5 |  * the terms of the Do What The Fuck You Want To Public License, Version 2, as
  6 |  * published by Sam Hocevar. See the COPYING file for more details.
  7 |  */
  8 | 
  9 | #pragma GCC diagnostic ignored "-Wmissing-field-initializers"
 10 | 
 11 | #include <stdio.h>
 12 | #include <stdlib.h>
 13 | #include <stdbool.h>
 14 | #include <string.h>
 15 | #include <check.h>
 16 | 
 17 | #include "ringfs.h"
 18 | #include "flashsim.h"
 19 | 
 20 | /* Flashsim tests. */
 21 | 
 22 | START_TEST(test_flashsim)
 23 | {
 24 |     printf("# test_flashsim\n");
 25 | 
 26 |     struct flashsim *smallsim = flashsim_open("tests/test.sim", 1024, 16);
 27 |     uint8_t buf[48];
 28 |     uint8_t data[16];
 29 | 
 30 |     flashsim_sector_erase(smallsim, 0);
 31 |     flashsim_sector_erase(smallsim, 16);
 32 |     flashsim_sector_erase(smallsim, 32);
 33 | 
 34 |     memset(data, 0x5a, 16);
 35 |     flashsim_program(smallsim, 16, data, 16);
 36 | 
 37 |     flashsim_read(smallsim, 0, buf, 48);
 38 |     for (int i=0; i<16; i++)
 39 |         ck_assert_int_eq(buf[i], 0xff);
 40 |     for (int i=16; i<32; i++)
 41 |         ck_assert_int_eq(buf[i], 0x5a);
 42 |     for (int i=32; i<48; i++)
 43 |         ck_assert_int_eq(buf[i], 0xff);
 44 | 
 45 |     memset(data, 0x01, 16);
 46 |     flashsim_program(smallsim, 0, data, 16);
 47 |     memset(data, 0x10, 16);
 48 |     flashsim_program(smallsim, 32, data, 16);
 49 |     flashsim_sector_erase(smallsim, 16);
 50 | 
 51 |     flashsim_read(smallsim, 0, buf, 48);
 52 |     for (int i=0; i<16; i++)
 53 |         ck_assert_int_eq(buf[i], 0x01);
 54 |     for (int i=16; i<32; i++)
 55 |         ck_assert_int_eq(buf[i], 0xff);
 56 |     for (int i=32; i<48; i++)
 57 |         ck_assert_int_eq(buf[i], 0x10);
 58 | 
 59 |     free(smallsim);
 60 | }
 61 | END_TEST
 62 | 
 63 | /* Flash simulator + MTD partition fixture. */
 64 | 
 65 | static struct flashsim *sim;
 66 | 
 67 | static int op_sector_erase(struct ringfs_flash_partition *flash, int address)
 68 | {
 69 |     (void) flash;
 70 |     flashsim_sector_erase(sim, address);
 71 |     return 0;
 72 | }
 73 | 
 74 | static ssize_t op_program(struct ringfs_flash_partition *flash, int address, const void *data, size_t size)
 75 | {
 76 |     (void) flash;
 77 |     flashsim_program(sim, address, data, size);
 78 |     return size;
 79 | }
 80 | 
 81 | static ssize_t op_read(struct ringfs_flash_partition *flash, int address, void *data, size_t size)
 82 | {
 83 |     (void) flash;
 84 |     flashsim_read(sim, address, data, size);
 85 |     return size;
 86 | }
 87 | 
 88 | /*
 89 |  * A really small filesystem: 3 slots per sector, 15 slots total.
 90 |  * Has the benefit of causing frequent wraparounds, potentially finding
 91 |  * more bugs.
 92 |  */
 93 | static struct ringfs_flash_partition flash = {
 94 |     .sector_size = 32,
 95 |     .sector_offset = 4,
 96 |     .sector_count = 6,
 97 | 
 98 |     .sector_erase = op_sector_erase,
 99 |     .program = op_program,
100 |     .read = op_read,
101 | };
102 | 
103 | static void fixture_flashsim_setup(void)
104 | {
105 |     sim = flashsim_open("tests/ringfs.sim",
106 |             flash.sector_size * (flash.sector_offset + flash.sector_count),
107 |             flash.sector_size);
108 | }
109 | 
110 | static void fixture_flashsim_teardown(void)
111 | {
112 |     flashsim_close(sim);
113 |     sim = NULL;
114 | }
115 | 
116 | /* RingFS tests. */
117 | 
118 | #define DEFAULT_VERSION 0x000000042
119 | typedef int object_t;
120 | #define SECTOR_HEADER_SIZE 8
121 | #define SLOT_HEADER_SIZE 4
122 | 
123 | static void assert_loc_equiv_to_offset(const struct ringfs *fs, const struct ringfs_loc *loc, int offset)
124 | {
125 |     int loc_offset = loc->sector * fs->slots_per_sector + loc->slot;
126 |     ck_assert_int_eq(offset, loc_offset);
127 | }
128 | 
129 | static void assert_scan_integrity(const struct ringfs *fs)
130 | {
131 |     struct ringfs newfs;
132 |     ringfs_init(&newfs, fs->flash, fs->version, fs->object_size);
133 |     ck_assert(ringfs_scan(&newfs) == 0);
134 |     ck_assert_int_eq(newfs.read.sector, fs->read.sector);
135 |     ck_assert_int_eq(newfs.read.slot, fs->read.slot);
136 |     ck_assert_int_eq(newfs.write.sector, fs->write.sector);
137 |     ck_assert_int_eq(newfs.write.slot, fs->write.slot);
138 | }
139 | 
140 | START_TEST(test_ringfs_format)
141 | {
142 |     printf("# test_ringfs_format\n");
143 | 
144 |     struct ringfs fs1;
145 |     printf("## ringfs_init()\n");
146 |     ringfs_init(&fs1, &flash, DEFAULT_VERSION, sizeof(object_t));
147 |     printf("## ringfs_format()\n");
148 |     ringfs_format(&fs1);
149 | }
150 | END_TEST
151 | 
152 | START_TEST(test_ringfs_scan)
153 | {
154 |     printf("# test_ringfs_scan\n");
155 | 
156 |     /* first format a filesystem */
157 |     struct ringfs fs1;
158 |     printf("## ringfs_init()\n");
159 |     ringfs_init(&fs1, &flash, DEFAULT_VERSION, sizeof(object_t));
160 |     printf("## ringfs_format()\n");
161 |     ringfs_format(&fs1);
162 | 
163 |     /* now try to scan it */
164 |     struct ringfs fs2;
165 |     printf("## ringfs_init()\n");
166 |     ringfs_init(&fs2, &flash, DEFAULT_VERSION, sizeof(object_t));
167 |     printf("## ringfs_scan()\n");
168 |     ck_assert(ringfs_scan(&fs2) == 0);
169 | 
170 |     /* this is an empty FS, should start with this: */
171 |     ck_assert_int_eq(fs2.slots_per_sector, (flash.sector_size-SECTOR_HEADER_SIZE)/(SLOT_HEADER_SIZE+sizeof(object_t)));
172 |     assert_loc_equiv_to_offset(&fs2, &fs2.read, 0);
173 |     assert_loc_equiv_to_offset(&fs2, &fs2.cursor, 0);
174 |     assert_loc_equiv_to_offset(&fs2, &fs2.write, 0);
175 | 
176 |     /* now insert some objects */
177 |     ck_assert(ringfs_append(&fs2, (int[]) { 0x11 }) == 0);
178 |     ck_assert(ringfs_append(&fs2, (int[]) { 0x22 }) == 0);
179 |     ck_assert(ringfs_append(&fs2, (int[]) { 0x33 }) == 0);
180 | 
181 |     /* rescan */
182 |     printf("## ringfs_scan()\n");
183 |     ck_assert(ringfs_scan(&fs2) == 0);
184 | 
185 |     /* make sure the objects are there */
186 |     ck_assert(ringfs_count_exact(&fs2) == 3);
187 | 
188 |     /* scan should fail if we supply a different version */
189 |     struct ringfs fs3;
190 |     printf("## ringfs_init()\n");
191 |     ringfs_init(&fs3, &flash, DEFAULT_VERSION+1, sizeof(object_t));
192 |     printf("## ringfs_scan()\n");
193 |     ck_assert(ringfs_scan(&fs3) != 0);
194 | }
195 | END_TEST
196 | 
197 | START_TEST(test_ringfs_append)
198 | {
199 |     printf("# test_ringfs_append\n");
200 | 
201 |     /* first format a filesystem */
202 |     int obj;
203 |     struct ringfs fs;
204 |     printf("## ringfs_init()\n");
205 |     ringfs_init(&fs, &flash, DEFAULT_VERSION, sizeof(object_t));
206 |     printf("## ringfs_format()\n");
207 |     ringfs_format(&fs);
208 | 
209 |     /* fetches before appends should not change anything */
210 |     for (int i=0; i<3; i++) {
211 |         printf("## ringfs_fetch()\n");
212 |         ck_assert(ringfs_fetch(&fs, &obj) < 0);
213 |     }
214 |     assert_loc_equiv_to_offset(&fs, &fs.read, 0);
215 |     assert_loc_equiv_to_offset(&fs, &fs.write, 0);
216 |     assert_loc_equiv_to_offset(&fs, &fs.cursor, 0);
217 |     assert_scan_integrity(&fs);
218 | 
219 |     /* now we're brave and we write some data */
220 |     for (int i=0; i<3; i++) {
221 |         printf("## ringfs_append()\n");
222 |         ringfs_append(&fs, (int[]) { 0x11*(i+1) });
223 | 
224 |         /* make sure the write head has advanced */
225 |         assert_loc_equiv_to_offset(&fs, &fs.write, i+1);
226 |         assert_scan_integrity(&fs);
227 |     }
228 | 
229 |     /* now we fetch at it. */
230 |     for (int i=0; i<3; i++) {
231 |         printf("## ringfs_fetch()\n");
232 |         ck_assert(ringfs_fetch(&fs, &obj) == 0);
233 |         ck_assert_int_eq(obj, 0x11*(i+1));
234 | 
235 |         /* make sure the cursor head has advanced */
236 |         assert_loc_equiv_to_offset(&fs, &fs.cursor, i+1);
237 |     }
238 |     /* there should be no data left */
239 |     ck_assert(ringfs_fetch(&fs, &obj) < 0);
240 | 
241 |     /* test the rewind. */
242 |     ck_assert(ringfs_rewind(&fs) == 0);
243 |     assert_loc_equiv_to_offset(&fs, &fs.cursor, 0);
244 | 
245 |     /* try to read the objects once again. */
246 |     for (int i=0; i<3; i++) {
247 |         printf("## ringfs_fetch()\n");
248 |         ck_assert(ringfs_fetch(&fs, &obj) == 0);
249 |         ck_assert_int_eq(obj, 0x11*(i+1));
250 |     }
251 | }
252 | END_TEST
253 | 
254 | START_TEST(test_ringfs_discard)
255 | {
256 |     printf("# test_ringfs_discard\n");
257 | 
258 |     struct ringfs fs;
259 |     printf("## ringfs_init()\n");
260 |     ringfs_init(&fs, &flash, DEFAULT_VERSION, sizeof(object_t));
261 |     printf("## ringfs_format()\n");
262 |     ringfs_format(&fs);
263 | 
264 |     /* write some records */
265 |     for (int i=0; i<4; i++) {
266 |         printf("## ringfs_append()\n");
267 |         ringfs_append(&fs, (int[]) { 0x11*(i+1) });
268 |         assert_scan_integrity(&fs);
269 |     }
270 |     /* read some of them */
271 |     int obj;
272 |     for (int i=0; i<2; i++) {
273 |         printf("## ringfs_fetch()\n");
274 |         ck_assert(ringfs_fetch(&fs, &obj) == 0);
275 |         ck_assert_int_eq(obj, 0x11*(i+1));
276 |     }
277 |     /* discard whatever was read */
278 |     ck_assert(ringfs_discard(&fs) == 0);
279 |     assert_scan_integrity(&fs);
280 |     /* make sure we're consistent */
281 |     assert_loc_equiv_to_offset(&fs, &fs.read, 2);
282 |     assert_loc_equiv_to_offset(&fs, &fs.cursor, 2);
283 |     assert_loc_equiv_to_offset(&fs, &fs.write, 4);
284 | 
285 |     /* read the rest of the records */
286 |     for (int i=2; i<4; i++) {
287 |         printf("## ringfs_fetch()\n");
288 |         ck_assert(ringfs_fetch(&fs, &obj) == 0);
289 |         ck_assert_int_eq(obj, 0x11*(i+1));
290 |     }
291 |     /* discard them */
292 |     ck_assert(ringfs_discard(&fs) == 0);
293 |     assert_loc_equiv_to_offset(&fs, &fs.read, 4);
294 |     assert_loc_equiv_to_offset(&fs, &fs.cursor, 4);
295 |     assert_loc_equiv_to_offset(&fs, &fs.write, 4);
296 |     assert_scan_integrity(&fs);
297 | }
298 | END_TEST
299 | 
300 | START_TEST(test_ringfs_capacity)
301 | {
302 |     printf("# test_ringfs_capacity\n");
303 | 
304 |     struct ringfs fs;
305 |     ringfs_init(&fs, &flash, DEFAULT_VERSION, sizeof(object_t));
306 | 
307 |     int slots_per_sector = (flash.sector_size-SECTOR_HEADER_SIZE)/(SLOT_HEADER_SIZE+sizeof(object_t));
308 |     int sectors = flash.sector_count;
309 |     ck_assert_int_eq(ringfs_capacity(&fs), (sectors-1) * slots_per_sector);
310 | }
311 | END_TEST
312 | 
313 | START_TEST(test_ringfs_count)
314 | {
315 |     printf("# test_ringfs_count\n");
316 | 
317 |     int obj;
318 |     struct ringfs fs;
319 |     ringfs_init(&fs, &flash, DEFAULT_VERSION, sizeof(object_t));
320 |     ringfs_format(&fs);
321 |     ck_assert(ringfs_count_exact(&fs) == 0);
322 | 
323 |     printf("## write some records\n");
324 |     for (int i=0; i<10; i++)
325 |         ringfs_append(&fs, (int[]) { 0x11*(i+1) });
326 |     ck_assert_int_eq(ringfs_count_exact(&fs), 10);
327 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 10);
328 | 
329 |     printf("## rescan\n");
330 |     ck_assert(ringfs_scan(&fs) == 0);
331 |     ck_assert_int_eq(ringfs_count_exact(&fs), 10);
332 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 10);
333 | 
334 |     printf("## append more records\n");
335 |     for (int i=10; i<13; i++)
336 |         ringfs_append(&fs, (int[]) { 0x11*(i+1) });
337 |     ck_assert_int_eq(ringfs_count_exact(&fs), 13);
338 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 13);
339 | 
340 |     printf("## fetch some objects without discard\n");
341 |     for (int i=0; i<4; i++) {
342 |         ck_assert(ringfs_fetch(&fs, &obj) == 0);
343 |         ck_assert_int_eq(obj, 0x11*(i+1));
344 |     }
345 |     ck_assert_int_eq(ringfs_count_exact(&fs), 13);
346 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 13);
347 | 
348 |     printf("## rescan\n");
349 |     ck_assert(ringfs_scan(&fs) == 0);
350 |     ck_assert_int_eq(ringfs_count_exact(&fs), 13);
351 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 13);
352 | 
353 |     printf("## fetch some objects with discard\n");
354 |     for (int i=0; i<4; i++) {
355 |         ck_assert(ringfs_fetch(&fs, &obj) == 0);
356 |         ck_assert_int_eq(obj, 0x11*(i+1));
357 |     }
358 |     ck_assert_int_eq(ringfs_count_exact(&fs), 13);
359 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 13);
360 |     ck_assert(ringfs_discard(&fs) == 0);
361 |     ck_assert_int_eq(ringfs_count_exact(&fs), 9);
362 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 9);
363 | 
364 |     printf("## fill the segment\n");
365 |     int count = fs.slots_per_sector - 1;
366 |     for (int i=0; i<count; i++)
367 |         ringfs_append(&fs, (int[]) { 0x42 });
368 |     ck_assert_int_eq(ringfs_count_exact(&fs), 9+count);
369 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 9+count);
370 | 
371 |     printf("## extra synthetic tests for estimation\n");
372 |     /* wrapping around */
373 |     fs.read = (struct ringfs_loc) { fs.flash->sector_count - 1, fs.slots_per_sector - 1 };
374 |     fs.write = (struct ringfs_loc) { 0, 0 };
375 |     ck_assert_int_eq(ringfs_count_estimate(&fs), 1);
376 | }
377 | END_TEST
378 | 
379 | START_TEST(test_ringfs_overflow)
380 | {
381 |     printf("# test_ringfs_overflow\n");
382 | 
383 |     printf("## format\n");
384 |     struct ringfs fs;
385 |     ringfs_init(&fs, &flash, DEFAULT_VERSION, sizeof(object_t));
386 |     ringfs_format(&fs);
387 | 
388 |     int capacity = ringfs_capacity(&fs);
389 | 
390 |     printf("## fill filesystem to the brim\n");
391 |     for (int i=0; i<capacity; i++)
392 |         ringfs_append(&fs, (int[]) { i });
393 |     ck_assert_int_eq(ringfs_count_exact(&fs), capacity);
394 |     assert_scan_integrity(&fs);
395 | 
396 |     /* won't hurt to stress it a little bit! */
397 |     for (int round=0; round<3; round++) {
398 |         printf("## add one more object\n");
399 |         ringfs_append(&fs, (int[]) { 0x42 });
400 |         /* should kill one entire sector to make space */
401 |         ck_assert_int_eq(ringfs_count_exact(&fs), capacity - fs.slots_per_sector + 1);
402 |         assert_scan_integrity(&fs);
403 | 
404 |         printf("## fill back up to the sector capacity\n");
405 |         for (int i=0; i<fs.slots_per_sector-1; i++)
406 |             ringfs_append(&fs, (int[]) { i });
407 | 
408 |         ck_assert_int_eq(ringfs_count_exact(&fs), capacity);
409 |         assert_scan_integrity(&fs);
410 |     }
411 | }
412 | END_TEST
413 | 
414 | Suite *ringfs_suite(void)
415 | {
416 |     Suite *s = suite_create ("ringfs");
417 |     TCase *tc;
418 | 
419 |     tc = tcase_create("flashsim");
420 |     tcase_add_test(tc, test_flashsim);
421 |     suite_add_tcase(s, tc);
422 | 
423 |     tc = tcase_create("ringfs");
424 |     tcase_add_checked_fixture(tc, fixture_flashsim_setup, fixture_flashsim_teardown);
425 |     tcase_add_test(tc, test_ringfs_format);
426 |     tcase_add_test(tc, test_ringfs_scan);
427 |     tcase_add_test(tc, test_ringfs_append);
428 |     tcase_add_test(tc, test_ringfs_discard);
429 |     tcase_add_test(tc, test_ringfs_capacity);
430 |     tcase_add_test(tc, test_ringfs_count);
431 |     tcase_add_test(tc, test_ringfs_overflow);
432 |     suite_add_tcase(s, tc);
433 | 
434 |     return s;
435 | }
436 | 
437 | int main()
438 | {
439 |     int number_failed;
440 |     Suite *s = ringfs_suite();
441 |     SRunner *sr = srunner_create(s);
442 |     srunner_run_all(sr, CK_NORMAL);
443 |     number_failed = srunner_ntests_failed(sr);
444 |     srunner_free(sr);
445 |     return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE;
446 | }
447 | 
448 | /* vim: set ts=4 sw=4 et: */
449 | 


--------------------------------------------------------------------------------