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 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 Some targets use the same value for multiple
170  * different types of peripherals. For example SPI 0
171  * and UART 0 may both be identified by the peripheral
172  * value 0. If your target does this then do not
173  * use this function to skip peripherals, as this will
174  * unintentionally cause all peripherals with that value
175  * to be skipped. Instead these entries should be removed
176  * from the peripheral PinMap itself.
177  *
178  * @return Pointer to a peripheral list of peripheral to avoid
179  */
180 const PeripheralList *pinmap_restricted_peripherals(void);
181 
182 #ifdef TARGET_FF_ARDUINO
183 
184 /**
185  * Get the pin list of the Arduino form factor
186  *
187  * @return Pointer to the Arduino pin list
188  */
189 const PinList *pinmap_ff_arduino_pins(void);
190 
191 /**
192  * Get the string representation of a form factor pin
193  *
194  * @param pin Pin to get a string for
195  * @return String representing the form factor pin
196  */
197 const char *pinmap_ff_arduino_pin_to_string(PinName pin);
198 
199 /* Default to arduino form factor if unspecified */
200 #ifndef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
201 #define MBED_CONF_TARGET_DEFAULT_FORM_FACTOR arduino
202 #endif
203 
204 #endif
205 
206 #ifdef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
207 
208 #define PINMAP_DEFAULT_PINS_(name) pinmap_ff_ ## name ## _pins
209 #define PINMAP_DEFAULT_PIN_TO_STRING_(name) pinmap_ff_ ## name ## _pin_to_string
210 #define PINMAP_DEFAULT_PINS(name) PINMAP_DEFAULT_PINS_(name)
211 #define PINMAP_DEFAULT_PIN_TO_STRING(name) PINMAP_DEFAULT_PIN_TO_STRING_(name)
212 #define pinmap_ff_default_pins PINMAP_DEFAULT_PINS(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
213 #define pinmap_ff_default_pin_to_string PINMAP_DEFAULT_PIN_TO_STRING(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
214 
215 /**
216  * Get the pin list of the default form factor
217  *
218  * This is an alias to whichever form factor is set
219  * to be the default.
220  *
221  * @return Pointer to the default pin list
222  */
223 const PinList *pinmap_ff_default_pins(void);
224 
225 /**
226  * Get the string representation of a form factor pin
227  *
228  * This is an alias to whichever form factor is set
229  * to be the default.
230  *
231  * @param pin Pin to get a string for
232  * @return String representing the form factor pin
233  */
234 const char *pinmap_ff_default_pin_to_string(PinName pin);
235 
236 #endif
237 
238 #ifdef __cplusplus
239 }
240 #endif
241 
242 #endif
243 
244 /** @}*/
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_restricted_peripherals
const PeripheralList * pinmap_restricted_peripherals(void)
Get the pin list of peripherals to avoid during 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.
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.