ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #8552 from cmonr/rollup 

Rollup PR: UK Docathon pt2
pull/12790/head^2
Cruz Monrreal 2018-10-27 08:27:02 -05:00 committed by GitHub
parent a5b757312d 3da861808b
commit d23d7855fc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
28 changed files with 1085 additions and 889 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.github/issue_template.md vendored
View File

@ -1,3 +1,19 @@
<!--
************************************** WARNING **************************************
The ciarcom bot parses this header automatically. Any deviation from the
template may cause the bot to automatically correct this header or may result in a
warning message, requesting updates.
Please ensure that nothing follows the Issue request type section, all
issue details are within the Description section and no changes are made to the
template format (as detailed below).
*************************************************************************************
-->
### Description
<!--

46
CONTRIBUTING.md
View File

@ -1,45 +1,5 @@
# Description
This document is cheat sheet for everyone who wants to contribute to [ARMmbed/mbed-os](https://github.com/ARMmbed/mbed-os) GitHub repository at GitHub.
All changes in code base should originate from GitHub Issues and take advantage of existing GitHub flows. Goal is to attract contributors and allow them contribute to code and documentation at the same time.
# Contributing to Mbed OS
Guidelines from this document are created to help new and existing contributors understand process workflow and align to project rules before pull request is submitted. It explains how a participant should do things like format code, test fixes, and submit patches.
Mbed OS is an open-source, device software platform for the Internet of Things. Contributions are an important part of the platform, and our goal is to make it as simple as possible to become a contributor.
## Where to get more information?
You can read more on our [documentation page](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/cont/contributing/).
# How to contribute
We really appreciate your contributions! We are Open Source project and we need your help. We want to keep it as easy as possible to contribute changes that get things working in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
Before a pull request will be merged, the [mbed Contributor Agreement](http://developer.mbed.org/contributor_agreement/) must be signed.
You can pick up existing [mbed-os GitHub Issue](https://github.com/ARMmbed/mbed-os/issues) and solve it or implement new feature you find important, attractive or just necessary. We will review your proposal via pull request mechanism, give you comments and merge your changes if we decide your contribution satisfy criteria such as quality.
# Enhancements vs Bugs
Enhancements are:
* New features implementation.
* Code refactoring.
* Coding rules, coding styles improvements.
* Code comments improvement.
* Documentation work.
Bugs are:
* Issues rose internally or externally by [ARMmbed/mbed-os](https://github.com/ARMmbed/mbed-os) users.
* Internally (within mbed team) created issues from Continuous Integration pipeline and build servers.
* Issues detected using automation tools such as compilers, sanitizers, static code analysis tools etc.
# Gate Keeper role
Gate Keeper is a person responsible for GitHub process workflow execution and is responsible for repository / project code base. Gate Keeper is also responsible for code (pull request) quality stamp and approves or rejects code changes in project’s code base.
Gate Keepers will review your pull request code, give you comments in pull request comment section and in the end if everything goes well merge your pull request to one of our branches (most probably default ```master``` branch).
Please be patient, digest Gate Keeper's feedback and respond promptly :)
# mbed SDK porting
* For more information regarding mbed SDK porting please refer to [mbed SDK porting](http://developer.mbed.org/handbook/mbed-SDK-porting) handbook.
* Before starting the mbed SDK porting, you might want to familiarize with the [mbed SDK library internals](http://developer.mbed.org/handbook/mbed-library-internals) first.
# Glossary
* Gate Keeper – persons responsible for overall code-base quality of [ARMmbed/mbed-os](https://github.com/ARMmbed/mbed-os) project.
* Enhancement – New feature deployment, code refactoring actions or existing code improvements.
* Bugfix – Issues originated from GitHub Issues pool, raised internally within mbed classic team or issues from automated code validators like linters, static code analysis tools etc.
* Mbed classic – mbed SDK 2.0 located in GitHub at [ARMmbed/mbed-os](https://github.com/ARMmbed/mbed-os).
To encourage productive collaboration, as well as robust, consistent and maintainable code, we have a set of guidelines for contributing to Mbed OS. Please see: [contributing guidelines](https://os.mbed.com/docs/latest/reference/contributing.html).

7
TESTS/mbed_hal/critical_section/critical_section_test.h
View File

@ -14,7 +14,10 @@
* limitations under the License.
*/
/** \addtogroup hal_critical_tests
/** \addtogroup hal_critical
* @{
* \defgroup hal_critical_test Tests
* Tests definitions of the HAL Critical module.
* @{
*/
@ -45,7 +48,7 @@
template <int N>
void test_critical_section();
/**@}*/
/**@}*/
#endif // MBED_CRITICAL_SECTION_TEST_H

6
TESTS/mbed_hal/qspi/qspi_test.h
View File

@ -14,7 +14,10 @@
* limitations under the License.
*/
/** \addtogroup hal_qspi_tests
/** \addtogroup hal_qspi
* @{
* \defgroup hal_qspi_tests Tests
* QSPI tests of the HAL.
* @{
*/
#ifndef MBED_QSPI_TEST_H
@ -96,3 +99,4 @@ void qspi_write_read_test(void);
#endif
/** @}*/
/** @}*/

6
TESTS/mbed_hal/sleep/sleep_test_utils.h
View File

@ -15,7 +15,10 @@
*/
/**
* @addtogroup hal_sleep_test_utils
* @addtogroup hal_sleep
* @{
* @defgroup hal_sleep_test_util Tests
* Tests of the sleep HAL.
* @{
*/
@ -112,3 +115,4 @@ void lp_ticker_isr(const ticker_data_t *const ticker_data)
#endif
/** @}*/
/** @}*/

28
components/wifi/esp8266-driver/ESP8266Interface.h
View File

@ -153,36 +153,12 @@ public:
*/
using NetworkInterface::add_dns_server;
/** Set socket options
*
* The setsockopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
*
* @param handle Socket handle
* @param level Stack-specific protocol level
* @param optname Stack-specific option identifier
* @param optval Option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
/** @copydoc NetworkStack::setsockopt
*/
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
int optname, const void *optval, unsigned optlen);
/** Get socket options
*
* getsockopt allows an application to retrieve stack-specific options
* from the underlying stack using stack-specific level and option names,
* or to request generic options using levels from nsapi_socket_level_t.
*
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t
* @param optname Level-specific option name
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
/** @copydoc NetworkStack::getsockopt
*/
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname,
void *optval, unsigned *optlen);

2
doxyfile_options
View File

@ -491,7 +491,7 @@ HIDE_UNDOC_CLASSES = YES
# included in the documentation.
# The default value is: NO.
HIDE_FRIEND_COMPOUNDS = NO
HIDE_FRIEND_COMPOUNDS = YES
# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
# documentation blocks found inside the body of a function. If set to NO, these

1
doxygen_options.json
View File

@ -27,6 +27,7 @@
"HIDE_SCOPE_NAMES": "YES",
"HIDE_UNDOC_CLASSES": "YES",
"HIDE_UNDOC_MEMBERS": "YES",
"HIDE_FRIEND_COMPOUNDS": "YES",
"INLINE_INFO": "NO",
"INLINE_INHERITED_MEMB": "YES",
"JAVADOC_AUTOBRIEF": "YES",

27
drivers/MbedCRC.h
View File

@ -175,7 +175,7 @@ public:
*
* CRC data if not available fully, CRC can be computed in parts with available data.
*
* In case of hardware, intermediate values and states are saved by hardware and mutex
* In case of hardware, intermediate values and states are saved by hardware. Mutex
* locking is used to serialize access to hardware CRC.
*
* In case of software CRC, previous CRC output should be passed as argument to the
@ -217,7 +217,7 @@ public:
return status;
}
/** Compute partial start, indicate start of partial computation
/** Compute partial start, indicate start of partial computation.
*
* This API should be called before performing any partial computation
* with compute_partial API.
@ -257,6 +257,7 @@ public:
* This API is used to perform final computation to get correct CRC value.
*
* @param crc CRC result
* @return 0 on success or a negative in case of failure.
*/
int32_t compute_partial_stop(uint32_t *crc)
{
@ -283,7 +284,7 @@ public:
return 0;
}
/** Get the current CRC polynomial
/** Get the current CRC polynomial.
*
* @return Polynomial value
*/
@ -309,7 +310,7 @@ private:
uint32_t *_crc_table;
CrcMode _mode;
/** Acquire exclusive access to CRC hardware/software
/** Acquire exclusive access to CRC hardware/software.
*/
void lock()
{
@ -320,7 +321,7 @@ private:
#endif
}
/** Release exclusive access to CRC hardware/software
/** Release exclusive access to CRC hardware/software.
*/
virtual void unlock()
{
@ -331,7 +332,7 @@ private:
#endif
}
/** Get the current CRC data size
/** Get the current CRC data size.
*
* @return CRC data size in bytes
*/
@ -340,7 +341,7 @@ private:
return (width <= 8 ? 1 : (width <= 16 ? 2 : 4));
}
/** Get the top bit of current CRC
/** Get the top bit of current CRC.
*
* @return Top bit is set high for respective data width of current CRC
* Top bit for CRC width less then 8 bits will be set as 8th bit.
@ -350,7 +351,7 @@ private:
return (width < 8 ? (1u << 7) : (uint32_t)(1ul << (width - 1)));
}
/** Get the CRC data mask
/** Get the CRC data mask.
*
* @return CRC data mask is generated based on current CRC width
*/
@ -359,7 +360,7 @@ private:
return (width < 8 ? ((1u << 8) - 1) : (uint32_t)((uint64_t)(1ull << width) - 1));
}
/** Final value of CRC is reflected
/** Final value of CRC is reflected.
*
* @param data final crc value, which should be reflected
* @return Reflected CRC value
@ -382,7 +383,7 @@ private:
}
}
/** Data bytes are reflected
/** Data bytes are reflected.
*
* @param data value to be reflected
* @return Reflected data value
@ -404,7 +405,7 @@ private:
}
}
/** Bitwise CRC computation
/** Bitwise CRC computation.
*
* @param buffer data buffer
* @param size size of the data
@ -448,7 +449,7 @@ private:
return 0;
}
/** CRC computation using ROM tables
/** CRC computation using ROM tables.
*
* @param buffer data buffer
* @param size size of the data
@ -493,7 +494,7 @@ private:
return 0;
}
/** Constructor init called from all specialized cases of constructor
/** Constructor init called from all specialized cases of constructor.
* Note: All construtor common code should be in this function.
*/
void mbed_crc_ctor(void)

220
drivers/SPI.h
View File

@ -36,39 +36,44 @@
namespace mbed {
/** \addtogroup drivers */
/** A SPI Master, used for communicating with SPI slave devices
/** A SPI Master, used for communicating with SPI slave devices.
*
* The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz
* The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz.
*
* Most SPI devices will also require Chip Select and Reset signals. These
* can be controlled using DigitalOut pins
* can be controlled using DigitalOut pins.
*
* @note Synchronization level: Thread safe
*
* Example:
* Example of how to send a byte to a SPI slave and record the response:
* @code
* // Send a byte to a SPI slave, and record the response
*
* #include "mbed.h"
*
* // hardware ssel (where applicable)
* //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel
* SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK)
*
* // software ssel
* SPI device(p5, p6, p7); // mosi, miso, sclk
* DigitalOut cs(p8); // ssel
* DigitalOut chip_select(SPI_CS);
*
* int main() {
* // hardware ssel (where applicable)
* //int response = device.write(0xFF);
*
* device.lock();
* // software ssel
* cs = 0;
* int response = device.write(0xFF);
* cs = 1;
* device.unlock();
* chip_select = 0;
*
* int response = device.write(0xFF);
*
* chip_select = 1;
* device.unlock();
* }
* @endcode
*
* Example using hardware Chip Select line:
* @code
* #include "mbed.h"
*
* SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK, SPI_CS)
*
* int main() {
* device.lock();
* int response = device.write(0xFF);
* device.unlock();
* }
* @endcode
* @ingroup drivers
@ -77,22 +82,22 @@ class SPI : private NonCopyable<SPI> {
public:
/** Create a SPI master connected to the specified pins
/** Create a SPI master connected to the specified pins.
*
* mosi or miso can be specified as NC if not used
* @note You can specify mosi or miso as NC if not used.
*
* @param mosi SPI Master Out, Slave In pin
* @param miso SPI Master In, Slave Out pin
* @param sclk SPI Clock pin
* @param ssel SPI chip select pin
* @param mosi SPI Master Out, Slave In pin.
* @param miso SPI Master In, Slave Out pin.
* @param sclk SPI Clock pin.
* @param ssel SPI Chip Select pin.
*/
SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel = NC);
virtual ~SPI();
/** Configure the data transmission format
/** Configure the data transmission format.
*
* @param bits Number of bits per SPI frame (4 - 16)
* @param mode Clock polarity and phase mode (0 - 3)
* @param bits Number of bits per SPI frame (4 - 16).
* @param mode Clock polarity and phase mode (0 - 3).
*
* @code
* mode | POL PHA
@ -105,51 +110,50 @@ public:
*/
void format(int bits, int mode = 0);
/** Set the spi bus clock frequency
/** Set the SPI bus clock frequency.
*
* @param hz SCLK frequency in hz (default = 1MHz)
* @param hz Clock frequency in Hz (default = 1MHz).
*/
void frequency(int hz = 1000000);
/** Write to the SPI Slave and return the response
/** Write to the SPI Slave and return the response.
*
* @param value Data to be sent to the SPI slave
* @param value Data to be sent to the SPI slave.
*
* @returns
* Response from the SPI slave
* @return Response from the SPI slave.
*/
virtual int write(int value);
/** Write to the SPI Slave and obtain the response
/** Write to the SPI Slave and obtain the response.
*
* The total number of bytes sent and received will be the maximum of
* tx_length and rx_length. The bytes written will be padded with the
* value 0xff.
*
* @param tx_buffer Pointer to the byte-array of data to write to the device
* @param tx_length Number of bytes to write, may be zero
* @param rx_buffer Pointer to the byte-array of data to read from the device
* @param rx_length Number of bytes to read, may be zero
* @returns
* @param tx_buffer Pointer to the byte-array of data to write to the device.
* @param tx_length Number of bytes to write, may be zero.
* @param rx_buffer Pointer to the byte-array of data to read from the device.
* @param rx_length Number of bytes to read, may be zero.
* @return
* The number of bytes written and read from the device. This is
* maximum of tx_length and rx_length.
*/
virtual int write(const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length);
/** Acquire exclusive access to this SPI bus
/** Acquire exclusive access to this SPI bus.
*/
virtual void lock(void);
/** Release exclusive access to this SPI bus
/** Release exclusive access to this SPI bus.
*/
virtual void unlock(void);
/** Set default write data
/** Set default write data.
* SPI requires the master to send some data during a read operation.
* Different devices may require different default byte values.
* For example: A SD Card requires default bytes to be 0xFF.
*
* @param data Default character to be transmitted while read operation
* @param data Default character to be transmitted during a read operation.
*/
void set_default_write_value(char data);
@ -157,17 +161,20 @@ public:
/** Start non-blocking SPI transfer using 8bit buffers.
*
* This function locks the deep sleep until any event has occurred
* This function locks the deep sleep until any event has occurred.
*
* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
* the default SPI value is sent
* @param tx_length The length of TX buffer in bytes
* the default SPI value is sent.
* @param tx_length The length of TX buffer in bytes.
* @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
* received data are ignored
* @param rx_length The length of RX buffer in bytes
* @param callback The event callback function
* @param event The logical OR of events to modify. Look at spi hal header file for SPI events.
* @return Zero if the transfer has started, or -1 if SPI peripheral is busy
* received data are ignored.
* @param rx_length The length of RX buffer in bytes.
* @param callback The event callback function.
* @param event The event mask of events to modify. @see spi_api.h for SPI events.
*
* @return Operation result.
* @retval 0 If the transfer has started.
* @retval -1 If SPI peripheral is busy.
*/
template<typename Type>
int transfer(const Type *tx_buffer, int tx_length, Type *rx_buffer, int rx_length, const event_callback_t &callback, int event = SPI_EVENT_COMPLETE)
@ -179,75 +186,85 @@ public:
return 0;
}
/** Abort the on-going SPI transfer, and continue with transfer's in the queue if any.
/** Abort the on-going SPI transfer, and continue with transfers in the queue, if any.
*/
void abort_transfer();
/** Clear the transaction buffer
/** Clear the queue of transfers.
*/
void clear_transfer_buffer();
/** Clear the transaction buffer and abort on-going transfer.
/** Clear the queue of transfers and abort the on-going transfer.
*/
void abort_all_transfers();
/** Configure DMA usage suggestion for non-blocking transfers
/** Configure DMA usage suggestion for non-blocking transfers.
*
* @param usage The usage DMA hint for peripheral
* @return Zero if the usage was set, -1 if a transaction is on-going
* @param usage The usage DMA hint for peripheral.
*
* @return Result of the operation.
* @retval 0 The usage was set.
* @retval -1 Usage cannot be set as there is an ongoing transaction.
*/
int set_dma_usage(DMAUsage usage);
protected:
/** SPI IRQ handler
*
/** SPI interrupt handler.
*/
void irq_handler_asynch(void);
/** Common transfer method
/** Start the transfer or put it on the queue.
*
* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
* the default SPI value is sent
* @param tx_length The length of TX buffer in bytes
* @param tx_length The length of TX buffer in bytes.
* @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
* received data are ignored
* @param rx_length The length of RX buffer in bytes
* @param bit_width The buffers element width
* @param callback The event callback function
* @param event The logical OR of events to modify
* @return Zero if the transfer has started or was added to the queue, or -1 if SPI peripheral is busy/buffer is full
* received data are ignored.
* @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width in bits.
* @param callback The event callback function.
* @param event The event mask of events to modify.
*
* @return Operation success.
* @retval 0 A transfer was started or added to the queue.
* @retval -1 Transfer can't be added because queue is full.
*/
int transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event);
/**
/** Put a transfer on the transfer queue.
*
* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
* the default SPI value is sent
* @param tx_length The length of TX buffer in bytes
* the default SPI value is sent.
* @param tx_length The length of TX buffer in bytes.
* @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
* received data are ignored
* @param rx_length The length of RX buffer in bytes
* @param bit_width The buffers element width
* @param callback The event callback function
* @param event The logical OR of events to modify
* @return Zero if a transfer was added to the queue, or -1 if the queue is full
* received data are ignored.
* @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width in bits.
* @param callback The event callback function.
* @param event The event mask of events to modify.
*
* @return Operation success.
* @retval 0 A transfer was added to the queue.
* @retval -1 Transfer can't be added because queue is full.
*/
int queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event);
/** Configures a callback, spi peripheral and initiate a new transfer
/** Configure a callback, SPI peripheral, and initiate a new transfer.
*
* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
* the default SPI value is sent
* @param tx_length The length of TX buffer in bytes
* the default SPI value is sent.
* @param tx_length The length of TX buffer in bytes.
* @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
* received data are ignored
* @param rx_length The length of RX buffer in bytes
* @param bit_width The buffers element width
* @param callback The event callback function
* @param event The logical OR of events to modify
* received data are ignored.
* @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width.
* @param callback The event callback function.
* @param event The event mask of events to modify.
*/
void start_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event);
#if !defined(DOXYGEN_ONLY)
private:
/** Lock deep sleep only if it is not yet locked */
void lock_deep_sleep();
@ -258,44 +275,63 @@ private:
#if TRANSACTION_QUEUE_SIZE_SPI
/** Start a new transaction
/** Start a new transaction.
*
* @param data Transaction data
* @param data Transaction data.
*/
void start_transaction(transaction_t *data);
/** Dequeue a transaction
*
/** Dequeue a transaction and start the transfer if there was one pending.
*/
void dequeue_transaction();
/* Queue of pending transfers */
static CircularBuffer<Transaction<SPI>, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer;
#endif
#endif
#endif //!defined(DOXYGEN_ONLY)
#endif //DEVICE_SPI_ASYNCH
#if !defined(DOXYGEN_ONLY)
protected:
/* Internal SPI object identifying the resources */
spi_t _spi;
#if DEVICE_SPI_ASYNCH
/* Interrupt */
CThunk<SPI> _irq;
/* Interrupt handler callback */
event_callback_t _callback;
/* Current preferred DMA mode @see dma_api.h */
DMAUsage _usage;
/* Current sate of the sleep manager */
bool _deep_sleep_locked;
#endif
/* Take over the physical SPI and apply our settings (thread safe) */
void aquire(void);
/* Current user of the SPI */
static SPI *_owner;
/* Used by lock and unlock for thread safety */
static SingletonPtr<PlatformMutex> _mutex;
/* Size of the SPI frame */
int _bits;
/* Clock polairy and phase */
int _mode;
/* Clock frequency */
int _hz;
/* Default character used for NULL transfers */
char _write_fill;
private:
/* Private acquire function without locking/unlocking
* Implemented in order to avoid duplicate locking and boost performance
/** Private acquire function without locking/unlocking.
* Implemented in order to avoid duplicate locking and boost performance.
*/
void _acquire(void);
#endif //!defined(DOXYGEN_ONLY)
};
} // namespace mbed

