diff options
author | Ludovic Ferrandis <ludovic.ferrandis@intel.com> | 2013-02-25 14:38:03 +0100 |
---|---|---|
committer | Ludovic Ferrandis <ludovic.ferrandis@intel.com> | 2013-02-25 16:26:28 +0100 |
commit | 5acfdc473af4ac99f37fc3f4fd5685dca67c6473 (patch) | |
tree | e49dfb9945778120a4b4db6456b0ba139439aecd | |
parent | ebe4382e96a5ff955dcfd223c64e55cbd946158f (diff) | |
download | dleyna-core-5acfdc473af4ac99f37fc3f4fd5685dca67c6473.tar.gz |
[Documentation] Add doc folder
Add doc files:
- logging.txt
- TODO.txt
- coding-style.txt
Signed-off-by: Ludovic Ferrandis <ludovic.ferrandis@intel.com>
-rw-r--r-- | doc/TODO.txt | 7 | ||||
-rw-r--r-- | doc/coding-style.txt | 198 | ||||
-rw-r--r-- | doc/logging.txt | 101 |
3 files changed, 306 insertions, 0 deletions
diff --git a/doc/TODO.txt b/doc/TODO.txt new file mode 100644 index 0000000..09b38b2 --- /dev/null +++ b/doc/TODO.txt @@ -0,0 +1,7 @@ +TODO: +----- + +You can check the list of features we have planned or are currently working on +in github: + +<https://github.com/01org/dleyna-core/issues?labels=enhancement&page=1&state=open> diff --git a/doc/coding-style.txt b/doc/coding-style.txt new file mode 100644 index 0000000..69bf5a4 --- /dev/null +++ b/doc/coding-style.txt @@ -0,0 +1,198 @@ +Coding Style +-------------- + +dLeyna uses the linux kernel coding standard (1), with some exceptions +and additions. The linux kernel coding standard needs to be read in +addition to this document before code can be submitted to dLeyna. +There is one exception to the linux coding standard permitted by +dLeyna; typedefs are used for structures, for example + + typedef struct dleyna_buf_t_ dleyna_buf_t; + struct dleyna_buf_t_ { + unsigned int size; + unsigned int max_size; + unsigned int block_size; + uint8_t *buffer; + }; + +We also have a number of additions to the linux coding guidelines, +each of which will be described in its own section. + +Naming +------- + +All identifiers, be they labels, function names, types or variables +should be in lower case. Underscores '_', should be used to separate +the different words that compose multi-word identifiers, e.g., +do_something. + +Identifiers that are accessible in public headers should be prefixed by +dleyna_ or DLEYNA_ depending on whether they are types, functions and +variables or macros. + +Identifiers that are accessible outside the file in which they are +defined, but not in public header, should be prefixed by one of the +prefix defined below, like dlc_ or DLC_ depending on whether they are +types, functions and variables or macros. + +List of prefix by component: + +|--------------------------------------------------------------------| +| Component | GitHub repository | Function prefix | +|--------------------------------------------------------------------| +| dLeyna Core | dleyna-core | dlc_ | +| dLeyna Server | dleyna-server | dls_ | +| dLeyna Renderer | dleyna-renderer | dlr_ | +|--------------------------------------------------------------------| +| Connectors dbus | dleyna-connector-dbus | dcd_ | +|--------------------------------------------------------------------| + +The names of any new types defined should end in _t. + +Functions that are private to a given file should be static and their +names should be prefixed with prv_, e.g., prv_open_file. + +The names of functions that are accessible outside a file and are +essentially methods that operate on a structure should be prefixed by +the name of the structure, in addition to dleyna_. Therefore a function +that creates a pointer array might be called dleyna_pointer_array_create. + +Parameters +----------- + +Function parameters should not be prefixed with any identifiers that +indicate whether they are input or output parameters. + +Input parameters should appear at the beginning of the parameter list. + +Output parameters should appear at the end of the argument list. The +first parameter of a method that operates on an existing structure +instance should be a pointer to that structure instance. An exception +here are constructor functions, where the created structure instance +will be passed out of the constructor using the final output parameter +of the parameter list. Here are some examples, + + void dleyna_file_new(const char *fname, map_file_t **map_file); + const char *dleyna_file_search(map_file_t *map_file, + const char *key); + +Errors +----------- + +In all but the most simple functions errors should be handled using +gotos. For example; + + int fn() + { + if (!fn1()) + goto on_error; + + if (!fn2()) + goto on_error; + + on_error: + + return err; + } + + +The label on_error should be used as the label to jump to in +case of error. You are free to define additional labels using your own +naming scheme if necessary, e.g., no_free. + +Functions +------------- + +Functions should only have one exit point. Multiple exit points typically +lead to memory leaks and other errors. Multiple return statements are +permitted in one case only and this is when both return statements appear at +the bottom of the function on either sides of an error label. Sometimes +this is useful to avoid having to set local variables whose ownership is +being transferred to the caller to NULL, e.g., + + gboolean fn(char **name) + { + char *str; + + str = strdup("Hello"); + if (!str) + goto on_error; + + ok = fn1(str); + if (!ok) + goto on_error; + + *name = str; + + return TRUE; + + on_error: + + free(str); + + return FALSE; +} + +Header Files: +------------- + +Should include header guards whose names should be in uppercase and derived +from the project name, e.g., DLEYNA_ or DLC_, and the file name. The +guard names should be followed by an underscore, e.g., + + + #ifndef DLEYNA_UTILS_H__ + #define DLEYNA_UTILS_H__ + + #ifndef DLC_CORE_UTILS_H__ + #define DLC_CORE_UTILS_H__ + +config.h should never be included in a header file as it does not +contain any header guards. + +Local Variables: +---------------- + +Local variables should all be declared at the top of the function. +This is enforced by compiler options. + + +Global Variables: +----------------- + +Global variables are permitted if and only if it can be argued that their use +significantly simplifies the code. The names of global variables should +be begin with g_, i.e., g_token_dictionary. + +Git Usage: +----------- + +We will try to maintain a single branch in our git repository. Please rebase +your changes before submitting patches. + +Do not submit multiple features or bugs fixes in the same patch. Split your +changes into separate smaller patches. + +Checking files: +--------------- + +To check sources and headers files, you can use the script checkpatch.pl, +provided by the kernel. You can find it a the location below, depending of your +kernel version: + +/usr/src/linux-headers-X.Y.Z-TT/scripts/checkpatch.pl + +You can run it on files with these options: + +checkpatch.pl --no-tree -f --strict --show-types --ignore NEW_TYPEDEFS + +checkpatch.pl exceptions: +------------------------- + +There is currently 1 checkpatch exceptions + + - Line over 80 chars. Allowed only for error messages. + +References +---------- +(1) http://www.kernel.org/doc/Documentation/CodingStyle diff --git a/doc/logging.txt b/doc/logging.txt new file mode 100644 index 0000000..ee98160 --- /dev/null +++ b/doc/logging.txt @@ -0,0 +1,101 @@ +dLeyna components allow information to be output using a logging mechanism. +This service currently implements 2 output mechanisms and different 'levels' of +importance for messages. + +Logging type: +------------- + +dLeyna components can choose between 'syslog' or glib logging system. + +The logging type can be set at configuration time and changed dynamically at +runtime. + +When configuring the project, use the --with-log-type option to select your +desired logging service. + + --with-log-type=0: syslog service will be used. + --with-log-type=1: glib system will be used. + + +The logging options of a dLeyna service can also be modified at runtime +by modifying the service's configuration file. Each dLeyna service has +its own configuration file, e.g., dleyna-server.conf or dleyna-renderer.conf, +and these files are located in the default local configuration folder (usually +in your home folder, /home/<user>/.config/). + +Each configuration file has an option called log-type. + + log-type=0: syslog service will be used. + log-type=1: glib system will be used. + +dLeyna components monitor these configuration files. Any changes on it are +applied immediately. + + +Logging level: +-------------- + +The logging level selects which kind of messages in the code are going to be +logged. + +The logging level is set at configuration time and a subset of this initial +configuration can be changed dynamically at run time. + +dLeyna components define 6 levels of importance: + + 1: errors + 2: critical messages + 3: warnings + 4: messages/notices + 5: informational messages + 6: debug messages + +When configuring the project, use the --with-log-level option to select your +desired logging messages. + +Allowed values for --with-log-level are: + 0 = disabled + 7 = default (=1,2,5) + 8 = all (=1,2,3,4,5,6) + 1,..,6 = a comma separated list of log level + +ex: --with-log-level=2,5,6 will log only critical, informational and debug +messages. + +The service can also be changed at runtime by modifying the configuration file. +The service's configuration file has an option called log-level. +The values for log-level are the same as for --with-log-level. + +Be careful, logging messages not selected during the configuration of the +project, could not be enabled at runtime. These messages are stripped at +compilation time. You can only specify a sub selection of the one defined with +--with-log-level option. + +ex: +--with-log-level=2,5,6 +At run time you can change log-level to +log-level=2: Only critical messages will be logged. +log-level=5,6: sub selection of --with-log-level. +log-level=8: enable all options define by --with-log-level. Same as =2,5,6 +log-level=0: disable logging + +DOES NOT WORK: log-level=1,3. Not part of --with-log-level option. + + +Macros: +------- + +To log messages, use the predefined macros below: + +DLEYNA_LOG_LEVEL_ERROR +DLEYNA_LOG_LEVEL_CRITICAL +DLEYNA_LOG_LEVEL_WARNING +DLEYNA_LOG_LEVEL_MESSAGE +DLEYNA_LOG_LEVEL_INFO +DLEYNA_LOG_LEVEL_DEBUG + +DLEYNA_LOG_LEVEL_ERROR should not be used in release code but only for debug +purpose. +When log-level=1 (error message) is used with log-type=1 (glib), a call to +the the logging function is always fatal, and results in a call to abort(). +This is not acceptable in release. |