maa: make common.h header to replace maa.h header to simplify includes

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

api/maa.h

@@ -1,6 +1,5 @@
 /*
  * Author: Brendan Le Foll <brendan.le.foll@intel.com>
- * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
  * Copyright © 2014 Intel Corporation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -24,213 +23,10 @@
 
 #pragma once
 
-/** @file
- *
- * This file defines the basic shared values for libmaa
- */
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/**
- * MAA return codes
- */
-typedef enum {
-    MAA_SUCCESS                              =  0, /**< Expected response */
-    MAA_ERROR_FEATURE_NOT_IMPLEMENTED        =  1, /**< Feature TODO */
-    MAA_ERROR_FEATURE_NOT_SUPPORTED          =  2, /**< Feature not supported by HW */
-    MAA_ERROR_INVALID_VERBOSITY_LEVEL        =  3, /**< Verbosity level wrong */
-    MAA_ERROR_INVALID_PARAMETER              =  4, /**< Parameter invalid */
-    MAA_ERROR_INVALID_HANDLE                 =  5, /**< Handle invalid */
-    MAA_ERROR_NO_RESOURCES                   =  6, /**< No resource of that type avail */
-    MAA_ERROR_INVALID_RESOURCE               =  7, /**< Resource invalid */
-    MAA_ERROR_INVALID_QUEUE_TYPE             =  8, /**< Queue type incorrect */
-    MAA_ERROR_NO_DATA_AVAILABLE              =  9, /**< No data available */
-    MAA_ERROR_INVALID_PLATFORM               = 10, /**< Platform not recognised */
-    MAA_ERROR_PLATFORM_NOT_INITIALISED       = 11, /**< Board information not initialised */
-    MAA_ERROR_PLATFORM_ALREADY_INITIALISED   = 12, /**< Board is already initialised */
-
-    MAA_ERROR_UNSPECIFIED                    = 99 /**< Unknown Error */
-} maa_result_t;
-
-/**
- * MAA boolean type
- * 1 For TRUE
- */
-typedef unsigned int maa_boolean_t;
-
-/**
- * Enum representing different possible modes for a pin.
- */
-typedef enum {
-    MAA_PIN_VALID       = 0, /**< Pin Valid */
-    MAA_PIN_GPIO        = 1, /**< General Purpose IO */
-    MAA_PIN_PWM         = 2, /**< Pulse Width Modulation */
-    MAA_PIN_FAST_GPIO   = 3, /**< Faster GPIO */
-    MAA_PIN_SPI         = 4, /**< SPI */
-    MAA_PIN_I2C         = 5, /**< I2C */
-    MAA_PIN_AIO         = 6  /**< Analog in */
-} maa_pinmodes_t;
-
-/**
- * A bitfield representing the capabilities of a pin.
- */
-typedef struct {
-    /*@{*/
-    maa_boolean_t valid:1;     /**< Is the pin valid at all */
-    maa_boolean_t gpio:1;      /**< Is the pin gpio capable */
-    maa_boolean_t pwm:1;       /**< Is the pin pwm capable */
-    maa_boolean_t fast_gpio:1; /**< Is the pin fast gpio capable */
-    maa_boolean_t spi:1;       /**< Is the pin spi capable */
-    maa_boolean_t i2c:1;       /**< Is the pin i2c capable */
-    maa_boolean_t aio:1;       /**< Is the pin analog input capable */
-    /*@}*/
-} maa_pincapabilities_t;
-
-/**
- * A Structure representing a multiplexer and the required value
- */
-typedef struct {
-    /*@{*/
-    unsigned int pin;   /**< Raw GPIO pin id */
-    unsigned int value; /**< Raw GPIO value */
-    /*@}*/
-} maa_mux_t;
-
-/**
- * A Strucutre representing a singular I/O pin. i.e GPIO/PWM
- */
-typedef struct {
-    /*@{*/
-    unsigned int pinmap; /**< sysfs pin */
-    unsigned int parent_id; /** parent chip id */
-    unsigned int mux_total; /** Numfer of muxes needed for operation of pin */
-    maa_mux_t mux[6]; /** Array holding information about mux */
-    /*@}*/
-} maa_pin_t;
-
-typedef struct {
-    /*@{*/
-    char mem_dev[32]; /**< Memory device to use /dev/uio0 etc */
-    unsigned int mem_sz; /** Size of memory to map */
-    unsigned int bit_pos; /** Position of value bit */
-    maa_pin_t gpio; /** GPio context containing none mmap info */
-    /*@}*/
-} maa_mmap_pin_t;
-
-/**
- * A Structure representing a physical Pin.
- */
-typedef struct {
-    /*@{*/
-    char name[8];                      /**< Pin's real world name */
-    maa_pincapabilities_t capabilites; /**< Pin Capabiliites */
-    maa_pin_t gpio; /**< GPIO structure */
-    maa_pin_t pwm;  /**< PWM structure */
-    maa_pin_t aio;  /**< Anaglog Pin */
-    maa_mmap_pin_t mmap; /**< GPIO through memory */
-    maa_pin_t i2c;  /**< i2c bus/pin */
-    maa_pin_t spi;  /**< spi bus/pin */
-    /*@}*/
-} maa_pininfo_t;
-
-/**
- * A Structure representing the physical properties of a i2c bus.
- */
-typedef struct {
-    /*@{*/
-    unsigned int bus_id; /**< ID as exposed in the system */
-    unsigned int scl; /**< i2c SCL */
-    unsigned int sda; /**< i2c SDA */
-    /*@}*/
-} maa_i2c_bus_t;
-
-/**
- * A Structure representing the physical properties of a spi bus.
- */
-typedef struct {
-    /*@{*/
-    unsigned int bus_id; /**< The Bus ID as exposed to the system. */
-    unsigned int slave_s; /**< Slave select */
-    maa_boolean_t three_wire; /**< Is the bus only a three wire system */
-    unsigned int sclk; /**< Serial Clock */
-    unsigned int mosi; /**< Master Out, Slave In. */
-    unsigned int miso; /**< Master In, Slave Out. */
-    unsigned int cs; /**< Chip Select, used when the board is a spi slave */
-    /*@}*/
-} maa_spi_bus_t;
-
-/**
- * A Structure representing a platform/board.
- */
-typedef struct {
-    /*@{*/
-    unsigned int phy_pin_count; /**< The Total IO pins on board */
-    unsigned int gpio_count; /**< GPIO Count */
-    unsigned int aio_count;  /**< Analog side Count */
-    unsigned int i2c_bus_count; /**< Usable i2c Count */
-    maa_i2c_bus_t  i2c_bus[6]; /**< Array of i2c */
-    unsigned int def_i2c_bus; /**< Position in array of default i2c bus */
-    unsigned int spi_bus_count; /**< Usable spi Count */
-    maa_spi_bus_t spi_bus[6];       /**< Array of spi */
-    unsigned int def_spi_bus; /**< Position in array of defult spi bus */
-    maa_pininfo_t* pins;     /**< Pointer to pin array */
-    /*@}*/
-} maa_board_t;
-
-/**
- * Initialise MAA
- *
- * Detects running platform and attempts to use included pinmap
- *
- * @return Result of operation
- */
-#ifndef SWIG
-// this sets a compiler attribute (supported by GCC & clang) to have maa_init()
-// be called as a constructor make sure your libc supports this!  uclibc needs
-// to be compiled with UCLIBC_CTOR_DTOR
-maa_result_t maa_init() __attribute__((constructor));
-#else
-maa_result_t maa_init();
-#endif
-
-/**
- * This function attempts to set the maa process to a given priority and the
- * scheduler to SCHED_RR. Highest * priority is typically 99 and minimum is 0.
- * This function * will set to MAX if * priority is > MAX. Function will return
- * -1 on failure.
-
- * @param priority Value from typically 0 to 99
- * @return The priority value set
- */
-int maa_set_priority(const unsigned int priority);
-
-/** Get the version string of maa autogenerated from git tag
- *
- * The version returned may not be what is expected however it is a reliable
- * number associated with the git tag closest to that version at build time
- *
- * @return version string from version.h
- */
-const char* maa_get_version();
-
-/**
- * Print a textual representation of the maa_result_t
- *
- * @param result the result to print
- */
-void maa_result_print(maa_result_t result);
-
-/**
- * Checks if a pin is able to use the passed in mode.
- *
- * @param pin Physical Pin to be checked.
- * @param mode the mode to be tested.
- * @return boolean if the mode is supported, 0=false.
- */
-maa_boolean_t maa_pin_mode_test(int pin, maa_pinmodes_t mode);
-
 #include "maa/pwm.h"
 #include "maa/aio.h"
 #include "maa/gpio.h"