96
features/mbedtls/README.md
View File

@ -1,25 +1,93 @@
README for mbed TLS
===================
## README for Mbed TLS
mbed TLS for mbed OS
--------------------
### Mbed TLS for Mbed OS
This edition of mbed TLS has been adapted for mbed OS and imported from its standalone release, which you can find on [github here](https://github.com/ARMmbed/mbedtls). This edition of mbed TLS does not include test code, sample applications, or the scripts used in the development of the library. All of these can be found in the standalone release.
This edition of Mbed TLS has been adapted for Mbed OS and imported from its standalone release, which you can find on [GitHub](https://github.com/ARMmbed/mbedtls). This edition of Mbed TLS does not include the test code or scripts used in the development of the library. You can find these in the standalone release.
### Getting started
Getting Help and Support
------------------------
Several example programs are available that demonstrate Mbed TLS with Mbed OS. These can help you become familiar with the library:
The [mbed TLS website](https://tls.mbed.org/) contains full documentation for the library, including function by function descriptions, knowledgebase articles, blogs and a support forum for questions to the community.
* [**TLS Client:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/tls-client) TLS Client demonstrates the use of Mbed TLS to establish a TLS connection to a remote server.
* [**Benchmark:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/benchmark) Benchmark measures the time taken to perform basic cryptographic functions used in the library.
Contributing to the Project
---------------------------
* [**Hashing:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/hashing) Hashing demonstrates the various APIs for computing hashes of data (also known as message digests) with SHA-256.
We gratefully accept bug reports and contributions from the community. There are some requirements we need to fulfill in order to be able to integrate contributions:
* [**Authenticated encryption:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/authcrypt) Authcrypt demonstrates usage of the cipher API for encrypting and authenticating data with AES-CCM.
- Simple bug fixes to existing code do not contain copyright themselves and we can integrate without issue. The same is true of trivial contributions.
- For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will send to you in case you submit a contribution or pull request that we deem this necessary for.
These examples are fully integrated into Mbed OS. Each of them comes with complete usage instructions as a `README.md` file.
Contributions should be submitted to the [standalone mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the mbed OS imported edition of mbed TLS.
### Configuring Mbed TLS features
With Mbed TLS, you can disable any unneeded features during compilation for a particular project. The default configuration enables widely used features of the TLS protocol, which meets the needs of most projects. It also disables all older and less common features to minimize the code footprint.
The list of available compilation flags is available in the fully documented [`config.h` file](https://github.com/ARMmbed/mbedtls/blob/development/include/mbedtls/config.h).
If you need to adjust these flags, you can provide your own supplementary configuration adjustment file with suitable `#define` and `#undef` statements. These are included between the default definitions and the sanity checks. Your configuration file should be in your application's include directory and can be named freely, but you then need to tell Mbed TLS the file's name. To do that, you can use the [Mbed OS configuration system](https://os.mbed.com/docs/latest/reference/configuration.html).
For example, if you wanted to enable the options `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C` and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project.
The Mbed TLS configuration file would be specified in the `.json` file as:
```
{
"macros" : [
"MBEDTLS_USER_CONFIG_FILE" : "my_config.h",
"MBEDTLS_PEM_WRITE_C",
"MBEDTLS_CMAC_C"
]
[remainder of file]
}
```
You can then use the additional configuration file `my_config.h` as a normal configuration header file to include or exclude configurations. For example, it could include the following lines to include ECJPAKE, and to disable the CBC block mode:
```
#define MBEDTLS_ECJPAKE_C
#define MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED
#undef MBEDTLS_CIPHER_MODE_CBC
```
You can use this to change any configuration normally in the `config.h` file.
### Getting Mbed TLS from GitHub
We maintain and develop Mbed TLS in the open, independently of Mbed OS, and you can find its source on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import a different version of Mbed TLS into an instance of Mbed OS, there is a `Makefile` script to update the local Git repository, extract a specific version and modify the configuration files to Mbed OS defaults.
To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the Git tag or commit ID of the Mbed TLS release or version you want to use, or modify the `Makefile` itself. If `MBED_TLS_RELEASE` is not set, the HEAD of the main development branch will be extracted.
Run the following commands in the `importer` directory in the Mbed TLS directory:
```
make update
make
```
The `make update` command pulls the specified version of Mbed TLS into the local `importer/TARGET_IGNORE` directory, and `make` transforms it into the `src` directory, modifying its configuration file as necessary.
Once these steps are complete, you can build Mbed OS normally with the new version of Mbed TLS.
### Differences between the standalone and Mbed OS editions
Although the two editions share the same code base, there are differences, mainly in configuration and integration. Remember these differences if you consult our [knowledge base](https://tls.mbed.org/kb), as the knowledge base articles refer to the standalone edition.
* The Mbed OS edition has a smaller set of features enabled by default in `config.h`, to reduce footprint. Although the default configuration of the standalone edition puts more emphasis on maintaining interoperability with old peers, the Mbed OS edition only enables the most modern ciphers and the latest version of (D)TLS.
* The following components of Mbed TLS are disabled in the Mbed OS edition: `net_sockets.c` and `timing.c`. This is because Mbed OS includes its own equivalents.
### Help and support
For further documentation and help, you can visit the [Mbed TLS website](https://tls.mbed.org/), which contains full documentation of the library, including function-by-function descriptions, knowledge base articles and blogs. Additionally, you can join our [support forum](https://forums.mbed.com/c/mbed-tls) for questions to the community or to help others.
### Contributing to the project
We are happy to accept bug reports and contributions from the community. There are some requirements to integrate contributions:
* Simple bug fixes to existing code do not contain copyright themselves, and we can integrate without issue. The same is true of trivial contributions.
* For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will send to you if you submit a contribution or pull request that we deem this necessary for.
Please submit contributions to the [standalone Mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the version of Mbed TLS embedded within Mbed OS.

85
features/netsocket/CellularBase.h
View File

@ -18,115 +18,114 @@
#include "netsocket/NetworkInterface.h"
/** CellularBase class
*
* Common interface that is shared between Cellular interfaces
/** Common interface that is shared between cellular interfaces.
* @addtogroup netsocket
*/
class CellularBase: public NetworkInterface {
public:
/** Get the default Cellular interface.
/** Get the default cellular interface.
*
* This is provided as a weak method so applications can override.
* Default behaviour is to get the target's default interface, if
* any.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
static CellularBase *get_default_instance();
/** Set the Cellular network credentials
/** Set the cellular network credentials.
*
* Please check documentation of connect() for default behaviour of APN settings.
*
* @param apn Access point name
* @param uname optionally, Username
* @param pwd optionally, password
* @param apn Access point name.
* @param uname Username (optional).
* @param pwd Password (optional).
*/
virtual void set_credentials(const char *apn, const char *uname = 0,
const char *pwd = 0) = 0;
/** Set the pin code for SIM card
/** Set the PIN code for SIM card.
*
* @param sim_pin PIN for the SIM card
* @param sim_pin PIN for the SIM card.
*/
virtual void set_sim_pin(const char *sim_pin) = 0;
/** Start the interface
/** Attempt to connect to a cellular network with a PIN and credentials.
*
* Attempts to connect to a Cellular network.
*
* @param sim_pin PIN for the SIM card
* @param apn optionally, access point name
* @param uname optionally, Username
* @param pwd optionally, password
* @return NSAPI_ERROR_OK on success, or negative error code on failure
* @param sim_pin PIN for the SIM card.
* @param apn Access point name (optional).
* @param uname Username (optional).
* @param pwd Password (optional).
* @return NSAPI_ERROR_OK on success, or negative error code on failure.
*/
virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
const char *uname = 0,
const char *pwd = 0) = 0;
/** Start the interface
/** Attempt to connect to a cellular network.
*
* Attempts to connect to a Cellular network.
* If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
* If the SIM requires a PIN, and it is invalid or not set, NSAPI_ERROR_AUTH_ERROR is returned.
*
* @return NSAPI_ERROR_OK on success, or negative error code on failure
* @return NSAPI_ERROR_OK on success, or negative error code on failure.
*/
virtual nsapi_error_t connect() = 0;
/** Stop the interface
/** Stop the interface.
*
* @return 0 on success, or error code on failure
* @return NSAPI_ERROR_OK on success, or error code on failure.
*/
virtual nsapi_error_t disconnect() = 0;
/** Check if the connection is currently established or not
/** Check if the connection is currently established.
*
* @return true/false If the cellular module have successfully acquired a carrier and is
* connected to an external packet data network using PPP, isConnected()
* API returns true and false otherwise.
* @return `true` if the cellular module have successfully acquired a carrier and is
* connected to an external packet data network using PPP, `false` otherwise.
*/
virtual bool is_connected() = 0;
/** Get the local IP address
/** Get the local IP address.
*
* @return Null-terminated representation of the local IP address
* or null if no IP address has been received
* @return Null-terminated representation of the local IP address,
* or null if no IP address has been received.
*/
virtual const char *get_ip_address() = 0;
/** Get the local network mask
/** Get the local network mask.
*
* @return Null-terminated representation of the local network mask
* or null if no network mask has been received
* @return Null-terminated representation of the local network mask,
* or null if no network mask has been received.
*/
virtual const char *get_netmask() = 0;
/** Get the local gateways
/** Get the local gateways.
*
* @return Null-terminated representation of the local gateway
* or null if no network mask has been received
* @return Null-terminated representation of the local gateway,
* or null if no network mask has been received.
*/
virtual const char *get_gateway() = 0;
/** @copydoc NetworkInterface::cellularBase
*/
virtual CellularBase *cellularBase()
{
return this;
}
#if !defined(DOXYGEN_ONLY)
protected:
/** Get the target's default Cellular interface.
/** Get the target's default cellular interface.
*
* This is provided as a weak method so targets can override. The
* default implementation configures and returns the OnBoardModemInterface
* default implementation configures and returns the OnBoardModemInterface,
* if available.
*
* @return pointer to interface, if any
* @return Pointer to interface, if any.
*/
static CellularBase *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
};
#endif //CELLULAR_BASE_H

58
features/netsocket/DNS.h
View File

@ -20,7 +20,7 @@
class DNS {
public:
/** Translates a hostname to an IP address with specific version
/** Translate a hostname to an IP address with specific version.
*
* The hostname may be either a domain name or an IP address. If the
* hostname is an IP address, no network transactions will be performed.
@ -28,18 +28,18 @@ public:
* If no stack-specific DNS resolution is provided, the hostname
* will be resolve using a UDP socket on the stack.
*
* @param host Hostname to resolve
* @param address Destination for the host SocketAddress
* @param host Hostname to resolve.
* @param address Pointer to a SocketAddress to store the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
* @return 0 on success, negative error code on failure
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t gethostbyname(const char *host,
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC) = 0;
/** Hostname translation callback (asynchronous)
/** Hostname translation callback for gethostbyname_async.
*
* Callback will be called after DNS resolution completes or a failure occurs.
* The callback is called after DNS resolution completes, or a failure occurs.
*
* Callback should not take more than 10ms to execute, otherwise it might
* prevent underlying thread processing. A portable user of the callback
@ -47,49 +47,49 @@ public:
* The callback should not perform expensive operations such as socket recv/send
* calls or blocking operations.
*
* @param status 0 on success, negative error code on failure
* @param address On success, destination for the host SocketAddress
* @param result NSAPI_ERROR_OK on success, negative error code on failure.
* @param address On success, destination for the host SocketAddress.
*/
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
/** Translates a hostname to an IP address (asynchronous)
/** Translate a hostname to an IP address (asynchronous).
*
* The hostname may be either a domain name or an IP address. If the
* hostname is an IP address, no network transactions will be performed.
*
* If no stack-specific DNS resolution is provided, the hostname
* will be resolve using a UDP socket on the stack.
* will be resolved using a UDP socket on the stack.
*
* Call is non-blocking. Result of the DNS operation is returned by the callback.
* If this function returns failure, callback will not be called. In case result
* is success (IP address was found from DNS cache), callback will be called
* before function returns.
* The call is non-blocking. The result of the DNS operation is returned by the callback.
* If this function returns failure, the callback will not be called. If it is successful,
* (the IP address was found from the DNS cache), the callback will be called
* before the function returns.
*
* @param host Hostname to resolve
* @param callback Callback that is called for result
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
* @return 0 on immediate success,
* @param host Hostname to resolve.
* @param callback Callback that is called to return the result.
* @param version IP version of address to resolve. NSAPI_UNSPEC indicates that the
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return NSAPI_ERROR_OK on immediate success,
* negative error code on immediate failure or
* a positive unique id that represents the hostname translation operation
* and can be passed to cancel
* a positive unique ID that represents the hostname translation operation
* and can be passed to cancel.
*/
virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
nsapi_version_t version = NSAPI_UNSPEC) = 0;
/** Cancels asynchronous hostname translation
/** Cancel asynchronous hostname translation.
*
* When translation is cancelled, callback will not be called.
* When translation is canceled, callback is not called.
*
* @param id Unique id of the hostname translation operation
* @return 0 on success, negative error code on failure
* @param id Unique ID of the hostname translation operation returned by gethostbyname_async.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0;
/** Add a domain name server to list of servers to query
/** Add a domain name server to list of servers to query.
*
* @param address Destination for the host address
* @return 0 on success, negative error code on failure
* @param address DNS server host address.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t add_dns_server(const SocketAddress &address) = 0;
};

12
features/netsocket/EthInterface.h
View File

@ -23,13 +23,13 @@
#include "netsocket/NetworkInterface.h"
/** EthInterface class
*
* Common interface that is shared between ethernet hardware.
/** Common interface that is shared between Ethernet hardware.
*/
class EthInterface : public virtual NetworkInterface {
public:
/** @copydoc NetworkInterface::ethInterface
*/
virtual EthInterface *ethInterface()
{
return this;
@ -41,10 +41,11 @@ public:
* Default behaviour is to get the target's default interface, if
* any.
*
* @return pointer to interface, if any
* @return Pointer to interface, if one exists.
*/
static EthInterface *get_default_instance();
#if !defined(DOXYGEN_ONLY)
protected:
/** Get the target's default Ethernet interface.
@ -53,9 +54,10 @@ protected:
* default implementation will invoke EthernetInterface with the
* default EMAC and default network stack, if DEVICE_EMAC is set.
*
* @return pointer to interface, if any
* @return Pointer to interface, if one exists.
*/
static EthInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
};

9
features/netsocket/EthernetInterface.h
View File

@ -21,12 +21,11 @@
#include "EMACInterface.h"
/** EthernetInterface class
* Implementation of the NetworkStack for an EMAC-based Ethernet driver
/** Implementation of the NetworkStack for an EMAC-based Ethernet driver.
*/
class EthernetInterface : public EMACInterface, public EthInterface {
public:
/** Create an EMAC-based ethernet interface.
/** Create an EMAC-based Ethernet interface.
*
* The default arguments obtain the default EMAC, which will be target-
* dependent (and the target may have some JSON option to choose which
@ -36,8 +35,8 @@ public:
* Due to inability to return errors from the constructor, no real
* work is done until the first call to connect().
*
* @param emac Reference to EMAC to use
* @param stack Reference to onboard-network stack to use
* @param emac Reference to EMAC to use.
* @param stack Reference to onboard-network stack to use.
*/
EthernetInterface(EMAC &emac = EMAC::get_default_instance(),
OnboardNetworkStack &stack = OnboardNetworkStack::get_default_instance()) : EMACInterface(emac, stack) { }

148
features/netsocket/InternetSocket.h
View File

@ -32,176 +32,104 @@
*/
class InternetSocket : public Socket {
public:
/** Destroy a socket
/** Destroy the socket.
*
* Closes socket if the socket is still open
* @note Closes socket if it's still open.
*/
virtual ~InternetSocket() {}
/** Opens a socket
/** Open a network socket on the network stack of the given
* network interface.
*
* Creates a network socket on the network stack of the given
* network interface. Not needed if stack is passed to the
* socket's constructor.
* @note Not needed if stack is passed to the socket's constructor.
*
* @param stack Network stack as target for socket
* @return 0 on success, negative error code on failure
* @param stack Network stack as target for socket.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
nsapi_error_t open(NetworkStack *stack);
#if !defined(DOXYGEN_ONLY)
template <typename S>
nsapi_error_t open(S *stack)
{
return open(nsapi_create_stack(stack));
}
#endif //!defined(DOXYGEN_ONLY)
/** Close the socket
*
* Closes any open connection and deallocates any memory associated
/** Close any open connection, and deallocate any memory associated
* with the socket. Called from destructor if socket is not closed.
*
* @return 0 on success, negative error code on failure
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
virtual nsapi_error_t close();
/** Subscribes to an IP multicast group
/** Subscribe to an IP multicast group.
*
* @param address Multicast group IP address
* @return Negative error code on failure
* @param address Multicast group IP address.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
int join_multicast_group(const SocketAddress &address);
/** Leave an IP multicast group
/** Leave an IP multicast group.
*
* @param address Multicast group IP address
* @return Negative error code on failure
* @param address Multicast group IP address.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
int leave_multicast_group(const SocketAddress &address);
/** Bind a specific address to a socket
/** Bind the socket to a port on which to receive data.
*
* Binding a socket specifies the address and port on which to receive
* data.
*
* @param port Local port to bind
* @return 0 on success, negative error code on failure.
* @param port Local port to bind.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
nsapi_error_t bind(uint16_t port);
/** Bind a specific address to a socket
*
* Binding a socket specifies the address and port on which to receive
/** Bind the socket to a specific address and port on which to receive
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Null-terminated local address to bind
* @param port Local port to bind
* @return 0 on success, negative error code on failure.
* @param address Null-terminated local address to bind.
* @param port Local port to bind.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/
nsapi_error_t bind(const char *address, uint16_t port);
/** Bind a specific address to a socket
*
* Binding a socket specifies the address and port on which to receive
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Local address to bind
* @return 0 on success, negative error code on failure.
/** @copydoc Socket::bind
*/
virtual nsapi_error_t bind(const SocketAddress &address);
/** Set blocking or non-blocking mode of the socket
*
* Initially all sockets are in blocking mode. In non-blocking mode
* blocking operations such as send/recv/accept return
* NSAPI_ERROR_WOULD_BLOCK if they can not continue.
*
* set_blocking(false) is equivalent to set_timeout(-1)
* set_blocking(true) is equivalent to set_timeout(0)
*
* @param blocking true for blocking mode, false for non-blocking mode.
/** @copydoc Socket::set_blocking
*/
virtual void set_blocking(bool blocking);
/** Set timeout on blocking socket operations
*
* Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
* is returned if a blocking operation takes longer than the specified
* timeout. A timeout of 0 removes the timeout from the socket. A negative
* value give the socket an unbounded timeout.
*
* set_timeout(0) is equivalent to set_blocking(false)
* set_timeout(-1) is equivalent to set_blocking(true)
*
* @param timeout Timeout in milliseconds
/** @copydoc Socket::set_timeout
*/
virtual void set_timeout(int timeout);
/* Set socket options
*
* setsockopt allows an application to pass stack-specific options
* to the underlying stack using stack-specific level and option names,
* or to request generic options using levels from nsapi_socket_level_t.
*
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t
* @param optname Level-specific option name
* @param optval Option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
/** @copydoc Socket::setsockopt
*/
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
/* Get socket options
*
* getsockopt allows an application to retrieve stack-specific options
* from the underlying stack using stack-specific level and option names,
* or to request generic options using levels from nsapi_socket_level_t.
*
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t
* @param optname Level-specific option name
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
/** @copydoc Socket::getsockopt
*/
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);
/** Register a callback on state change of the socket
*
* The specified callback will be called on state changes such as when
* the socket can recv/send/accept successfully and on when an error
* occurs. The callback may also be called spuriously without reason.
*
* The callback may be called in an interrupt context and should not
* perform expensive operations such as recv/send calls.
*
* Note! This is not intended as a replacement for a poll or attach-like
* asynchronous api, but rather as a building block for constructing
* such functionality. The exact timing of when the registered function
* is called is not guaranteed and susceptible to change.
*
* @param func Function to call on state change
/** @copydoc Socket::sigio
*/
virtual void sigio(mbed::Callback<void()> func);
/** Register a callback on state change of the socket
/** Register a callback on state change of the socket.
*
* @see Socket::sigio
* @deprecated
* The behaviour of Socket::attach differs from other attach functions in
* mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
* The behavior of Socket::attach differs from other attach functions in
* Mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
*/
MBED_DEPRECATED_SINCE("mbed-os-5.4",
"The behaviour of Socket::attach differs from other attach functions in "
"mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
"The behavior of Socket::attach differs from other attach functions in "
"Mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
void attach(mbed::Callback<void()> func);
/** Register a callback on state change of the socket
/** Register a callback on state change of the socket.
*
* @see Socket::sigio
* @deprecated
@ -217,6 +145,8 @@ public:
attach(mbed::callback(obj, method));
}
#if !defined(DOXYGEN_ONLY)
protected:
InternetSocket();
virtual nsapi_protocol_t get_proto() = 0;
@ -240,6 +170,8 @@ protected:
static const int READ_FLAG = 0x1u;
static const int WRITE_FLAG = 0x2u;
static const int FINISHED_FLAG = 0x3u;
#endif //!defined(DOXYGEN_ONLY)
};
#endif // INTERNETSOCKET_H

13
features/netsocket/MeshInterface.h
View File

@ -23,13 +23,12 @@
#include "netsocket/NetworkInterface.h"
/** MeshInterface class
*
* Common interface that is shared between mesh hardware
/** Common interface that is shared between mesh hardware
*/
class MeshInterface : public virtual NetworkInterface {
public:
/** @copydoc NetworkInterface::meshInterface
*/
virtual MeshInterface *meshInterface()
{
return this;
@ -41,10 +40,11 @@ public:
* Default behaviour is to get the target's default interface, if
* any.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
static MeshInterface *get_default_instance();
#if !defined(DOXYGEN_ONLY)
protected:
/** Get the target's default Mesh interface.
@ -53,9 +53,10 @@ protected:
* default implementation will invoke LoWPANNDInterface or ThreadInterface
* with the default NanostackRfPhy.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
static MeshInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
};

133
features/netsocket/NetworkInterface.h
View File

@ -31,9 +31,8 @@ class MeshInterface;
class CellularBase;
class EMACInterface;
/** NetworkInterface class
/** Common interface that is shared between network devices.
*
* Common interface that is shared between network devices
* @addtogroup netsocket
*/
class NetworkInterface: public DNS {
@ -41,13 +40,14 @@ public:
virtual ~NetworkInterface() {};
/** Return the default network interface
/** Return the default network interface.
*
* Returns the default network interface, as determined by JSON option
* target.network-default-interface-type or other overrides.
*
* The type of the interface returned can be tested via the ethInterface()
* etc downcasts.
* The type of the interface returned can be tested by calling ethInterface(),
* wifiInterface(), meshInterface(), cellularBase(), emacInterface() and checking
* for NULL pointers.
*
* The default behaviour is to return the default interface for the
* interface type specified by target.network-default-interface-type. Targets
@ -79,75 +79,72 @@ public:
*/
static NetworkInterface *get_default_instance();
/** Get the local MAC address
/** Get the local MAC address.
*
* Provided MAC address is intended for info or debug purposes and
* may not be provided if the underlying network interface does not
* provide a MAC address
* may be not provided if the underlying network interface does not
* provide a MAC address.
*
* @return Null-terminated representation of the local MAC address
* or null if no MAC address is available
* or null if no MAC address is available.
*/
virtual const char *get_mac_address();
/** Get the local IP address
/** Get the local IP address.
*
* @return Null-terminated representation of the local IP address
* or null if no IP address has been received
* or null if no IP address has been received.
*/
virtual const char *get_ip_address();
/** Get the local network mask
/** Get the local network mask.
*
* @return Null-terminated representation of the local network mask
* or null if no network mask has been received
* or null if no network mask has been received.
*/
virtual const char *get_netmask();
/** Get the local gateway
/** Get the local gateway.
*
* @return Null-terminated representation of the local gateway
* or null if no network mask has been received
* or null if no network mask has been received.
*/
virtual const char *get_gateway();
/** Set a static IP address
*
* Configures this network interface to use a static IP address.
/** Configure this network interface to use a static IP address.
* Implicitly disables DHCP, which can be enabled in set_dhcp.
* Requires that the network is disconnected.
*
* @param ip_address Null-terminated representation of the local IP address
* @param netmask Null-terminated representation of the local network mask
* @param gateway Null-terminated representation of the local gateway
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway);
/** Enable or disable DHCP on the network
/** Enable or disable DHCP on connecting the network.
*
* Enables DHCP on connecting the network. Defaults to enabled unless
* a static IP address has been assigned. Requires that the network is
* disconnected.
* Enabled by default unless a static IP address has been assigned. Requires
* that the network is disconnected.
*
* @param dhcp True to enable DHCP
* @return 0 on success, negative error code on failure
* @param dhcp True to enable DHCP.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t set_dhcp(bool dhcp);
/** Start the interface
/** Start the interface.
*
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t connect() = 0;
/** Stop the interface
/** Stop the interface.
*
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t disconnect() = 0;
/** Translates a hostname to an IP address with specific version
/** Translate a hostname to an IP address with specific version.
*
* The hostname may be either a domain name or an IP address. If the
* hostname is an IP address, no network transactions will be performed.
@ -155,33 +152,33 @@ public:
* If no stack-specific DNS resolution is provided, the hostname
* will be resolve using a UDP socket on the stack.
*
* @param host Hostname to resolve
* @param address Destination for the host SocketAddress
* @param host Hostname to resolve.
* @param address Pointer to a SocketAddress to store the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
* @return 0 on success, negative error code on failure
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t gethostbyname(const char *host,
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
/** Hostname translation callback (asynchronous)
/** Hostname translation callback (for use with gethostbyname_async()).
*
* Callback will be called after DNS resolution completes or a failure occurs.
*
* Callback should not take more than 10ms to execute, otherwise it might
* @note Callback should not take more than 10ms to execute, otherwise it might
* prevent underlying thread processing. A portable user of the callback
* should not make calls to network operations due to stack size limitations.
* The callback should not perform expensive operations such as socket recv/send
* calls or blocking operations.
*
* @param status 0 on success, negative error code on failure
* @param address On success, destination for the host SocketAddress
* @param result NSAPI_ERROR_OK on success, negative error code on failure.
* @param address On success, destination for the host SocketAddress.
*/
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
/** Translates a hostname to an IP address (asynchronous)
/** Translate a hostname to an IP address (asynchronous).
*
* The hostname may be either a domain name or an IP address. If the
* The hostname may be either a domain name or a dotted IP address. If the
* hostname is an IP address, no network transactions will be performed.
*
* If no stack-specific DNS resolution is provided, the hostname
@ -192,87 +189,100 @@ public:
* is success (IP address was found from DNS cache), callback will be called
* before function returns.
*
* @param host Hostname to resolve
* @param callback Callback that is called for result
* @param host Hostname to resolve.
* @param callback Callback that is called for result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return 0 on immediate success,
* negative error code on immediate failure or
* a positive unique id that represents the hostname translation operation
* and can be passed to cancel
* and can be passed to cancel.
*/
virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
nsapi_version_t version = NSAPI_UNSPEC);
/** Cancels asynchronous hostname translation
/** Cancel asynchronous hostname translation.
*
* When translation is cancelled, callback will not be called.
*
* @param id Unique id of the hostname translation operation
* @return 0 on success, negative error code on failure
* @param id Unique id of the hostname translation operation (returned
* by gethostbyname_async)
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t gethostbyname_async_cancel(int id);
/** Add a domain name server to list of servers to query
*
* @param address Destination for the host address
* @return 0 on success, negative error code on failure
* @param address Address for the dns host.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t add_dns_server(const SocketAddress &address);
/** Register callback for status reporting
/** Register callback for status reporting.
*
* The specified status callback function will be called on status changes
* on the network. The parameters on the callback are the event type and
* event-type dependent reason parameter.
*
* @param status_cb The callback for status changes
* @param status_cb The callback for status changes.
*/
virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
/** Get the connection status
/** Get the connection status.
*
* @return The connection status according to ConnectionStatusType
* @return The connection status (@see nsapi_types.h).
*/
virtual nsapi_connection_status_t get_connection_status() const;
/** Set blocking status of connect() which by default should be blocking
/** Set blocking status of connect() which by default should be blocking.
*
* @param blocking true if connect is blocking
* @return 0 on success, negative error code on failure
* @param blocking Use true to make connect() blocking.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t set_blocking(bool blocking);
/** Dynamic downcast to an EthInterface */
/** Return pointer to an EthInterface.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual EthInterface *ethInterface()
{
return 0;
}
/** Dynamic downcast to a WiFiInterface */
/** Return pointer to a WiFiInterface.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual WiFiInterface *wifiInterface()
{
return 0;
}
/** Dynamic downcast to a MeshInterface */
/** Return pointer to a MeshInterface.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual MeshInterface *meshInterface()
{
return 0;
}
/** Dynamic downcast to a CellularBase */
/** Return pointer to a CellularBase.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual CellularBase *cellularBase()
{
return 0;
}
/** Dynamic downcast to an EMACInterface */
/** Return pointer to an EMACInterface.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual EMACInterface *emacInterface()
{
return 0;
}
#if !defined(DOXYGEN_ONLY)
protected:
friend class InternetSocket;
friend class UDPSocket;
@ -318,6 +328,7 @@ protected:
* performs the search described by get_default_instance.
*/
static NetworkInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
};

58
features/netsocket/NetworkStack.h
View File

@ -54,10 +54,10 @@ public:
* will be resolve using a UDP socket on the stack.
*
* @param host Hostname to resolve
* @param address Destination for the host SocketAddress
* @param address Pointer to a SocketAddress to store the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t gethostbyname(const char *host,
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
@ -72,7 +72,7 @@ public:
* The callback should not perform expensive operations such as socket recv/send
* calls or blocking operations.
*
* @param status 0 on success, negative error code on failure
* @param status NSAPI_ERROR_OK on success, negative error code on failure
* @param address On success, destination for the host SocketAddress
*/
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
@ -107,14 +107,14 @@ public:
* When translation is cancelled, callback will not be called.
*
* @param id Unique id of the hostname translation operation
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t gethostbyname_async_cancel(int id);
/** Add a domain name server to list of servers to query
*
* @param address Destination for the host address
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t add_dns_server(const SocketAddress &address);
@ -125,7 +125,7 @@ public:
*
* @param index Index of the DNS server, starts from zero
* @param address Destination for the host address
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t get_dns_server(int index, SocketAddress *address);
@ -142,7 +142,7 @@ public:
* @param optname Level-specific option name
* @param optval Option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen);
@ -156,7 +156,7 @@ public:
* @param optname Level-specific option name
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen);
@ -182,7 +182,7 @@ protected:
*
* @param handle Destination for the handle to a newly created socket
* @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0;
@ -192,7 +192,7 @@ protected:
* with the socket.
*
* @param handle Socket handle
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0;
@ -203,7 +203,7 @@ protected:
*
* @param handle Socket handle
* @param address Local address to bind
* @return 0 on success, negative error code on failure.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0;
@ -215,7 +215,7 @@ protected:
* @param handle Socket handle
* @param backlog Number of pending connections that can be queued
* simultaneously
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0;
@ -226,7 +226,7 @@ protected:
*
* @param handle Socket handle
* @param address The SocketAddress of the remote host
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0;
@ -246,7 +246,7 @@ protected:
* @param server Socket handle to server to accept from
* @param handle Destination for a handle to the newly created socket
* @param address Destination for the remote address or NULL
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t socket_accept(nsapi_socket_t server,
nsapi_socket_t *handle, SocketAddress *address = 0) = 0;
@ -336,34 +336,34 @@ protected:
*/
virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0;
/* Set stack-specific socket options
/** Set stack-specific socket options.
*
* The setsockopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
*
* @param handle Socket handle
* @param level Stack-specific protocol level
* @param optname Stack-specific option identifier
* @param optval Option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @param handle Socket handle.
* @param level Stack-specific protocol level.
* @param optname Stack-specific option identifier.
* @param optval Option value.
* @param optlen Length of the option value.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
int optname, const void *optval, unsigned optlen);
/* Get stack-specific socket options
/** Get stack-specific socket options.
*
* The getstackopt allow an application to retrieve stack-specific hints
* from the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
*
* @param handle Socket handle
* @param level Stack-specific protocol level
* @param optname Stack-specific option identifier
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @param handle Socket handle.
* @param level Stack-specific protocol level.
* @param optname Stack-specific option identifier.
* @param optval Destination for option value.
* @param optlen Length of the option value.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
int optname, void *optval, unsigned *optlen);
@ -397,7 +397,7 @@ private:
*
* @param delay Delay in milliseconds
* @param func Callback to be called
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
};

37
features/netsocket/Socket.h
View File

@ -38,7 +38,7 @@ public:
* Closes any open connection and deallocates any memory associated
* with the socket. Called from destructor if socket is not closed.
*
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t close() = 0;
@ -54,7 +54,7 @@ public:
* object have to be in the address parameter.
*
* @param address The SocketAddress of the remote peer
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t connect(const SocketAddress &address) = 0;
@ -142,10 +142,11 @@ public:
/** Bind a specific address to a socket.
*
* Binding assigns a local address to a socket.
* Binding a socket specifies the address and port on which to receive
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Local address to bind
* @return 0 on success, negative error code on failure.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t bind(const SocketAddress &address) = 0;
@ -190,11 +191,11 @@ public:
* such functionality. The exact timing of when the registered function
* is called is not guaranteed and susceptible to change.
*
* @param func Function to call on state change
* @param func Function to call on state change.
*/
virtual void sigio(mbed::Callback<void()> func) = 0;
/* Set socket options.
/** Set socket options.
*
* setsockopt() allows an application to pass stack-specific options
* to the underlying stack using stack-specific level and option names,
@ -203,15 +204,15 @@ public:
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t
* @param optname Level-specific option name
* @param optval Option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name.
* @param optval Option value.
* @param optlen Length of the option value.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
/* Get socket options.
/** Get socket options.
*
* getsockopt() allows an application to retrieve stack-specific options
* from the underlying stack using stack-specific level and option names,
@ -220,11 +221,11 @@ public:
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t
* @param optname Level-specific option name
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name.
* @param optval Destination for option value.
* @param optlen Length of the option value.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
@ -250,7 +251,7 @@ public:
*
* @param backlog Number of pending connections that can be queued
* simultaneously, defaults to 1
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
virtual nsapi_error_t listen(int backlog = 1) = 0;
};

125
features/netsocket/UDPSocket.h
View File

@ -26,22 +26,21 @@
#include "rtos/EventFlags.h"
/** UDP socket
/** UDP socket implementation.
*/
class UDPSocket : public InternetSocket {
public:
/** Create an uninitialized socket
/** Create an uninitialized socket.
*
* Must call open to initialize the socket on a network stack.
* @note Must call open to initialize the socket on a network stack.
*/
UDPSocket();
/** Create a socket on a network interface
*
* Creates and opens a socket on the network stack of the given
/** Create and open a socket on the network stack of the given
* network interface.
*
* @param stack Network stack as target for socket
* @tparam S Type of the Network stack.
* @param stack Network stack as target for socket.
*/
template <typename S>
UDPSocket(S *stack)
@ -49,96 +48,84 @@ public:
open(stack);
}
/** Destroy a socket
/** Destroy a socket.
*
* Closes socket if the socket is still open
* @note Closes socket if the socket is still open.
*/
virtual ~UDPSocket();
/** Send a packet over a UDP socket
*
* Sends data to the specified address specified by either a domain name
* or an IP address and port. Returns the number of bytes sent from the
* buffer.
/** Send data to the specified host and port.
*
* By default, sendto blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* nonblocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
*
* @param host Hostname of the remote host
* @param port Port of the remote host
* @param data Buffer of data to send to the host
* @param size Size of the buffer in bytes
* @param host Domain name of the remote host or a dotted notation IP address.
* @param port Port of the remote host.
* @param data Buffer of data to send to the host.
* @param size Size of the buffer in bytes.
* @return Number of sent bytes on success, negative error
* code on failure
* code on failure.
*/
virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port,
const void *data, nsapi_size_t size);
/** Send a packet over a UDP socket
*
* Sends data to the specified address. Returns the number of bytes
* sent from the buffer.
/** Send data to the specified address.
*
* By default, sendto blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* nonblocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
*
* @param address The SocketAddress of the remote host
* @param data Buffer of data to send to the host
* @param size Size of the buffer in bytes
* @param address The SocketAddress of the remote host.
* @param data Buffer of data to send to the host.
* @param size Size of the buffer in bytes.
* @return Number of sent bytes on success, negative error
* code on failure
* code on failure.
*/
virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
const void *data, nsapi_size_t size);
/** Receive a datagram over a UDP socket
/** Receive a datagram and store the source address in address if it's not NULL.
*
* Receives a datagram and stores the source address in address if address
* is not NULL. Returns the number of bytes written into the buffer. If the
* datagram is larger than the buffer, the excess data is silently discarded.
* By default, recvfrom blocks until a datagram is received. If socket is set to
* nonblocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
* is returned.
*
* If socket is connected, only packets coming from connected peer address
* @note If the datagram is larger than the buffer, the excess data is silently discarded.
*
* @note If socket is connected, only packets coming from connected peer address
* are accepted.
*
* @note recvfrom() is allowed write to address and data buffers even if error occurs.
*
* By default, recvfrom blocks until a datagram is received. If socket is set to
* non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
* is returned.
*
* @param address Destination for the source address or NULL
* @param data Destination buffer for datagram received from the host
* @param size Size of the buffer in bytes
* @param address Destination for the source address or NULL.
* @param data Destination buffer for datagram received from the host.
* @param size Size of the buffer in bytes.
* @return Number of received bytes on success, negative error
* code on failure
* code on failure.
*/
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
void *data, nsapi_size_t size);
/** Set remote peer address
*
* Set the remote address for next send() call and filtering
* for incomming packets. To reset the address, zero initialised
/** Set the remote address for next send() call and filtering
* of incoming packets. To reset the address, zero initialized
* SocketAddress must be in the address parameter.
*
* @param address The SocketAddress of the remote host
* @return 0 on success, negative error code on failure
* @param address The SocketAddress of the remote host.
* @return 0 on success, negative error code on failure.
*/
virtual nsapi_error_t connect(const SocketAddress &address);
/** Send a datagram to pre-specified remote.
*
* The socket must be connected to a remote host before send() call.
* Returns the number of bytes sent from the buffer.
/** Send a datagram to connected remote address.
*
* By default, send blocks until all data is sent. If socket is set to
* non-blocking or times out, a partial amount can be written.
* nonblocking or times out, a partial amount can be written.
* NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
*
* @param data Buffer of data to send to the host
* @param size Size of the buffer in bytes
* @note The socket must be connected to a remote host before send() call.
*
* @param data Buffer of data to send to the host.
* @param size Size of the buffer in bytes.
* @return Number of sent bytes on success, negative error
* code on failure.
*/
@ -146,40 +133,44 @@ public:
/** Receive data from a socket.
*
* This is equivalent of calling recvfrom(NULL, data, size).
* This is equivalent to calling recvfrom(NULL, data, size).
*
* If socket is connected, only packets coming from connected peer address
* If the socket is connected, only packets coming from a connected peer address
* are accepted.
*
* By default, recv blocks until some data is received. If socket is set to
* nonblocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
* indicate no data.
*
* @note recv() is allowed write to data buffer even if error occurs.
*
* By default, recv blocks until some data is received. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
* indicate no data.
*
* @param data Destination buffer for data received from the host
* @param size Size of the buffer in bytes
* @param data Pointer to buffer for data received from the host.
* @param size Size of the buffer in bytes.
* @return Number of received bytes on success, negative error
* code on failure.
*/
virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
/** Not implemented for UDP
/** Not implemented for UDP.
*
* @param error unused
* @param error Not used.
* @return NSAPI_ERROR_UNSUPPORTED
*/
virtual Socket *accept(nsapi_error_t *error = NULL);
/** Not implemented for UDP
/** Not implemented for UDP.
*
* @param backlog unused
* @param backlog Not used.
* @return NSAPI_ERROR_UNSUPPORTED
*/
virtual nsapi_error_t listen(int backlog = 1);
#if !defined(DOXYGEN_ONLY)
protected:
virtual nsapi_protocol_t get_proto();
#endif //!defined(DOXYGEN_ONLY)
};

75
features/netsocket/WiFiInterface.h
View File

@ -22,104 +22,103 @@
#include "netsocket/NetworkInterface.h"
#include "netsocket/WiFiAccessPoint.h"
/** WiFiInterface class
/** Common interface that is shared between Wi-Fi devices.
*
* Common interface that is shared between WiFi devices
* @addtogroup netsocket
*/
class WiFiInterface: public virtual NetworkInterface {
public:
/** Get the default WiFi interface.
/** Get the default Wi-Fi interface.
*
* This is provided as a weak method so applications can override.
* Default behaviour is to get the target's default interface, if
* any.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
static WiFiInterface *get_default_instance();
/** Set the WiFi network credentials
/** Set the Wi-Fi network credentials.
*
* @param ssid Name of the network to connect to
* @param pass Security passphrase to connect to the network
* @param ssid Name of the network to connect to.
* @param pass Security passphrase to connect to the network.
* @param security Type of encryption for connection
* (defaults to NSAPI_SECURITY_NONE)
* @return 0 on success, or error code on failure
* (defaults to NSAPI_SECURITY_NONE).
* @return NSAPI_ERROR_OK on success, or error code on failure.
*/
virtual nsapi_error_t set_credentials(const char *ssid, const char *pass,
nsapi_security_t security = NSAPI_SECURITY_NONE) = 0;
/** Set the WiFi network channel
/** Set the Wi-Fi network channel.
*
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0)
* @return 0 on success, or error code on failure
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0).
* @return NSAPI_ERROR_OK on success, or error code on failure.
*/
virtual nsapi_error_t set_channel(uint8_t channel) = 0;
/** Gets the current radio signal strength for active connection
/** Get the current radio signal strength for active connection.
*
* @return Connection strength in dBm (negative value),
* or 0 if measurement impossible
* or 0 if measurement impossible.
*/
virtual int8_t get_rssi() = 0;
/** Start the interface
/** Attempt to connect to a Wi-Fi network.
*
* Attempts to connect to a WiFi network.
*
* @param ssid Name of the network to connect to
* @param pass Security passphrase to connect to the network
* @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE)
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0)
* @return 0 on success, or error code on failure
* @param ssid Name of the network to connect to.
* @param pass Security passphrase to connect to the network.
* @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE).
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0).
* @return NSAPI_ERROR_OK on success, or error code on failure.
*/
virtual nsapi_error_t connect(const char *ssid, const char *pass,
nsapi_security_t security = NSAPI_SECURITY_NONE, uint8_t channel = 0) = 0;
/** Start the interface
*
* Attempts to connect to a WiFi network. Requires ssid and passphrase to be set.
/** Attempt to connect to a Wi-Fi network. Requires ssid and passphrase to be set.
* If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned.
*
* @return 0 on success, negative error code on failure
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t connect() = 0;
/** Stop the interface
/** Stop the interface.
*
* @return 0 on success, or error code on failure
* @return NSAPI_ERROR_OK on success, or error code on failure.
*/
virtual nsapi_error_t disconnect() = 0;
/** Scan for available networks
/** Scan for available networks.
*
* This function will block. If the @a count is 0, function will only return count of available networks, so that
* user can allocated necessary memory. If the \p count is grater than 0 and the a \p res is not NULL it'll be populated
* with discovered networks up to value of \p count.
* This function will block. If the count is 0, function will only return count of available networks, so that
* user can allocated necessary memory. If the count is grater than 0 and the a \p res is not NULL it'll be populated
* with discovered networks up to value of count.
*
* @param res Pointer to allocated array to store discovered AP
* @param count Size of allocated @a res array, or 0 to only count available AP
* @return Number of entries in \p count, or if \p count was 0 number of available networks,
* negative on error see @a nsapi_error
* @param res Pointer to allocated array to store discovered APs.
* @param count Size of allocated res array, or 0 to only count available APs.
* @return Number of entries in res, or if count was 0 number of available networks.
* Negative on error (@see nsapi_types.h for nsapi_error).
*/
virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;
/** @copydoc NetworkInterface::wifiInterface
*/
virtual WiFiInterface *wifiInterface()
{
return this;
}
#if !defined(DOXYGEN_ONLY)
protected:
/** Get the target's default WiFi interface.
/** Get the target's default Wi-Fi interface.
*
* This is provided as a weak method so targets can override. The
* default implementation returns NULL.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
static WiFiInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
};
#endif

8
features/netsocket/nsapi_types.h
View File

@ -351,7 +351,7 @@ typedef struct nsapi_stack_api {
*/
nsapi_error_t (*add_dns_server)(nsapi_stack_t *stack, nsapi_addr_t addr);
/* Set stack-specific stack options
/** Set stack-specific stack options
*
* The setstackopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options,
@ -367,7 +367,7 @@ typedef struct nsapi_stack_api {
nsapi_error_t (*setstackopt)(nsapi_stack_t *stack, int level,
int optname, const void *optval, unsigned optlen);
/* Get stack-specific stack options
/** Get stack-specific stack options
*
* The getstackopt allow an application to retrieve stack-specific hints
* from the underlying stack. For unsupported options,
@ -567,7 +567,7 @@ typedef struct nsapi_stack_api {
void (*socket_attach)(nsapi_stack_t *stack, nsapi_socket_t socket,
void (*callback)(void *), void *data);
/* Set stack-specific socket options
/** Set stack-specific socket options
*
* The setsockopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options,
@ -584,7 +584,7 @@ typedef struct nsapi_stack_api {
nsapi_error_t (*setsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level,
int optname, const void *optval, unsigned optlen);
/* Get stack-specific socket options
/** Get stack-specific socket options
*
* The getstackopt allow an application to retrieve stack-specific hints
* from the underlying stack. For unsupported options,

177
platform/NonCopyable.h
View File

@ -23,91 +23,106 @@
namespace mbed {
/** \addtogroup platform */
/** @{*/
/**
* Inheriting from this class autogeneration of copy construction and copy
* assignment operations.
* \defgroup platform_NonCopyable NonCopyable class
* @{
*/
/**
* Prevents generation of copy constructor and copy assignment operator in
* derived classes.
*
* Classes which are not value type should inherit privately from this class
* to avoid generation of invalid copy constructor or copy assignment operator
* which can lead to unnoticeable programming errors.
* @par Usage
*
* As an example consider the following signature:
* To prevent generation of copy constructor and copy assignment operator,
* inherit privately from the NonCopyable class.
*
* @code
* class Resource;
* class Resource : NonCopyable<Resource> { };
*
* class Foo {
* public:
* Foo() : _resource(new Resource()) { }
* ~Foo() { delete _resource; }
* private:
* Resource* _resource;
* Resource r;
* // generates compile time error:
* Resource r2 = r;
* @endcode
*
* @par Background information
*
* Instances of polymorphic classes are not meant to be copied. The
* C++ standards generate a default copy constructor and copy assignment
* function if these functions have not been defined in the class.
*
* Consider the following example:
*
* @code
* // base class representing a connection
* struct Connection {
* Connection();
* virtual ~Connection();
* virtual void open() = 0;
* }
*
* Foo get_foo();
*
* Foo foo = get_foo();
* @endcode
*
* There is a bug in this function, it returns a temporary value which will be
* byte copied into foo then destroyed. Unfortunately, internally the Foo class
* manage a pointer to a Resource object. This pointer will be released when the
* temporary is destroyed and foo will manage a pointer to an already released
* Resource.
*
* Two issues has to be fixed in the example above:
* - Function signature has to be changed to reflect the fact that Foo
* instances cannot be copied. In that case accessor should return a
* reference to give access to objects already existing and managed.
* Generator on the other hand should return a pointer to the created object.
*
* @code
* // return a reference to an already managed Foo instance
* Foo& get_foo();
* Foo& foo = get_foo();
*
* // create a new Foo instance
* Foo* make_foo();
* Foo* m = make_foo();
* @endcode
*
* - Copy constructor and copy assignment operator has to be made private
* in the Foo class. It prevents unwanted copy of Foo objects. This can be
* done by declaring copy constructor and copy assignment in the private
* section of the Foo class.
*
* @code
* class Foo {
* class SerialConnection : public Connection {
* public:
* Foo() : _resource(new Resource()) { }
* ~Foo() { delete _resource; }
* SerialConnection(Serial*);
*
* private:
* // disallow copy operations
* Foo(const Foo&);
* Foo& operator=(const Foo&);
* // data members
* Resource* _resource;
* Serial* _serial;
* };
*
* Connection& get_connection() {
* static SerialConnection serial_connection;
* return serial_connection;
* }
*
* Connection connection = get_connection();
* @endcode
*
* There is a subtle bug in this code, the function get_connection returns a
* reference to a Connection which is captured by value instead of reference.
*
* When `get_connection` returns a reference to serial_connection it is copied into
* the local variable connection. The vtable and others members defined in Connection
* are copied, but members defined in SerialConnection are left apart. This can cause
* severe crashes or bugs if the virtual functions captured use members not present
* in the base declaration.
*
* To solve that problem, the copy constructor and assignment operator have to
* be declared (but don't need to be defined) in the private section of the
* Connection class:
*
* @code
* struct Connection {
* private:
* Connection(const Connection&);
* Connection& operator=(const Connection&);
* }
* @endcode
*
* Another solution is to inherit privately from the NonCopyable class.
* It reduces the boiler plate needed to avoid copy operations but more
* importantly it clarifies the programmer intent and the object semantic.
* Although manually declaring private copy constructor and assignment functions
* works, it is not ideal. These declarations are usually easy to forget,
* not immediately visible, and may be obscure to uninformed programmers.
*
* class Foo : private NonCopyable<Foo> {
* public:
* Foo() : _resource(new Resource()) { }
* ~Foo() { delete _resource; }
* private:
* Resource* _resource;
* Using the NonCopyable class reduces the boilerplate required and expresses
* the intent because class inheritance appears right after the class name
* declaration.
*
* @code
* struct Connection : private NonCopyable<Connection> {
* // regular declarations
* }
* @endcode
*
* @tparam T The type that should be made non copyable. It prevent cases where
* the empty base optimization cannot be applied and therefore ensure that the
* cost of this semantic sugar is null.
*
* @par Implementation details
*
* Using a template type prevents cases where the empty base optimization cannot
* be applied and therefore ensures that the cost of the NonCopyable semantic
* sugar is null.
*
* As an example, the empty base optimization is prohibited if one of the empty
* base class is also a base type of the first non static data member:
* base classes is also a base type of the first nonstatic data member:
*
* @code
* struct A { };
@ -121,11 +136,11 @@ namespace mbed {
* };
*
* // empty base optimization cannot be applied here because A from C and A from
* // B shall have a different address. In that case, with the alignment
* // B have a different address. In that case, with the alignment
* // sizeof(C) == 2* sizeof(int)
* @endcode
*
* The solution to that problem is to templatize the empty class to makes it
* The solution to that problem is to templatize the empty class to make it
* unique to the type it is applied to:
*
* @code
@ -142,12 +157,15 @@ namespace mbed {
* // kind of A. sizeof(C) == sizeof(B) == sizeof(int).
* @endcode
*
* @note Compile time errors are disabled if the develop or the release profile
* is used. To override this behavior and force compile time errors in all profile
* @tparam T The type that should be made noncopyable.
*
* @note Compile time errors are disabled if you use the develop or release profile.
* To override this behavior and force compile time errors in all profiles,
* set the configuration parameter "platform.force-non-copyable-error" to true.
*/
template<typename T>
class NonCopyable {
#ifndef DOXYGEN_ONLY
protected:
/**
* Disallow construction of NonCopyable objects from outside of its hierarchy.
@ -162,11 +180,11 @@ protected:
/**
* NonCopyable copy constructor.
*
* A compile time warning is issued when this function is used and a runtime
* A compile time warning is issued when this function is used, and a runtime
* warning is printed when the copy construction of the noncopyable happens.
*
* If you see this warning, your code is probably doing something unspecified.
* Copy of non copyable resources can lead to resource leak and random error.
* Copying of noncopyable resources can lead to resource leak and random error.
*/
MBED_DEPRECATED("Invalid copy construction of a NonCopyable resource.")
NonCopyable(const NonCopyable &)
@ -177,11 +195,11 @@ protected:
/**
* NonCopyable copy assignment operator.
*
* A compile time warning is issued when this function is used and a runtime
* A compile time warning is issued when this function is used, and a runtime
* warning is printed when the copy construction of the noncopyable happens.
*
* If you see this warning, your code is probably doing something unspecified.
* Copy of non copyable resources can lead to resource leak and random error.
* Copying of noncopyable resources can lead to resource leak and random error.
*/
MBED_DEPRECATED("Invalid copy assignment of a NonCopyable resource.")
NonCopyable &operator=(const NonCopyable &)
@ -193,19 +211,24 @@ protected:
#else
private:
/**
* Declare copy constructor as private, any attempt to copy construct
* Declare copy constructor as private. Any attempt to copy construct
* a NonCopyable will fail at compile time.
*/
NonCopyable(const NonCopyable &);
/**
* Declare copy assignment operator as private, any attempt to copy assign
* Declare copy assignment operator as private. Any attempt to copy assign
* a NonCopyable will fail at compile time.
*/
NonCopyable &operator=(const NonCopyable &);
#endif
#endif
};
/**@}*/
/**@}*/
} // namespace mbed
#endif /* MBED_NONCOPYABLE_H_ */

56
platform/PlatformMutex.h
View File

@ -1,10 +1,3 @@
/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_PlatformMutex PlatformMutex class
* @{
*/
/* mbed Microcontroller Library
* Copyright (c) 2006-2013 ARM Limited
*
@ -25,32 +18,67 @@
#include "platform/NonCopyable.h"
/** \addtogroup platform
* @{
*/
/** \defgroup platform_PlatformMutex PlatformMutex class
* @{
*/
/** The PlatformMutex class is used to synchronize the execution of threads.
*
* Mbed drivers use the PlatformMutex class instead of rtos::Mutex.
* This enables the use of drivers when the Mbed OS is compiled without the RTOS.
*
* @note
* - When the RTOS is present, the PlatformMutex becomes a typedef for rtos::Mutex.
* - When the RTOS is absent, all methods are defined as noop.
*/
#ifdef MBED_CONF_RTOS_PRESENT
#include "rtos/Mutex.h"
typedef rtos::Mutex PlatformMutex;
#else
/** A stub mutex for when an RTOS is not present
*/
class PlatformMutex: private mbed::NonCopyable<PlatformMutex> {
public:
/** Create a PlatformMutex object.
*
* @note When the RTOS is present, this is an alias for rtos::Mutex::Mutex().
*/
PlatformMutex()
{
// Stub
}
/** PlatformMutex destructor.
*
* @note When the RTOS is present, this is an alias for rtos::Mutex::~Mutex().
*/
~PlatformMutex()
{
// Stub
}
/** Wait until a PlatformMutex becomes available.
*
* @note
* - When the RTOS is present, this is an alias for rtos::Mutex::lock().
* - When the RTOS is absent, this is a noop.
*/
void lock()
{
// Do nothing
}
/** Unlock a PlatformMutex that the same thread has previously locked.
*
* @note
* - When the RTOS is present, this is an alias for rtos::Mutex::unlock().
* - When the RTOS is absent, this is a noop.
*/
void unlock()
{
// Do nothing
}
};

198
rtos/ConditionVariable.h
View File

@ -1,5 +1,5 @@
/* mbed Microcontroller Library
* Copyright (c) 2017-2017 ARM Limited
/* Mbed Microcontroller Library
* Copyright (c) 2017-2018 ARM Limited
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@ -35,108 +35,147 @@ namespace rtos {
struct Waiter;
/** This class provides a safe way to wait for or send notifications of condition changes
/** The ConditionVariable class is a synchronization primitive that allows
* threads to wait until a particular condition occurs.
*
* This class is used in conjunction with a mutex to safely wait for or
* notify waiters of condition changes to a resource accessible by multiple
* Use the condition variable in conjunction with a mutex to safely wait for
* or notify waiters of condition changes to a resource accessible by multiple
* threads.
*
* # Defined behavior
* - All threads waiting on the condition variable wake when
* ConditionVariable::notify_all is called.
* - If one or more threads are waiting on the condition variable at least
* one of them wakes when ConditionVariable::notify is called.
* The thread that intends to wait on a ConditionVariable must:
* - Acquire a lock on a mutex.
* - Execute `wait`, `wait_for` or `wait_until`. While the thread is waiting,
* the mutex is unlocked.
* - When the condition variable has been notified, or in the case of `wait_for`
* and `wait_until` the timeout expires, the thread is awakened.
*
* # Undefined behavior
* - The thread which is unblocked on ConditionVariable::notify_one is
* undefined if there are multiple waiters.
* - The order which in which waiting threads acquire the condition variable's
* mutex after ConditionVariable::notify_all is called is undefined.
* - When ConditionVariable::notify_one or ConditionVariable::notify_all is
* called and there are one or more waiters and one or more threads attempting
* to acquire the condition variable's mutex the order in which the mutex is
* acquired is undefined.
* - The behavior of ConditionVariable::wait and ConditionVariable::wait_for
* The thread that intends to notify a ConditionVariable must:
* - Acquire a lock on the mutex used to construct the condition variable.
* - Execute `notify_one` or `notify_all` on the condition variable.
*
* All threads waiting on the condition variable wake when
* `ConditionVariable::notify_all` is called.
* At least one thread waiting on the condition variable wakes
* when `ConditionVariable::notify_one` is called.
*
* While a thread is waiting for notification of a
* ConditionVariable, it releases the lock held on the mutex.
* The ConditionVariable reacquires the mutex lock before exiting the wait
* function.
*
* #### Unspecified behavior
* - The thread that is unblocked on `ConditionVariable::notify_one` is
* unspecified if there are multiple waiters.
* - When `ConditionVariable::notify_one` or `ConditionVariable::notify_all` is
* called and there are one or more waiters, and one or more threads
* attempting to acquire the condition variable's mutex, the order in which the mutex is
* acquired is unspecified.
* - Spurious notifications (not triggered by the application) can occur.
*
* #### Undefined behavior
* - Calling wait if the mutex is not locked by the current thread is undefined
* behavior.
* - The order in which waiting threads acquire the condition variable's
* mutex after `ConditionVariable::notify_all` is called is undefined.
* - The behavior of `ConditionVariable::wait` and `ConditionVariable::wait_for`
* is undefined if the condition variable's mutex is locked more than once by
* the calling thread.
* - Spurious notifications (not triggered by the application) can occur
* and it is not defined when these occur.
*
* @note Synchronization level: Thread safe
*
* Example:
*
* @code
* #include "mbed.h"
*
* Mutex mutex;
* ConditionVariable cond(mutex);
* ConditionVariable cv(mutex);
*
* // These variables are protected by locking mutex
* uint32_t count = 0;
* // These variables are protected by locking the mutex.
* uint32_t work_count = 0;
* bool done = false;
*
* void worker_thread()
* {
* // Acquire lock on mutex before accessing protected variables and waiting.
* mutex.lock();
* do {
* printf("Worker: Count %lu\r\n", count);
*
* // Wait for a condition to change
* cond.wait();
* while (done == false) {
* printf("Worker thread: Count: %lu\r\n", work_count);
*
* // Wait for main thread to notify the condition variable.
* printf("Worker thread: Waiting\r\n");
* cv.wait();
* }
*
* } while (!done);
* printf("Worker: Exiting\r\n");
*
* // The condition variable acquires the lock when exiting the `wait` function.
* // Unlock mutex when exiting the thread.
* mutex.unlock();
* }
*
* int main() {
* int main()
* {
* Thread thread;
* thread.start(worker_thread);
*
* for (int i = 0; i < 5; i++) {
*
* // Acquire lock on mutex before modifying variables and notifying.
* mutex.lock();
* // Change count and notify waiters of this
* count++;
* printf("Main: Set count to %lu\r\n", count);
* cond.notify_all();
*
* // Change count and notify waiters.
* work_count++;
* printf("Main thread: Set count to: %lu\r\n", work_count);
* printf("Main thread: Notifying worker thread\r\n");
* cv.notify_all();
*
* // Mutex must be unlocked before the worker thread can acquire it.
* mutex.unlock();
*
* wait(1.0);
* }
*
* // Change done and notify waiters of this.
* mutex.lock();
* // Change done and notify waiters of this
* done = true;
* printf("Main: Set done\r\n");
* cond.notify_all();
* cv.notify_all();
* mutex.unlock();
*
* thread.join();
*
* printf("Main: Exiting\r\n");
* }
* @endcode
*/
class ConditionVariable : private mbed::NonCopyable<ConditionVariable> {
public:
/** Create and Initialize a ConditionVariable object
/** Create and initialize a ConditionVariable object.
*
* @note You cannot call this function from ISR context.
*/
ConditionVariable(Mutex &mutex);
/** Wait for a notification
/** Wait for a notification.
*
* Wait until a notification occurs.
* Wait causes the current thread to block until the condition variable
* receives a notification from another thread.
*
* @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex and it must be locked exactly once
* @note - Spurious notifications can occur so the caller of this API
* should check to make sure the condition they are waiting on has
* been met
* ConditionVariable's mutex, and it must be locked exactly once.
*
* @note - Spurious notifications can occur, so the caller of this API
* should check to make sure the condition the caller is waiting on has
* been met.
*
* @note - The current thread releases the lock while inside the wait
* function and reacquires it upon exiting the function.
*
* Example:
* @code
* mutex.lock();
*
* while (!condition_met) {
* cond.wait();
* }
@ -150,16 +189,24 @@ public:
*/
void wait();
/** Wait for a notification until specified time
/** Wait for a notification until the specified time.
*
* @param millisec absolute end time referenced to Kernel::get_ms_count()
* @return true if a timeout occurred, false otherwise.
* Wait until causes the current thread to block until the condition
* variable is notified, or a specific time given by millisec parameter is
* reached.
*
* @param millisec Absolute end time referenced to `Kernel::get_ms_count()`
* @return `true` if a timeout occurred, `false` otherwise.
*
* @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex and it must be locked exactly once
* @note - Spurious notifications can occur so the caller of this API
* should check to make sure the condition they are waiting on has
* been met
* ConditionVariable's mutex, and it must be locked exactly once.
*
* @note - Spurious notifications can occur, so the caller of this API
* should check to make sure the condition the caller is waiting on has
* been met.
*
* @note - The current thread releases the lock while inside the wait
* function and reacquires it upon exiting the function.
*
* Example:
* @code
@ -183,16 +230,24 @@ public:
*/
bool wait_until(uint64_t millisec);
/** Wait for a notification or timeout
/** Wait for a notification or timeout.
*
* @param millisec timeout value or osWaitForever in case of no time-out.
* @return true if a timeout occurred, false otherwise.
* `Wait for` causes the current thread to block until the condition
* variable receives a notification from another thread, or the timeout
* specified by the millisec parameter is reached.
*
* @param millisec Timeout value or osWaitForever in case of no timeout.
* @return `true` if a timeout occurred, `false` otherwise.
*
* @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex and it must be locked exactly once
* @note - Spurious notifications can occur so the caller of this API
* should check to make sure the condition they are waiting on has
* been met
* ConditionVariable's mutex, and it must be locked exactly once.
*
* @note - Spurious notifications can occur, so the caller of this API
* should check to make sure the condition the caller is waiting on has
* been met.
*
* @note - The current thread releases the lock while inside the wait
* function and reacquire it upon exiting the function.
*
* Example:
* @code
@ -218,7 +273,14 @@ public:
/** Notify one waiter on this condition variable that a condition changed.
*
* @note - The thread calling this function must be the owner of the ConditionVariable's mutex
* This function unblocks one of the threads waiting for the condition
* variable.
*
* @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex.
*
* @note - The thread that is unblocked on ConditionVariable::notify_one is
* undefined if there are multiple waiters.
*
* @note You cannot call this function from ISR context.
*/
@ -226,18 +288,27 @@ public:
/** Notify all waiters on this condition variable that a condition changed.
*
* @note - The thread calling this function must be the owner of the ConditionVariable's mutex
* This function unblocks all of the threads waiting for the condition
* variable.
*
* @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex.
*
* @note - If there are one or more waiters and one or more threads
* attempting to acquire the condition variable's mutex the order in which
* the mutex is acquired is undefined.
*
* @note You cannot call this function from ISR context.
*/
void notify_all();
/** ConditionVariable destructor
/** ConditionVariable destructor.
*
* @note You cannot call this function from ISR context.
*/
~ConditionVariable();
#if !defined(DOXYGEN_ONLY)
protected:
struct Waiter {
Waiter();
@ -251,6 +322,7 @@ protected:
static void _remove_wait_list(Waiter **wait_list, Waiter *waiter);
Mutex &_mutex;
Waiter *_wait_list;
#endif // !defined(DOXYGEN_ONLY)
};
}

106
rtos/Mail.h
View File

@ -43,27 +43,30 @@ namespace rtos {
* @{
*/
/** The Mail class allow to control, send, receive, or wait for mail.
A mail is a memory block that is send to a thread or interrupt service routine.
@tparam T data type of a single message element.
@tparam queue_sz maximum number of messages in queue.
@note
Memory considerations: The mail data store and control structures will be created on current thread's stack,
both for the mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
/** The Mail class allows you to control, send, receive or wait for mail.
* A mail is a memory block that is sent to a thread or interrupt service routine (ISR).
* @tparam T Data type of a single mail message element.
* @tparam queue_sz Maximum number of mail messages in queue.
*
* @note
* Memory considerations: The mail data store and control structures are part of this class - they do not (themselves)
* allocate memory on the heap, both for the Mbed OS and underlying RTOS objects (static or dynamic RTOS memory
* pools are not being used).
*/
template<typename T, uint32_t queue_sz>
class Mail : private mbed::NonCopyable<Mail<T, queue_sz> > {
public:
/** Create and Initialize Mail queue.
/** Create and initialize Mail queue.
*
* @note You cannot call this function from ISR context.
*/
Mail() { };
/** Check if the mail queue is empty
/** Check if the mail queue is empty.
*
* @return True if the mail queue is empty, false if not
* @return State of queue.
* @retval true Mail queue is empty.
* @retval false Mail queue contains mail.
*
* @note You may call this function from ISR context.
*/
@ -72,9 +75,11 @@ public:
return _queue.empty();
}
/** Check if the mail queue is full
/** Check if the mail queue is full.
*
* @return True if the mail queue is full, false if not
* @return State of queue.
* @retval true Mail queue is full.
* @retval false Mail queue is not full.
*
* @note You may call this function from ISR context.
*/
@ -83,47 +88,55 @@ public:
return _queue.full();
}
/** Allocate a memory block of type T
@param millisec timeout value or 0 in case of no time-out. (default: 0).
@return pointer to memory block that can be filled with mail or NULL in case error.
@note You may call this function from ISR context if the millisec parameter is set to 0.
/** Allocate a memory block of type T.
*
* @param millisec Not used.
*
* @return Pointer to memory block that you can fill with mail or NULL in case error.
*
* @note You may call this function from ISR context.
*/
T *alloc(uint32_t millisec = 0)
{
T* alloc(uint32_t millisec=0) {
return _pool.alloc();
}
/** Allocate a memory block of type T and set memory block to zero.
@param millisec timeout value or 0 in case of no time-out. (default: 0).
@return pointer to memory block that can be filled with mail or NULL in case error.
@note You may call this function from ISR context if the millisec parameter is set to 0.
/** Allocate a memory block of type T, and set memory block to zero.
*
* @param millisec Not used.
*
* @return Pointer to memory block that you can fill with mail or NULL in case error.
*
* @note You may call this function from ISR context.
*/
T *calloc(uint32_t millisec = 0)
{
T* calloc(uint32_t millisec=0) {
return _pool.calloc();
}
/** Put a mail in the queue.
@param mptr memory block previously allocated with Mail::alloc or Mail::calloc.
@return status code that indicates the execution status of the function.
@note You may call this function from ISR context.
*
* @param mptr Memory block previously allocated with Mail::alloc or Mail::calloc.
*
* @return Status code that indicates the execution status of the function (osOK on success).
*
* @note You may call this function from ISR context.
*/
osStatus put(T *mptr)
{
osStatus put(T *mptr) {
return _queue.put(mptr);
}
/** Get a mail from a queue.
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
@return event that contains mail information or error code.
@note You may call this function from ISR context if the millisec parameter is set to 0.
/** Get a mail from the queue.
*
* @param millisec Timeout value or 0 in case of no timeout (default: osWaitForever).
*
* @return Event that contains mail information or error code.
* @retval osEventMessage Message received.
* @retval osOK No mail is available (and no timeout was specified).
* @retval osEventTimeout No mail has arrived during the given timeout period.
* @retval osErrorParameter A parameter is invalid or outside of a permitted range.
*
* @note You may call this function from ISR context if the millisec parameter is set to 0.
*/
osEvent get(uint32_t millisec = osWaitForever)
{
osEvent get(uint32_t millisec=osWaitForever) {
osEvent evt = _queue.get(millisec);
if (evt.status == osEventMessage) {
evt.status = osEventMail;
@ -132,13 +145,14 @@ public:
}
/** Free a memory block from a mail.
@param mptr pointer to the memory block that was obtained with Mail::get.
@return status code that indicates the execution status of the function.
@note You may call this function from ISR context.
*
* @param mptr Pointer to the memory block that was obtained with Mail::get.
*
* @return Status code that indicates the execution status of the function (osOK on success).
*
* @note You may call this function from ISR context.
*/
osStatus free(T *mptr)
{
osStatus free(T *mptr) {
return _pool.free(mptr);
}

141
rtos/Queue.h
View File

@ -22,14 +22,11 @@
#ifndef QUEUE_H
#define QUEUE_H
#include <stdint.h>
#include <string.h>
#include "cmsis_os2.h"
#include "mbed_rtos1_types.h"
#include "mbed_rtos_storage.h"
#include "platform/mbed_error.h"
#include "platform/NonCopyable.h"
#include "mbed_rtos1_types.h"
namespace rtos {
/** \addtogroup rtos */
@ -39,20 +36,30 @@ namespace rtos {
* @{
*/
/** The Queue class allow to control, send, receive, or wait for messages.
A message can be a integer or pointer value to a certain type T that is send
to a thread or interrupt service routine.
@tparam T data type of a single message element.
@tparam queue_sz maximum number of messages in queue.
@note
Memory considerations: The queue control structures will be created on current thread's stack, both for the mbed OS
and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
/** The Queue class represents a collection of objects that are stored first by
* order of priorty, and then in first-in, first-out (FIFO) order.
*
* You can use a queue when you need to store data and then access it in the same
* order that it has been stored. The order in which you retrieve the data is in
* order of descending priority. If multiple elements have the same priority,
* they are retrieved in FIFO order.
*
* The object type stored in the queue can be an integer, pointer or a generic
* type given by the template parameter T.
*
* @tparam T Specifies the type of elements stored in the queue.
* @tparam queue_sz Maximum number of messages that you can store in the queue.
*
* @note Memory considerations: The queue control structures are created on the
* current thread's stack, both for the Mbed OS and underlying RTOS
* objects (static or dynamic RTOS memory pools are not being used).
*
*/
template<typename T, uint32_t queue_sz>
class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
public:
/** Create and initialize a message Queue.
/** Create and initialize a message Queue of objects of the parameterized
* type `T` and maximum capacity specified by `queue_sz`.
*
* @note You cannot call this function from ISR context.
*/
@ -67,6 +74,7 @@ public:
_id = osMessageQueueNew(queue_sz, sizeof(T *), &attr);
MBED_ASSERT(_id);
}
/** Queue destructor
*
* @note You cannot call this function from ISR context.
@ -76,7 +84,7 @@ public:
osMessageQueueDelete(_id);
}
/** Check if the queue is empty
/** Check if the queue is empty.
*
* @return True if the queue is empty, false if not
*
@ -87,7 +95,7 @@ public:
return osMessageQueueGetCount(_id) == 0;
}
/** Check if the queue is full
/** Check if the queue is full.
*
* @return True if the queue is full, false if not
*
@ -98,36 +106,83 @@ public:
return osMessageQueueGetSpace(_id) == 0;
}
/** Put a message in a Queue.
@param data message pointer.
@param millisec timeout value or 0 in case of no time-out. (default: 0)
@param prio priority value or 0 in case of default. (default: 0)
@return status code that indicates the execution status of the function:
@a osOK the message has been put into the queue.
@a osErrorTimeout the message could not be put into the queue in the given time.
@a osErrorResource not enough space in the queue.
@a osErrorParameter internal error or non-zero timeout specified in an ISR.
@note You may call this function from ISR context if the millisec parameter is set to 0.
/** Inserts the given element to the end of the queue.
*
* This function puts the message pointed to by `data` into the queue. The
* parameter `prio` is used to sort the message according to their priority
* (higher numbers indicate higher priority) on insertion.
*
* The timeout indicated by the parameter `millisec` specifies how long the
* function blocks waiting for the message to be inserted into the
* queue.
*
* The parameter `millisec` can have the following values:
* - When the timeout is 0 (the default), the function returns instantly.
* - When the timeout is osWaitForever, the function waits for an
* infinite time.
* - For all other values, the function waits for the given number of
* milliseconds.
*
* @param data Pointer to the element to insert into the queue.
* @param millisec Timeout for the operation to be executed, or 0 in case
* of no timeout. (default: 0)
* @param prio Priority of the operation or 0 in case of default.
* (default: 0)
*
* @return Status code that indicates the execution status of the function:
* @a osOK The message has been successfully inserted
* into the queue.
* @a osErrorTimeout The message could not be inserted into the
* queue in the given time.
* @a osErrorResource The message could not be inserted because
* the queue is full.
* @a osErrorParameter Internal error or nonzero timeout specified
* in an ISR.
*
* @note You may call this function from ISR context if the millisec
* parameter is set to 0.
*
*/
osStatus put(T *data, uint32_t millisec = 0, uint8_t prio = 0)
{
osStatus put(T* data, uint32_t millisec=0, uint8_t prio=0) {
return osMessageQueuePut(_id, &data, prio, millisec);
}
/** Get a message or Wait for a message from a Queue. Messages are retrieved in a descending priority order or
first in first out when the priorities are the same.
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
@return event information that includes the message in event.value and the status code in event.status:
@a osEventMessage message received.
@a osOK no message is available in the queue and no timeout was specified.
@a osEventTimeout no message has arrived during the given timeout period.
@a osErrorParameter a parameter is invalid or outside of a permitted range.
@note You may call this function from ISR context if the millisec parameter is set to 0.
/** Get a message or wait for a message from the queue.
*
* This function retrieves a message from the queue. The message is stored
* in the value field of the returned `osEvent` object.
*
* The timeout specified by the parameter `millisec` specifies how long the
* function waits to retrieve the message from the queue.
*
* The timeout parameter can have the following values:
* - When the timeout is 0, the function returns instantly.
* - When the timeout is osWaitForever (default), the function waits
* infinite time until the message is retrieved.
* - When the timeout is any other value, the function waits for the
* specified time before returning a timeout error.
*
* Messages are retrieved in descending priority order. If two messages
* share the same priority level, they are retrieved in first-in, first-out
* (FIFO) order.
*
* @param millisec Timeout value or 0 in case of no time-out.
* (default: osWaitForever).
*
* @return Event information that includes the message in event. Message
* value and the status code in event.status:
* @a osEventMessage Message successfully received.
* @a osOK No message is available in the queue, and no
* timeout was specified.
* @a osEventTimeout No message was received before a timeout
* event occurred.
* @a osErrorParameter A parameter is invalid or outside of a
* permitted range.
*
* @note You may call this function from ISR context if the millisec
* parameter is set to 0.
*/
osEvent get(uint32_t millisec = osWaitForever)
{
osEvent get(uint32_t millisec=osWaitForever) {
osEvent event;
T *data = NULL;
osStatus_t res = osMessageQueueGet(_id, &data, NULL, millisec);
@ -161,6 +216,6 @@ private:
/** @}*/
/** @}*/
}
#endif
} // namespace rtos
#endif // QUEUE_H