doc: cleanup internal documentation and naming

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>

CMakeLists.txt

@@ -18,7 +18,7 @@ if ("x_${VERSION}" STREQUAL "x_GIT-NOTFOUND")
   set (VERSION "v0.5.0-dirty")
 endif ()
 
-message (INFO " - MRAA Version ${VERSION}")
+message (INFO " - libmraa Version ${VERSION}")
 
 #parse the version information into pieces.
 string (REGEX REPLACE "^v([0-9]+)\\..*" "\\1" VERSION_MAJOR "${VERSION}")

README.md

@@ -1,4 +1,4 @@
-MRAA - Low Level Skeleton Library for Communication on GNU/Linux platforms
+libmraa - Low Level Skeleton Library for Communication on GNU/Linux platforms
 ==============
 
 Library in C/C++ to interface with Galileo & other Intel platforms, in a

docs/index.md

@@ -1,4 +1,4 @@
-MRAA - Low Level Skeleton Library for Communication on Intel platforms
+libmraa - Low Level Skeleton Library for Communication on Intel platforms
 ==============
 
 Library in C/C++ to interface with Galileo & other Intel platforms, in a
@@ -49,11 +49,12 @@ cmake, libm and pthreads are technically required to compile.
 
 ## COMPILING
 
-More information on compiling is @ref building page
+More information on compiling is @ref building page.
 
 ## CONTRIBUTING
 
-Please see the @ref contributing page
+Please see the @ref contributing page, the @ref internals page may also be of
+use.
 
 ## API Changelog
 

docs/internals.md

