From c5c5c9b7003a13c4e969eb3832daaddff3fdc960 Mon Sep 17 00:00:00 2001 From: Brendan Le Foll Date: Fri, 3 Oct 2014 10:18:13 +0100 Subject: [PATCH] doc: cleanup internal documentation and naming Signed-off-by: Brendan Le Foll --- CMakeLists.txt | 2 +- README.md | 2 +- docs/index.md | 7 ++- docs/internals.md | 130 ++++++++++++++++++++++++++++++++++++++++++++ docs/platform-hooks.md | 19 +++++-- src/python/docs/example.rst | 8 ++- 6 files changed, 157 insertions(+), 11 deletions(-) create mode 100644 docs/internals.md diff --git a/CMakeLists.txt b/CMakeLists.txt index 8a8828e..15cbfaa 100644 --- a/CMakeLists.txt +++ b/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}") diff --git a/README.md b/README.md index d9198f2..be3f7be 100644 --- a/README.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index 49ae37f..e552266 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/internals.md b/docs/internals.md new file mode 100644 index 0000000..bd008aa --- /dev/null +++ b/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...) + diff --git a/docs/platform-hooks.md b/docs/platform-hooks.md index ece7291..5499dd7 100644 --- a/docs/platform-hooks.md +++ b/docs/platform-hooks.md @@ -1,16 +1,25 @@ -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. +platform-hooks {#hooks} +============== + +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 diff --git a/src/python/docs/example.rst b/src/python/docs/example.rst index f1b1e04..6063f3b 100644 --- a/src/python/docs/example.rst +++ b/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 === -- 2.7.4