From a02923beec9412383bd7de907384f7bd31d233d6 Mon Sep 17 00:00:00 2001 From: Brendan Le Foll Date: Thu, 29 May 2014 14:51:38 +0100 Subject: [PATCH] docs: Add docs/ folder with in depth topics as well as DoxygenLayout.xml file * C headers now have @briefs and include examples * Examples have altered 'Interesting' Sections Signed-off-by: Brendan Le Foll --- Doxyfile.in | 20 +++-- DoxygenLayout.xml | 194 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 45 ++++-------- api/aio.h | 9 ++- api/gpio.h | 9 ++- api/i2c.h | 9 ++- api/pwm.h | 8 +- api/spi.h | 3 + docs/building.md | 27 +++++++ docs/contributing.md | 17 +++++ docs/galileorevd.md | 10 +++ examples/analogin_a0.c | 5 +- examples/hellomaa.c | 5 +- 13 files changed, 312 insertions(+), 49 deletions(-) create mode 100644 DoxygenLayout.xml create mode 100644 docs/building.md create mode 100644 docs/contributing.md create mode 100644 docs/galileorevd.md diff --git a/Doxyfile.in b/Doxyfile.in index a4c441e..da05e2e 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -99,7 +99,7 @@ BRIEF_MEMBER_DESC = YES # brief descriptions will be completely suppressed. # The default value is: YES. -REPEAT_BRIEF = YES +REPEAT_BRIEF = NO # This tag implements a quasi-intelligent brief description abbreviator that is # used to form the text in various listings. Each string in this list, if found @@ -129,6 +129,8 @@ ABBREVIATE_BRIEF = "The $name class" \ ALWAYS_DETAILED_SEC = NO +DETAILS_AT_TOP = YES + # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those # members were ordinary class members. Constructors, destructors and assignment @@ -510,7 +512,7 @@ HIDE_SCOPE_NAMES = YES # the files that are included by a file in the documentation of that file. # The default value is: YES. -SHOW_INCLUDE_FILES = YES +SHOW_INCLUDE_FILES = NO # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each # grouped member an include statement to the documentation, telling the reader @@ -536,7 +538,7 @@ INLINE_INFO = YES # name. If set to NO the members will appear in declaration order. # The default value is: YES. -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member @@ -671,7 +673,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = +LAYOUT_FILE = @CMAKE_CURRENT_SOURCE_DIR@/DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -753,7 +755,10 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = @CMAKE_CURRENT_SOURCE_DIR@/api/ @CMAKE_CURRENT_SOURCE_DIR@/README.md +INPUT = @CMAKE_CURRENT_SOURCE_DIR@/api/ \ + @CMAKE_CURRENT_SOURCE_DIR@/README.md \ + @CMAKE_CURRENT_SOURCE_DIR@/include/ \ + @CMAKE_CURRENT_SOURCE_DIR@/docs/ # 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 @@ -863,7 +868,8 @@ EXCLUDE_SYMBOLS = # command). EXAMPLE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/examples/ \ - @CMAKE_CURRENT_SOURCE_DIR@/examples/c++/ + @CMAKE_CURRENT_SOURCE_DIR@/examples/c++/ \ + @CMAKE_CURRENT_SOURCE_DIR@/docs/ # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and @@ -2206,7 +2212,7 @@ INCLUDE_GRAPH = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -INCLUDED_BY_GRAPH = YES +INCLUDED_BY_GRAPH = NO # If the CALL_GRAPH tag is set to YES then doxygen will generate a call # dependency graph for every global function or class method. diff --git a/DoxygenLayout.xml b/DoxygenLayout.xml new file mode 100644 index 0000000..4af56fd --- /dev/null +++ b/DoxygenLayout.xml @@ -0,0 +1,194 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/README.md b/README.md index 0da1559..a906906 100644 --- a/README.md +++ b/README.md @@ -16,37 +16,24 @@ classes directly wrap the C API and provide a near 1:1 mapping of functionality.
-C API Modules | C++ API Classes -:-------------------:|:-------------------: - @ref gpio.h "gpio" | @ref maa::Gpio "Gpio class" - @ref i2c.h "i2c" | @ref maa::I2c "I2c class" - @ref aio.h "aio" | @ref maa::Aio "Aio class" - @ref pwm.h "pwm" | @ref maa::Pwm "Pwm class" - @ref spi.h "spi" | @ref maa::Spi "Spi class" - @ref maa.h "maa" | @ref maa.h "maa" +| C API Modules | C++ API Classes | +|:-------------------:|:---------------------------:| +| @ref gpio.h "gpio" | @ref maa::Gpio "Gpio class" | +| @ref i2c.h "i2c" | @ref maa::I2c "I2c class" | +| @ref aio.h "aio" | @ref maa::Aio "Aio class" | +| @ref pwm.h "pwm" | @ref maa::Pwm "Pwm class" | +| @ref spi.h "spi" | @ref maa::Spi "Spi class" | +| @ref maa.h "maa" | @ref maa.h "maa" |
### Hello Maa @snippet hellomaa.c Interesting -### Basic GPIO -@snippet gpio_read6.c Interesting - -### Basic PWM -@snippet cycle-pwm3.c Interesting - -### Basic I2C -@snippet analogin_a0.c Interesting - -### Basic AIO -@snippet analogin_a0.c Interesting - -### Basic SPI -@snippet spi_mcp4261.c Interesting - ## Supported platforms -- Galileo (Fab D) +Specific platform information for supported platforms is documented here: + +- @ref galileorevd ### ENV RECOMENDATIONS @@ -60,15 +47,11 @@ cmake, libm and pthreads are technically required to compile. ## COMPILING -mkdir build/ -cmake -i .. -make +More information on compiling is @ref building page -## DEVELOPMENT +## CONTRIBUTING -Please fork the code on github and then send pull requests. Please avoid merges -in your forks. I will also accept patches sent in git style with signoffs to -brendan.le.foll@intel.com +Please see the @ref contributing page ## API Changelog diff --git a/api/aio.h b/api/aio.h index 47d9ed3..4513e24 100644 --- a/api/aio.h +++ b/api/aio.h @@ -25,8 +25,12 @@ #pragma once /** @file * - * This file defines the aio (analog in) interface for libmaa + * @brief Analog input/output * + * AIO is the anlog input & output interface to libmaa. It is used to read or + * set the voltage applied to an AIO pin. + * + * @snippet analogin_a0.c Interesting */ #ifdef __cplusplus @@ -44,7 +48,8 @@ extern "C" { #define ADC_SUPPORTED_RESOLUTION_BITS (10) /** - * Opaque pointer definition to the internal struct _aio + * Opaque pointer definition to the internal struct _aio. This context refers + * to one single AIO pin on the board. */ typedef struct _aio* maa_aio_context; diff --git a/api/gpio.h b/api/gpio.h index b371154..14e6e09 100644 --- a/api/gpio.h +++ b/api/gpio.h @@ -26,8 +26,15 @@ /** @file * - * This file defines the gpio interface for libmaa + * @brief General Purpose IO * + * GPIO is the General Purpose IO interface to libmaa. It's features depends on + * the board type used, it can use gpiolibs (exported via a kernel module + * through sysfs), or memory mapped IO via a /dev/uio device or /dev/mem + * depending again on the board configuratio, or memory mapped IO via a + * /dev/uio device or /dev/mem depending again on the board configuration. + * + * @snippet gpio_read6.c Interesting */ #ifdef __cplusplus diff --git a/api/i2c.h b/api/i2c.h index 360f78a..86c9f2f 100644 --- a/api/i2c.h +++ b/api/i2c.h @@ -26,8 +26,15 @@ /** @file * - * This file defines the i2c interface for libmaa + * @brief Inter-Integrated Circuit * + * This file defines the i2c/Iic interface for libmaa. A context represents a + * bus and that bus may contain multiple addresses or i2c slaves. It is + * considered best practice to make sure the address is correct before doing + * any calls on i2c, in case another application or even thread changed the + * addres on that bus. Multiple instances of the same bus can exist. + * + * @snippet i2c_HMC5883L.c Interesting */ #ifdef __cplusplus diff --git a/api/pwm.h b/api/pwm.h index dc76590..fce45c8 100644 --- a/api/pwm.h +++ b/api/pwm.h @@ -26,8 +26,14 @@ /** @file * - * This file defines the pwm interface for libmaa + * @brief Pulse Width Modulation module * + * PWM is the Pulse Width Modulation interface to libmaa. It allows the + * generation of a signal on a pin. Some boards may have higher or lower levels + * of resolution so make sure you check the board & pin you are using before + * hand. + * + * @snippet cycle-pwm3.c Interesting */ #ifdef __cplusplus diff --git a/api/spi.h b/api/spi.h index a4223c4..a1d7bea 100644 --- a/api/spi.h +++ b/api/spi.h @@ -26,8 +26,11 @@ /** @file * + * @brief System Packet Interface + * * This file defines the spi interface for libmaa * + * @snippet spi_mcp4261.c Interesting */ #ifdef __cplusplus diff --git a/docs/building.md b/docs/building.md new file mode 100644 index 0000000..923610a --- /dev/null +++ b/docs/building.md @@ -0,0 +1,27 @@ +Building libmaa {#building} +=============== + +libmaa uses cmake in order to make compilation relatively painless. Cmake runs +build out of tree so the recommended way is to clone from git and make a build/ directory. + +~~~~~~~~~~~~~{.sh} +mkdir build +cd build +cmake .. +make +~~~~~~~~~~~~~ + +Our cmake configure has a number of options, `cmake -i` will ask you all sorts +of interesting questions, you can disable swig modules, build documentation +etc... + +Few recommended options: +Changing install path from /usr/local to /usr +-DCMAKE_INSTALL_PREFIX:PATH=/usr + +Building debug build: +-DCMAKE_BUILD_TYPE=DEBUG + +Using clang instead of gcc: + -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang + diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..f295473 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,17 @@ +Contributing to libmaa {#contributing} +====================== + +libmaa is an opensource project and we are actively looking for people to help +with: + +- Writing platform supports for all types of embedded boards running linux +- People to write cool samples +- People to extend the functionality + +The recommended method to contribute is to fork on github, and then send pull +requests to the main project. Questions can be also be asked and issues raised +on github. + +If you'd rather not use github you are more than welcome to send git formatted +patches to brendan.le.foll@intel.com. + diff --git a/docs/galileorevd.md b/docs/galileorevd.md new file mode 100644 index 0000000..dca6174 --- /dev/null +++ b/docs/galileorevd.md @@ -0,0 +1,10 @@ +Galileo Rev D {#galileorevd} +============= + +Galileo is a microcontroller board based on the Intel® Quark SoC X1000 +Application Processor, a 32-bit Intel Pentium-class system on a chip. + +The rev D board has the following limitations in libmaa: + +- gpio register access via /dev/uio is limited to pin2 and 3 +- gpio interupts will only work on GPIO_EDGE_BOTH diff --git a/examples/analogin_a0.c b/examples/analogin_a0.c index 24f44d5..a543bd2 100644 --- a/examples/analogin_a0.c +++ b/examples/analogin_a0.c @@ -23,7 +23,7 @@ */ #include - +//! [Interesting] #include "aio.h" int main () @@ -31,7 +31,6 @@ int main () maa_aio_context adc_a0; uint16_t adc_value = 0; -//! [Interesting] adc_a0 = maa_aio_init(0); if (adc_a0 == NULL) { return 1; @@ -43,7 +42,7 @@ int main () } maa_aio_close(adc_a0); -//! [Interesting] return MAA_SUCCESS; } +//! [Interesting] diff --git a/examples/hellomaa.c b/examples/hellomaa.c index 69d6c4b..b9ed70a 100644 --- a/examples/hellomaa.c +++ b/examples/hellomaa.c @@ -23,14 +23,13 @@ */ #include "stdio.h" - +//! [Interesting] #include "maa.h" int main(int argc, char **argv) { -//! [Interesting] fprintf(stdout, "hello maa\n Version: %s\n", maa_get_version()); return 0; -//! [Interesting] } +//! [Interesting] -- 2.7.4