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 #8519 from cmonr/rollup 

Rollup PR - UK Docathon pt1
pull/8537/head
Cruz Monrreal 2018-10-24 09:32:46 -05:00 committed by GitHub
parent 7cd1478147 fe1d6b0565
commit b18c819837
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 148 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
drivers/I2CSlave.h
View File

@ -25,38 +25,41 @@
namespace mbed {
/** \addtogroup drivers */
/** An I2C Slave, used for communicating with an I2C Master device
/** An I2C Slave, used for communicating with an I2C Master device.
*
* @note Synchronization level: Not protected
*
* Example:
* Example Simple I2C responder:
* @code
* // Simple I2C responder
* #include <mbed.h>
*
* I2CSlave slave(p9, p10);
* const int SLAVE_ADDRESS = 0xA0;
* const char message[] = "Slave!";
*
* I2CSlave slave(I2C_SDA, I2C_SCL);
*
* int main() {
* char buf[10];
* char msg[] = "Slave!";
*
* slave.address(0xA0);
* slave.address(SLAVE_ADDRESS);
* while (1) {
* int i = slave.receive();
* switch (i) {
* int operation = slave.receive();
* switch (operation) {
* case I2CSlave::ReadAddressed:
* slave.write(msg, strlen(msg) + 1); // Includes null char
* int status = slave.write(message, sizeof(message));
* if (status == 0) {
* printf("Written message: %s\n", message);
* } else {
* printf("Failed to write message.\n");
* }
* break;
* case I2CSlave::WriteGeneral:
* slave.read(buf, 10);
* printf("Read G: %s\n", buf);
* int byte_read = slave.read();
* printf("Read General: %c (%d)\n", byte_read, byte_read);
* break;
* case I2CSlave::WriteAddressed:
* slave.read(buf, 10);
* printf("Read A: %s\n", buf);
* int byte_read = slave.read();
* printf("Read Addressed: %c (%d)\n", byte_read, byte_read);
* break;
* }
* for(int i = 0; i < 10; i++) buf[i] = 0; // Clear buffer
* }
* }
* @endcode
@ -74,71 +77,71 @@ public:
/** Create an I2C Slave interface, connected to the specified pins.
*
* @param sda I2C data line pin
* @param scl I2C clock line pin
* @param sda I2C data line pin.
* @param scl I2C clock line pin.
*/
I2CSlave(PinName sda, PinName scl);
/** Set the frequency of the I2C interface
/** Set the frequency of the I2C interface.
*
* @param hz The bus frequency in hertz
* @param hz The bus frequency in Hertz.
*/
void frequency(int hz);
/** Checks to see if this I2C Slave has been addressed.
/** Check if this I2C Slave has been addressed.
*
* @returns
* A status indicating if the device has been addressed, and how
* - NoData - the slave has not been addressed
* - ReadAddressed - the master has requested a read from this slave
* - WriteAddressed - the master is writing to this slave
* - WriteGeneral - the master is writing to all slave
* @return A status indicating if the device has been addressed and how.
* @retval NoData The slave has not been addressed.
* @retval ReadAddressed The master has requested a read from this slave.
* @retval WriteAddressed The master is writing to this slave.
* @retval WriteGeneral The master is writing to all slave.
*/
int receive(void);
/** Read from an I2C master.
/** Read specified number of bytes from an I2C master.
*
* @param data pointer to the byte array to read data in to
* @param length maximum number of bytes to read
* @param data Pointer to the buffer to read data into.
* @param length Number of bytes to read.
*
* @returns
* 0 on success,
* non-0 otherwise
* @return Result of the operation.
* @retval 0 If the number of bytes read is equal to length requested.
* @retval nonzero On error or if the number of bytes read is less than requested.
*/
int read(char *data, int length);
/** Read a single byte from an I2C master.
*
* @returns
* the byte read
* @return The byte read.
*/
int read(void);
/** Write to an I2C master.
*
* @param data pointer to the byte array to be transmitted
* @param length the number of bytes to transmite
* @param data Pointer to the buffer containing the data to be sent.
* @param length Number of bytes to send.
*
* @returns
* 0 on success,
* non-0 otherwise
* @return
* @retval 0 If written all bytes successfully.
* @retval nonzero On error or if the number of bytes written is less than requested.
*/
int write(const char *data, int length);
/** Write a single byte to an I2C master.
*
* @param data the byte to write
* @param data Value to write.
*
* @returns
* '1' if an ACK was received,
* '0' otherwise
* @return Result of the operation.
* @retval 0 If a NACK is received.
* @retval 1 If an ACK is received.
* @retval 2 On timeout.
*/
int write(int data);
/** Sets the I2C slave address.
/** Set the I2C slave address.
*
* @param address The address to set for the slave (ignoring the least
* signifcant bit). If set to 0, the slave will only respond to the
* @param address The address to set for the slave (least significant bit is ignored).
*
* @note If address is set to 0, the slave will only respond to the
* general call address.
*/
void address(int address);
@ -147,8 +150,13 @@ public:
*/
void stop(void);
#if !defined(DOXYGEN_ONLY)
protected:
/* Internal i2c object identifying the resources */
i2c_t _i2c;
#endif //!defined(DOXYGEN_ONLY)
};
} // namespace mbed

