mbed_interface.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 ARM Limited
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef MBED_INTERFACE_H
00018 #define MBED_INTERFACE_H
00019 
00020 #include <stdarg.h>
00021 
00022 #include "platform/mbed_toolchain.h"
00023 #include "device.h"
00024 
00025 /** \addtogroup platform-public-api */
00026 /** @{*/
00027 
00028 /**
00029  * \defgroup platform_interface Network interface and other utility functions
00030  * @{
00031  */
00032 
00033 /* Mbed interface mac address
00034  * if MBED_MAC_ADD_x are zero, interface uid sets mac address,
00035  * otherwise MAC_ADD_x are used.
00036  */
00037 #define MBED_MAC_ADDR_INTERFACE 0x00
00038 #define MBED_MAC_ADDR_0  MBED_MAC_ADDR_INTERFACE
00039 #define MBED_MAC_ADDR_1  MBED_MAC_ADDR_INTERFACE
00040 #define MBED_MAC_ADDR_2  MBED_MAC_ADDR_INTERFACE
00041 #define MBED_MAC_ADDR_3  MBED_MAC_ADDR_INTERFACE
00042 #define MBED_MAC_ADDR_4  MBED_MAC_ADDR_INTERFACE
00043 #define MBED_MAC_ADDR_5  MBED_MAC_ADDR_INTERFACE
00044 #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)
00045 
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 #if DEVICE_SEMIHOST
00051 
00052 /**
00053  * \defgroup platform_interface interface functions
00054  * @{
00055  */
00056 
00057 /** Functions to control the mbed interface
00058  *
00059  * mbed Microcontrollers have a built-in interface to provide functionality such as
00060  * drag-n-drop download, reset, serial-over-usb, and access to the mbed local file
00061  * system. These functions provide means to control the interface using semihost
00062  * calls it supports.
00063  */
00064 
00065 /** Determine whether the mbed interface is connected, based on whether debug is enabled
00066  *
00067  *  @returns
00068  *    1 if interface is connected,
00069  *    0 otherwise
00070  */
00071 int mbed_interface_connected(void);
00072 
00073 /** Instruct the mbed interface to reset, as if the reset button had been pressed
00074  *
00075  *  @returns
00076  *    1 if successful,
00077  *    0 otherwise (e.g. interface not present)
00078  */
00079 int mbed_interface_reset(void);
00080 
00081 /** This will disconnect the debug aspect of the interface, so semihosting will be disabled.
00082  * The interface will still support the USB serial aspect
00083  *
00084  *  @returns
00085  *    0 if successful,
00086  *   -1 otherwise (e.g. interface not present)
00087  */
00088 int mbed_interface_disconnect(void);
00089 
00090 /** This will disconnect the debug aspect of the interface, and if the USB cable is not
00091  * connected, also power down the interface. If the USB cable is connected, the interface
00092  * will remain powered up and visible to the host
00093  *
00094  *  @returns
00095  *    0 if successful,
00096  *   -1 otherwise (e.g. interface not present)
00097  */
00098 int mbed_interface_powerdown(void);
00099 
00100 /** This returns a string containing the 32-character UID of the mbed interface
00101  *  This is a weak function that can be overwritten if required
00102  *
00103  *  @param uid A 33-byte array to write the null terminated 32-byte string
00104  *
00105  *  @returns
00106  *    0 if successful,
00107  *   -1 otherwise (e.g. interface not present)
00108  */
00109 int mbed_interface_uid(char *uid);
00110 
00111 #endif
00112 
00113 /** This returns a unique 6-byte MAC address, based on the interface UID
00114  * If the interface is not present, it returns a default fixed MAC address (00:02:F7:F0:00:00)
00115  *
00116  * This is a weak function that can be overwritten if you want to provide your own mechanism to
00117  * provide a MAC address.
00118  *
00119  *  @param mac A 6-byte array to write the MAC address
00120  */
00121 void mbed_mac_address(char *mac);
00122 
00123 /** Cause the mbed to flash the BLOD (Blue LEDs Of Death) sequence
00124  */
00125 MBED_NORETURN void mbed_die(void);
00126 
00127 /** Print out an error message.  This is typically called when
00128  * handling a crash.
00129  *
00130  * @note Synchronization level: Interrupt safe, as long as the
00131  *       FileHandle::write of the stderr device is. See mbed_error_puts
00132  *       for more information.
00133  * @note This uses an internal 128-byte buffer to format the string,
00134  *       so the output may be truncated. If you need to write a potentially
00135  *       long string, use mbed_error_puts.
00136  *
00137  * @param format    C string that contains data stream to be printed.
00138  *                  Code snippets below show valid format.
00139  *
00140  * @code
00141  * mbed_error_printf("Failed: %s, file: %s, line %d \n", expr, file, line);
00142  * @endcode
00143  *
00144  */
00145 void mbed_error_printf(const char *format, ...) MBED_PRINTF(1, 2);
00146 
00147 /** Print out an error message.  Similar to mbed_error_printf
00148  * but uses a va_list.
00149  *
00150  * @note Synchronization level: Interrupt safe, as long as the
00151  *       FileHandle::write of the stderr device is. See mbed_error_puts
00152  *       for more information.
00153  *
00154  * @param format    C string that contains data stream to be printed.
00155  * @param arg       Variable arguments list
00156  *
00157  */
00158 void mbed_error_vprintf(const char *format, va_list arg) MBED_PRINTF(1, 0);
00159 
00160 /** Print out an error message. This is typically called when
00161  * handling a crash.
00162  *
00163  * Unlike mbed_error_printf, there is no limit to the maximum output
00164  * length. Unlike standard puts, but like standard fputs, this does not
00165  * append a '\n' character.
00166  *
00167  * @note Synchronization level: Interrupt safe, as long as the
00168  *       FileHandle::write of the stderr device is. The default
00169  *       serial console is safe, either buffered or not. If the
00170  *       console has not previously been initialized, an attempt
00171  *       to use this from interrupt may crash during console initialization.
00172  *       Special handling of `mbed_error` relaxes various system traps
00173  *       to increase the chance of initialization working.
00174  *
00175  * @param str    C string that contains data stream to be printed.
00176  *
00177  */
00178 void mbed_error_puts(const char *str);
00179 
00180 /** @deprecated   Renamed to mbed_error_vprintf to match functionality */
00181 MBED_DEPRECATED_SINCE ("mbed-os-5.11",
00182                       "Renamed to mbed_error_vprintf to match functionality.")
00183 void mbed_error_vfprintf(const char *format, va_list arg) MBED_PRINTF(1, 0);
00184 /** @}*/
00185 
00186 
00187 #ifdef __cplusplus
00188 }
00189 #endif
00190 
00191 #endif
00192 
00193 /** @}*/