Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
mbed_interface.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2019 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 #ifndef MBED_INTERFACE_H
18 #define MBED_INTERFACE_H
19 
20 #include <stdarg.h>
21 
22 #include "platform/mbed_toolchain.h"
23 #include "device.h"
24 
25 /** \addtogroup platform-public-api */
26 /** @{*/
27 
28 /**
29  * \defgroup platform_interface Network interface and other utility functions
30  * @{
31  */
32 
33 /* Mbed interface mac address
34  * if MBED_MAC_ADD_x are zero, interface uid sets mac address,
35  * otherwise MAC_ADD_x are used.
36  */
37 #define MBED_MAC_ADDR_INTERFACE 0x00
38 #define MBED_MAC_ADDR_0 MBED_MAC_ADDR_INTERFACE
39 #define MBED_MAC_ADDR_1 MBED_MAC_ADDR_INTERFACE
40 #define MBED_MAC_ADDR_2 MBED_MAC_ADDR_INTERFACE
41 #define MBED_MAC_ADDR_3 MBED_MAC_ADDR_INTERFACE
42 #define MBED_MAC_ADDR_4 MBED_MAC_ADDR_INTERFACE
43 #define MBED_MAC_ADDR_5 MBED_MAC_ADDR_INTERFACE
44 #define MBED_MAC_ADDRESS_SUM (MBED_MAC_ADDR_0 | MBED_MAC_ADDR_1 | MBED_MAC_ADDR_2 | MBED_MAC_ADDR_3 | MBED_MAC_ADDR_4 | MBED_MAC_ADDR_5)
45 
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49 
50 #if DEVICE_SEMIHOST
51 
52 /**
53  * \defgroup platform_interface interface functions
54  * @{
55  */
56 
57 /** Functions to control the mbed interface
58  *
59  * mbed Microcontrollers have a built-in interface to provide functionality such as
60  * drag-n-drop download, reset, serial-over-usb, and access to the mbed local file
61  * system. These functions provide means to control the interface using semihost
62  * calls it supports.
63  */
64 
65 /** Determine whether the mbed interface is connected, based on whether debug is enabled
66  *
67  * @returns
68  * 1 if interface is connected,
69  * 0 otherwise
70  */
71 int mbed_interface_connected(void);
72 
73 /** Instruct the mbed interface to reset, as if the reset button had been pressed
74  *
75  * @returns
76  * 1 if successful,
77  * 0 otherwise (e.g. interface not present)
78  */
79 int mbed_interface_reset(void);
80 
81 /** This will disconnect the debug aspect of the interface, so semihosting will be disabled.
82  * The interface will still support the USB serial aspect
83  *
84  * @returns
85  * 0 if successful,
86  * -1 otherwise (e.g. interface not present)
87  */
88 int mbed_interface_disconnect(void);
89 
90 /** This will disconnect the debug aspect of the interface, and if the USB cable is not
91  * connected, also power down the interface. If the USB cable is connected, the interface
92  * will remain powered up and visible to the host
93  *
94  * @returns
95  * 0 if successful,
96  * -1 otherwise (e.g. interface not present)
97  */
98 int mbed_interface_powerdown(void);
99 
100 /** This returns a string containing the 32-character UID of the mbed interface
101  * This is a weak function that can be overwritten if required
102  *
103  * @param uid A 33-byte array to write the null terminated 32-byte string
104  *
105  * @returns
106  * 0 if successful,
107  * -1 otherwise (e.g. interface not present)
108  */
109 int mbed_interface_uid(char *uid);
110 
111 #endif
112 
113 /** This returns a unique 6-byte MAC address, based on the interface UID
114  * If the interface is not present, it returns a default fixed MAC address (00:02:F7:F0:00:00)
115  *
116  * This is a weak function that can be overwritten if you want to provide your own mechanism to
117  * provide a MAC address.
118  *
119  * @param mac A 6-byte array to write the MAC address
120  */
121 void mbed_mac_address(char *mac);
122 
123 /** Cause the mbed to flash the BLOD (Blue LEDs Of Death) sequence
124  */
125 MBED_NORETURN void mbed_die(void);
126 
127 /** Print out an error message. This is typically called when
128  * handling a crash.
129  *
130  * @note Synchronization level: Interrupt safe, as long as the
131  * FileHandle::write of the stderr device is. See mbed_error_puts
132  * for more information.
133  * @note This uses an internal 128-byte buffer to format the string,
134  * so the output may be truncated. If you need to write a potentially
135  * long string, use mbed_error_puts.
136  *
137  * @param format C string that contains data stream to be printed.
138  * Code snippets below show valid format.
139  *
140  * @code
141  * mbed_error_printf("Failed: %s, file: %s, line %d \n", expr, file, line);
142  * @endcode
143  *
144  */
145 void mbed_error_printf(const char *format, ...) MBED_PRINTF(1, 2);
146 
147 /** Print out an error message. Similar to mbed_error_printf
148  * but uses a va_list.
149  *
150  * @note Synchronization level: Interrupt safe, as long as the
151  * FileHandle::write of the stderr device is. See mbed_error_puts
152  * for more information.
153  *
154  * @param format C string that contains data stream to be printed.
155  * @param arg Variable arguments list
156  *
157  */
158 void mbed_error_vprintf(const char *format, va_list arg) MBED_PRINTF(1, 0);
159 
160 /** Print out an error message. This is typically called when
161  * handling a crash.
162  *
163  * Unlike mbed_error_printf, there is no limit to the maximum output
164  * length. Unlike standard puts, but like standard fputs, this does not
165  * append a '\n' character.
166  *
167  * @note Synchronization level: Interrupt safe, as long as the
168  * FileHandle::write of the stderr device is. The default
169  * serial console is safe, either buffered or not. If the
170  * console has not previously been initialized, an attempt
171  * to use this from interrupt may during console initialization.
172  * Special handling of `mbed_error` relaxes various system traps
173  * to increase the chance of initialization working.
174  *
175  * @param str C string that contains data stream to be printed.
176  *
177  */
178 void mbed_error_puts(const char *str);
179 
180 /** @deprecated Renamed to mbed_error_vprintf to match functionality */
181 MBED_DEPRECATED_SINCE("mbed-os-5.11",
182  "Renamed to mbed_error_vprintf to match functionality.")
183 void mbed_error_vfprintf(const char *format, va_list arg) MBED_PRINTF(1, 0);
184 /** @}*/
185 
186 
187 #ifdef __cplusplus
188 }
189 #endif
190 
191 #endif
192 
193 /** @}*/
mbed_error_vfprintf
void mbed_error_vfprintf(const char *format, va_list arg) MBED_PRINTF(1
mbed_die
MBED_NORETURN void mbed_die(void)
Cause the mbed to flash the BLOD (Blue LEDs Of Death) sequence.
mbed_error_printf
void mbed_error_printf(const char *format,...) MBED_PRINTF(1
Print out an error message.
mbed_mac_address
void mbed_mac_address(char *mac)
This returns a unique 6-byte MAC address, based on the interface UID If the interface is not present...
mbed_error_vprintf
void void mbed_error_vprintf(const char *format, va_list arg) MBED_PRINTF(1
Print out an error message.
mbed_error_puts
void void void mbed_error_puts(const char *str)
Print out an error message.
MBED_NORETURN
#define MBED_NORETURN
MBED_NORETURN Declare a function that will never return.
Definition: mbed_toolchain.h:313
MBED_DEPRECATED_SINCE
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Definition: mbed_toolchain.h:378
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.