Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
pinmap.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2006-2013 ARM Limited
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 #ifndef MBED_PINMAP_H
21 #define MBED_PINMAP_H
22 
23 #include "PinNames.h"
24 #include <stdbool.h>
25 #include <stdint.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 typedef struct {
32  PinName pin;
33  int peripheral;
34  int function;
35 } PinMap;
36 
37 typedef struct {
38  uint32_t count;
39  const PinName *pins;
40 } PinList;
41 
42 typedef struct {
43  uint32_t count;
44  const int *peripheral;
45 } PeripheralList;
46 
47 void pin_function(PinName pin, int function);
48 void pin_mode(PinName pin, PinMode mode);
49 
50 uint32_t pinmap_peripheral(PinName pin, const PinMap *map);
51 uint32_t pinmap_function(PinName pin, const PinMap *map);
52 uint32_t pinmap_merge(uint32_t a, uint32_t b);
53 void pinmap_pinout(PinName pin, const PinMap *map);
54 uint32_t pinmap_find_peripheral(PinName pin, const PinMap *map);
55 uint32_t pinmap_find_function(PinName pin, const PinMap *map);
56 
57 /**
58  * Find a combination of pins suitable for use given the constraints
59  *
60  * This function finds pins which meet these specific properties:
61  * - The pin is part of the form factor
62  * - The pin is not in the restricted list
63  * - The pin is contained within the respective pinmap
64  * - The pin belongs to the given peripheral
65  * - Each pin found is distinct; in the example below
66  * mosi and miso will never be assigned the same pin
67  *
68  * Example:
69  * @code
70  * #include "mbed.h"
71  * #include "pinmap.h"
72  *
73  * int main()
74  * {
75  * int per = spi_master_cs_pinmap()->peripheral;
76  * const PinList *pins_ff = pinmap_ff_default_pins();
77  * const PinList *pins_avoid = pinmap_restricted_pins();
78  * PinName mosi = NC;
79  * PinName miso = NC;
80  * PinName sclk = NC;
81  * PinName ssel = NC;
82  * const PinMap *maps[] = {
83  * spi_master_mosi_pinmap(),
84  * spi_master_miso_pinmap(),
85  * spi_master_clk_pinmap(),
86  * spi_master_cs_pinmap()
87  * };
88  * PinName *pins[] = {
89  * &mosi,
90  * &miso,
91  * &sclk,
92  * &ssel
93  * };
94  * if (pinmap_find_peripheral_pins(pins_ff, pins_avoid, per, maps, pins, sizeof(maps) / sizeof(maps[0]))) {
95  * printf("Found SPI pins to test instance %i with:\n"
96  * " mosi=%s\n"
97  * " miso=%s\n"
98  * " sclk=%s\n"
99  * " ssel=%s\n", per,
100  * pinmap_ff_default_pin_to_string(mosi),
101  * pinmap_ff_default_pin_to_string(miso),
102  * pinmap_ff_default_pin_to_string(sclk),
103  * pinmap_ff_default_pin_to_string(ssel));
104  * } else {
105  * printf("Could not find SPI combination to test %i\n", per);
106  * }
107  * return 0;
108  * }
109  * @endcode
110  *
111  * @param whitelist List of pins to choose from
112  * @param blacklist List of pins which cannot be used
113  * @param per Peripheral to which the pins belong
114  * @param maps An array of pin maps to select from
115  * @param pins An array of pins to find. Pins already set to a value will be
116  * left unchanged. Only pins initialized to NC will be updated by this function
117  * @param count The size of maps and pins
118  * @return true if a suitable combination of pins was found and
119  * written to the pins array, otherwise false
120  */
121 bool pinmap_find_peripheral_pins(const PinList *whitelist, const PinList *blacklist, int per, const PinMap *const *maps, PinName **pins, uint32_t count);
122 
123 /**
124  * Check if the pin is in the list
125  *
126  * @param list pin list to check
127  * @param pin pin to check for in the list
128  * @return true if the pin is in the list, false otherwise
129  */
130 bool pinmap_list_has_pin(const PinList *list, PinName pin);
131 
132 /**
133  * Check if the peripheral is in the list
134  *
135  * @param list peripheral list to check
136  * @param peripheral peripheral to check for in the list
137  * @return true if the peripheral is in the list, false otherwise
138  */
139 bool pinmap_list_has_peripheral(const PeripheralList *list, int peripheral);
140 
141 /**
142  * Get the pin list of pins to avoid during testing
143  *
144  * The restricted pin list is used to indicate to testing
145  * that a pin should be skipped due to some caveat about it.
146  * For example, using USBRX and USBTX during tests will interfere
147  * with the test runner and should be avoided.
148  *
149  * Targets should override the weak implementation of this
150  * function if they have additional pins which should be
151  * skipped during testing.
152  *
153  * @return Pointer to a pin list of pins to avoid
154  */
155 const PinList *pinmap_restricted_pins(void);
156 
157 /**
158  * Get the pin list of peripherals per interface to avoid during testing
159  *
160  * The restricted peripheral list is used to indicate to testing
161  * that a peripheral should be skipped due to some caveat about it.
162  * For example, using the USB serial port during tests will interfere
163  * with the test runner and should be avoided.
164  *
165  * Targets should override the weak implementation of this
166  * function if they have peripherals which should be
167  * skipped during testing.
168  *
169  * @note Restricting peripheral is at the moment available for UART
170  * interface only as only STDIO UART must be skipped because it is
171  * used by Mbed.
172  * Restricting peripherals for other interfaces should be added
173  * in the future if required.
174  *
175  * @return Pointer to a peripheral list of peripheral to avoid
176  */
177 #if DEVICE_SERIAL
178 const PeripheralList *pinmap_uart_restricted_peripherals(void);
179 #endif
180 
181 /**
182  * Get the pin list of pins to avoid during GPIO/GPIO_IRQ testing
183  *
184  * The GPIO restricted pin list is used to indicate to testing
185  * that a pin should be skipped due to some caveat about it.
186  *
187  * Targets should override the weak implementation of this
188  * function if they have peripherals which should be
189  * skipped during testing.
190  *
191  * @note This is special case only for GPIO/GPIO_IRQ tests because
192  * targets do not provide pin-maps for GPIO.
193  *
194  * @return Pointer to a peripheral list of peripheral to avoid
195  */
196 const PinList *pinmap_gpio_restricted_pins(void);
197 
198 #ifdef TARGET_FF_ARDUINO
199 
200 /**
201  * Get the pin list of the Arduino form factor
202  *
203  * @return Pointer to the Arduino pin list
204  */
205 const PinList *pinmap_ff_arduino_pins(void);
206 
207 /**
208  * Get the string representation of a form factor pin
209  *
210  * @param pin Pin to get a string for
211  * @return String representing the form factor pin
212  */
213 const char *pinmap_ff_arduino_pin_to_string(PinName pin);
214 
215 /* Default to arduino form factor if unspecified */
216 #ifndef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
217 #define MBED_CONF_TARGET_DEFAULT_FORM_FACTOR arduino
218 #endif
219 
220 #endif
221 
222 #ifdef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
223 
224 #define PINMAP_DEFAULT_PINS_(name) pinmap_ff_ ## name ## _pins
225 #define PINMAP_DEFAULT_PIN_TO_STRING_(name) pinmap_ff_ ## name ## _pin_to_string
226 #define PINMAP_DEFAULT_PINS(name) PINMAP_DEFAULT_PINS_(name)
227 #define PINMAP_DEFAULT_PIN_TO_STRING(name) PINMAP_DEFAULT_PIN_TO_STRING_(name)
228 #define pinmap_ff_default_pins PINMAP_DEFAULT_PINS(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
229 #define pinmap_ff_default_pin_to_string PINMAP_DEFAULT_PIN_TO_STRING(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
230 
231 /**
232  * Get the pin list of the default form factor
233  *
234  * This is an alias to whichever form factor is set
235  * to be the default.
236  *
237  * @return Pointer to the default pin list
238  */
239 const PinList *pinmap_ff_default_pins(void);
240 
241 /**
242  * Get the string representation of a form factor pin
243  *
244  * This is an alias to whichever form factor is set
245  * to be the default.
246  *
247  * @param pin Pin to get a string for
248  * @return String representing the form factor pin
249  */
250 const char *pinmap_ff_default_pin_to_string(PinName pin);
251 
252 #endif
253 
254 #ifdef __cplusplus
255 }
256 #endif
257 
258 #endif
259 
260 /** @}*/
PinList
Definition: pinmap.h:37
pinmap_list_has_peripheral
bool pinmap_list_has_peripheral(const PeripheralList *list, int peripheral)
Check if the peripheral is in the list.
pinmap_find_peripheral_pins
bool pinmap_find_peripheral_pins(const PinList *whitelist, const PinList *blacklist, int per, const PinMap *const *maps, PinName **pins, uint32_t count)
Find a combination of pins suitable for use given the constraints.
pinmap_list_has_pin
bool pinmap_list_has_pin(const PinList *list, PinName pin)
Check if the pin is in the list.
pinmap_gpio_restricted_pins
const PinList * pinmap_gpio_restricted_pins(void)
Get the pin list of pins to avoid during GPIO/GPIO_IRQ testing.
PinMap
Definition: pinmap.h:31
pinmap_restricted_pins
const PinList * pinmap_restricted_pins(void)
Get the pin list of pins to avoid during testing.
list
Connected isochronous stream linked list.
Definition: lctr_int_cis.h:306
pinmap_uart_restricted_peripherals
const PeripheralList * pinmap_uart_restricted_peripherals(void)
Get the pin list of peripherals per interface to avoid during testing.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.