Diff: mbed-dev/targets/TARGET_Atmel/TARGET_SAM_CortexM4/services/ioport/ioport.h

Revision:

18:6a4db94011d3

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mbed-dev/targets/TARGET_Atmel/TARGET_SAM_CortexM4/services/ioport/ioport.h	Sun May 14 23:18:57 2017 +0000
@@ -0,0 +1,541 @@
+/**
+ * \file
+ *
+ * \brief Common IOPORT service main header file for AVR, UC3 and ARM
+ *        architectures.
+ *
+ * Copyright (c) 2012-2015 Atmel Corporation. All rights reserved.
+ *
+ * \asf_license_start
+ *
+ * \page License
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. The name of Atmel may not be used to endorse or promote products derived
+ *    from this software without specific prior written permission.
+ *
+ * 4. This software may only be redistributed and used in connection with an
+ *    Atmel microcontroller product.
+ *
+ * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
+ * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ * \asf_license_stop
+ *
+ */
+/*
+ * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
+ */
+#ifndef IOPORT_H
+#define IOPORT_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <parts.h>
+#include <compiler.h>
+
+/**
+ * \defgroup ioport_group Common IOPORT API
+ *
+ * See \ref ioport_quickstart.
+ *
+ * This is common IOPORT service for GPIO pin configuration and control in a
+ * standardized manner across the MEGA, MEGA_RF, XMEGA, UC3 and ARM devices.
+ *
+ * Port pin control code is optimized for each platform, and should produce
+ * both compact and fast execution times when used with constant values.
+ *
+ * \section dependencies Dependencies
+ * This driver depends on the following modules:
+ * - \ref sysclk_group for clock speed and functions.
+ * @{
+ */
+
+/**
+ * \def IOPORT_CREATE_PIN(port, pin)
+ * \brief Create IOPORT pin number
+ *
+ * Create a IOPORT pin number for use with the IOPORT functions.
+ *
+ * \param port IOPORT port (e.g. PORTA, PA or PIOA depending on chosen
+ *             architecture)
+ * \param pin IOPORT zero-based index of the I/O pin
+ */
+
+/** \brief IOPORT pin directions */
+enum ioport_direction {
+    IOPORT_DIR_INPUT,  /*!< IOPORT input direction */
+    IOPORT_DIR_OUTPUT, /*!< IOPORT output direction */
+};
+
+/** \brief IOPORT levels */
+enum ioport_value {
+    IOPORT_PIN_LEVEL_LOW,  /*!< IOPORT pin value low */
+    IOPORT_PIN_LEVEL_HIGH, /*!< IOPORT pin value high */
+};
+
+#if MEGA_RF
+/** \brief IOPORT edge sense modes */
+enum ioport_sense {
+    IOPORT_SENSE_LEVEL,     /*!< IOPORT sense low level  */
+    IOPORT_SENSE_BOTHEDGES, /*!< IOPORT sense both rising and falling edges */
+    IOPORT_SENSE_FALLING,   /*!< IOPORT sense falling edges */
+    IOPORT_SENSE_RISING,    /*!< IOPORT sense rising edges */
+};
+#elif SAM && !SAM4L
+/** \brief IOPORT edge sense modes */
+enum ioport_sense {
+    IOPORT_SENSE_BOTHEDGES, /*!< IOPORT sense both rising and falling edges */
+    IOPORT_SENSE_FALLING,   /*!< IOPORT sense falling edges */
+    IOPORT_SENSE_RISING,    /*!< IOPORT sense rising edges */
+    IOPORT_SENSE_LEVEL_LOW, /*!< IOPORT sense low level  */
+    IOPORT_SENSE_LEVEL_HIGH,/*!< IOPORT sense High level  */
+};
+#else
+enum ioport_sense {
+    IOPORT_SENSE_BOTHEDGES, /*!< IOPORT sense both rising and falling edges */
+    IOPORT_SENSE_RISING,    /*!< IOPORT sense rising edges */
+    IOPORT_SENSE_FALLING,   /*!< IOPORT sense falling edges */
+};
+#endif
+
+
+#if XMEGA
+# include "xmega/ioport.h"
+# if defined(IOPORT_XMEGA_COMPAT)
+#  include "xmega/ioport_compat.h"
+# endif
+#elif MEGA
+#  include "mega/ioport.h"
+#elif UC3
+# include "uc3/ioport.h"
+#elif SAM
+# if SAM4L
+#  include "sam/ioport_gpio.h"
+# elif (SAMD20 | SAMD21)
+#  include "sam0/ioport.h"
+# else
+#  include "sam/ioport_pio.h"
+# endif
+#endif
+
+/**
+ * \brief Initializes the IOPORT service, ready for use.
+ *
+ * This function must be called before using any other functions in the IOPORT
+ * service.
+ */
+static inline void ioport_init(void)
+{
+    arch_ioport_init();
+}
+
+/**
+ * \brief Enable an IOPORT pin, based on a pin created with \ref
+ * IOPORT_CREATE_PIN().
+ *
+ * \param pin  IOPORT pin to enable
+ */
+static inline void ioport_enable_pin(ioport_pin_t pin)
+{
+    arch_ioport_enable_pin(pin);
+}
+
+/**
+ * \brief Enable multiple pins in a single IOPORT port.
+ *
+ * \param port IOPORT port to enable
+ * \param mask Mask of pins within the port to enable
+ */
+static inline void ioport_enable_port(ioport_port_t port,
+                                      ioport_port_mask_t mask)
+{
+    arch_ioport_enable_port(port, mask);
+}
+
+/**
+ * \brief Disable IOPORT pin, based on a pin created with \ref
+ *        IOPORT_CREATE_PIN().
+ *
+ * \param pin IOPORT pin to disable
+ */
+static inline void ioport_disable_pin(ioport_pin_t pin)
+{
+    arch_ioport_disable_pin(pin);
+}
+
+/**
+ * \brief Disable multiple pins in a single IOPORT port.
+ *
+ * \param port IOPORT port to disable
+ * \param mask Pin mask of pins to disable
+ */
+static inline void ioport_disable_port(ioport_port_t port,
+                                       ioport_port_mask_t mask)
+{
+    arch_ioport_disable_port(port, mask);
+}
+
+/**
+ * \brief Set multiple pin modes in a single IOPORT port, such as pull-up,
+ * pull-down, etc. configuration.
+ *
+ * \param port IOPORT port to configure
+ * \param mask Pin mask of pins to configure
+ * \param mode Mode masks to configure for the specified pins (\ref
+ * ioport_modes)
+ */
+static inline void ioport_set_port_mode(ioport_port_t port,
+                                        ioport_port_mask_t mask, ioport_mode_t mode)
+{
+    arch_ioport_set_port_mode(port, mask, mode);
+}
+
+/**
+ * \brief Set pin mode for one single IOPORT pin.
+ *
+ * \param pin IOPORT pin to configure
+ * \param mode Mode masks to configure for the specified pin (\ref ioport_modes)
+ */
+static inline void ioport_set_pin_mode(ioport_pin_t pin, ioport_mode_t mode)
+{
+    arch_ioport_set_pin_mode(pin, mode);
+}
+
+/**
+ * \brief Reset multiple pin modes in a specified IOPORT port to defaults.
+ *
+ * \param port IOPORT port to configure
+ * \param mask Mask of pins whose mode configuration is to be reset
+ */
+static inline void ioport_reset_port_mode(ioport_port_t port,
+        ioport_port_mask_t mask)
+{
+    arch_ioport_set_port_mode(port, mask, 0);
+}
+
+/**
+ * \brief Reset pin mode configuration for a single IOPORT pin
+ *
+ * \param pin IOPORT pin to configure
+ */
+static inline void ioport_reset_pin_mode(ioport_pin_t pin)
+{
+    arch_ioport_set_pin_mode(pin, 0);
+}
+
+/**
+ * \brief Set I/O direction for a group of pins in a single IOPORT.
+ *
+ * \param port IOPORT port to configure
+ * \param mask Pin mask of pins to configure
+ * \param dir Direction to set for the specified pins (\ref ioport_direction)
+ */
+static inline void ioport_set_port_dir(ioport_port_t port,
+                                       ioport_port_mask_t mask, enum ioport_direction dir)
+{
+    arch_ioport_set_port_dir(port, mask, dir);
+}
+
+/**
+ * \brief Set direction for a single IOPORT pin.
+ *
+ * \param pin IOPORT pin to configure
+ * \param dir Direction to set for the specified pin (\ref ioport_direction)
+ */
+static inline void ioport_set_pin_dir(ioport_pin_t pin,
+                                      enum ioport_direction dir)
+{
+    arch_ioport_set_pin_dir(pin, dir);
+}
+
+/**
+ * \brief Set an IOPORT pin to a specified logical value.
+ *
+ * \param pin IOPORT pin to configure
+ * \param level Logical value of the pin
+ */
+static inline void ioport_set_pin_level(ioport_pin_t pin, bool level)
+{
+    arch_ioport_set_pin_level(pin, level);
+}
+
+/**
+ * \brief Set a group of IOPORT pins in a single port to a specified logical
+ * value.
+ *
+ * \param port IOPORT port to write to
+ * \param mask Pin mask of pins to modify
+ * \param level Level of the pins to be modified
+ */
+static inline void ioport_set_port_level(ioport_port_t port,
+        ioport_port_mask_t mask, ioport_port_mask_t level)
+{
+    arch_ioport_set_port_level(port, mask, level);
+}
+
+/**
+ * \brief Get current value of an IOPORT pin, which has been configured as an
+ * input.
+ *
+ * \param pin IOPORT pin to read
+ * \return Current logical value of the specified pin
+ */
+static inline bool ioport_get_pin_level(ioport_pin_t pin)
+{
+    return arch_ioport_get_pin_level(pin);
+}
+
+/**
+ * \brief Get current value of several IOPORT pins in a single port, which have
+ * been configured as an inputs.
+ *
+ * \param port IOPORT port to read
+ * \param mask Pin mask of pins to read
+ * \return Logical levels of the specified pins from the read port, returned as
+ * a mask.
+ */
+static inline ioport_port_mask_t ioport_get_port_level(ioport_pin_t port,
+        ioport_port_mask_t mask)
+{
+    return arch_ioport_get_port_level(port, mask);
+}
+
+/**
+ * \brief Toggle the value of an IOPORT pin, which has previously configured as
+ * an output.
+ *
+ * \param pin IOPORT pin to toggle
+ */
+static inline void ioport_toggle_pin_level(ioport_pin_t pin)
+{
+    arch_ioport_toggle_pin_level(pin);
+}
+
+/**
+ * \brief Toggle the values of several IOPORT pins located in a single port.
+ *
+ * \param port IOPORT port to modify
+ * \param mask Pin mask of pins to toggle
+ */
+static inline void ioport_toggle_port_level(ioport_port_t port,
+        ioport_port_mask_t mask)
+{
+    arch_ioport_toggle_port_level(port, mask);
+}
+
+/**
+ * \brief Set the pin sense mode of a single IOPORT pin.
+ *
+ * \param pin IOPORT pin to configure
+ * \param pin_sense Edge to sense for the pin (\ref ioport_sense)
+ */
+static inline void ioport_set_pin_sense_mode(ioport_pin_t pin,
+        enum ioport_sense pin_sense)
+{
+    arch_ioport_set_pin_sense_mode(pin, pin_sense);
+}
+
+/**
+ * \brief Set the pin sense mode of a multiple IOPORT pins on a single port.
+ *
+ * \param port IOPORT port to configure
+ * \param mask Bitmask if pins whose edge sense is to be configured
+ * \param pin_sense Edge to sense for the pins (\ref ioport_sense)
+ */
+static inline void ioport_set_port_sense_mode(ioport_port_t port,
+        ioport_port_mask_t mask,
+        enum ioport_sense pin_sense)
+{
+    arch_ioport_set_port_sense_mode(port, mask, pin_sense);
+}
+
+/**
+ * \brief Convert a pin ID into a its port ID.
+ *
+ * \param pin IOPORT pin ID to convert
+ * \retval Port ID for the given pin ID
+ */
+static inline ioport_port_t ioport_pin_to_port_id(ioport_pin_t pin)
+{
+    return arch_ioport_pin_to_port_id(pin);
+}
+
+/**
+ * \brief Convert a pin ID into a bitmask mask for the given pin on its port.
+ *
+ * \param pin IOPORT pin ID to convert
+ * \retval Bitmask with a bit set that corresponds to the given pin ID in its port
+ */
+static inline ioport_port_mask_t ioport_pin_to_mask(ioport_pin_t pin)
+{
+    return arch_ioport_pin_to_mask(pin);
+}
+
+/** @} */
+
+/**
+ * \page ioport_quickstart Quick start guide for the common IOPORT service
+ *
+ * This is the quick start guide for the \ref ioport_group, with
+ * step-by-step instructions on how to configure and use the service in a
+ * selection of use cases.
+ *
+ * The use cases contain several code fragments. The code fragments in the
+ * steps for setup can be copied into a custom initialization function, while
+ * the steps for usage can be copied into, e.g., the main application function.
+ *
+ * \section ioport_quickstart_basic Basic use case
+ * In this use case we will configure one IO pin for button input and one for
+ * LED control. Then it will read the button state and output it on the LED.
+ *
+ * \section ioport_quickstart_basic_setup Setup steps
+ *
+ * \subsection ioport_quickstart_basic_setup_code Example code
+ * \code
+	 #define MY_LED    IOPORT_CREATE_PIN(PORTA, 5)
+	 #define MY_BUTTON IOPORT_CREATE_PIN(PORTA, 6)
+
+	 ioport_init();
+
+	 ioport_set_pin_dir(MY_LED, IOPORT_DIR_OUTPUT);
+	 ioport_set_pin_dir(MY_BUTTON, IOPORT_DIR_INPUT);
+	 ioport_set_pin_mode(MY_BUTTON, IOPORT_MODE_PULLUP);
+\endcode
+ *
+ * \subsection ioport_quickstart_basic_setup_flow Workflow
+ * -# It's useful to give the GPIOs symbolic names and this can be done with
+ *    the \ref IOPORT_CREATE_PIN macro. We define one for a LED and one for a
+ *    button.
+ *   - \code
+	#define MY_LED    IOPORT_CREATE_PIN(PORTA, 5)
+	#define MY_BUTTON IOPORT_CREATE_PIN(PORTA, 6)
+\endcode
+ *   - \note The usefulness of the \ref IOPORT_CREATE_PIN macro and port names
+ *           differ between architectures:
+ *     - MEGA, MEGA_RF and XMEGA: Use \ref IOPORT_CREATE_PIN macro with port definitions
+ *              PORTA, PORTB ...
+ *     - UC3: Most convenient to pick up the device header file pin definition
+ *            and us it directly. E.g.: AVR32_PIN_PB06
+ *     - SAM: Most convenient to pick up the device header file pin definition
+ *            and us it directly. E.g.: PIO_PA5_IDX<br>
+ *            \ref IOPORT_CREATE_PIN can also be used with port definitions
+ *            PIOA, PIOB ...
+ * -# Initialize the ioport service. This typically enables the IO module if
+ *    needed.
+ *   - \code ioport_init(); \endcode
+ * -# Set the LED GPIO as output:
+ *   - \code ioport_set_pin_dir(MY_LED, IOPORT_DIR_OUTPUT); \endcode
+ * -# Set the button GPIO as input:
+ *   - \code ioport_set_pin_dir(MY_BUTTON, IOPORT_DIR_INPUT); \endcode
+ * -# Enable pull-up for the button GPIO:
+ *   - \code ioport_set_pin_mode(MY_BUTTON, IOPORT_MODE_PULLUP); \endcode
+ *
+ * \section ioport_quickstart_basic_usage Usage steps
+ *
+ * \subsection ioport_quickstart_basic_usage_code Example code
+ * \code
+	 bool value;
+
+	 value = ioport_get_pin_level(MY_BUTTON);
+	 ioport_set_pin_level(MY_LED, value);
+\endcode
+ *
+ * \subsection ioport_quickstart_basic_usage_flow Workflow
+ * -# Define a boolean variable for state storage:
+ *   - \code bool value; \endcode
+ * -# Read out the button level into variable value:
+ *   - \code value = ioport_get_pin_level(MY_BUTTON); \endcode
+ * -# Set the LED to read out value from the button:
+ *   - \code ioport_set_pin_level(MY_LED, value); \endcode
+ *
+ * \section ioport_quickstart_advanced Advanced use cases
+ * - \subpage ioport_quickstart_use_case_1 : Port access
+ */
+
+/**
+ * \page ioport_quickstart_use_case_1 Advanced use case doing port access
+ *
+ * In this case we will read out the pins from one whole port and write the
+ * read value to another port.
+ *
+ * \section ioport_quickstart_use_case_1_setup Setup steps
+ *
+ * \subsection ioport_quickstart_use_case_1_setup_code Example code
+ * \code
+	 #define IN_PORT  IOPORT_PORTA
+	 #define OUT_PORT IOPORT_PORTB
+	 #define MASK     0x00000060
+
+	 ioport_init();
+
+	 ioport_set_port_dir(IN_PORT, MASK, IOPORT_DIR_INPUT);
+	 ioport_set_port_dir(OUT_PORT, MASK, IOPORT_DIR_OUTPUT);
+\endcode
+ *
+ * \subsection ioport_quickstart_basic_setup_flow Workflow
+ * -# It's useful to give the ports symbolic names:
+ *   - \code
+	#define IN_PORT  IOPORT_PORTA
+	#define OUT_PORT IOPORT_PORTB
+\endcode
+ *   - \note The port names differ between architectures:
+ *     - MEGA_RF, MEGA and XMEGA: There are predefined names for ports: IOPORT_PORTA,
+ *              IOPORT_PORTB ...
+ *     - UC3: Use the index value of the different IO blocks: 0, 1 ...
+ *     - SAM: There are predefined names for ports: IOPORT_PIOA, IOPORT_PIOB
+ *            ...
+ * -# Also useful to define a mask for the bits to work with:
+ *     - \code #define MASK     0x00000060 \endcode
+ * -# Initialize the ioport service. This typically enables the IO module if
+ *    needed.
+ *   - \code ioport_init(); \endcode
+ * -# Set one of the ports as input:
+ *   - \code ioport_set_pin_dir(IN_PORT, MASK, IOPORT_DIR_INPUT); \endcode
+ * -# Set the other port as output:
+ *   - \code ioport_set_pin_dir(OUT_PORT, MASK, IOPORT_DIR_OUTPUT); \endcode
+ *
+ * \section ioport_quickstart_basic_usage Usage steps
+ *
+ * \subsection ioport_quickstart_basic_usage_code Example code
+ * \code
+	 ioport_port_mask_t value;
+
+	 value = ioport_get_port_level(IN_PORT, MASK);
+	 ioport_set_port_level(OUT_PORT, MASK, value);
+\endcode
+ *
+ * \subsection ioport_quickstart_basic_usage_flow Workflow
+ * -# Define a variable for port date storage:
+ *   - \code ioport_port_mask_t value; \endcode
+ * -# Read out from one port:
+ *   - \code value = ioport_get_port_level(IN_PORT, MASK); \endcode
+ * -# Put the read data out on the other port:
+ *   - \code ioport_set_port_level(OUT_PORT, MASK, value); \endcode
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* IOPORT_H */