mbed_interface.h

00001 
00002 /** \addtogroup platform */
00003 /** @{*/
00004 /**
00005  * \defgroup platform_interface Network interface and other utility functions
00006  * @{
00007  */
00008 
00009 /* mbed Microcontroller Library
00010  * Copyright (c) 2006-2013 ARM Limited
00011  * SPDX-License-Identifier: Apache-2.0
00012  *
00013  * Licensed under the Apache License, Version 2.0 (the "License");
00014  * you may not use this file except in compliance with the License.
00015  * You may obtain a copy of the License at
00016  *
00017  *     http://www.apache.org/licenses/LICENSE-2.0
00018  *
00019  * Unless required by applicable law or agreed to in writing, software
00020  * distributed under the License is distributed on an "AS IS" BASIS,
00021  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00022  * See the License for the specific language governing permissions and
00023  * limitations under the License.
00024  */
00025 #ifndef MBED_INTERFACE_H
00026 #define MBED_INTERFACE_H
00027 
00028 #include <stdarg.h>
00029 
00030 #include "mbed_toolchain.h"
00031 #include "device.h"
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 suing 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
00131  * @note This uses an internal 128-byte buffer to format the string,
00132  *       so the output may be truncated. If you need to write a potentially
00133  *       long string, use mbed_error_puts.
00134  *
00135  * @param format    C string that contains data stream to be printed.
00136  *                  Code snippets below show valid format.
00137  *
00138  * @code
00139  * mbed_error_printf("Failed: %s, file: %s, line %d \n", expr, file, line);
00140  * @endcode
00141  *
00142  */
00143 void mbed_error_printf(const char *format, ...) MBED_PRINTF(1, 2);
00144 
00145 /** Print out an error message.  Similar to mbed_error_printf
00146  * but uses a va_list.
00147  *
00148  * @note Synchronization level: Interrupt safe
00149  *
00150  * @param format    C string that contains data stream to be printed.
00151  * @param arg       Variable arguments list
00152  *
00153  */
00154 void mbed_error_vprintf(const char *format, va_list arg) MBED_PRINTF(1, 0);
00155 
00156 /** Print out an error message. This is typically called when
00157  * handling a crash.
00158  *
00159  * Unlike mbed_error_printf, there is no limit to the maximum output
00160  * length. Unlike standard puts, but like standard fputs, this does not
00161  * append a '\n' character.
00162  *
00163  * @note Synchronization level: Interrupt safe
00164  *
00165  * @param str    C string that contains data stream to be printed.
00166  *
00167  */
00168 void mbed_error_puts(const char *str);
00169 
00170 /** @deprecated   Renamed to mbed_error_vprintf to match functionality */
00171 MBED_DEPRECATED_SINCE("mbed-os-5.11",
00172                       "Renamed to mbed_error_vprintf to match functionality.")
00173 void mbed_error_vfprintf(const char *format, va_list arg) MBED_PRINTF(1, 0);
00174 /** @}*/
00175 
00176 
00177 #ifdef __cplusplus
00178 }
00179 #endif
00180 
00181 #endif
00182 
00183 /** @}*/