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 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 typedef struct {
31  PinName pin;
32  int peripheral;
33  int function;
34 } PinMap;
35 
36 typedef struct {
37  uint32_t count;
38  const PinName *pins;
39 } PinList;
40 
41 typedef struct {
42  uint32_t count;
43  const int *peripheral;
44 } PeripheralList;
45 
46 void pin_function(PinName pin, int function);
47 void pin_mode(PinName pin, PinMode mode);
48 
49 uint32_t pinmap_peripheral(PinName pin, const PinMap *map);
50 uint32_t pinmap_function(PinName pin, const PinMap *map);
51 uint32_t pinmap_merge(uint32_t a, uint32_t b);
52 void pinmap_pinout(PinName pin, const PinMap *map);
53 uint32_t pinmap_find_peripheral(PinName pin, const PinMap *map);
54 uint32_t pinmap_find_function(PinName pin, const PinMap *map);
55 
56 /**
57  * Find a combination of pins suitable for use given the constraints
58  *
59  * This function finds pins which meet these specific properties:
60  * - The pin is part of the form factor
61  * - The pin is not in the restricted list
62  * - The pin is contained within the respective pinmap
63  * - The pin belongs to the given peripheral
64  * - Each pin found is distinct; in the example below
65  * mosi and miso will never be assigned the same pin
66  *
67  * Example:
68  * @code
69  * #include "mbed.h"
70  * #include "pinmap.h"
71  *
72  * int main()
73  * {
74  * int per = spi_master_cs_pinmap()->peripheral;
75  * const PinList *pins_ff = pinmap_ff_default_pins();
76  * const PinList *pins_avoid = pinmap_restricted_pins();
77  * PinName mosi = NC;
78  * PinName miso = NC;
79  * PinName sclk = NC;
80  * PinName ssel = NC;
81  * const PinMap *maps[] = {
82  * spi_master_mosi_pinmap(),
83  * spi_master_miso_pinmap(),
84  * spi_master_clk_pinmap(),
85  * spi_master_cs_pinmap()
86  * };
87  * PinName *pins[] = {
88  * &mosi,
89  * &miso,
90  * &sclk,
91  * &ssel
92  * };
93  * if (pinmap_find_peripheral_pins(pins_ff, pins_avoid, per, maps, pins, sizeof(maps) / sizeof(maps[0]))) {
94  * printf("Found SPI pins to test instance %i with:\n"
95  * " mosi=%s\n"
96  * " miso=%s\n"
97  * " sclk=%s\n"
98  * " ssel=%s\n", per,
99  * pinmap_ff_default_pin_to_string(mosi),
100  * pinmap_ff_default_pin_to_string(miso),
101  * pinmap_ff_default_pin_to_string(sclk),
102  * pinmap_ff_default_pin_to_string(ssel));
103  * } else {
104  * printf("Could not find SPI combination to test %i\n", per);
105  * }
106  * return 0;
107  * }
108  * @endcode
109  *
110  * @param whitelist List of pins to choose from
111  * @param blacklist List of pins which cannot be used
112  * @param per Peripheral to which the pins belong
113  * @param maps An array of pin maps to select from
114  * @param pins An array of pins to find. Pins already set to a value will be
115  * left unchanged. Only pins initialized to NC will be updated by this function
116  * @param count The size of maps and pins
117  * @return true if a suitable combination of pins was found and
118  * written to the pins array, otherwise false
119  */
120 bool pinmap_find_peripheral_pins(const PinList *whitelist, const PinList *blacklist, int per, const PinMap *const *maps, PinName **pins, uint32_t count);
121 
122 /**
123  * Check if the pin is in the list
124  *
125  * @param list pin list to check
126  * @param pin pin to check for in the list
127  * @return true if the pin is in the list, false otherwise
128  */
129 bool pinmap_list_has_pin(const PinList *list, PinName pin);
130 
131 /**
132  * Check if the peripheral is in the list
133  *
134  * @param list peripheral list to check
135  * @param peripheral peripheral to check for in the list
136  * @return true if the peripheral is in the list, false otherwise
137  */
138 bool pinmap_list_has_peripheral(const PeripheralList *list, int peripheral);
139 
140 /**
141  * Get the pin list of pins to avoid during testing
142  *
143  * The restricted pin list is used to indicate to testing
144  * that a pin should be skipped due to some caveat about it.
145  * For example, using USBRX and USBTX during tests will interfere
146  * with the test runner and should be avoided.
147  *
148  * Targets should override the weak implementation of this
149  * function if they have additional pins which should be
150  * skipped during testing.
151  *
152  * @return Pointer to a pin list of pins to avoid
153  */
154 const PinList *pinmap_restricted_pins(void);
155 
156 /**
157  * Get the pin list of peripherals to avoid during testing
158  *
159  * The restricted peripheral list is used to indicate to testing
160  * that a peripheral should be skipped due to some caveat about it.
161  * For example, using the USB serial port during tests will interfere
162  * with the test runner and should be avoided.
163  *
164  * Targets should override the weak implementation of this
165  * function if they have peripherals which should be
166  * skipped during testing.
167  *
168  * @note Some targets use the same value for multiple
169  * different types of peripherals. For example SPI 0
170  * and UART 0 may both be identified by the peripheral
171  * value 0. If your target does this then do not
172  * use this function to skip peripherals, as this will
173  * unintentionally cause all peripherals with that value
174  * to be skipped. Instead these entries should be removed
175  * from the peripheral PinMap itself.
176  *
177  * @return Pointer to a peripheral list of peripheral to avoid
178  */
179 const PeripheralList *pinmap_restricted_peripherals(void);
180 
181 #ifdef TARGET_FF_ARDUINO
182 
183 /**
184  * Get the pin list of the Arduino form factor
185  *
186  * @return Pointer to the Arduino pin list
187  */
188 const PinList *pinmap_ff_arduino_pins(void);
189 
190 /**
191  * Get the string representation of a form factor pin
192  *
193  * @param pin Pin to get a string for
194  * @return String representing the form factor pin
195  */
196 const char *pinmap_ff_arduino_pin_to_string(PinName pin);
197 
198 /* Default to arduino form factor if unspecified */
199 #ifndef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
200 #define MBED_CONF_TARGET_DEFAULT_FORM_FACTOR arduino
201 #endif
202 
203 #endif
204 
205 #ifdef MBED_CONF_TARGET_DEFAULT_FORM_FACTOR
206 
207 #define PINMAP_DEFAULT_PINS_(name) pinmap_ff_ ## name ## _pins
208 #define PINMAP_DEFAULT_PIN_TO_STRING_(name) pinmap_ff_ ## name ## _pin_to_string
209 #define PINMAP_DEFAULT_PINS(name) PINMAP_DEFAULT_PINS_(name)
210 #define PINMAP_DEFAULT_PIN_TO_STRING(name) PINMAP_DEFAULT_PIN_TO_STRING_(name)
211 #define pinmap_ff_default_pins PINMAP_DEFAULT_PINS(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
212 #define pinmap_ff_default_pin_to_string PINMAP_DEFAULT_PIN_TO_STRING(MBED_CONF_TARGET_DEFAULT_FORM_FACTOR)
213 
214 /**
215  * Get the pin list of the default form factor
216  *
217  * This is an alias to whichever form factor is set
218  * to be the default.
219  *
220  * @return Pointer to the default pin list
221  */
222 const PinList *pinmap_ff_default_pins(void);
223 
224 /**
225  * Get the string representation of a form factor pin
226  *
227  * This is an alias to whichever form factor is set
228  * to be the default.
229  *
230  * @param pin Pin to get a string for
231  * @return String representing the form factor pin
232  */
233 const char *pinmap_ff_default_pin_to_string(PinName pin);
234 
235 #endif
236 
237 #ifdef __cplusplus
238 }
239 #endif
240 
241 #endif
242 
243 /** @}*/
PinList
Definition: pinmap.h:36
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:30
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.