pinmap.h

00001 
00002 /** \addtogroup hal */
00003 /** @{*/
00004 /* mbed Microcontroller Library
00005  * Copyright (c) 2006-2013 ARM Limited
00006  * SPDX-License-Identifier: Apache-2.0
00007  *
00008  * Licensed under the Apache License, Version 2.0 (the "License");
00009  * you may not use this file except in compliance with the License.
00010  * You may obtain a copy of the License at
00011  *
00012  *     http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  * Unless required by applicable law or agreed to in writing, software
00015  * distributed under the License is distributed on an "AS IS" BASIS,
00016  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017  * See the License for the specific language governing permissions and
00018  * limitations under the License.
00019  */
00020 #ifndef MBED_PINMAP_H
00021 #define MBED_PINMAP_H
00022 
00023 #include "PinNames.h"
00024 #include <stdbool.h>
00025 #include <stdint.h>
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif
00030 
00031 typedef struct {
00032     PinName pin;
00033     int peripheral;
00034     int function;
00035 } PinMap;
00036 
00037 typedef struct {
00038     uint32_t count;
00039     const PinName *pins;
00040 } PinList;
00041 
00042 typedef struct {
00043     uint32_t count;
00044     const int *peripheral;
00045 } PeripheralList;
00046 
00047 void pin_function(PinName pin, int function);
00048 void pin_mode(PinName pin, PinMode mode);
00049 
00050 uint32_t pinmap_peripheral(PinName pin, const PinMap *map);
00051 uint32_t pinmap_function(PinName pin, const PinMap *map);
00052 uint32_t pinmap_merge(uint32_t a, uint32_t b);
00053 void     pinmap_pinout(PinName pin, const PinMap *map);
00054 uint32_t pinmap_find_peripheral(PinName pin, const PinMap *map);
00055 uint32_t pinmap_find_function(PinName pin, const PinMap *map);
00056 
00057 /**
00058  * Find a combination of pins suitable for use given the constraints
00059  *
00060  * This function finds pins which meet these specific properties:
00061  * - The pin is part of the form factor
00062  * - The pin is not in the restricted list
00063  * - The pin is contained within the respective pinmap
00064  * - The pin belongs to the given peripheral
00065  * - Each pin found is distinct; in the example below
00066  *      mosi and miso will never be assigned the same pin
00067  *
00068  * Example:
00069  * @code
00070  * #include "mbed.h"
00071  * #include "pinmap.h"
00072  *
00073  * int main()
00074  * {
00075  *     int per = spi_master_cs_pinmap()->peripheral;
00076  *     const PinList *pins_ff = pinmap_ff_default_pins();
00077  *     const PinList *pins_avoid = pinmap_restricted_pins();
00078  *     PinName mosi = NC;
00079  *     PinName miso = NC;
00080  *     PinName sclk = NC;
00081  *     PinName ssel = NC;
00082  *     const PinMap *maps[] = {
00083  *         spi_master_mosi_pinmap(),
00084  *         spi_master_miso_pinmap(),
00085  *         spi_master_clk_pinmap(),
00086  *         spi_master_cs_pinmap()
00087  *     };
00088  *     PinName *pins[] = {
00089  *         &mosi,
00090  *         &miso,
00091  *         &sclk,
00092  *         &ssel
00093  *     };
00094  *     if (pinmap_find_peripheral_pins(pins_ff, pins_avoid, per, maps, pins, sizeof(maps) / sizeof(maps[0]))) {
00095  *         printf("Found SPI pins to test instance %i with:\n"
00096  *                "  mosi=%s\n"
00097  *                "  miso=%s\n"
00098  *                "  sclk=%s\n"
00099  *                "  ssel=%s\n", per,
00100  *                pinmap_ff_default_pin_to_string(mosi),
00101  *                pinmap_ff_default_pin_to_string(miso),
00102  *                pinmap_ff_default_pin_to_string(sclk),
00103  *                pinmap_ff_default_pin_to_string(ssel));
00104  *     } else {
00105  *         printf("Could not find SPI combination to test %i\n", per);
00106  *     }
00107  *     return 0;
00108  * }
00109  * @endcode
00110  *
00111  * @param whitelist List of pins to choose from
00112  * @param blacklist List of pins which cannot be used
00113  * @param per Peripheral to which the pins belong
00114  * @param maps An array of pin maps to select from
00115  * @param pins An array of pins to find. Pins already set to a value will be
00116  *             left unchanged. Only pins initialized to NC will be updated by this function
00117  * @param count The size of maps and pins
00118  * @return true if a suitable combination of pins was found and
00119  *         written to the pins array, otherwise false
00120  */
00121 bool pinmap_find_peripheral_pins(const PinList *whitelist, const PinList *blacklist, int per, const PinMap *const *maps, PinName **pins, uint32_t count);
00122 
00123 /**
00124  * Check if the pin is in the list
00125  *
00126  * @param list pin list to check
00127  * @param pin pin to check for in the list
00128  * @return true if the pin is in the list, false otherwise
00129  */
00130 bool pinmap_list_has_pin(const PinList *list, PinName pin);
00131 
00132 /**
00133  * Check if the peripheral is in the list
00134  *
00135  * @param list peripheral list to check
00136  * @param peripheral peripheral to check for in the list
00137  * @return true if the peripheral is in the list, false otherwise
00138  */
00139 bool pinmap_list_has_peripheral(const PeripheralList *list, int peripheral);
00140 
00141 /**
00142  * Get the pin list of pins to avoid during testing
00143  *
00144  * The restricted pin list is used to indicate to testing
00145  * that a pin should be skipped due to some caveat about it.
00146  * For example, using USBRX and USBTX during tests will interfere
00147  * with the test runner and should be avoided.
00148  *
00149  * Targets should override the weak implementation of this
00150  * function if they have additional pins which should be
00151  * skipped during testing.
00152  *
00153  * @return Pointer to a pin list of pins to avoid
00154  */
00155 const PinList *pinmap_restricted_pins(void);
00156 
00157 /**
00158  * Get the pin list of peripherals to avoid during testing
00159  *
00160  * The restricted peripheral list is used to indicate to testing
00161  * that a peripheral should be skipped due to some caveat about it.
00162  * For example, using the USB serial port during tests will interfere
00163  * with the test runner and should be avoided.
00164  *
00165  * Targets should override the weak implementation of this
00166  * function if they have peripherals which should be
00167  * skipped during testing.
00168  *
00169  * @note Some targets use the same value for multiple
00170  * different types of peripherals. For example SPI 0
00171  * and UART 0 may both be identified by the peripheral
00172  * value 0. If your target does this then do not
00173  * use this function to skip peripherals, as this will
00174  * unintentionally cause all peripherals with that value
00175  * to be skipped. Instead these entries should be removed
00176  * from the peripheral PinMap itself.
00177  *
00178  * @return Pointer to a peripheral list of peripheral to avoid
00179  */
00180 const PeripheralList *pinmap_restricted_peripherals(void);
00181 
00182 #ifdef TARGET_FF_ARDUINO
00183 
00184 /**
00185  * Get the pin list of the Arduino form factor
00186  *
00187  * @return Pointer to the Arduino pin list
00188  */
00189 const PinList *pinmap_ff_arduino_pins(void);
00190 
00191 /**
00192  * Get the string representation of a form factor pin
00193  *
00194  * @param pin Pin to get a string for
00195  * @return String representing the form factor pin
00196  */
00197 const char *pinmap_ff_arduino_pin_to_string(PinName pin);
00198 
00199 /* Default to arduino form factor if unspecified */
00200 #ifndef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
00201 #define MBED_CONF_TARGET_DEFAULT_FORM_FACTOR arduino
00202 #endif
00203 
00204 #endif
00205 
00206 #ifdef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
00207 
00208 #define PINMAP_DEFAULT_PINS_(name)              pinmap_ff_ ## name ## _pins
00209 #define PINMAP_DEFAULT_PIN_TO_STRING_(name)     pinmap_ff_ ## name ## _pin_to_string
00210 #define PINMAP_DEFAULT_PINS(name)               PINMAP_DEFAULT_PINS_(name)
00211 #define PINMAP_DEFAULT_PIN_TO_STRING(name)      PINMAP_DEFAULT_PIN_TO_STRING_(name)
00212 #define pinmap_ff_default_pins                  PINMAP_DEFAULT_PINS(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
00213 #define pinmap_ff_default_pin_to_string         PINMAP_DEFAULT_PIN_TO_STRING(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
00214 
00215 /**
00216  * Get the pin list of the default form factor
00217  *
00218  * This is an alias to whichever form factor is set
00219  * to be the default.
00220  *
00221  * @return Pointer to the default pin list
00222  */
00223 const PinList *pinmap_ff_default_pins(void);
00224 
00225 /**
00226  * Get the string representation of a form factor pin
00227  *
00228  * This is an alias to whichever form factor is set
00229  * to be the default.
00230  *
00231  * @param pin Pin to get a string for
00232  * @return String representing the form factor pin
00233  */
00234 const char *pinmap_ff_default_pin_to_string(PinName pin);
00235 
00236 #endif
00237 
00238 #ifdef __cplusplus
00239 }
00240 #endif
00241 
00242 #endif
00243 
00244 /** @}*/