api/maa.hpp

@@ -24,7 +24,7 @@
 
 #pragma once
 
-#include "maa.h"
+#include "maa/common.h"
 #include "maa/pwm.hpp"
 #include "maa/aio.hpp"
 #include "maa/gpio.hpp"

api/maa/aio.h

@@ -41,7 +41,7 @@ extern "C" {
 #include <unistd.h>
 #include <stdint.h>
 
-#include "maa.h"
+#include "common.h"
 #include "gpio.h"
 
 #define ADC_RAW_RESOLUTION_BITS         (12)

api/maa/common.h

@@ -0,0 +1,236 @@
+/*
+ * Author: Brendan Le Foll <brendan.le.foll@intel.com>
+ * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
+ * Copyright © 2014 Intel Corporation
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#pragma once
+
+/** @file
+ *
+ * This file defines the basic shared values for libmaa
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * MAA return codes
+ */
+typedef enum {
+    MAA_SUCCESS                              =  0, /**< Expected response */
+    MAA_ERROR_FEATURE_NOT_IMPLEMENTED        =  1, /**< Feature TODO */
+    MAA_ERROR_FEATURE_NOT_SUPPORTED          =  2, /**< Feature not supported by HW */
+    MAA_ERROR_INVALID_VERBOSITY_LEVEL        =  3, /**< Verbosity level wrong */
+    MAA_ERROR_INVALID_PARAMETER              =  4, /**< Parameter invalid */
+    MAA_ERROR_INVALID_HANDLE                 =  5, /**< Handle invalid */
+    MAA_ERROR_NO_RESOURCES                   =  6, /**< No resource of that type avail */
+    MAA_ERROR_INVALID_RESOURCE               =  7, /**< Resource invalid */
+    MAA_ERROR_INVALID_QUEUE_TYPE             =  8, /**< Queue type incorrect */
+    MAA_ERROR_NO_DATA_AVAILABLE              =  9, /**< No data available */
+    MAA_ERROR_INVALID_PLATFORM               = 10, /**< Platform not recognised */
+    MAA_ERROR_PLATFORM_NOT_INITIALISED       = 11, /**< Board information not initialised */
+    MAA_ERROR_PLATFORM_ALREADY_INITIALISED   = 12, /**< Board is already initialised */
+
+    MAA_ERROR_UNSPECIFIED                    = 99 /**< Unknown Error */
+} maa_result_t;
+
+/**
+ * MAA boolean type
+ * 1 For TRUE
+ */
+typedef unsigned int maa_boolean_t;
+
+/**
+ * Enum representing different possible modes for a pin.
+ */
+typedef enum {
+    MAA_PIN_VALID       = 0, /**< Pin Valid */
+    MAA_PIN_GPIO        = 1, /**< General Purpose IO */
+    MAA_PIN_PWM         = 2, /**< Pulse Width Modulation */
+    MAA_PIN_FAST_GPIO   = 3, /**< Faster GPIO */
+    MAA_PIN_SPI         = 4, /**< SPI */
+    MAA_PIN_I2C         = 5, /**< I2C */
+    MAA_PIN_AIO         = 6  /**< Analog in */
+} maa_pinmodes_t;
+
+/**
+ * A bitfield representing the capabilities of a pin.
+ */
+typedef struct {
+    /*@{*/
+    maa_boolean_t valid:1;     /**< Is the pin valid at all */
+    maa_boolean_t gpio:1;      /**< Is the pin gpio capable */
+    maa_boolean_t pwm:1;       /**< Is the pin pwm capable */
+    maa_boolean_t fast_gpio:1; /**< Is the pin fast gpio capable */
+    maa_boolean_t spi:1;       /**< Is the pin spi capable */
+    maa_boolean_t i2c:1;       /**< Is the pin i2c capable */
+    maa_boolean_t aio:1;       /**< Is the pin analog input capable */
+    /*@}*/
+} maa_pincapabilities_t;
+
+/**
+ * A Structure representing a multiplexer and the required value
+ */
+typedef struct {
+    /*@{*/
+    unsigned int pin;   /**< Raw GPIO pin id */
+    unsigned int value; /**< Raw GPIO value */
+    /*@}*/
+} maa_mux_t;
+
+/**
+ * A Strucutre representing a singular I/O pin. i.e GPIO/PWM
+ */
+typedef struct {
+    /*@{*/
+    unsigned int pinmap; /**< sysfs pin */
+    unsigned int parent_id; /** parent chip id */
+    unsigned int mux_total; /** Numfer of muxes needed for operation of pin */
+    maa_mux_t mux[6]; /** Array holding information about mux */
+    /*@}*/
+} maa_pin_t;
+
+typedef struct {
+    /*@{*/
+    char mem_dev[32]; /**< Memory device to use /dev/uio0 etc */
+    unsigned int mem_sz; /** Size of memory to map */
+    unsigned int bit_pos; /** Position of value bit */
+    maa_pin_t gpio; /** GPio context containing none mmap info */
+    /*@}*/
+} maa_mmap_pin_t;
+
+/**
+ * A Structure representing a physical Pin.
+ */
+typedef struct {
+    /*@{*/
+    char name[8];                      /**< Pin's real world name */
+    maa_pincapabilities_t capabilites; /**< Pin Capabiliites */
+    maa_pin_t gpio; /**< GPIO structure */
+    maa_pin_t pwm;  /**< PWM structure */
+    maa_pin_t aio;  /**< Anaglog Pin */
+    maa_mmap_pin_t mmap; /**< GPIO through memory */
+    maa_pin_t i2c;  /**< i2c bus/pin */
+    maa_pin_t spi;  /**< spi bus/pin */
+    /*@}*/
+} maa_pininfo_t;
+
+/**
+ * A Structure representing the physical properties of a i2c bus.
+ */
+typedef struct {
+    /*@{*/
+    unsigned int bus_id; /**< ID as exposed in the system */
+    unsigned int scl; /**< i2c SCL */
+    unsigned int sda; /**< i2c SDA */
+    /*@}*/
+} maa_i2c_bus_t;
+
+/**
+ * A Structure representing the physical properties of a spi bus.
+ */
+typedef struct {
+    /*@{*/
+    unsigned int bus_id; /**< The Bus ID as exposed to the system. */
+    unsigned int slave_s; /**< Slave select */
+    maa_boolean_t three_wire; /**< Is the bus only a three wire system */
+    unsigned int sclk; /**< Serial Clock */
+    unsigned int mosi; /**< Master Out, Slave In. */
+    unsigned int miso; /**< Master In, Slave Out. */
+    unsigned int cs; /**< Chip Select, used when the board is a spi slave */
+    /*@}*/
+} maa_spi_bus_t;
+
+/**
+ * A Structure representing a platform/board.
+ */
+typedef struct {
+    /*@{*/
+    unsigned int phy_pin_count; /**< The Total IO pins on board */
+    unsigned int gpio_count; /**< GPIO Count */
+    unsigned int aio_count;  /**< Analog side Count */
+    unsigned int i2c_bus_count; /**< Usable i2c Count */
+    maa_i2c_bus_t  i2c_bus[6]; /**< Array of i2c */
+    unsigned int def_i2c_bus; /**< Position in array of default i2c bus */
+    unsigned int spi_bus_count; /**< Usable spi Count */
+    maa_spi_bus_t spi_bus[6];       /**< Array of spi */
+    unsigned int def_spi_bus; /**< Position in array of defult spi bus */
+    maa_pininfo_t* pins;     /**< Pointer to pin array */
+    /*@}*/
+} maa_board_t;
+
+/**
+ * Initialise MAA
+ *
+ * Detects running platform and attempts to use included pinmap
+ *
+ * @return Result of operation
+ */
+#ifndef SWIG
+// this sets a compiler attribute (supported by GCC & clang) to have maa_init()
+// be called as a constructor make sure your libc supports this!  uclibc needs
+// to be compiled with UCLIBC_CTOR_DTOR
+maa_result_t maa_init() __attribute__((constructor));
+#else
+maa_result_t maa_init();
+#endif
+
+/**
+ * This function attempts to set the maa process to a given priority and the
+ * scheduler to SCHED_RR. Highest * priority is typically 99 and minimum is 0.
+ * This function * will set to MAX if * priority is > MAX. Function will return
+ * -1 on failure.
+
+ * @param priority Value from typically 0 to 99
+ * @return The priority value set
+ */
+int maa_set_priority(const unsigned int priority);
+
+/** Get the version string of maa autogenerated from git tag
+ *
+ * The version returned may not be what is expected however it is a reliable
+ * number associated with the git tag closest to that version at build time
+ *
+ * @return version string from version.h
+ */
+const char* maa_get_version();
+
+/**
+ * Print a textual representation of the maa_result_t
+ *
+ * @param result the result to print
+ */
+void maa_result_print(maa_result_t result);
+
+/**
+ * Checks if a pin is able to use the passed in mode.
+ *
+ * @param pin Physical Pin to be checked.
+ * @param mode the mode to be tested.
+ * @return boolean if the mode is supported, 0=false.
+ */
+maa_boolean_t maa_pin_mode_test(int pin, maa_pinmodes_t mode);
+
+#ifdef __cplusplus
+}
+#endif

