Merge branch 'newapi' of https://bitbucket.org/tsg-/liberasurecode into newapi

7 files changed, 217 insertions, 113 deletions

diff --git a/.gitignore b/.gitignore
index 24fafc3..fb2a4e9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,3 +44,8 @@ config_liberasurecode.h.in
 .deps
 config_liberasurecode.h
 stamp-h1
+
+# doxygen documentation
+^doc/.*\.doxytag
+^doc/html
+^doc/doxygen.cfg
diff --git a/Makefile.am b/Makefile.am
index b7ec5dc..6787508 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,7 +1,8 @@
 # Top-level liberasurecode automake configuration
 ACLOCAL_AMFLAGS = -I m4
 
-SUBDIRS = src test
+SUBDIRS = src test doc
+
 EXTRA_DIST = autogen.sh
 
 INCLUDE = -I$(abs_top_builddir)/include \
diff --git a/README.md b/README.md
index ca3febf..b2be7b5 100644
--- a/README.md
+++ b/README.md
@@ -43,56 +43,23 @@ Backend Support
 ---------------

 

 ``` c

-/* =~=*=~==~=*=~==~=*=~= Supported EC backends =~=*=~==~=*=~==~=*=~==~=*=~== */

 

 typedef enum {

-    EC_BACKEND_NULL                 = 0,

-    EC_BACKEND_JERASURE_RS_VAND     = 1,

-    EC_BACKEND_JERASURE_RS_CAUCHY   = 2,

-    EC_BACKEND_FLAT_XOR_HD          = 3,

+    EC_BACKEND_NULL                 = 0, /* "null" */

+    EC_BACKEND_JERASURE_RS_VAND     = 1, /* "jerasure_rs_vand" */

+    EC_BACKEND_JERASURE_RS_CAUCHY   = 2, /* "jerasure_rs_cauchy" */

+    EC_BACKEND_FLAT_XOR_HD          = 3, /* "flat_xor_hd */

     EC_BACKENDS_MAX,

 } ec_backend_id_t;

 

-/* Supported EC backends */

-static const char *ec_backend_names[EC_BACKENDS_MAX] = {

-    "null",

-    "jerasure_rs_vand",

-    "jerasure_rs_cauchy",

-    "flat_xor_hd",

-};

 ```

 

 ----

 

-Erasure Code Fragment Checksum Support

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

-

-``` c

-

-/* ~=*=~==~=*=~= EC Fragment metadata - supported checksum types ~=*=~==~=*=~ */

-

-/* Checksum types supported for fragment metadata stored in each fragment */

-typedef enum {

-    CHKSUM_NONE                     = 0,

-    CHKSUM_CRC32                    = 1,

-    CHKSUM_MD5                      = 2,

-    CHKSUM_TYPES_MAX,

-} ec_checksum_type_t;

-

-/* Supported checksum types */

-static const char *ec_chksum_types[CHKSUM_TYPES_MAX] = {

-    "none",

-    "crc32",

-    "md5",

-};

-```

-----

-

 User Arguments

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

 

 ``` c

-/* =~=*=~==~=*=~== EC Arguments - Common and backend-specific =~=*=~==~=*=~== */

 

 /**

  * Common and backend-specific args

@@ -118,6 +85,7 @@ struct ec_args {
                               * future backend args */

     ec_checksum_type_t ct;  /* fragment checksum type */

 };

+

 ```

 

 ---

@@ -126,7 +94,6 @@ User-facing API Functions
 -------------------------

 

 ``` c

-/* =~=*=~==~=*=~== liberasurecode frontend API functions =~=*=~==~=~=*=~==~= */

 

 /* liberasurecode frontend API functions */

 

@@ -298,11 +265,29 @@ int liberasurecode_fragments_needed(int desc,
         int *fragments_to_exclude,

         int *fragments_needed);

 

+```

+

+Erasure Code Fragment Checksum Types Supported

+----------------------------------------------

+

+``` c

 

-/* ==~=*=~==~=*=~== liberasurecode fragment metadata routines ==~*==~=*=~==~ */

+/* Checksum types supported for fragment metadata stored in each fragment */

+typedef enum {

+    CHKSUM_NONE                     = 0, /* "none" (default) */

+    CHKSUM_CRC32                    = 1, /* "crc32" */

+    CHKSUM_MD5                      = 2, /* "md5" */

+    CHKSUM_TYPES_MAX,

+} ec_checksum_type_t;

 

-#define LIBERASURECODE_MAX_CHECKSUM_LEN 8

-typedef struct __attribute__((__packed__))

+```

+

+Erasure Code Fragment Checksum API

+----------------------------------

+