@@ -0,0 +1,130 @@
+libmraa Internals                       {#internals}
+=================
+
+For building see @ref building. This will describe the general internal build
+of libmraa and will be useful to developers who'd like to understand more of
+how libmraa works or who'd like to add additional platforms. The internals will
+deal with the C API as that is the low level API which libmraa is built around.
+Note that C++ is simply a header only wrapper of the C API.
+
+libmraa has the philosophy that the board mapping is what we typically use in
+the API with the execption of i2c/spi bus numbering as they are typically not
+labelled on boards and so we use the kernel numbering scheme. Whilst this can
+confuse some, it's typically not an issue as platforms rarely expose more than
+one of these for user use and so when this is the case, libmraa will always use
+the bus in the pinmapper. For example edison uses i2c #6 but since there is
+only one, libmraa will try to be helpful and everything is treated as 6 when
+doing a mraa_i2c_init and so when this is the case, libmraa will always use the
+bus in the pinmapper. For example edison uses i2c #6 but since there is only
+one, libmraa will try to be helpful and everything is treated as 6 when doing a
+mraa_i2c_init().
+
+In libmraa, all code is split into 7 modules, src/{i2c, spi, gpio, uart, pwm,
+aio and common}. These should be fairly self explanatory in goals/purpose but a
+few work in different ways. Public APIs are stored in api/ and internal headers
+are in include/
+
+### Logging ###
+
+Logging is now done purely in syslog(). Note that on platforms running systemd
+journald will intercept syslog(3) calls and log to the journal instead. You can
+set the log mask by using mraa_set_log_level(). Doing a DEBUG build of libmraa
+will also cause the DEBUG macro to be defined which will cause the syslog mask
+to be unset.
+
+### Contexts ###
+
+libmraa uses contexts to store all information, this context cannot be accessed
+by the user and so it's layout can and may be changed without warning to users.
+If an init() function fails it will return NULL and further calls with this
+context will lead to undefined behaviour.
+
+### Pinmapper ###
+
+The mraa_board_t is defined in mraa/common.h. It's a mostly static structure
+initialised during mraa_init(). The pinmap file in
+src/{manufacturer}_{boardname}_{revision}.c then fills this array. It's also
+where platform hooks can be defined, functions that will be run at various
+'hook' points in the code.
+
+The mraa_pininfo_t structure needs to be set for the board pincount (set in a
+macro in the platform configuration header. Every pin will have a
+mraa_pincapabilities_t which will define what it can do. The doxygen doc
+explains how this works but it's essentially a bitfield which needs to be set
+for every capability the pin can have. Gpios can have multiple muxes which will
+be set at the gpio init before it can be toggled.
+
+### i2c ###
+
+I2c from userspace in GNU/Linux is handled by character devices handled by the
+kernel driver i2c-dev. For more details the i2c/dev-interface documentation
+file in the kernel is the place to go.
+
+In libmraa, we re-use part of a library - libi2c from RoadNarrows -
+i2c/smbus.c. This library simply makes it easier for us to handle the error
+conditions that can arrise when writing on i2c buses. Essentially the API is
+fairly simple consisting of writes & reads.
+
+Careful - on alot of platforms i2cdetect will often crash, for finding your i2c
+addresses please look at your sensors datasheet!
+
+### spi ###
+
+### gpio ###
+
+GPIO is probably the most complicated and odd module in libmraa. It is based on
+the gpiolib kernel driver framework which uses sysfs. There is a lot of good
+documentation in gpio/sysfs.txt in the kernel docs.
+
+The main issue is that gpios on hobbyist boards typically come with a number of
+muxers or level shifters and are often mapped in crazy ways. libmraa's goal is
+to make the label on your board match the API :) We hope that pleases you.
+
+Because boards are very different we use alot of platform hooks (@ref hooks) to
+make the initialisation work on all platforms. The hope is that simple
+platforms with no level shifters or expanders will work with just the pinmap
+definition.
+
+GPIOs are typically interfaced via sysfs because that's easier for us but we
+can also work with fast gpio. This is typically preffered to do mmap gpio
+access. This is however trickier and typically relies on lots of platform
+hooks. We do support by default to go hit /dev/mem or another device at
+specific addresses to toggle gpios which is how mmap access works on some
+boards.
+
+### uart ###
+
+libmraa does not support UART/serial as there are many good libraries that do
+this already. In the future we may wrap or use one. However the class exists to
+set the pinmapper correctly for uart to work on some platforms.
+
+### pwm ###
+
+### aio ###
+
+### Initialisation ###
+
+mraa_init() needs to be called in order to initialise the platform files or
+'pinmap'. Because calling this is tedious libmraa uses a C constructor to run
+mraa_init on library load. This means that it is not possible to stop this
+running and all functino calls like mraa_set_log_level() will not work during
+mraa_init(). This feature is supported by most sane compilers & libcs but you
+can turn off CTORS in uclibc, though I've yet to find a configuration with
+someone doing that. mraa_init() can be called multiple times if you feel like
+being 'safe'.
+
+In the SWIG modulse mraa_init() is called during the %init stage of the module
+loading. This is simply to avoid mraa_init() running 'too' early, though I've
+never seen an issue in running it in a CTOR.
+
+### SWIG ###
+
+At the time when libmraa was created the only - working - API/wrapper
+generation tool that supported nodejs was SWIG. For more general information on
+swig please see the swig documentation.
+
+The src/{javascript, python} & src/mraa.i folders contain all the files for the
+swig generation. The C++ headers in api/mraa/ are given as input sources to
+SWIG. SWIG modules do not link to libmraa (although maybe that would be a good
+idea...)
+

docs/platform-hooks.md

@@ -1,16 +1,25 @@
-Hooks can be defined per supported platform to allow for highly custom operations if needed.
+platform-hooks                             {#hooks}
-This feature of MRAA should only be used by developers defining the board definitions, NOT an end user.
+==============
+
+Hooks can be defined per supported platform to allow for highly custom
+operations if needed.  This feature of MRAA should only be used by developers
+defining the board definitions, NOT an end user.
 
 ##Types of Hooks
 
 ###REPLACE
-Defining a replace function will entirely replace the associate function. This should only be done if your new function can handle everything the mraa function would normally.
+Defining a replace function will entirely replace the associate function. This
+should only be done if your new function can handle everything the mraa
+function would normally.
 
 ###PRE
-Any functionality defined here will be performed when the main function is called.
+Any functionality defined here will be performed when the main function is
+called.
 
 ###POST
-Any functionality perfomed here is done just before the normal function returns. All post functions will have passed into them the return value that would normally be returned.
+Any functionality perfomed here is done just before the normal function
+returns. All post functions will have passed into them the return value that
+would normally be returned.
 
 ##Hooks
 ### GPIO

src/python/docs/example.rst

@@ -20,7 +20,10 @@ GPIO Interupt (isr)
 ===================
 
 The GPIO module allows you to set an interupt on a GPIO. This interupt is
-controlled by the mode that the 'edge' is in.
+controlled by the mode that the 'edge' is in. Before setting another isr please
+remove the first one, multiple isrs on one pin are not supported. Some
+platforms will not support interupts on all pins so please check your return
+values.
 
 **Note:** Galileo Gen1 only supports EDGE_BOTH
 
@@ -31,6 +34,9 @@ controlled by the mode that the 'edge' is in.
 **Note:** If the python script is ended the destructors will run meaning that
 the ISR will not run. The sleep call is there for that function.
 
+**Note:** The python isr module treats only objects. This means that int
+counters will not work inside your isr. Please use the different edge modes.
+
 I2c
 ===