api/maa/gpio.h

@@ -48,7 +48,7 @@ extern "C" {
 #include <stdio.h>
 #include <pthread.h>
 
-#include "maa.h"
+#include "common.h"
 
 /**
  * Opaque pointer definition to the internal struct _gpio

api/maa/i2c.h

@@ -46,7 +46,7 @@ extern "C" {
 #include <fcntl.h>
 #include <stdint.h>
 
-#include "maa.h"
+#include "common.h"
 #include "gpio.h"
 
 /**

api/maa/pwm.h

@@ -43,7 +43,7 @@ extern "C" {
 #include <stdio.h>
 #include <fcntl.h>
 
-#include "maa.h"
+#include "common.h"
 
 typedef struct _pwm* maa_pwm_context;
 

api/maa/spi.h

@@ -41,7 +41,7 @@ extern "C" {
 #include <fcntl.h>
 #include <stdint.h>
 
-#include "maa.h"
+#include "common.h"
 
 /**
  * Opaque pointer definition to the internal struct _spi

docs/index.md

@@ -16,14 +16,14 @@ classes directly wrap the C API and provide a near 1:1 mapping of
 functionality.
 
 <center>
-| C API Modules       | C++ API Classes             |
+| C API Modules          | C++ API Classes             |
-|:-------------------:|:---------------------------:|
+|:----------------------:|:---------------------------:|
-| @ref gpio.h "gpio"  | @ref maa::Gpio "Gpio class" |
+| @ref gpio.h "gpio"     | @ref maa::Gpio "Gpio class" |
-| @ref i2c.h "i2c"    | @ref maa::I2c "I2c class"   |
+| @ref i2c.h "i2c"       | @ref maa::I2c "I2c class"   |
-| @ref aio.h "aio"    | @ref maa::Aio "Aio class"   |
+| @ref aio.h "aio"       | @ref maa::Aio "Aio class"   |
-| @ref pwm.h "pwm"    | @ref maa::Pwm "Pwm class"   |
+| @ref pwm.h "pwm"       | @ref maa::Pwm "Pwm class"   |
-| @ref spi.h "spi"    | @ref maa::Spi "Spi class"   |
+| @ref spi.h "spi"       | @ref maa::Spi "Spi class"   |
-| @ref maa.h "maa"    | @ref maa.h "maa"            |
+| @ref common.h "common" | @ref common.h "common"      |
 </center>
 
 ### Hello Maa

include/maa_internal.h

@@ -24,7 +24,7 @@
 
 #pragma once
 
-#include "maa.h"
+#include "common.h"
 
 /** Setup gpio
  *

src/CMakeLists.txt

@@ -55,7 +55,7 @@ if (DOXYGEN_FOUND)
     add_custom_target (${_file}class_doc_i DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${_file}_class_doc.i)
     add_dependencies (${_file}class_doc_i doc)
   endforeach ()
-  set (DOCFILES maa ${DOCCLASSES})
+  set (DOCFILES common ${DOCCLASSES})
   foreach (_file ${DOCFILES})
     add_custom_command (OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${_file}_doc.i
       COMMAND ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/doxy2swig.py -n

src/intel_galileo_rev_d.c

@@ -25,7 +25,7 @@
 #include <stdlib.h>
 #include <string.h>
 
-#include "maa.h"
+#include "common.h"
 
 maa_board_t*
 maa_intel_galileo_rev_d()

src/maa.c

@@ -28,7 +28,6 @@
 #include <sched.h>
 #include <string.h>
 
-#include "maa.h"
 #include "maa_internal.h"
 #include "intel_galileo_rev_d.h"
 #include "gpio.h"

src/maa.i

@@ -1,5 +1,5 @@
 #ifdef DOXYGEN
-    %include maa_doc.i
+    %include common_doc.i
     %include gpio_class_doc.i
     %include i2c_class_doc.i
     %include pwm_class_doc.i
@@ -8,7 +8,7 @@
 #endif
 
 %{
-    #include "maa.h"
+    #include "common.h"
     #include "gpio.hpp"
     #include "pwm.hpp"
     #include "i2c.hpp"

src/python/CMakeLists.txt

@@ -17,7 +17,7 @@ if (DOXYGEN_FOUND)
   foreach (_file ${DOCCLASSES})
     add_dependencies (${SWIG_MODULE_pymaa_REAL_NAME} ${_file}class_doc_i)
   endforeach ()
-  add_dependencies (${SWIG_MODULE_pymaa_REAL_NAME} maadoc_i)
+  add_dependencies (${SWIG_MODULE_pymaa_REAL_NAME} commondoc_i)
 
   add_custom_target (pydoc
     pydoc -w ${CMAKE_CURRENT_BINARY_DIR}/pymaa.py ${CMAKE_CURRENT_BINARY_DIR}/