+``` c

+

+struct

 fragment_metadata

 {

     uint32_t    idx;                /* 4 */

@@ -313,8 +298,6 @@ fragment_metadata
     uint8_t     chksum_mismatch;    /* 1 */

 } fragment_metadata_t;

 

-#define FRAGSIZE_2_BLOCKSIZE(fragment_size) \

-    (fragment_size - sizeof(fragment_header_t))

 

 /**

  * Get opaque metadata for a fragment.  The metadata is opaque to the

@@ -345,8 +328,6 @@ int liberasurecode_get_fragment_metadata(int desc,
 int liberasurecode_verify_stripe_metadata(int desc,

         char **fragments, int num_fragments);

 

-/* ==~=*=~===~=*=~==~=*=~== liberasurecode Helpers ==~*==~=*=~==~=~=*=~==~= */

-

 /**

  * This computes the aligned size of a buffer passed into 

  * the encode function.  The encode function must pad fragments

@@ -372,6 +353,7 @@ int liberasurecode_get_aligned_data_size(int desc, uint64_t data_len);
  * @return minimum data length length, or -error code on error

  */

 int liberasurecode_get_minimum_encode_size(int desc);

+

 ```

 ----

 

@@ -379,18 +361,15 @@ Error Codes
 -----------

 

 ``` c

-/* ==~=*=~===~=*=~==~=*=~== liberasurecode Error codes =~=*=~==~=~=*=~==~== */

 

 /* Error codes */

 typedef enum {

-    EBACKENDNOTSUPP  = 200,

-    EECMETHODNOTIMPL = 201,

-    EBACKENDINITERR  = 202,

-    EBACKENDINUSE    = 203,

-    EBACKENDNOTAVAIL = 204,

+    EBACKENDNOTSUPP  = 200, /* EC Backend not supported by the library */

+    EECMETHODNOTIMPL = 201, /* EC Backend method not implemented */

+    EBACKENDINITERR  = 202, /* EC Backend could not be initialized */

+    EBACKENDINUSE    = 203, /* EC Backend in use (locked) */

 } LIBERASURECODE_ERROR_CODES;

 

-/* =~=*=~==~=*=~==~=*=~==~=*=~===~=*=~==~=*=~===~=*=~==~=*=~===~=*=~==~=*=~= */

 ```

 ---

 

@@ -413,54 +392,54 @@ top-level directory:
 Code organization

 =================

 ```

-  ├── include

-  │   ├── erasurecode

-  │   │   ├── erasurecode.h            --> liberasurecode frontend API header

-  │   │   └── erasurecode_backend.h    --> liberasurecode backend API header

-  │   └── xor_codes                    --> headers for the built-in XOR codes

-  |

-  ├── src

-  │   ├── erasurecode.c                --> liberasurecode API implementation

-  |   |                                    (frontend + backend)

-  │   ├── backends

-  │   │   └── null

-  │   │       └─── null.c              --> 'null' erasure code backend

-  │   │   └── xor

-  │   │       └─── flat_xor_hd.c       --> 'flat_xor_hd' erasure code backend

-  │   │   └── jerasure                 

-  │   │       ├── jerasure_rs_cauchy.c --> 'jerasure_rs_vand' erasure code backend

-  │   │       └── jerasure_rs_vand.c   --> 'jerasure_rs_cauchy' erasure code backend

-  |   |

-  │   ├── builtin

-  │   │   └── xor_codes                --> XOR HD code backend, built-in erasure

-  |   |       |                            code implementation (shared library)

-  │   │       ├── xor_code.c

-  │   │       └── xor_hd_code.c

-  |   |

-  │   └── utils

-  │       └── chksum                   --> fragment checksum utils for erasure

-  │           ├── alg_sig.c                coded fragments

-  │           └── crc32.c

-  |

-  ├── doc                              --> API Documentation

-  │   ├── Doxyfile

-  │   └── html

-  |

-  └─── test                            --> Test routines

-  │    ├── builtin

-  |    │   └── xor_codes

-  │    ├── liberasurecode_test.c

-  │    └── utils

-  |

-  ├── autogen.sh

-  ├── configure.ac

-  ├── Makefile.am

-  ├── README

-  ├── NEWS

-  ├── COPYING

-  ├── AUTHORS

-  ├── INSTALL

-  └── ChangeLog

+ |-- include

+ |   +-- erasurecode

+ |   |   +-- erasurecode.h            --> liberasurecode frontend API header

+ |   |   +-- erasurecode_backend.h    --> liberasurecode backend API header

+ |   +-- xor_codes                    --> headers for the built-in XOR codes

+ |

+ |-- src

+ |   |-- erasurecode.c                --> liberasurecode API implementation

+ |   |                                    (frontend + backend)

+ |   |-- backends

+ |   |   +-- null

+ |   |       +--- null.c              --> 'null' erasure code backend

+ |   |   +-- xor

+ |   |       +--- flat_xor_hd.c       --> 'flat_xor_hd' erasure code backend

+ |   |   +-- jerasure                 

+ |   |       +-- jerasure_rs_cauchy.c --> 'jerasure_rs_vand' erasure code backend

+ |   |       +-- jerasure_rs_vand.c   --> 'jerasure_rs_cauchy' erasure code backend

+ |   |

+ |   |-- builtin

+ |   |   +-- xor_codes                --> XOR HD code backend, built-in erasure

+ |   |       |                            code implementation (shared library)

+ |   |       +-- xor_code.c

+ |   |       +-- xor_hd_code.c

+ |   |

+ |   +-- utils

+ |       +-- chksum                   --> fragment checksum utils for erasure

+ |           +-- alg_sig.c                coded fragments

+ |           +-- crc32.c

+ |

+ |-- doc                              --> API Documentation

+ |   +-- Doxyfile

+ |   +-- html

+ |

+ |--- test                            --> Test routines

+ |    +-- builtin

+ |    |   +-- xor_codes

+ |    +-- liberasurecode_test.c

+ |    +-- utils

+ |

+ |-- autogen.sh

+ |-- configure.ac

+ |-- Makefile.am

+ |-- README

+ |-- NEWS

+ |-- COPYING

+ |-- AUTHORS

+ |-- INSTALL

+ +-- ChangeLog

 ```

 ---

 

