Mbed OS Reference
Loading...
Searching...
No Matches
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
47extern "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 */
71int 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 */
79int 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 */
88int 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 */
98int 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 */
109int 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 */
121void mbed_mac_address(char *mac);
122
123/** Cause the mbed to flash the BLOD (Blue LEDs Of Death) sequence
124 */
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 */
145void 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 */
158void 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 crash 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 */
178void mbed_error_puts(const char *str);
179
180/** @}*/
181
182
183#ifdef __cplusplus
184}
185#endif
186
187#endif
188
189/** @}*/
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,...
void mbed_error_printf(const char *format,...) MBED_PRINTF(1
Print out an error message.
MBED_NORETURN void mbed_die(void)
Cause the mbed to flash the BLOD (Blue LEDs Of Death) sequence.
void void void mbed_error_puts(const char *str)
Print out an error message.
void void mbed_error_vprintf(const char *format, va_list arg) MBED_PRINTF(1
Print out an error message.
#define MBED_NORETURN
MBED_NORETURN Declare a function that will never return.