54
drivers/SPISlave.h
View File

@ -26,19 +26,18 @@
namespace mbed {
/** \addtogroup drivers */
/** A SPI slave, used for communicating with a SPI Master device
/** A SPI slave, used for communicating with a SPI master device.
*
* 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.
*
* @note Synchronization level: Not protected
*
* Example:
* Example of how to reply to a SPI master as slave:
* @code
* // Reply to a SPI master as slave
*
* #include "mbed.h"
*
* SPISlave device(p5, p6, p7, p8); // mosi, miso, sclk, ssel
* SPISlave device(SPI_MOSI, SPI_MISO, SPI_SCLK, SPI_CS);
*
* int main() {
* device.reply(0x00); // Prime SPI with first reply
@ -57,21 +56,21 @@ class SPISlave : private NonCopyable<SPISlave> {
public:
/** Create a SPI slave connected to the specified pins
/** Create a SPI slave connected to the specified pins.
*
* mosi or miso can be specified as NC if not used
* @note Either mosi or miso can be specified 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.
*/
SPISlave(PinName mosi, PinName miso, PinName sclk, PinName ssel);
/** 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
@ -84,40 +83,47 @@ 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);
/** Polls the SPI to see if data has been received
/** Polls the SPI to see if data has been received.
*
* @returns
* 0 if no data,
* 1 otherwise
* @return Presence of received data.
* @retval 0 No data waiting.
* @retval 1 Data waiting.
*/
int receive(void);
/** Retrieve data from receive buffer as slave
/** Retrieve data from receive buffer as slave.
*
* @returns
* the data in the receive buffer
* @return The data in the receive buffer.
*/
int read(void);
/** Fill the transmission buffer with the value to be written out
* as slave on the next received message from the master.
*
* @param value the data to be transmitted next
* @param value The data to be transmitted next.
*/
void reply(int value);
#if !defined(DOXYGEN_ONLY)
protected:
/* Internal SPI object identifying the resources */
spi_t _spi;
/* How many bits in an SPI frame */
int _bits;
/* Clock phase and polarity */
int _mode;
/* Clock frequency */
int _hz;
#endif //!defined(DOXYGEN_ONLY)
};
} // namespace mbed

10
features/netsocket/SocketAddress.h
View File

@ -42,7 +42,7 @@ public:
*
* @param stack Network stack to use for DNS resolution
* @param host Hostname to resolve
* @param port Optional 16-bit port
* @param port Optional 16-bit port, defaults to 0
* @deprecated
* Constructors hide possible errors. Replaced by
* NetworkInterface::gethostbyname.
@ -57,16 +57,18 @@ public:
}
/** Create a SocketAddress from a raw IP address and port
*
* To construct from a host name, use NetworkInterface::gethostbyname
*
* @param addr Raw IP address
* @param port Optional 16-bit port
* @param port Optional 16-bit port, defaults to 0
*/
SocketAddress(nsapi_addr_t addr = nsapi_addr_t(), uint16_t port = 0);
/** Create a SocketAddress from an IP address and port
*
* @param addr Null-terminated representation of the IP address
* @param port Optional 16-bit port
* @param port Optional 16-bit port, defaults to 0
*/
SocketAddress(const char *addr, uint16_t port = 0);
@ -74,7 +76,7 @@ public:
*
* @param bytes Raw IP address in big-endian order
* @param version IP address version, NSAPI_IPv4 or NSAPI_IPv6
* @param port Optional 16-bit port
* @param port Optional 16-bit port, defaults to 0
*/
SocketAddress(const void *bytes, nsapi_version_t version, uint16_t port = 0);