diff --git a/aclocal.m4 b/aclocal.m4
index 9bbc37a..f338346 100644
--- a/aclocal.m4
+++ b/aclocal.m4
@@ -114,6 +114,46 @@ AC_PREREQ([2.50])dnl
 am_aux_dir=`cd $ac_aux_dir && pwd`
 ])
 
+# AM_COND_IF                                            -*- Autoconf -*-
+
+# Copyright (C) 2008, 2010 Free Software Foundation, Inc.
+#
+# This file is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# serial 3
+
+# _AM_COND_IF
+# _AM_COND_ELSE
+# _AM_COND_ENDIF
+# --------------
+# These macros are only used for tracing.
+m4_define([_AM_COND_IF])
+m4_define([_AM_COND_ELSE])
+m4_define([_AM_COND_ENDIF])
+
+
+# AM_COND_IF(COND, [IF-TRUE], [IF-FALSE])
+# ---------------------------------------
+# If the shell condition COND is true, execute IF-TRUE, otherwise execute
+# IF-FALSE.  Allow automake to learn about conditional instantiating macros
+# (the AC_CONFIG_FOOS).
+AC_DEFUN([AM_COND_IF],
+[m4_ifndef([_AM_COND_VALUE_$1],
+	   [m4_fatal([$0: no such condition "$1"])])dnl
+_AM_COND_IF([$1])dnl
+if test -z "$$1_TRUE"; then :
+  m4_n([$2])[]dnl
+m4_ifval([$3],
+[_AM_COND_ELSE([$1])dnl
+else
+  $3
+])dnl
+_AM_COND_ENDIF([$1])dnl
+fi[]dnl
+])
+
 # AM_CONDITIONAL                                            -*- Autoconf -*-
 
 # Copyright (C) 1997, 2000, 2001, 2003, 2004, 2005, 2006, 2008
diff --git a/configure.ac b/configure.ac
index 4b5e6e9..5312850 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,3 +1,6 @@
+################################################################################
+#                           Standard Stuff
+################################################################################
 AC_INIT(liberasurecode,0.9.10)
 AC_GNU_SOURCE
 
@@ -25,13 +28,20 @@ AC_PROG_MAKE_SET
 
 AX_EXT()
 
+################################################################################
+#                             System Headers
+################################################################################
 dnl Check for C library headers
 AC_HEADER_STDC
-AC_CHECK_HEADERS(sys/types.h stdio.h stdlib.h stddef.h stdarg.h malloc.h memory.h \
-                 string.h strings.h inttypes.h stdint.h ctype.h math.h iconv.h \
-                 signal.h dlfcn.h pthread.h unistd.h limits.h errno.h syslog.h)
+AC_CHECK_HEADERS(sys/types.h stdio.h stdlib.h stddef.h stdarg.h \
+                 malloc.h memory.h string.h strings.h inttypes.h \
+                 stdint.h ctype.h math.h iconv.h signal.h dlfcn.h \
+                 pthread.h unistd.h limits.h errno.h syslog.h)
 AC_CHECK_FUNCS(malloc calloc realloc free openlog)
 
