diff options
author | Eric Lambert <eric_lambert@xyratex.com> | 2014-09-10 17:51:28 -0700 |
---|---|---|
committer | Eric Lambert <eric_lambert@xyratex.com> | 2014-09-10 17:51:28 -0700 |
commit | ac395fdd9a23692c1b15bed7b9c9885e8119d7c2 (patch) | |
tree | e6796baa7b9903aec284836655cef8c8692a16bc | |
parent | 512353f8be456f9f8045faafbdb3356a4dbdb8ad (diff) | |
parent | c85e1bacd36ca83ece37d70ae63409d010aef0cf (diff) | |
download | liberasurecode-ac395fdd9a23692c1b15bed7b9c9885e8119d7c2.tar.gz |
Merge branch 'newapi' of https://bitbucket.org/tsg-/liberasurecode into newapi
-rw-r--r-- | .gitignore | 5 | ||||
-rw-r--r-- | Makefile.am | 3 | ||||
-rw-r--r-- | README.md | 179 | ||||
-rw-r--r-- | aclocal.m4 | 40 | ||||
-rw-r--r-- | configure.ac | 48 | ||||
-rw-r--r-- | doc/Makefile.am | 36 | ||||
-rw-r--r-- | doc/doxygen.cfg.in (renamed from doc/Doxyfile) | 19 |
7 files changed, 217 insertions, 113 deletions
@@ -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 \ @@ -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
```
---
@@ -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 |