33
platform/Span.h
View File

@ -25,6 +25,13 @@
namespace mbed {
/** \addtogroup platform */
/** @{*/
/**
* \defgroup platform_Span Span class
* @{
*/
// Internal details of Span
// It is used construct Span from Span of convertible types (non const -> const)
namespace span_detail {
@ -47,12 +54,18 @@ public:
}
#if defined(DOXYGEN_ONLY)
/**
* Special value for the Extent parameter of Span.
* If the type uses this value, then the size of the array is stored in the object
* at runtime.
*
* @relates Span
*/
const ptrdiff_t SPAN_DYNAMIC_EXTENT = -1;
#else
#define SPAN_DYNAMIC_EXTENT -1
#endif
/**
* Nonowning view to a sequence of contiguous elements.
@ -691,7 +704,7 @@ struct Span<ElementType, SPAN_DYNAMIC_EXTENT> {
* @return A subspan of this starting at Offset and Count long.
*/
template<std::ptrdiff_t Offset, std::ptrdiff_t Count>
Span<element_type, Count == SPAN_DYNAMIC_EXTENT ? SPAN_DYNAMIC_EXTENT : Count>
Span<element_type, Count>
subspan() const
{
MBED_ASSERT(0 <= Offset && Offset <= _size);
@ -699,7 +712,7 @@ struct Span<ElementType, SPAN_DYNAMIC_EXTENT> {
(Count == SPAN_DYNAMIC_EXTENT) ||
(0 <= Count && (Count + Offset) <= _size)
);
return Span<element_type, Count == SPAN_DYNAMIC_EXTENT ? SPAN_DYNAMIC_EXTENT : Count>(
return Span<element_type, Count>(
_data + Offset,
Count == SPAN_DYNAMIC_EXTENT ? _size - Offset : Count
);
@ -774,6 +787,8 @@ private:
*
* @return True if Spans in input have the same size and the same content and
* false otherwise.
*
* @relates Span
*/
template<typename T, typename U, ptrdiff_t LhsExtent, ptrdiff_t RhsExtent>
bool operator==(const Span<T, LhsExtent> &lhs, const Span<U, RhsExtent> &rhs)
@ -827,6 +842,8 @@ bool operator==(T (&lhs)[LhsExtent], const Span<T, RhsExtent> &rhs)
*
* @return True if arrays in input do not have the same size or the same content
* and false otherwise.
*
* @relates Span
*/
template<typename T, typename U, ptrdiff_t LhsExtent, ptrdiff_t RhsExtent>
bool operator!=(const Span<T, LhsExtent> &lhs, const Span<U, RhsExtent> &rhs)
@ -876,6 +893,8 @@ bool operator!=(T (&lhs)[LhsExtent], const Span<T, RhsExtent> &rhs)
*
* @note This helper avoids the typing of template parameter when Span is
* created 'inline'.
*
* @relates Span
*/
template<typename T, size_t Size>
Span<T, Size> make_Span(T (&elements)[Size])
@ -914,6 +933,8 @@ Span<T, Extent> make_Span(T *elements)
*
* @note This helper avoids the typing of template parameter when Span is
* created 'inline'.
*
* @relates Span
*/
template<typename T>
Span<T> make_Span(T *array_ptr, ptrdiff_t array_size)
@ -951,6 +972,8 @@ Span<const T, Extent> make_const_Span(const T (&elements)[Extent])
*
* @note This helper avoids the typing of template parameter when Span is
* created 'inline'.
*
* @relates Span
*/
template<size_t Extent, typename T>
Span<const T, Extent> make_const_Span(const T *elements)
@ -971,6 +994,8 @@ Span<const T, Extent> make_const_Span(const T *elements)
*
* @note This helper avoids the typing of template parameter when Span is
* created 'inline'.
*
* @relates Span
*/
template<typename T>
Span<const T> make_const_Span(T *array_ptr, size_t array_size)
@ -978,6 +1003,10 @@ Span<const T> make_const_Span(T *array_ptr, size_t array_size)
return Span<const T>(array_ptr, array_size);
}
/**@}*/
/**@}*/
} // namespace mbed
#endif /* MBED_PLATFORM_SPAN_H_ */

4
platform/mbed_rtc_time.h
View File

@ -40,10 +40,10 @@ extern "C" {
* int main() {
* set_time(1256729737); // Set RTC time to Wed, 28 Oct 2009 11:35:37
*
* while(1) {
* while (true) {
* time_t seconds = time(NULL);
*
* printf("Time as seconds since January 1, 1970 = %d\n", seconds);
* printf("Time as seconds since January 1, 1970 = %u\n", (unsigned int)seconds);
*
* printf("Time as a basic string = %s", ctime(&seconds));
*

46
rtos/EventFlags.h
View File

@ -37,22 +37,24 @@ namespace rtos {
* @{
*/
/** The EventFlags class is used to signal or wait for an arbitrary event or events.
/** The EventFlags class is used to control event flags or wait for event flags other threads control.
@note
EventFlags support 31 flags so the MSB flag is ignored, it is used to return an error code (@a osFlagsError)
EventFlags support 31 flags. The MSB flag is ignored. It is used to return an error code (@a osFlagsError).
@note
Memory considerations: The EventFlags control structures will be created on current thread's stack, both for the mbed OS
Memory considerations: The EventFlags control structures will be 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).
*/
class EventFlags : private mbed::NonCopyable<EventFlags> {
public:
/** Create and Initialize an EventFlags object
/** Create and initialize an EventFlags object.
*
* @note You cannot call this function from ISR context.
*/
EventFlags();
/** Create and Initialize a EventFlags object
/** Create and initialize an EventFlags object.
@param name name to be used for this EventFlags. It has to stay allocated for the lifetime of the thread.
@ -60,50 +62,50 @@ public:
*/
EventFlags(const char *name);
/** Set the specified Event Flags.
@param flags specifies the flags that shall be set.
@return event flags after setting or error code if highest bit set (@a osFlagsError).
/** Set the specified event flags.
@param flags the flags that will be set.
@return event flags after setting or error code if highest bit set (see @a osFlagsError for details).
@note This function may be called from ISR context.
*/
uint32_t set(uint32_t flags);
/** Clear the specified Event Flags.
@param flags specifies the flags that shall be cleared. (default: 0x7fffffff - all flags)
@return event flags before clearing or error code if highest bit set (@a osFlagsError).
/** Clear the specified event flags.
@param flags the flags that will be cleared (default: 0x7fffffff -- all flags).
@return event flags before clearing or error code if highest bit set (see @a osFlagsError for details).
@note You may call this function from ISR context.
*/
uint32_t clear(uint32_t flags = 0x7fffffff);
/** Get the currently set Event Flags.
@return set event flags.
/** Get the currently set event flags.
@return current event flags.
@note You may call this function from ISR context.
*/
uint32_t get() const;
/** Wait for all of the specified event flags to become signaled.
@param flags specifies the flags to wait for.
@param timeout timeout value or 0 in case of no time-out. (default: osWaitForever)
@param clear specifies wether to clear the flags after waiting for them. (default: true)
@return event flags before clearing or error code if highest bit set (@a osFlagsError).
@param flags the flags to wait for (default: 0 -- no flags).
@param timeout timeout value or 0 in case of no time-out (default: osWaitForever).
@param clear clear specified event flags after waiting for them (default: true).
@return event flags before clearing or error code if highest bit set (see @a osFlagsError for details).
@note You may call this function from ISR context if the timeout parameter is set to 0.
*/
uint32_t wait_all(uint32_t flags = 0, uint32_t timeout = osWaitForever, bool clear = true);
/** Wait for any of the specified event flags to become signaled.
@param flags specifies the flags to wait for. (default: 0)
@param timeout timeout value or 0 in case of no time-out. (default: osWaitForever)
@param clear specifies wether to clear the flags after waiting for them. (default: true)
@return event flags before clearing or error code if highest bit set (@a osFlagsError).
@param flags the flags to wait for (default: 0 -- no flags).
@param timeout timeout value or 0 in case of no timeout (default: osWaitForever).
@param clear clear specified event flags after waiting for them (default: true).
@return event flags before clearing or error code if highest bit set (see @a osFlagsError for details).
@note This function may be called from ISR context if the timeout parameter is set to 0.
*/
uint32_t wait_any(uint32_t flags = 0, uint32_t timeout = osWaitForever, bool clear = true);
/** Event flags destructor
/** EventFlags destructor.
@note You cannot call this function from ISR context.
*/