+#################################################################################
+#                             Debug/coverage Options
+#################################################################################
 AC_ARG_ENABLE([debug],
 [  --enable-debug    Turn on debugging],
 [case "${enableval}" in
@@ -74,15 +84,47 @@ dnl Expand the sources and objects needed to build the library
 AC_SUBST(ac_aux_dir)
 AC_SUBST(OBJECTS)
 
+#################################################################################
+#                             Doxygen Documentation
+#################################################################################
+AC_CHECK_PROG(DOXYGEN, doxygen, true, false)
+AM_CONDITIONAL(HAVE_DOXYGEN, $DOXYGEN)
+AC_SUBST(HAVE_DOXYGEN)
+
+dnl Let people disable the doxygen stuff.
+AC_ARG_ENABLE(doxygen, [  --enable-doxygen         Use doxygen to build documentation (default=auto)],
+    enable_doxygen="$enableval",
+    enable_doxygen=auto)
+
+if test x$enable_doxygen = xauto ; then
+    if test x$DOXYGEN = xtrue ; then
+        enable_doxygen=yes
+    else
+        enable_doxygen=no
+    fi
+fi
+
+dnl NOTE: We need to use a separate automake conditional for this
+dnl       to make this work with the tarballs.
+AM_CONDITIONAL(ENABLE_DOXYGEN, test x$enable_doxygen = xyes)
+
+################################################################################
+#                           Output Files
+################################################################################
 AC_CONFIG_FILES([\
     src/builtin/null_code/Makefile \
     src/builtin/xor_codes/Makefile \
     src/Makefile \
     test/Makefile \
+    doc/Makefile \
     Makefile \
     erasurecode.pc \
     Xorcode.pc
 ])
 
+AM_CONDITIONAL([HAVE_DOXYGEN], [test -n "$DOXYGEN"])
+AM_COND_IF([HAVE_DOXYGEN],
+           [AC_CONFIG_FILES([doc/doxygen.cfg])])
+
 AC_OUTPUT
 
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..aea521f
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,36 @@
+DOC_MODULE="liberasurecode"
+HTML_DIR=$(datadir)/$(DOC_MODULE)/html
+TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+
+all-local:	html/index.html
+
+if ENABLE_DOXYGEN
+html/index.html: doxygen.cfg
+	doxygen doxygen.cfg
+else
+html/index.html:
+endif
+
+clean-local:
+	rm -f *~ *.bak
+	rm -rf html
+
+install-data-local: html
+	$(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)
+	(installfiles=`echo html/*`; \
+	if test "$$installfiles" = 'html/*'; \
+	then echo '-- Nothing to install' ; \
+	else \
+		for i in $$installfiles; do \
+			echo '-- Installing '$$i ; \
+			$(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \
+		done; \
+	fi)
+
+dist-hook:
+	mkdir $(distdir)/html
+	mkdir $(distdir)/man
+	-cp html/* $(distdir)/html
+	-cp man/* $(distdir)/man
+
+.PHONY : html latex man
diff --git a/doc/Doxyfile b/doc/doxygen.cfg.in
index 11fce98..ec2c87d 100644
--- a/doc/Doxyfile
+++ b/doc/doxygen.cfg.in
@@ -32,13 +32,13 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "liberasurecode"
+PROJECT_NAME           = @PACKAGE_NAME@
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = @PACKAGE_VERSION@
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -140,7 +140,7 @@ INLINE_INHERITED_MEMB  = NO
 # shortest path that makes the file name unique will be used
 # The default value is: YES.
 
-FULL_PATH_NAMES        = YES
+FULL_PATH_NAMES        = NO
 
 # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
 # Stripping is only done if one of the specified strings matches the left-hand
@@ -177,7 +177,7 @@ SHORT_NAMES            = NO
 # description.)
 # The default value is: NO.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
 # line (until the first dot) of a Qt-style comment as the brief description. If
@@ -242,7 +242,7 @@ TCL_SUBST              =
 # members will be omitted, etc.
 # The default value is: NO.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
 # Python sources only. Doxygen will then generate output that is more tailored
@@ -427,7 +427,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,
@@ -460,7 +460,7 @@ EXTRACT_ANON_NSPACES   = NO
 # section is generated. This option has no effect if EXTRACT_ALL is enabled.
 # The default value is: NO.
 
-HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_MEMBERS     = YES
 
 # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
 # undocumented classes that are normally visible in the class hierarchy. If set
@@ -751,7 +751,8 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "../src" "../include"
+INPUT                  = @top_srcdir@/include/erasurecode/erasurecode.h \
+                         @top_srcdir@/include/erasurecode/erasurecode_backend.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -973,7 +974,7 @@ USE_HTAGS              = NO
 # See also: Section \class.
 # The default value is: YES.
 
-VERBATIM_HEADERS       = YES
+VERBATIM_HEADERS       = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to the alphabetical class index