From 752836f0b683e9bb715b65fb6f4be5af1b03e147 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 18:51:38 +0100 Subject: [PATCH 01/15] doc: document auto_init --- sys/include/auto_init.h | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/sys/include/auto_init.h b/sys/include/auto_init.h index 3d6e804ee7..93d4d30a82 100644 --- a/sys/include/auto_init.h +++ b/sys/include/auto_init.h @@ -36,6 +36,13 @@ extern "C" { #endif +/** + * @brief Initializes all high level modules that do not require parameters for + * initialization or uses default values. + * + * This function gets called - if not explicitely disabled - by @ref + * kernel_init right before jumping into @e main. + */ void auto_init(void); #ifdef __cplusplus From cd81c040d8324684908c049d41b74914f1b7298f Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 18:52:53 +0100 Subject: [PATCH 02/15] uart0: remove superfluous prototype from header Declare and document prototype in CPU part instead. --- cpu/arm7_common/include/arm_cpu.h | 11 +++++++++++ sys/include/board_uart0.h | 1 - 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/cpu/arm7_common/include/arm_cpu.h b/cpu/arm7_common/include/arm_cpu.h index 902369f5a0..cf8db69083 100644 --- a/cpu/arm7_common/include/arm_cpu.h +++ b/cpu/arm7_common/include/arm_cpu.h @@ -29,6 +29,17 @@ void cpu_clock_scale(uint32_t source, uint32_t target, uint32_t *prescale); void arm_reset(void); void stdio_flush(void); +/** + * @brief Writes an array of characters to the UART0 device + * + * @param[in] astring The string to write + * @param[in] length Length of the string + * + * @returns Always @p length + */ +int uart0_puts(char *astring, int length); + + #ifdef __cplusplus } #endif diff --git a/sys/include/board_uart0.h b/sys/include/board_uart0.h index c52b7a659a..134c6503c0 100644 --- a/sys/include/board_uart0.h +++ b/sys/include/board_uart0.h @@ -35,7 +35,6 @@ void uart0_notify_thread(void); int uart0_readc(void); void uart0_putc(int c); -int uart0_puts(char *astring, int length); #ifdef __cplusplus } From da3377bf6df3514e974606d64c1a7f14f939c6f5 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 19:01:40 +0100 Subject: [PATCH 03/15] doc: document board_uart0 module --- sys/include/board_uart0.h | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/sys/include/board_uart0.h b/sys/include/board_uart0.h index 134c6503c0..a32b9b2b3c 100644 --- a/sys/include/board_uart0.h +++ b/sys/include/board_uart0.h @@ -27,13 +27,42 @@ extern "C" { #endif +/** + * @brief Process identifier for the UART0 module. + */ extern kernel_pid_t uart0_handler_pid; +/** + * @brief Initialize and starts the UART0 handler. + */ void board_uart0_init(void); + +/** + * @brief To be called from the uart interrupt handler for every incoming + * character. + * + * @param[in] c The received character. + */ void uart0_handle_incoming(int c); + +/** + * @brief Notify the chardev thread that new characters are available in the + * ringbuffer. + */ void uart0_notify_thread(void); +/** + * @brief Reads one character from the ringbuffer. + * + * @returns The first available character from the ringbuffer. + */ int uart0_readc(void); + +/** + * @brief Wrapper to putchar. + * + * @param[in] c The character to put on the UART. + */ void uart0_putc(int c); #ifdef __cplusplus From 67a2b37ff856305afca5e4f4ee1f46c2d050b838 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 19:08:15 +0100 Subject: [PATCH 04/15] cc110x: cleanup cc110x_legacy_csma driver Remove unused radio_t struct and fixed documentation. --- drivers/cc110x_legacy_csma/cc1100.c | 15 ------- .../cc110x_legacy_csma/cc1100-interface.h | 2 - sys/include/radio/radio.h | 39 +++---------------- 3 files changed, 6 insertions(+), 50 deletions(-) diff --git a/drivers/cc110x_legacy_csma/cc1100.c b/drivers/cc110x_legacy_csma/cc1100.c index 4decf00cd5..6c4df25ede 100644 --- a/drivers/cc110x_legacy_csma/cc1100.c +++ b/drivers/cc110x_legacy_csma/cc1100.c @@ -97,21 +97,6 @@ volatile cc1100_flags rflags; ///< Radio control flags static uint8_t radio_address; ///< Radio address static uint8_t radio_channel; ///< Radio channel number -const radio_t radio_cc1100 = { ///< Radio driver API - "CC1100", - CC1100_BROADCAST_ADDRESS, - MAX_OUTPUT_POWER, - cc1100_get_avg_transmission_duration, - cc1100_get_address, - cc1100_set_address, - cc1100_set_output_power, - cc1100_set_packet_monitor, - cc1100_set_packet_handler, - cc1100_send_csmaca, - cc1100_print_statistic, - cc1100_print_config -}; - /*---------------------------------------------------------------------------*/ // Data structures for mode control /*---------------------------------------------------------------------------*/ diff --git a/drivers/include/cc110x_legacy_csma/cc1100-interface.h b/drivers/include/cc110x_legacy_csma/cc1100-interface.h index 4cf16ff2c4..6042cb26d9 100644 --- a/drivers/include/cc110x_legacy_csma/cc1100-interface.h +++ b/drivers/include/cc110x_legacy_csma/cc1100-interface.h @@ -56,8 +56,6 @@ extern "C" { #define CC1100_RADIO_MODE CC1100_MODE_CONSTANT_RX #endif -/// CC1100 radio interface -extern const radio_t radio_cc1100; /** * @brief Initialize radio layer. diff --git a/sys/include/radio/radio.h b/sys/include/radio/radio.h index 40525ca33c..9f6cd6d372 100644 --- a/sys/include/radio/radio.h +++ b/sys/include/radio/radio.h @@ -28,9 +28,7 @@ * * @author baar * @author Thomas Hillebrandt - * @version $Revision: 1961 $ * - * @note $Id$ */ #include @@ -41,40 +39,15 @@ extern "C" { #endif -#define L1_PROTOCOL_CATCH_ALL (0xff) ///< Catch all protocol ID - -enum layer_1_protocols { - LAYER_1_PROTOCOL_LL_ACK = 1, ///< Link-Level Acknowledgement (LL-ACK) - LAYER_1_PROTOCOL_MM = 2, ///< Micro Mesh network packet (MM) -}; +#define L1_PROTOCOL_CATCH_ALL (0xff) /**< Catch all protocol ID */ /** - * Radio/MAC API. + * @brief Link layer protocols (sic!) for proprietary cc110x protocol stack */ -typedef struct { - const char *name; - const radio_address_t broadcast_address; - const uint8_t output_power_max; - /** - * @return the average transmission duration of one packet - * in milliseconds, e.g. till ACK received. - */ - int (*get_avg_transmission_duration)(void); - radio_address_t (*get_address)(void); - bool (*set_address)(radio_address_t address); - bool (*set_output_power)(uint8_t pa_idx); - bool (*set_packet_monitor)(packet_monitor_t monitor); - /** - * @return -1 if an error occurs (e.g. handler table full) else >= 0. - */ - int (*set_packet_handler)(protocol_t protocol, packet_handler_t handler); - /** - * @return A negative value if operation failed; else the number of transmitted bytes. - */ - int (*send)(radio_address_t address, protocol_t protocol, int priority, char *payload, int payload_len); - void (*print_stats)(void); - void (*print_config)(void); -} radio_t; +enum layer_1_protocols { + LAYER_1_PROTOCOL_LL_ACK = 1, /**< Link-Level Acknowledgement (LL-ACK) */ + LAYER_1_PROTOCOL_MM = 2, /**< Micro Mesh network packet (MM) */ +}; #ifdef __cplusplus } From 93c7627f07c195d3c69e7e03b34b73a198505693 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 19:47:12 +0100 Subject: [PATCH 05/15] doc: fix doxygen warnings for CBOR --- sys/include/cbor.h | 174 +++++++++++++++++++++++++++++++-------------- 1 file changed, 120 insertions(+), 54 deletions(-) diff --git a/sys/include/cbor.h b/sys/include/cbor.h index 48bec77371..20f22c93e5 100644 --- a/sys/include/cbor.h +++ b/sys/include/cbor.h @@ -129,46 +129,52 @@ extern "C" { * @sa cbor_destroy */ typedef struct cbor_stream_t { - /* Array containing CBOR encoded data */ + /** Array containing CBOR encoded data */ unsigned char *data; - /* Size of the array */ + /** Size of the array */ size_t size; - /* Index to the next free byte */ + /** Index to the next free byte */ size_t pos; } cbor_stream_t; /** - * Initialize cbor struct + * @brief Initialize cbor struct * * @note Does *not* take ownership of @p buffer - * - * @param buffer The buffer used for storing CBOR-encoded data - * @param size The size of buffer @p buffer + * @param[in] stream The cbor struct to initialize + * @param[in] buffer The buffer used for storing CBOR-encoded data + * @param[in] size The size of buffer @p buffer */ void cbor_init(cbor_stream_t *stream, unsigned char *buffer, size_t size); /** - * Clear cbor struct + * @brief Clear cbor struct * - * Sets pos to zero + * Sets pos to zero + * + * @param[in, out] stream Pointer to the cbor struct */ void cbor_clear(cbor_stream_t *stream); /** - * Destroy the cbor struct + * @brief Destroy the cbor struct * * @note Does *not* free data + * + * @param[in, out] stream Pointer to the cbor struct */ void cbor_destroy(cbor_stream_t *stream); #ifndef CBOR_NO_PRINT /** - * Print @p stream in hex representation + * @brief Print @p stream in hex representation + * + * @param[in] stream Pointer to the cbor struct */ void cbor_stream_print(const cbor_stream_t *stream); /** - * Decode CBOR from @p stream + * @brief Decode CBOR from @p stream * * This method interprets the data and prints each item in its natural representation * @@ -181,6 +187,8 @@ void cbor_stream_print(const cbor_stream_t *stream); * (tag: 0, date/time string: "Mon Jul 14 19:07:40 2014") * (tag: 1, date/time epoch: 1405357660) * @endcode + * + * @param[in] stream Pointer to the cbor struct */ void cbor_stream_decode(cbor_stream_t *stream); #endif /* CBOR_NO_PRINT */ @@ -203,26 +211,35 @@ size_t cbor_deserialize_double(const cbor_stream_t *stream, size_t offset, doubl #endif /* CBOR_NO_FLOAT */ size_t cbor_serialize_byte_string(cbor_stream_t *s, const char *val); + /** - * Deserialize bytes from @p stream to @p val + * @brief Deserialize bytes from @p stream to @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[in] val Pointer to destination array + * @param[in] length Length of destination array * - * @param val Pointer to destination array - * @param length Length of destination array * @return Number of bytes written into @p val */ size_t cbor_deserialize_byte_string(const cbor_stream_t *stream, size_t offset, char *val, size_t length); -size_t cbor_serialize_unicode_string(cbor_stream_t *s, const char *val); + +size_t cbor_serialize_unicode_string(cbor_stream_t *stream, const char *val); + /** - * Deserialize unicode string from @p stream to @p val + * @brief Deserialize unicode string from @p stream to @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[in] val Pointer to destination array + * @param[in] length Length of destination array * - * @param val Pointer to destination array - * @param length Length of destination array * @return Number of bytes written into @p val */ size_t cbor_deserialize_unicode_string(const cbor_stream_t *stream, size_t offset, char *val, size_t length); /** - * Serialize array of length @p array_length + * @brief Serialize array of length @p array_length * * Basic usage: * @code @@ -234,32 +251,40 @@ size_t cbor_deserialize_unicode_string(const cbor_stream_t *stream, size_t offse * @note You have to make sure to serialize the correct amount of items. * If you exceed the length @p array_length, items will just be appened as normal * - * @param array_length Length of the array of items which follows + * @param[out] stream The destination stream for serializing the array + * @param[in] array_length Length of the array of items which follows * - * @return Number of bytes written to stream @p s + * @return Number of bytes written to stream @p stream */ -size_t cbor_serialize_array(cbor_stream_t *s, size_t array_length); +size_t cbor_serialize_array(cbor_stream_t *stream, size_t array_length); + /** - * Deserialize array of items + * @brief Deserialize array of items * * Basic usage: * @code * size_t array_length; - * size_t offset = cbor_deserialize_array(&stream, 0, &array_length); // read out length of the array + * // read out length of the array + * size_t offset = cbor_deserialize_array(&stream, 0, &array_length); * int i1, i2; * offset += cbor_deserialize_int(&stream, offset, &i1); // read item 1 * offset += cbor_deserialize_int(&stream, offset, &i2); // read item 2 * @endcode * - * @param array_length Where the array length is stored + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream + * @param[in] array_length Where the array length is stored + * + * @return Number of deserialized bytes from stream */ -size_t cbor_deserialize_array(const cbor_stream_t *s, size_t offset, size_t *array_length); +size_t cbor_deserialize_array(const cbor_stream_t *stream, size_t offset, size_t *array_length); -size_t cbor_serialize_array_indefinite(cbor_stream_t *s); -size_t cbor_deserialize_array_indefinite(const cbor_stream_t *s, size_t offset); +size_t cbor_serialize_array_indefinite(cbor_stream_t *stream); + +size_t cbor_deserialize_array_indefinite(const cbor_stream_t *stream, size_t offset); /** - * Serialize map of length @p map_length + * @brief Serialize map of length @p map_length * * Basic usage: * @code @@ -270,11 +295,15 @@ size_t cbor_deserialize_array_indefinite(const cbor_stream_t *s, size_t offset); * cbor_serialize_byte_string(&stream, "2")); // write value 2 * @endcode * + * @param[out] stream The destination stream for serializing the map * @param map_length Length of the map of items which follows + * + * @return Number of bytes written to stream @p stream */ -size_t cbor_serialize_map(cbor_stream_t *s, size_t map_length); +size_t cbor_serialize_map(cbor_stream_t *stream, size_t map_length); + /** - * Deserialize map of items + * @brief Deserialize map of items * * Basic usage: * @code @@ -288,17 +317,22 @@ size_t cbor_serialize_map(cbor_stream_t *s, size_t map_length); * offset += cbor_deserialize_byte_string(&stream, offset, value2, sizeof(value)); // read value 2 * @endcode * - * @param map_length Where the array length is stored + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[in] map_length Where the array length is stored + * + * @return Number of deserialized bytes from @p stream */ -size_t cbor_deserialize_map(const cbor_stream_t *s, size_t offset, size_t *map_length); +size_t cbor_deserialize_map(const cbor_stream_t *stream, size_t offset, size_t *map_length); -size_t cbor_serialize_map_indefinite(cbor_stream_t *s); -size_t cbor_deserialize_map_indefinite(const cbor_stream_t *s, size_t offset); +size_t cbor_serialize_map_indefinite(cbor_stream_t *stream); + +size_t cbor_deserialize_map_indefinite(const cbor_stream_t *stream, size_t offset); #ifndef CBOR_NO_SEMANTIC_TAGGING #ifndef CBOR_NO_CTIME /** - * Serialize date and time + * @brief Serialize date and time * * Basic usage: * @code @@ -313,11 +347,15 @@ size_t cbor_deserialize_map_indefinite(const cbor_stream_t *s, size_t offset); * cbor_serialize_date_time(&stream, &val); * @endcode * - * @param val tm struct containing the date/time info to be encoded + * @param[out] stream The destination stream for serializing the date_time + * @param[in] val tm struct containing the date/time info to be encoded + * + * @return Number of bytes written to stream @p stream */ size_t cbor_serialize_date_time(cbor_stream_t *stream, struct tm *val); + /** - * Deserialize date and time + * @brief Deserialize date and time * * Basic usage: * @code @@ -325,48 +363,76 @@ size_t cbor_serialize_date_time(cbor_stream_t *stream, struct tm *val); * cbor_deserialize_date_time(&stream, 0, &val); * @endcode * - * @param val tm struct where the decoded date/time will be stored + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[in] val tm struct where the decoded date/time will be stored + * + * @return The number of deserialized bytes */ size_t cbor_deserialize_date_time(const cbor_stream_t *stream, size_t offset, struct tm *val); size_t cbor_serialize_date_time_epoch(cbor_stream_t *stream, time_t val); + size_t cbor_deserialize_date_time_epoch(const cbor_stream_t *stream, size_t offset, time_t *val); + #endif /* CBOR_NO_CTIME */ /** - * Write a tag to give the next CBOR item additional semantics + * @brief Write a tag to give the next CBOR item additional semantics * * Also see https://tools.ietf.org/html/rfc7049#section-2.4 (Optional Tagging of Items) + * + * @param[in, out] stream Pointer to the cbor struct + * @param[in] tag The tag to write + * + * @return Always 1 */ -size_t cbor_write_tag(cbor_stream_t *s, unsigned char tag); +size_t cbor_write_tag(cbor_stream_t *stream, unsigned char tag); + /** - * Whether we are at a tag symbol in stream @p s at offset @p offset + * @brief Whether we are at a tag symbol in stream @p stream at offset @p offset + * + * @param[in] stream Pointer to the cbor struct + * @param[in] offset The offset within @p stream * * @return True in case there is a tag symbol at the current offset */ -bool cbor_at_tag(const cbor_stream_t *s, size_t offset); -/** - * Write a break symbol at the current offset in stream @p s - * - * Used for marking the end of indefinite length CBOR items - */ +bool cbor_at_tag(const cbor_stream_t *stream, size_t offset); + #endif /* CBOR_NO_SEMANTIC_TAGGING */ -size_t cbor_write_break(cbor_stream_t *s); /** - * Whether we are at a break symbol in stream @p s at offset @p offset + * @brief Write a break symbol at the current offset in stream @p stream + * + * Used for marking the end of indefinite length CBOR items + * + * @param[in] stream Pointer to the cbor struct + * + * @return Always 1 + */ +size_t cbor_write_break(cbor_stream_t *stream); + +/** + * @brief Whether we are at a break symbol in stream @p stream at offset @p offset + * + * @param[in] stream Pointer to the cbor struct + * @param[in] offset The offset within @p stream * * @return True in case the there is a break symbol at the current offset */ -bool cbor_at_break(const cbor_stream_t *s, size_t offset); +bool cbor_at_break(const cbor_stream_t *stream, size_t offset); + /** - * Whether we are at the end of the stream @p s at offset @p offset + * @brief Whether we are at the end of the stream @p stream at offset @p offset * * Useful for abort conditions in loops while deserializing CBOR items * + * @param[in] stream Pointer to the cbor struct + * @param[in] offset The offset within @p stream + * * @return True in case @p offset marks the end of the stream */ -bool cbor_at_end(const cbor_stream_t *s, size_t offset); +bool cbor_at_end(const cbor_stream_t *stream, size_t offset); #ifdef __cplusplus } From 1270edace644e83010e9fb316b1d66e72e60e326 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 19:54:59 +0100 Subject: [PATCH 06/15] cbor: fixe line length --- sys/include/cbor.h | 88 ++++++++++++++++++++++++++++++---------------- 1 file changed, 57 insertions(+), 31 deletions(-) diff --git a/sys/include/cbor.h b/sys/include/cbor.h index 20f22c93e5..8d08e22db9 100644 --- a/sys/include/cbor.h +++ b/sys/include/cbor.h @@ -22,8 +22,10 @@ * * This is an implementation suited for constrained devices * Characteristics: - * - No dynamic memory allocation (i.e. no calls to @e malloc, @e free) used throughout the implementation - * - User may allocate static buffers, this implementation uses the space provided by them (cf. @ref cbor_stream_t) + * - No dynamic memory allocation (i.e. no calls to @e malloc, @e free) used + * throughout the implementation + * - User may allocate static buffers, this implementation uses the space + * provided by them (cf. @ref cbor_stream_t) * * @par Supported types (categorized by major type (MT)): * @@ -43,43 +45,50 @@ * * - Major type 4 (array of data items): Full support. Relevant functions: * - cbor_serialize_array(), cbor_deserialize_array() - * - cbor_serialize_indefinite_array(), cbor_deserialize_indefinite_array(), cbor_at_break() + * - cbor_serialize_indefinite_array(), cbor_deserialize_indefinite_array(), + * cbor_at_break() * * - Major type 5 (map of pairs of data items): Full support. Relevant functions: * - cbor_serialize_map(), cbor_deserialize_map() - * - cbor_serialize_indefinite_map(), cbor_deserialize_indefinite_map(), cbor_at_break() + * - cbor_serialize_indefinite_map(), cbor_deserialize_indefinite_map(), + * cbor_at_break() * - * - Major type 6 (optional semantic tagging of other major types): Basic support (see below). Relevant functions: + * - Major type 6 (optional semantic tagging of other major types): Basic + * support (see below). Relevant functions: * - cbor_write_tag() * - cbor_deserialize_date_time() * - cbor_serialize_date_time() * - * - Major type 7 (floating-point numbers and values with no content): Basic support (see below). Relevant functions: + * - Major type 7 (floating-point numbers and values with no content): Basic + * support (see below). Relevant functions: * - cbor_serialize_float_half(), cbor_deserialize_float_half() * - cbor_serialize_float(), cbor_deserialize_float() * - cbor_serialize_double(), cbor_deserialize_double() * - cbor_serialize_bool(), cbor_deserialize_bool() * * @par Notes about major type 3: - * Since we do not have a standardised C type for representing Unicode code points, - * we just provide API to serialize/deserialize @e char* arrays. The user then - * has to transform that into a meaningful representation + * Since we do not have a standardised C type for representing Unicode code + * points, we just provide API to serialize/deserialize @e char* arrays. The + * user then has to transform that into a meaningful representation * * @par Notes about major type 6 (cf. https://tools.ietf.org/html/rfc7049#section-2.4): - * Encoding date and time: date/time strings that follow the standard format described in Section 3.3 of [RFC3339]: + * Encoding date and time: date/time strings that follow the standard format + * described in Section 3.3 of [RFC3339]: * 2003-12-13T18:30:02Z - supported * 2003-12-13T18:30:02.25Z - not supported * 2003-12-13T18:30:02+01:00 - not supported * 2003-12-13T18:30:02.25+01:00 - not supported * Since we do not have C types for representing bignums/bigfloats/decimal-fraction * we do not provide API to serialize/deserialize them at all. - * You can still read out the actual data item behind the tag (via cbor_deserialize_byte_string()) - * and interpret it yourself. + * You can still read out the actual data item behind the tag (via + * cbor_deserialize_byte_string()) and interpret it yourself. * - * @par Notes about major type 7 and simple values (cf. https://tools.ietf.org/html/rfc7049#section-2.3) + * @par Notes about major type 7 and simple values + * (cf. https://tools.ietf.org/html/rfc7049#section-2.3) * Simple values: * - 0-19: (Unassigned) - No support - * - 20,21: True, False - Supported (see cbor_serialize_bool(), cbor_deserialize_bool()) + * - 20,21: True, False - Supported (see cbor_serialize_bool(), + * cbor_deserialize_bool()) * - 22,23: Null, Undefined - No support (what's the use-case?) * - 24-31: (Reserved) - No support * - 32-255: (Unassigned) - No support @@ -176,7 +185,8 @@ void cbor_stream_print(const cbor_stream_t *stream); /** * @brief Decode CBOR from @p stream * - * This method interprets the data and prints each item in its natural representation + * This method interprets the data and prints each item in its natural + * representation * * Example output: * @code @@ -194,20 +204,27 @@ void cbor_stream_decode(cbor_stream_t *stream); #endif /* CBOR_NO_PRINT */ size_t cbor_serialize_int(cbor_stream_t *s, int val); -size_t cbor_deserialize_int(const cbor_stream_t *stream, size_t offset, int *val); +size_t cbor_deserialize_int(const cbor_stream_t *stream, size_t offset, + int *val); size_t cbor_serialize_uint64_t(cbor_stream_t *s, uint64_t val); -size_t cbor_deserialize_uint64_t(const cbor_stream_t *stream, size_t offset, uint64_t *val); +size_t cbor_deserialize_uint64_t(const cbor_stream_t *stream, size_t offset, + uint64_t *val); size_t cbor_serialize_int64_t(cbor_stream_t *s, int64_t val); -size_t cbor_deserialize_int64_t(const cbor_stream_t *stream, size_t offset, int64_t *val); +size_t cbor_deserialize_int64_t(const cbor_stream_t *stream, size_t offset, + int64_t *val); size_t cbor_serialize_bool(cbor_stream_t *s, bool val); -size_t cbor_deserialize_bool(const cbor_stream_t *stream, size_t offset, bool *val); +size_t cbor_deserialize_bool(const cbor_stream_t *stream, size_t offset, + bool *val); #ifndef CBOR_NO_FLOAT size_t cbor_serialize_float_half(cbor_stream_t *s, float val); -size_t cbor_deserialize_float_half(const cbor_stream_t *stream, size_t offset, float *val); +size_t cbor_deserialize_float_half(const cbor_stream_t *stream, size_t offset, + float *val); size_t cbor_serialize_float(cbor_stream_t *s, float val); -size_t cbor_deserialize_float(const cbor_stream_t *stream, size_t offset, float *val); +size_t cbor_deserialize_float(const cbor_stream_t *stream, size_t offset, + float *val); size_t cbor_serialize_double(cbor_stream_t *s, double val); -size_t cbor_deserialize_double(const cbor_stream_t *stream, size_t offset, double *val); +size_t cbor_deserialize_double(const cbor_stream_t *stream, size_t offset, + double *val); #endif /* CBOR_NO_FLOAT */ size_t cbor_serialize_byte_string(cbor_stream_t *s, const char *val); @@ -222,7 +239,8 @@ size_t cbor_serialize_byte_string(cbor_stream_t *s, const char *val); * * @return Number of bytes written into @p val */ -size_t cbor_deserialize_byte_string(const cbor_stream_t *stream, size_t offset, char *val, size_t length); +size_t cbor_deserialize_byte_string(const cbor_stream_t *stream, size_t offset, + char *val, size_t length); size_t cbor_serialize_unicode_string(cbor_stream_t *stream, const char *val); @@ -236,7 +254,8 @@ size_t cbor_serialize_unicode_string(cbor_stream_t *stream, const char *val); * * @return Number of bytes written into @p val */ -size_t cbor_deserialize_unicode_string(const cbor_stream_t *stream, size_t offset, char *val, size_t length); +size_t cbor_deserialize_unicode_string(const cbor_stream_t *stream, + size_t offset, char *val, size_t length); /** * @brief Serialize array of length @p array_length @@ -277,7 +296,8 @@ size_t cbor_serialize_array(cbor_stream_t *stream, size_t array_length); * * @return Number of deserialized bytes from stream */ -size_t cbor_deserialize_array(const cbor_stream_t *stream, size_t offset, size_t *array_length); +size_t cbor_deserialize_array(const cbor_stream_t *stream, size_t offset, + size_t *array_length); size_t cbor_serialize_array_indefinite(cbor_stream_t *stream); @@ -308,13 +328,18 @@ size_t cbor_serialize_map(cbor_stream_t *stream, size_t map_length); * Basic usage: * @code * size_t map_length; - * size_t offset = cbor_deserialize_map(&stream, 0, &map_length); // read out length of the map + * // read out length of the map + * size_t offset = cbor_deserialize_map(&stream, 0, &map_length); * int key1, key1; * char value1[8], value2[8]; - * offset += cbor_deserialize_int(&stream, offset, &key1); // read key 1 - * offset += cbor_deserialize_byte_string(&stream, offset, value1, sizeof(value)); // read value 1 - * offset += cbor_deserialize_int(&stream, offset, &key2); // read key 2 - * offset += cbor_deserialize_byte_string(&stream, offset, value2, sizeof(value)); // read value 2 + * // read key 1 + * offset += cbor_deserialize_int(&stream, offset, &key1); + * // read value 1 + * offset += cbor_deserialize_byte_string(&stream, offset, value1, sizeof(value)); + * // read key 2 + * offset += cbor_deserialize_int(&stream, offset, &key2); + * // read value 2 + * offset += cbor_deserialize_byte_string(&stream, offset, value2, sizeof(value)); * @endcode * * @param[in] stream The stream to deserialize @@ -323,7 +348,8 @@ size_t cbor_serialize_map(cbor_stream_t *stream, size_t map_length); * * @return Number of deserialized bytes from @p stream */ -size_t cbor_deserialize_map(const cbor_stream_t *stream, size_t offset, size_t *map_length); +size_t cbor_deserialize_map(const cbor_stream_t *stream, size_t offset, + size_t *map_length); size_t cbor_serialize_map_indefinite(cbor_stream_t *stream); From 45ea87f403cff8a8646f65ff70faf7177f888295 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 20:15:52 +0100 Subject: [PATCH 07/15] doc: cbor: complemented documentation --- sys/include/cbor.h | 193 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 182 insertions(+), 11 deletions(-) diff --git a/sys/include/cbor.h b/sys/include/cbor.h index 8d08e22db9..4967f08c82 100644 --- a/sys/include/cbor.h +++ b/sys/include/cbor.h @@ -19,6 +19,7 @@ * * @author Kevin Funk * @author Jana Cavojska + * @author Oliver Hahm * * This is an implementation suited for constrained devices * Characteristics: @@ -203,38 +204,178 @@ void cbor_stream_print(const cbor_stream_t *stream); void cbor_stream_decode(cbor_stream_t *stream); #endif /* CBOR_NO_PRINT */ -size_t cbor_serialize_int(cbor_stream_t *s, int val); +/** + * @brief Serializes an integer + * + * @param[out] stream The destination stream for serializing the array + * @param[in] val The integer to serialize + * + * @return Number of bytes written to stream @p stream + */ +size_t cbor_serialize_int(cbor_stream_t *stream, int val); + +/** + * @brief Deserialize integers from @p stream to @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[out] val Pointer to destination array + * + * @return Number of bytes written into @p val + */ size_t cbor_deserialize_int(const cbor_stream_t *stream, size_t offset, int *val); -size_t cbor_serialize_uint64_t(cbor_stream_t *s, uint64_t val); + +/** + * @brief Serializes an unsigned 64 bit value + * + * @param[out] stream The destination stream for serializing the array + * @param[in] val The 64 bit integer to serialize + * + * @return Number of bytes written to stream @p stream + */ +size_t cbor_serialize_uint64_t(cbor_stream_t *stream, uint64_t val); + +/** + * @brief Deserialize unsigned 64 bit values from @p stream to @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[out] val Pointer to destination array + * + * @return Number of bytes written into @p val + */ size_t cbor_deserialize_uint64_t(const cbor_stream_t *stream, size_t offset, uint64_t *val); -size_t cbor_serialize_int64_t(cbor_stream_t *s, int64_t val); + +/** + * @brief Serializes a signed 64 bit value + * + * @param[out] stream The destination stream for serializing the array + * @param[in] val The 64 bit integer to serialize + * + * @return Number of bytes written to stream @p stream + */ +size_t cbor_serialize_int64_t(cbor_stream_t *stream, int64_t val); + +/** + * @brief Deserialize signed 64 bit values from @p stream to @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[out] val Pointer to destination array + * + * @return Number of bytes written into @p val + */ size_t cbor_deserialize_int64_t(const cbor_stream_t *stream, size_t offset, int64_t *val); -size_t cbor_serialize_bool(cbor_stream_t *s, bool val); + +/** + * @brief Serializes a boolean value + * + * @param[out] stream The destination stream for serializing the array + * @param[in] val The boolean value to serialize + * + * @return Number of bytes written to stream @p stream + */ +size_t cbor_serialize_bool(cbor_stream_t *stream, bool val); + +/** + * @brief Deserialize boolean values from @p stream to @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[out] val Pointer to destination array + * + * @return Number of bytes written into @p val + */ size_t cbor_deserialize_bool(const cbor_stream_t *stream, size_t offset, bool *val); + #ifndef CBOR_NO_FLOAT -size_t cbor_serialize_float_half(cbor_stream_t *s, float val); +/** + * @brief Serializes a half-width floating point value + * + * @param[out] stream The destination stream for serializing the array + * @param[in] val The half-width floating point value to serialize + * + * @return Number of bytes written to stream @p stream + */ +size_t cbor_serialize_float_half(cbor_stream_t *stream, float val); + +/** + * @brief Deserialize half-width floating point values values from @p stream to + * @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[out] val Pointer to destination array + * + * @return Number of bytes written into @p val + */ size_t cbor_deserialize_float_half(const cbor_stream_t *stream, size_t offset, float *val); -size_t cbor_serialize_float(cbor_stream_t *s, float val); +/** + * @brief Serializes a floating point value + * + * @param[out] stream The destination stream for serializing the array + * @param[in] val The float to serialize + * + * @return Number of bytes written to stream @p stream + */ +size_t cbor_serialize_float(cbor_stream_t *stream, float val); + +/** + * @brief Deserialize floating point values values from @p stream to @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[out] val Pointer to destination array + * + * @return Number of bytes written into @p val + */ size_t cbor_deserialize_float(const cbor_stream_t *stream, size_t offset, float *val); -size_t cbor_serialize_double(cbor_stream_t *s, double val); +/** + * @brief Serializes a double precision floating point value + * + * @param[out] stream The destination stream for serializing the array + * @param[in] val The double to serialize + * + * @return Number of bytes written to stream @p stream + */ +size_t cbor_serialize_double(cbor_stream_t *stream, double val); + +/** + * @brief Deserialize double precision floating point valeus from @p stream to + * @p val + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream where to start deserializing + * @param[out] val Pointer to destination array + * + * @return Number of bytes written into @p val + */ size_t cbor_deserialize_double(const cbor_stream_t *stream, size_t offset, double *val); #endif /* CBOR_NO_FLOAT */ -size_t cbor_serialize_byte_string(cbor_stream_t *s, const char *val); +/** + * @brief Serializes a signed 64 bit value + * + * @param[out] stream The destination stream for serializing the array + * @param[in] val The 64 bit integer to serialize + * + * @return Number of bytes written to stream @p stream + */ +size_t cbor_serialize_byte_string(cbor_stream_t *stream, const char *val); /** * @brief Deserialize bytes from @p stream to @p val * * @param[in] stream The stream to deserialize * @param[in] offset The offset within the stream where to start deserializing - * @param[in] val Pointer to destination array + * @param[out] val Pointer to destination array * @param[in] length Length of destination array * * @return Number of bytes written into @p val @@ -249,7 +390,7 @@ size_t cbor_serialize_unicode_string(cbor_stream_t *stream, const char *val); * * @param[in] stream The stream to deserialize * @param[in] offset The offset within the stream where to start deserializing - * @param[in] val Pointer to destination array + * @param[out] val Pointer to destination array * @param[in] length Length of destination array * * @return Number of bytes written into @p val @@ -299,8 +440,23 @@ size_t cbor_serialize_array(cbor_stream_t *stream, size_t array_length); size_t cbor_deserialize_array(const cbor_stream_t *stream, size_t offset, size_t *array_length); +/** + * @brief Serialize array of infite length + * + * @param[out] stream The destination stream for serializing the array + * + * @return Number of bytes written to stream @p stream + */ size_t cbor_serialize_array_indefinite(cbor_stream_t *stream); +/** + * @brief Deserialize array of items + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream + * + * @return Number of deserialized bytes from stream + */ size_t cbor_deserialize_array_indefinite(const cbor_stream_t *stream, size_t offset); /** @@ -351,8 +507,23 @@ size_t cbor_serialize_map(cbor_stream_t *stream, size_t map_length); size_t cbor_deserialize_map(const cbor_stream_t *stream, size_t offset, size_t *map_length); +/** + * @brief Serialize map of infite length + * + * @param[out] stream The destination stream for serializing the map + * + * @return Number of bytes written to stream @p stream + */ size_t cbor_serialize_map_indefinite(cbor_stream_t *stream); +/** + * @brief Deserialize map of items + * + * @param[in] stream The stream to deserialize + * @param[in] offset The offset within the stream + * + * @return Number of deserialized bytes from stream + */ size_t cbor_deserialize_map_indefinite(const cbor_stream_t *stream, size_t offset); #ifndef CBOR_NO_SEMANTIC_TAGGING @@ -391,7 +562,7 @@ size_t cbor_serialize_date_time(cbor_stream_t *stream, struct tm *val); * * @param[in] stream The stream to deserialize * @param[in] offset The offset within the stream where to start deserializing - * @param[in] val tm struct where the decoded date/time will be stored + * @param[out] val tm struct where the decoded date/time will be stored * * @return The number of deserialized bytes */ From a3ea98c06326820153b9693d8a6808b4ebdb445b Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 20:25:15 +0100 Subject: [PATCH 08/15] doc: fixed documentation for transceiver --- sys/include/transceiver.h | 121 +++++++++++++++++++++++--------------- 1 file changed, 75 insertions(+), 46 deletions(-) diff --git a/sys/include/transceiver.h b/sys/include/transceiver.h index b6d7f7066d..9503d35760 100644 --- a/sys/include/transceiver.h +++ b/sys/include/transceiver.h @@ -88,11 +88,17 @@ extern "C" { #endif -/* Stack size for transceiver thread */ +/** + * @brief Stack size for transceiver thread + */ #ifndef TRANSCEIVER_STACK_SIZE #define TRANSCEIVER_STACK_SIZE (KERNEL_CONF_STACKSIZE_DEFAULT) #endif +/** + * @name Defines the upper payload limit for all available transceivers + * @{ + */ #ifndef PAYLOAD_SIZE #define PAYLOAD_SIZE (0) #endif @@ -132,26 +138,40 @@ extern "C" { #define PAYLOAD_SIZE (NATIVE_MAX_DATA_LENGTH) #endif #endif -/* The maximum of threads to register */ +/** + * @} + */ + +/** + * @brief The maximum of threads to register + */ #define TRANSCEIVER_MAX_REGISTERED (4) -/* The size of the message queue between driver and transceiver (must be power - * of two */ +/** + * @brief The size of the message queue between driver and transceiver (must be + * power of two + */ #define TRANSCEIVER_MSG_BUFFER_SIZE (32) -/** The maximum number of ignored addresses */ +/** + * @brief The maximum number of ignored addresses + */ #define TRANSCEIVER_MAX_IGNORED_ADDR (10) /** - * @brief All supported transceivers + * @name All supported transceivers + * @{ + */ +#define TRANSCEIVER_NONE (0x0) /**< Invalid */ +#define TRANSCEIVER_CC1100 (0x01) /**< CC110X transceivers */ +#define TRANSCEIVER_CC1020 (0x02) /**< CC1020 transceivers */ +#define TRANSCEIVER_CC2420 (0x04) /**< CC2420 transceivers */ +#define TRANSCEIVER_MC1322X (0x08) /**< MC1322X transceivers */ +#define TRANSCEIVER_NATIVE (0x10) /**< NATIVE transceivers */ +#define TRANSCEIVER_AT86RF231 (0x20) /**< AT86RF231 transceivers */ +/** + * @} */ -#define TRANSCEIVER_NONE (0x0) ///< Invalid -#define TRANSCEIVER_CC1100 (0x01) ///< CC110X transceivers -#define TRANSCEIVER_CC1020 (0x02) ///< CC1020 transceivers -#define TRANSCEIVER_CC2420 (0x04) ///< CC2420 transceivers -#define TRANSCEIVER_MC1322X (0x08) ///< MC1322X transceivers -#define TRANSCEIVER_NATIVE (0x10) ///< NATIVE transceivers -#define TRANSCEIVER_AT86RF231 (0x20) ///< AT86RF231 transceivers /** * @brief Data type for transceiver specification @@ -168,60 +188,69 @@ typedef uint64_t transceiver_eui64_t; */ enum transceiver_msg_type_t { /* Message types for driver <-> transceiver communication */ - RCV_PKT_CC1020, ///< packet was received by CC1020 transceiver - RCV_PKT_CC1100, ///< packet was received by CC1100 transceiver - RCV_PKT_CC2420, ///< packet was received by CC2420 transceiver - RCV_PKT_MC1322X, ///< packet was received by mc1322x transceiver - RCV_PKT_NATIVE, ///< packet was received by native transceiver - RCV_PKT_AT86RF231, ///< packet was received by AT86RF231 transceiver + RCV_PKT_CC1020, /**< packet was received by CC1020 transceiver */ + RCV_PKT_CC1100, /**< packet was received by CC1100 transceiver */ + RCV_PKT_CC2420, /**< packet was received by CC2420 transceiver */ + RCV_PKT_MC1322X, /**< packet was received by mc1322x transceiver */ + RCV_PKT_NATIVE, /**< packet was received by native transceiver */ + RCV_PKT_AT86RF231, /**< packet was received by AT86RF231 transceiver */ /* Message types for transceiver <-> upper layer communication */ - PKT_PENDING, ///< packet pending in transceiver buffer - SND_PKT, ///< request for sending a packet - SND_ACK, ///< request for sending an acknowledgement - SWITCH_RX, ///< switch transceiver to RX sate - POWERDOWN, ///< power down transceiver - GET_CHANNEL, ///< Get current channel - SET_CHANNEL, ///< Set a new channel - GET_ADDRESS, ///< Get the radio address - SET_ADDRESS, ///< Set the radio address - GET_LONG_ADDR, ///< Get the long radio address, if existing - SET_LONG_ADDR, ///< Set the long radio address, if supported by hardware - SET_MONITOR, ///< Set transceiver to monitor mode (disable address checking) - GET_PAN, ///< Get current pan - SET_PAN, ///< Set a new pan + PKT_PENDING, /**< packet pending in transceiver buffer */ + SND_PKT, /**< request for sending a packet */ + SND_ACK, /**< request for sending an acknowledgement */ + SWITCH_RX, /**< switch transceiver to RX sate */ + POWERDOWN, /**< power down transceiver */ + GET_CHANNEL, /**< Get current channel */ + SET_CHANNEL, /**< Set a new channel */ + GET_ADDRESS, /**< Get the radio address */ + SET_ADDRESS, /**< Set the radio address */ + GET_LONG_ADDR, /**< Get the long radio address, if existing */ + SET_LONG_ADDR, /**< Set the long radio address, if supported by hardware */ + SET_MONITOR, /**< Set transceiver to monitor mode (disable address + checking) */ + GET_PAN, /**< Get current pan */ + SET_PAN, /**< Set a new pan */ /* debug message types */ - DBG_IGN, ///< add a physical address to the ignore list + DBG_IGN, /**< add a physical address to the ignore list */ /* Error messages */ - ENOBUFFER, ///< No buffer left + ENOBUFFER, /**< No buffer left */ /* reserve message types for higher layer notifications */ - UPPER_LAYER_1, ///< reserved - UPPER_LAYER_2, ///< reserved - UPPER_LAYER_3, ///< reserved - UPPER_LAYER_4, ///< reserved - UPPER_LAYER_5, ///< reserved + UPPER_LAYER_1, /**< reserved */ + UPPER_LAYER_2, /**< reserved */ + UPPER_LAYER_3, /**< reserved */ + UPPER_LAYER_4, /**< reserved */ + UPPER_LAYER_5, /**< reserved */ }; /** * @brief Manage registered threads per transceiver */ typedef struct { - transceiver_type_t transceivers; ///< the tranceivers the thread is registered for - kernel_pid_t pid; ///< the thread's pid + transceiver_type_t transceivers; /**< the tranceivers the thread is + registered for */ + kernel_pid_t pid; /**< the thread's pid */ } registered_t; +/** + * @brief Transceiver command struct + */ typedef struct { - transceiver_type_t transceivers; - void *data; + transceiver_type_t transceivers; /**< Bitfield of targeted transceivers */ + void *data; /**< The payload of the command */ } transceiver_command_t; -/* The transceiver thread's pid */ +/** + * @brief The transceiver thread's pid + */ extern volatile kernel_pid_t transceiver_pid; -/** An array of ignored link layer addresses */ +/** + * @brief An array of ignored link layer addresses + */ extern radio_address_t transceiver_ignored_addr[TRANSCEIVER_MAX_IGNORED_ADDR]; /** From 6c762d683b7f53306715f65b288205305bdb84fa Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 20:25:43 +0100 Subject: [PATCH 09/15] doc: added missing documentation for PRIu32 --- sys/include/timex.h | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sys/include/timex.h b/sys/include/timex.h index b6e9140549..9fd8e4bd59 100644 --- a/sys/include/timex.h +++ b/sys/include/timex.h @@ -29,7 +29,11 @@ extern "C" { #endif -// mspgcc bug : PRIxxx macros not defined before mid-2011 versions +/** + * @brief Formater for unsigned 32 bit values + * + * mspgcc bug : PRIxxx macros not defined before mid-2011 versions + */ #ifndef PRIu32 #define PRIu32 "lu" #endif From fb3e8939df824a63af948cf2dd0a5e9b0a45f8f8 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Fri, 5 Dec 2014 20:32:39 +0100 Subject: [PATCH 10/15] doc: fix vtimer documentation --- sys/include/vtimer.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/sys/include/vtimer.h b/sys/include/vtimer.h index d637eab1d0..3fcd84c8d9 100644 --- a/sys/include/vtimer.h +++ b/sys/include/vtimer.h @@ -38,7 +38,7 @@ extern "C" { #define MSG_TIMER 12345 /** - * A vtimer object. + * @brief A vtimer object. * * This structure is used for declaring a vtimer. This should not be used by * programmers, use the vtimer_set_*-functions instead. @@ -46,10 +46,15 @@ extern "C" { * \hideinitializer */ typedef struct vtimer_t { + /** entry in vtimer's internal priority queue */ priority_queue_node_t priority_queue_entry; + /** the absoule point in time when the timer expires */ timex_t absolute; + /** the action to perform when timer fires */ void (*action)(struct vtimer_t *timer); + /** optional argument for vtimer_t::action */ void *arg; + /** optional process id for vtimer_t::action to act on */ kernel_pid_t pid; } vtimer_t; @@ -105,6 +110,7 @@ int vtimer_set_msg(vtimer_t *t, timex_t interval, kernel_pid_t pid, void *ptr); /** * @brief set a vtimer with wakeup event * @param[in] t pointer to preinitialised vtimer_t + * @param[in] interval the interval after which the timer shall fire * @param[in] pid process id * @return 0 on success, < 0 on error */ From 04b67f1ff0a65159d032f76d91be59077a7f7e68 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Sat, 6 Dec 2014 01:12:31 +0100 Subject: [PATCH 11/15] doc: avr cleanup --- cpu/atmega_common/avr-libc-extra/errno.h | 16 +++++++++------- cpu/atmega_common/include/cpu.h | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/cpu/atmega_common/avr-libc-extra/errno.h b/cpu/atmega_common/avr-libc-extra/errno.h index a967eb5b6e..1c9e048aea 100644 --- a/cpu/atmega_common/avr-libc-extra/errno.h +++ b/cpu/atmega_common/avr-libc-extra/errno.h @@ -33,9 +33,10 @@ #define __ERRNO_H_ 1 /** - * @file + * @addtogroup cpu_atmega_common * - * @defgroup avr_errno : System Errors + * @{ + * @file * * @code #include @endcode * @@ -60,14 +61,14 @@ extern int errno; } #endif -/** \ingroup avr_errno - \def EDOM +/** + @def EDOM Domain error. */ #define EDOM 33 -/** \ingroup avr_errno - \def ERANGE +/** + @def ERANGE Range error. */ #define ERANGE 34 @@ -148,5 +149,6 @@ extern int errno; #define EINVAL 22 /* Invalid argument */ #define EOVERFLOW 75 /* Value too large for defined data type */ -/* \endcond */ +/** @} */ + #endif diff --git a/cpu/atmega_common/include/cpu.h b/cpu/atmega_common/include/cpu.h index 7716a86934..bf88a1d44b 100644 --- a/cpu/atmega_common/include/cpu.h +++ b/cpu/atmega_common/include/cpu.h @@ -7,7 +7,7 @@ */ /** - * @ingroup cpu_atmega + * @ingroup cpu_atmega_common * @brief Common implementations and headers for ATmega family based micro-controllers * @{ * From 1288b3f9cb340be222e60acdabceba42d2f1a902 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Sat, 6 Dec 2014 01:24:44 +0100 Subject: [PATCH 12/15] doc: fix bloom filter documentation --- sys/include/bloom.h | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/sys/include/bloom.h b/sys/include/bloom.h index 251ecb8bc6..9b7c08e593 100644 --- a/sys/include/bloom.h +++ b/sys/include/bloom.h @@ -132,22 +132,26 @@ extern "C" { #endif /** - * hashfp_t hash function to use in thee filter + * @brief hash function to use in thee filter */ typedef uint32_t (*hashfp_t)(const uint8_t *, int len); /** - * bloom_t bloom filter object + * @brief bloom_t bloom filter object */ typedef struct { + /** number of bytes in the bloom array */ size_t m; + /** number of hash functions */ size_t k; + /** the bloom array */ uint8_t *a; + /** the hash functions */ hashfp_t *hash; } bloom_t; /** - * bloom_new Allocate and return a pointer to a new Bloom filter. + * @brief Allocate and return a pointer to a new Bloom filter. * * For best results, make 'size' a power of 2. * @@ -161,7 +165,7 @@ typedef struct { bloom_t *bloom_new(size_t size, size_t num_hashes, ...); /** - * bloom_del Delete a Bloom filter. + * @brief Delete a Bloom filter. * * @param bloom The condemned * @return nothing @@ -170,20 +174,21 @@ bloom_t *bloom_new(size_t size, size_t num_hashes, ...); void bloom_del(bloom_t *bloom); /** - * bloom_add Add a string to a Bloom filter. + * @brief Add a string to a Bloom filter. * * CAVEAT * Once a string has been added to the filter, it cannot be "removed"! * * @param bloom Bloom filter * @param buf string to add + * @param len the length of the string @p buf * @return nothing * */ void bloom_add(bloom_t *bloom, const uint8_t *buf, size_t len); /** - * bloom_check Determine if a string is in the Bloom filter. + * @brief Determine if a string is in the Bloom filter. * * The string 's' is hashed once for each of the 'k' hash functions, as * though we were planning to add it to the filter. Instead of adding it @@ -213,6 +218,9 @@ void bloom_add(bloom_t *bloom, const uint8_t *buf, size_t len); * * @param bloom Bloom filter * @param buf string to check + * @param len the length of the string @p buf + * + * * @return false if string does not exist in the filter * @return true if string is may be in the filter * From 364e60d84c8316369661578d93e27f780a1ef965 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Sat, 6 Dec 2014 01:27:23 +0100 Subject: [PATCH 13/15] doc: fix quat_math documentation --- sys/quad_math/quad.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sys/quad_math/quad.h b/sys/quad_math/quad.h index ab37d13e4b..38e89b9a75 100644 --- a/sys/quad_math/quad.h +++ b/sys/quad_math/quad.h @@ -82,15 +82,15 @@ typedef unsigned long long u_quad_t; #define QUAD_MAX (LLONG_MAX) #define UQUAD_MAX (ULLONG_MAX) -/* +/** * Depending on the desired operation, we view a `long long' (aka quad_t) in * one or more of the following formats. */ union uu { - quad_t q; /* as a (signed) quad */ - u_quad_t uq; /* as an unsigned quad */ - int sl[2]; /* as two signed ints */ - u_int ul[2]; /* as two unsigned ints */ + quad_t q; /**< as a (signed) quad */ + u_quad_t uq; /**< as an unsigned quad */ + int sl[2]; /**< as two signed ints */ + u_int ul[2]; /**< as two unsigned ints */ }; /* From 26ab4829d7d895336a57d75e9257cc7faa951e71 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Sat, 6 Dec 2014 02:05:51 +0100 Subject: [PATCH 14/15] doc: fix posix wrapper documentation --- sys/include/posix_io.h | 45 ++++++++++++++++++- sys/posix/doc.txt | 2 +- sys/posix/include/semaphore.h | 5 +++ sys/posix/include/strings.h | 4 +- sys/posix/include/unistd.h | 5 +++ sys/posix/pthread/include/pthread_cond.h | 7 ++- .../pthread/include/pthread_threading_attr.h | 1 + 7 files changed, 65 insertions(+), 4 deletions(-) diff --git a/sys/include/posix_io.h b/sys/include/posix_io.h index 49dd93bd45..6e595befc5 100644 --- a/sys/include/posix_io.h +++ b/sys/include/posix_io.h @@ -7,7 +7,7 @@ */ /** - * @ingroup sys_posix + * @ingroup posix * @{ * @file posix_io.h * @brief POSIX-like IO @@ -31,14 +31,57 @@ extern "C" { #define READ 2 #define WRITE 3 +/** + * @brief POSIX IO ringbuffer + */ struct posix_iop_t { + /** number of bytes */ int nbytes; + /** array for the ringbuffer */ char *buffer; }; +/** + * @brief Opens a file descriptor - represented by a corresponding thread + * + * @param[in] pid The thread managing the fd to open + * @param[in] flags Access modes + * + * @return 0 on success + * @return a negative value in error case + */ int posix_open(int pid, int flags); + +/** + * @brief Closes an open file descriptor + * + * @param[in] pid The opened thread + * + * @return 0 on success + * @return a negative value in error case + */ int posix_close(int pid); + +/** + * @brief Reads from an open file descriptor + * + * @param[in] pid The thread managing the open fd + * @param[out] buffer Buffer to fill + * @param[in] bufsize Read up to that many bytes into @p buffer + * + * @return the number of read bytes + */ int posix_read(int pid, char *buffer, int bufsize); + +/** + * @brief Writes to an open file descriptor + * + * @param[in] pid The thread managing the open fd + * @param[in] buffer Buffer to write + * @param[in] bufsize Write that many bytes from @p buffer + * + * @return the number of written bytes + */ int posix_write(int pid, char *buffer, int bufsize); #ifdef __cplusplus diff --git a/sys/posix/doc.txt b/sys/posix/doc.txt index fc5c3e240a..d6ce3a0701 100644 --- a/sys/posix/doc.txt +++ b/sys/posix/doc.txt @@ -7,7 +7,7 @@ */ /** - * @defgroup sys_posix POSIX wrapper for RIOT + * @defgroup posix POSIX wrapper for RIOT * @brief POSIX header files * @see * The Open Group Specifications Issue 7 diff --git a/sys/posix/include/semaphore.h b/sys/posix/include/semaphore.h index 042afa4be0..0c21e0fb42 100644 --- a/sys/posix/include/semaphore.h +++ b/sys/posix/include/semaphore.h @@ -20,8 +20,13 @@ extern "C" { /** Value returned if `sem_open' failed. */ #define SEM_FAILED ((sem_t *) 0) +/** + * @brief Semaphore struct + */ typedef struct sem { + /** the value of the semaphore */ volatile unsigned int value; + /** list of threads waiting for the semaphore */ priority_queue_t queue; } sem_t; diff --git a/sys/posix/include/strings.h b/sys/posix/include/strings.h index b2c2013f07..e517375c47 100644 --- a/sys/posix/include/strings.h +++ b/sys/posix/include/strings.h @@ -7,7 +7,7 @@ */ /** - * @ingroup sys_posix + * @ingroup posix * @{ * * @file strings.h @@ -73,6 +73,7 @@ int strncasecmp(const char *s1, const char *s2, size_t n); * @param[in] s1 a string. * @param[in] s2 another string. * @param[in] n number of bytes to be compared + * @param[in] l locale, not used in RIOT * * @return A value greater 0 if, ignoring the case of the character, *s1* is * greater than *s2* up to n bytes, less than 0 if smaller, and 0 if @@ -109,6 +110,7 @@ int strncasecmp(const char *s1, const char *s2, size_t n); * * @param[in] s1 a string. * @param[in] s2 another string. + * @param[in] l locale, not used in RIOT * * @return A value greater 0 if, ignoring the case of the character, *s1* is * greater than *s2*, less than 0 if smaller, and 0 if equal diff --git a/sys/posix/include/unistd.h b/sys/posix/include/unistd.h index eb927120db..7a5286fae2 100644 --- a/sys/posix/include/unistd.h +++ b/sys/posix/include/unistd.h @@ -55,6 +55,10 @@ extern "C" { */ int close(int fildes); +/** + * @name Microseconds data type + * @{ + */ #ifndef __USECONDS_T_TYPE #if !(defined(__MACH__) || defined(__FreeBSD__)) typedef unsigned long __USECONDS_T_TYPE; @@ -66,6 +70,7 @@ typedef __darwin_useconds_t __useconds_t; #endif #endif typedef __useconds_t useconds_t; +/** @} */ /** * @brief the caller will sleep for given amount of micro seconds diff --git a/sys/posix/pthread/include/pthread_cond.h b/sys/posix/pthread/include/pthread_cond.h index a990860d03..bc56f043f0 100644 --- a/sys/posix/pthread/include/pthread_cond.h +++ b/sys/posix/pthread/include/pthread_cond.h @@ -32,11 +32,16 @@ extern "C" { * @note condition attributes are currently NOT USED in RIOT condition variables */ typedef struct pthread_condattr_t { + /** dumdidum */ int __dummy; } pthread_condattr_t; +/** + * @brief Condition variable + * + * @warning fields are managed by cv functions, don't touch + */ typedef struct pthread_cond_t { - /* fields are managed by cv functions, don't touch */ priority_queue_t queue; /**< Threads currently waiting to be signaled. */ } pthread_cond_t; diff --git a/sys/posix/pthread/include/pthread_threading_attr.h b/sys/posix/pthread/include/pthread_threading_attr.h index d772b4462e..b865a55f90 100644 --- a/sys/posix/pthread/include/pthread_threading_attr.h +++ b/sys/posix/pthread/include/pthread_threading_attr.h @@ -37,6 +37,7 @@ typedef struct pthread_attr * @brief This structure is unused right now, and only exists for POSIX compatibility. */ struct sched_param { + /** Todo is the greates magician in the land of RIOT */ int todo; /* TODO */ }; From a9ed34a29316273663441b934c46df8c3ac87f21 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Sat, 6 Dec 2014 11:55:28 +0100 Subject: [PATCH 15/15] doc: fixed documentation for crypto headers --- sys/include/crypto/aes.h | 8 +++++- sys/include/crypto/cbcmode.h | 20 +++++++------- sys/include/crypto/ciphers.h | 50 ++++++++++++++--------------------- sys/include/crypto/rc5.h | 2 ++ sys/include/crypto/sha256.h | 6 +++++ sys/include/crypto/skipjack.h | 2 +- sys/include/crypto/twofish.h | 12 ++++----- 7 files changed, 53 insertions(+), 47 deletions(-) diff --git a/sys/include/crypto/aes.h b/sys/include/crypto/aes.h index 0dbbde4944..ebfd665bc6 100644 --- a/sys/include/crypto/aes.h +++ b/sys/include/crypto/aes.h @@ -51,10 +51,15 @@ typedef uint8_t u8; #define AES_BLOCK_SIZE 16 #define AES_KEY_SIZE 16 - +/** + * @brief AES key + * @see cipher_context_t + */ struct aes_key_st { + /** @cond INTERNAL */ uint32_t rd_key[4 * (AES_MAXNR + 1)]; int rounds; + /** @endcond */ }; typedef struct aes_key_st AES_KEY; @@ -63,6 +68,7 @@ typedef struct aes_key_st AES_KEY; * @brief the cipher_context_t-struct adapted for AES */ typedef struct { + /** context data buffer */ uint32_t context[(4 * (AES_MAXNR + 1)) + 1]; } aes_context_t; diff --git a/sys/include/crypto/cbcmode.h b/sys/include/crypto/cbcmode.h index 2049031d7f..ecb1efaab0 100644 --- a/sys/include/crypto/cbcmode.h +++ b/sys/include/crypto/cbcmode.h @@ -77,22 +77,22 @@ enum { * @param spill1 test1 */ typedef struct CBCModeContext { - // Spill-Block 1 for temporary usage + /** Spill-Block 1 for temporary usage */ uint8_t spill1 [CBCMODE_MAX_BLOCK_SIZE ]; - // Spill-Block 2 for temporary usage + /** Spill-Block 2 for temporary usage */ uint8_t spill2 [CBCMODE_MAX_BLOCK_SIZE ]; - // the blocksize currently used + /** the blocksize currently used */ uint8_t bsize; - // how many more bytes of ciphertext do we need to recv + /** how many more bytes of ciphertext do we need to recv */ uint16_t remaining; - // how many bytes of plaintext we've deciphered. + /** how many bytes of plaintext we've deciphered. */ uint16_t completed; - // TRUE iff spill1 is the accumulator and spill2 holds prev cipher text. - // false o.w. + /** TRUE iff spill1 is the accumulator and spill2 holds prev cipher text. */ + /** false o.w. */ uint8_t accum; - // into the accumulator + /** into the accumulator */ uint8_t offset; - // state enum + /** state enum */ uint8_t state; } /*__attribute__ ((packed)) */ CBCModeContext; @@ -166,6 +166,7 @@ void dump_buffer(char *bufName, uint8_t *buf, uint8_t size); * cipher buffer are the same. (they may either be the same or * non-overlapping. partial overlaps are not supported). * + * @param context context object for this encryption * @param plain_blocks a plaintext block numBlocks, where each block is of * blockSize bytes * @param cipher_blocks an array of numBlocks * blockSize bytes to hold the @@ -190,6 +191,7 @@ int block_cipher_mode_encrypt(CipherModeContext *context, uint8_t *plain_blocks, * cipher buffer are the same. (they may either be the same or * non-overlapping. partial overlaps are not supported). * + * @param context context object for this decryption * @param cipher_blocks an array of num_bytes * blockSize bytes that holds * the cipher text * @param plain_blocks an array of num_bytes * blockSize bytes to hold the diff --git a/sys/include/crypto/ciphers.h b/sys/include/crypto/ciphers.h index 580bd197be..cc22cfb4c4 100644 --- a/sys/include/crypto/ciphers.h +++ b/sys/include/crypto/ciphers.h @@ -39,7 +39,7 @@ extern "C" { // #define TWOFISH // #define SKIPJACK -/// the length of keys in bytes +/** @brief the length of keys in bytes */ #define PARSEC_MAX_BLOCK_CIPHERS 5 #define CIPHERS_KEYSIZE 20 @@ -55,15 +55,15 @@ extern "C" { */ typedef struct { #if defined(RC5) - uint8_t context[104]; // supports RC5 and lower + uint8_t context[104]; /**< supports RC5 and lower */ #elif defined(THREEDES) - uint8_t context[24]; // supports ThreeDES and lower + uint8_t context[24]; /**< supports ThreeDES and lower */ #elif defined(AES) - uint8_t context[CIPHERS_KEYSIZE]; // supports AES and lower + uint8_t context[CIPHERS_KEYSIZE]; /**< supports AES and lower */ #elif defined(TWOFISH) - uint8_t context[CIPHERS_KEYSIZE]; // supports TwoFish and lower + uint8_t context[CIPHERS_KEYSIZE]; /**< supports TwoFish and lower */ #elif defined(SKIPJACK) - uint8_t context[20]; // supports SkipJack and lower + uint8_t context[20]; /**< supports SkipJack and lower */ #endif } cipher_context_t; @@ -72,53 +72,43 @@ typedef struct { * @brief BlockCipher-Interface for the Cipher-Algorithms */ typedef struct { + /** the name of the cipher algorithm as a string */ char name[10]; - // the init function + /** the init function */ int (*BlockCipher_init)(cipher_context_t *context, uint8_t blockSize, uint8_t keySize, uint8_t *key); - // the encrypt function + /** the encrypt function */ int (*BlockCipher_encrypt)(cipher_context_t *context, uint8_t *plainBlock, uint8_t *cipherBlock); - // the decrypt function + /** the decrypt function */ int (*BlockCipher_decrypt)(cipher_context_t *context, uint8_t *cipherBlock, uint8_t *plainBlock); - // the setupKey function + /** the setupKey function */ int (*setupKey)(cipher_context_t *context, uint8_t *key, uint8_t keysize); - // read the BlockSize of this Cipher + /** read the BlockSize of this Cipher */ uint8_t (*BlockCipherInfo_getPreferredBlockSize)(void); } block_cipher_interface_t; +/** + * @brief The cipher mode context + */ typedef struct CipherModeContext { - cipher_context_t cc; // CipherContext for the cipher-operations - uint8_t context[24]; // context for the block-cipher-modes' - // internal functions - //CBCModeContext* context; + cipher_context_t cc; /**< CipherContext for the cipher-operations */ + uint8_t context[24]; /**< context for the block-cipher-modes' */ } CipherModeContext; /** - * @brief struct for an archive of all available ciphers + * @brief struct for an archive of all available ciphers */ typedef struct { - // the number of available ciphers + /** the number of available ciphers */ uint8_t NoCiphers; - // the ciphers in form or BlockCipherInterface_ts + /** the ciphers in form or BlockCipherInterface_ts */ block_cipher_interface_t ciphers[PARSEC_MAX_BLOCK_CIPHERS]; } block_cipher_archive_t; -typedef struct { - // cipher_context_t for the cipher-operations - cipher_context_t cc; -#if defined(AES) || defined (TWOFISH) - // supports 16-Byte blocksize - uint8_t context[20]; -#else - // supports 8-Byte blocksize - uint8_t context[12]; -#endif -} cipher_mac_context_t; - #ifdef __cplusplus } #endif diff --git a/sys/include/crypto/rc5.h b/sys/include/crypto/rc5.h index 04df4b6a8f..5e7cd75e71 100644 --- a/sys/include/crypto/rc5.h +++ b/sys/include/crypto/rc5.h @@ -60,7 +60,9 @@ extern "C" { * @brief the cipher_context_t adapted for RC5 */ typedef struct { + /** @cond INTERNAL */ uint32_t skey [2 * (RC5_ROUNDS + 1)]; + /** @endcond */ } rc5_context_t; /** diff --git a/sys/include/crypto/sha256.h b/sys/include/crypto/sha256.h index 5b4395e803..21a27db81b 100644 --- a/sys/include/crypto/sha256.h +++ b/sys/include/crypto/sha256.h @@ -57,9 +57,15 @@ extern "C" { #define SHA256_DIGEST_LENGTH 32 +/** + * @brief Context for ciper operatins based on sha256 + */ typedef struct { + /** global state */ uint32_t state[8]; + /** processed bytes counter */ uint32_t count[2]; + /** data buffer */ unsigned char buf[64]; } sha256_context_t; diff --git a/sys/include/crypto/skipjack.h b/sys/include/crypto/skipjack.h index 623ebc4823..0eb1106261 100644 --- a/sys/include/crypto/skipjack.h +++ b/sys/include/crypto/skipjack.h @@ -91,7 +91,7 @@ extern "C" { * @brief The cipher_context_t adapted for SkipJack */ typedef struct { - // 2 times keysize. makes unrolling keystream easier / efficient + /** 2 times keysize. makes unrolling keystream easier / efficient */ uint8_t skey [ 20 ]; } skipjack_context_t; diff --git a/sys/include/crypto/twofish.h b/sys/include/crypto/twofish.h index cf9b71b741..17095c2c53 100644 --- a/sys/include/crypto/twofish.h +++ b/sys/include/crypto/twofish.h @@ -198,15 +198,15 @@ extern "C" { /** * @brief Structure for an expanded Twofish key. * - * @param s contains the key-dependent S-boxes composed with the MDS - * matrix; - * @param w contains the eight "whitening" subkeys, K[0] through K[7]. - * @param k holds the remaining, "round" subkeys. - * * Note that k[i] corresponds to what the Twofish paper calls K[i+8]. */ typedef struct { - uint32_t s[4][256], w[8], k[32]; + /** contains the key-dependent S-boxes composed with the MDS matrix */ + uint32_t s[4][256], + /** contains the eight "whitening" subkeys, K[0] through K[7] */ + w[8], + /** holds the remaining, "round" subkeys */ + k[32]; } twofish_context_t;