S Morita / mbed-mros2

Porting mros2 as an Mbed library.

Dependents:   mbed-os-example-mros2 example-mbed-mros2-sub-pose example-mbed-mros2-pub-twist example-mbed-mros2-mturtle-teleop

embeddedRTPS/thirdparty/Micro-CDR/README.md@7:c80f65422d99, 2022-03-19 (annotated)

Committer:
smoritaemb
Date:
Sat Mar 19 09:23:37 2022 +0900
Revision:
7:c80f65422d99
Parent:
0:580aba13d1a1 
Merge test_assortment_of_msgs branch.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
smoritaemb 0:580aba13d1a1 1 # eProsima Micro CDR
smoritaemb 0:580aba13d1a1 2
smoritaemb 0:580aba13d1a1 3 [![Releases](https://img.shields.io/github/release/eProsima/Micro-CDR.svg)](https://github.com/eProsima/Micro-CDR/releases)
smoritaemb 0:580aba13d1a1 4 [![License](https://img.shields.io/github/license/eProsima/Micro-CDR.svg)](https://github.com/eProsima/Micro-CDR/blob/master/LICENSE)
smoritaemb 0:580aba13d1a1 5 [![Issues](https://img.shields.io/github/issues/eProsima/Micro-CDR.svg)](https://github.com/eProsima/Micro-CDR/issues)
smoritaemb 0:580aba13d1a1 6 [![Forks](https://img.shields.io/github/forks/eProsima/Micro-CDR.svg)](https://github.com/eProsima/Micro-CDR/network/members)
smoritaemb 0:580aba13d1a1 7 [![Stars](https://img.shields.io/github/stars/eProsima/Micro-CDR.svg)](https://github.com/eProsima/Micro-CDR/stargazers)
smoritaemb 0:580aba13d1a1 8
smoritaemb 0:580aba13d1a1 9 <a href="http://www.eprosima.com"><img src="https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcSd0PDlVz1U_7MgdTe0FRIWD0Jc9_YH-gGi0ZpLkr-qgCI6ZEoJZ5GBqQ" align="left" hspace="8" vspace="2" width="100" height="100" ></a>
smoritaemb 0:580aba13d1a1 10
smoritaemb 0:580aba13d1a1 11 *eProsima MicroCDR* is a *C* library implementing the *CDR* standard serialization methods.
smoritaemb 0:580aba13d1a1 12 This library is focused on embedded and resource-limited systems.
smoritaemb 0:580aba13d1a1 13
smoritaemb 0:580aba13d1a1 14 *MicroCDR* uses a static buffer, and allow to serialize and deserialize in both, big endianness and little endianness.
smoritaemb 0:580aba13d1a1 15
smoritaemb 0:580aba13d1a1 16 ## Usage examples
smoritaemb 0:580aba13d1a1 17 This is a code example showing the serialization and deserialization of a string.
smoritaemb 0:580aba13d1a1 18 As *MicroCDR* uses a static buffer, that means the user has to provide a defined buffer and its size during the *ucdrBuffer* creation.
smoritaemb 0:580aba13d1a1 19
smoritaemb 0:580aba13d1a1 20 ```c
smoritaemb 0:580aba13d1a1 21 #include <ucdr/microcdr.h>
smoritaemb 0:580aba13d1a1 22 #include <stdio.h>
smoritaemb 0:580aba13d1a1 23
smoritaemb 0:580aba13d1a1 24 #define BUFFER_LENGTH 256
smoritaemb 0:580aba13d1a1 25
smoritaemb 0:580aba13d1a1 26 int main(int argc, char** args)
smoritaemb 0:580aba13d1a1 27 {
smoritaemb 0:580aba13d1a1 28 // Data buffer
smoritaemb 0:580aba13d1a1 29 uint8_t buffer[BUFFER_LENGTH];
smoritaemb 0:580aba13d1a1 30
smoritaemb 0:580aba13d1a1 31 // Structs for handle the buffer.
smoritaemb 0:580aba13d1a1 32 ucdrBuffer writer;
smoritaemb 0:580aba13d1a1 33 ucdrBuffer reader;
smoritaemb 0:580aba13d1a1 34
smoritaemb 0:580aba13d1a1 35 // Initialize the MicroBuffers for working with an user-managed buffer.
smoritaemb 0:580aba13d1a1 36 ucdr_init_buffer(&writer, buffer, BUFFER_LENGTH);
smoritaemb 0:580aba13d1a1 37 ucdr_init_buffer(&reader, buffer, BUFFER_LENGTH);
smoritaemb 0:580aba13d1a1 38
smoritaemb 0:580aba13d1a1 39 // Serialize data
smoritaemb 0:580aba13d1a1 40 char input[16] = "Hello MicroCDR!"; //16 characters
smoritaemb 0:580aba13d1a1 41 ucdr_serialize_array_char(&writer, input, 16);
smoritaemb 0:580aba13d1a1 42
smoritaemb 0:580aba13d1a1 43 // Deserialize data
smoritaemb 0:580aba13d1a1 44 char output[16];
smoritaemb 0:580aba13d1a1 45 ucdr_deserialize_array_char(&reader, output, 16);
smoritaemb 0:580aba13d1a1 46
smoritaemb 0:580aba13d1a1 47 printf("Input: %s\n", input);
smoritaemb 0:580aba13d1a1 48 printf("Output: %s\n", output);
smoritaemb 0:580aba13d1a1 49
smoritaemb 0:580aba13d1a1 50 return 0;
smoritaemb 0:580aba13d1a1 51 }
smoritaemb 0:580aba13d1a1 52 ```
smoritaemb 0:580aba13d1a1 53
smoritaemb 0:580aba13d1a1 54 ## API functions
smoritaemb 0:580aba13d1a1 55
smoritaemb 0:580aba13d1a1 56 ```c
smoritaemb 0:580aba13d1a1 57 void ucdr_init_buffer (ucdrBuffer* mb, uint8_t* data, const uint32_t size);
smoritaemb 0:580aba13d1a1 58 void ucdr_init_buffer_offset (ucdrBuffer* mb, uint8_t* data, const uint32_t size, uint32_t offset);
smoritaemb 0:580aba13d1a1 59 ```
smoritaemb 0:580aba13d1a1 60 Initialize a `ucdrBuffer` structure, the main struct of *MicroCDR*.
smoritaemb 0:580aba13d1a1 61 - `mb`: the `ucdrBuffer` struct
smoritaemb 0:580aba13d1a1 62 - `data`: the buffer that the `ucdrBuffer` will use.
smoritaemb 0:580aba13d1a1 63 - `size`: the size of the buffer that the `ucdrBuffer` will use.
smoritaemb 0:580aba13d1a1 64 - `offset`: where the serialization/deserialization will start.
smoritaemb 0:580aba13d1a1 65 Initially, the serialization/deserialization starts at the beginning of the buffer.
smoritaemb 0:580aba13d1a1 66
smoritaemb 0:580aba13d1a1 67 ---
smoritaemb 0:580aba13d1a1 68
smoritaemb 0:580aba13d1a1 69 ```c
smoritaemb 0:580aba13d1a1 70 void ucdr_copy_buffer (ucdrBuffer* mb_dest, const ucdrBuffer* mb_source);
smoritaemb 0:580aba13d1a1 71 ```
smoritaemb 0:580aba13d1a1 72 Copy a `ucdrBuffer` structure data to another `ucdrBuffer` structure.
smoritaemb 0:580aba13d1a1 73 - `mb_dest`: the destination `ucdrBuffer` struct.
smoritaemb 0:580aba13d1a1 74 - `mb_source`: the origin initialized `ucdrBuffer` struct.
smoritaemb 0:580aba13d1a1 75
smoritaemb 0:580aba13d1a1 76 ---
smoritaemb 0:580aba13d1a1 77
smoritaemb 0:580aba13d1a1 78 ```c
smoritaemb 0:580aba13d1a1 79 void ucdr_reset_buffer (ucdrBuffer* mb);
smoritaemb 0:580aba13d1a1 80 void ucdr_reset_buffer_offset(ucdrBuffer* mb, const uint32_t offset);
smoritaemb 0:580aba13d1a1 81 ```
smoritaemb 0:580aba13d1a1 82 Reset the `ucdrBuffer` as the same state that it was created.
smoritaemb 0:580aba13d1a1 83 - `mb`: the `ucdrBuffer` struct.
smoritaemb 0:580aba13d1a1 84 - `offset`: where the serialization/deserialization will start.
smoritaemb 0:580aba13d1a1 85 Initially, the serialization/deserialization starts at the beginning of the buffer.
smoritaemb 0:580aba13d1a1 86
smoritaemb 0:580aba13d1a1 87 ---
smoritaemb 0:580aba13d1a1 88
smoritaemb 0:580aba13d1a1 89 ```c
smoritaemb 0:580aba13d1a1 90 void ucdr_align_to (ucdrBuffer* mb, const uint32_t alignment);
smoritaemb 0:580aba13d1a1 91 ```
smoritaemb 0:580aba13d1a1 92 Align the ucdrBuffer to an `alignment` position.
smoritaemb 0:580aba13d1a1 93 After call this function, the serialization pointer will be moved only if the current `ucdrBuffer` was not aligment to the passed value.
smoritaemb 0:580aba13d1a1 94
smoritaemb 0:580aba13d1a1 95 - `mb`: the `ucdrBuffer` struct
smoritaemb 0:580aba13d1a1 96 - `alignment`: the alignment value used.
smoritaemb 0:580aba13d1a1 97
smoritaemb 0:580aba13d1a1 98 ---
smoritaemb 0:580aba13d1a1 99
smoritaemb 0:580aba13d1a1 100 ```c
smoritaemb 0:580aba13d1a1 101 uint32_t ucdr_aligment(uint32_t buffer_position, const uint32_t data_size);
smoritaemb 0:580aba13d1a1 102 ```
smoritaemb 0:580aba13d1a1 103 Returns the aligment necessary to serialize/deserialize a type with `data_size` size.
smoritaemb 0:580aba13d1a1 104
smoritaemb 0:580aba13d1a1 105 - `buffer_position`: the current serialization/deserialization position of the `ucdrBuffer`. (Typically `mb->iterator - mb->init`).
smoritaemb 0:580aba13d1a1 106 - `data_size`: the bytes of the data that you are asking for.
smoritaemb 0:580aba13d1a1 107
smoritaemb 0:580aba13d1a1 108 ---
smoritaemb 0:580aba13d1a1 109
smoritaemb 0:580aba13d1a1 110 ```c
smoritaemb 0:580aba13d1a1 111 uint32_t ucdr_buffer_alignment(const ucdrBuffer* mb, const uint32_t data_size);
smoritaemb 0:580aba13d1a1 112 ```
smoritaemb 0:580aba13d1a1 113 Returns the aligment necessary to serialize/deserialize a type with `data_size` size into the `ucdrBuffer` given.
smoritaemb 0:580aba13d1a1 114
smoritaemb 0:580aba13d1a1 115 - `mb`: the `ucdrBuffer` struct to ask the alignment.
smoritaemb 0:580aba13d1a1 116 - `data_size`: the bytes of the data that you are asking for.
smoritaemb 0:580aba13d1a1 117 ---
smoritaemb 0:580aba13d1a1 118
smoritaemb 0:580aba13d1a1 119 ```c
smoritaemb 0:580aba13d1a1 120 size_t ucdr_buffer_size(const ucdrBuffer* mb);
smoritaemb 0:580aba13d1a1 121 ```
smoritaemb 0:580aba13d1a1 122 Returns the memory size of the buffer.
smoritaemb 0:580aba13d1a1 123 - `mb`: the `ucdrBuffer` struct
smoritaemb 0:580aba13d1a1 124
smoritaemb 0:580aba13d1a1 125 ---
smoritaemb 0:580aba13d1a1 126
smoritaemb 0:580aba13d1a1 127 ```c
smoritaemb 0:580aba13d1a1 128 size_t ucdr_buffer_length(const ucdrBuffer* mb);
smoritaemb 0:580aba13d1a1 129 ```
smoritaemb 0:580aba13d1a1 130 Returns the size of the serialized/deserialized data.
smoritaemb 0:580aba13d1a1 131 - `mb`: the `ucdrBuffer` struct
smoritaemb 0:580aba13d1a1 132
smoritaemb 0:580aba13d1a1 133 ---
smoritaemb 0:580aba13d1a1 134
smoritaemb 0:580aba13d1a1 135 ```c
smoritaemb 0:580aba13d1a1 136 size_t ucdr_buffer_remaining(const ucdrBuffer* mb);
smoritaemb 0:580aba13d1a1 137 ```
smoritaemb 0:580aba13d1a1 138 Returns the remaining size for the serializing/deserializing.
smoritaemb 0:580aba13d1a1 139 - `mb`: the `ucdrBuffer` struct
smoritaemb 0:580aba13d1a1 140
smoritaemb 0:580aba13d1a1 141 ---
smoritaemb 0:580aba13d1a1 142
smoritaemb 0:580aba13d1a1 143 ```c
smoritaemb 0:580aba13d1a1 144 ucdrEndianness ucdr_buffer_endianness(const ucdrBuffer* mb);
smoritaemb 0:580aba13d1a1 145 ```
smoritaemb 0:580aba13d1a1 146 Returns the serialization/deserialization endianness.
smoritaemb 0:580aba13d1a1 147 - `mb`: the `ucdrBuffer` struct
smoritaemb 0:580aba13d1a1 148
smoritaemb 0:580aba13d1a1 149 ---
smoritaemb 0:580aba13d1a1 150
smoritaemb 0:580aba13d1a1 151 ```c
smoritaemb 0:580aba13d1a1 152 bool ucdr_buffer_error(const ucdrBuffer* mb);
smoritaemb 0:580aba13d1a1 153 ```
smoritaemb 0:580aba13d1a1 154 Returns the status error of the `ucdrBuffer`.
smoritaemb 0:580aba13d1a1 155 - `mb`: the `ucdrBuffer` struct
smoritaemb 0:580aba13d1a1 156
smoritaemb 0:580aba13d1a1 157
smoritaemb 0:580aba13d1a1 158 ### Serialization/deserialization functions
smoritaemb 0:580aba13d1a1 159 Adding to this, there is a big set of functions for deserialize and deserialize different kind of types:
smoritaemb 0:580aba13d1a1 160 - Basics: `bool`, `char`, `int8_t`, `uint8_t`,`int16_t`, `uint16_t`,`int32_t`, `uint32_t`,`int64_t`, `uint64_t`,`float`, `double`.
smoritaemb 0:580aba13d1a1 161 - Arrays: Any fixed size of basics types.
smoritaemb 0:580aba13d1a1 162 - Sequence: Similar to arrays, but the information about the size is serialized along with the data.
smoritaemb 0:580aba13d1a1 163
smoritaemb 0:580aba13d1a1 164 ### Endianness
smoritaemb 0:580aba13d1a1 165 *MicroCDR* supports little and big endianness.
smoritaemb 0:580aba13d1a1 166 The **machine endianness** can be set by the cmake variable: `CONFIG_BIG_ENDIANNESS`.
smoritaemb 0:580aba13d1a1 167 By default, if this varible is `OFF` which means that the machine endianness is little endianness.
smoritaemb 0:580aba13d1a1 168
smoritaemb 0:580aba13d1a1 169 The `ucdrBuffer` endianness can be set by the `endianness` parameter of the structure to `UCDR_BIG_ENDIANNESS` or `UCDR_LITTLE_ENDIANNESS`.
smoritaemb 0:580aba13d1a1 170 Also, there are a functions that allow to force an endianness independiently of the `ucdrBuffer` endianness in their serialization/deserialization.
smoritaemb 0:580aba13d1a1 171 These functions contains the name `endianness` in their signature.
smoritaemb 0:580aba13d1a1 172
smoritaemb 0:580aba13d1a1 173 ### Error
smoritaemb 0:580aba13d1a1 174 All serialization/deserialization functions return a boolean indicating the result of their operations.
smoritaemb 0:580aba13d1a1 175 When a serialization/deserialization could not be possible (the type can not be serialized, or the capacity of the destination buffer is not enough),
smoritaemb 0:580aba13d1a1 176 an status error is setted into the `ucdrBuffer`.
smoritaemb 0:580aba13d1a1 177 If a `ucdrBuffer` has an error state, the next serialization/deserialization operations will not works and will return `false` in their execution.
smoritaemb 0:580aba13d1a1 178 A buffer marked with an error can be used, but any serialization/deserialization operation over it will not produce any effect.
smoritaemb 0:580aba13d1a1 179
smoritaemb 0:580aba13d1a1 180 If is kwown that an operation can fails over a `ucdrBuffer`, and its necessary to continue with the serialization/deserialization if it happens,
smoritaemb 0:580aba13d1a1 181 the `ucdrBuffer` state can be saved using the `ucdr_copy_buffer` function.
smoritaemb 0:580aba13d1a1 182 After the application of the wrong serialization/deserialization, only the `ucdrBuffer` that performed the operation will have a dirty state.
smoritaemb 0:580aba13d1a1 183
smoritaemb 0:580aba13d1a1 184 ## Serialization/deserialization list
smoritaemb 0:580aba13d1a1 185 The available modes of serialization/deserializations in *MicroCDR* are shown in the following table.
smoritaemb 0:580aba13d1a1 186
smoritaemb 0:580aba13d1a1 187
smoritaemb 0:580aba13d1a1 188 | Type | Endianness |
smoritaemb 0:580aba13d1a1 189 | -------------------- | ---------- |
smoritaemb 0:580aba13d1a1 190 | bool | |
smoritaemb 0:580aba13d1a1 191 | char | |
smoritaemb 0:580aba13d1a1 192 | int8 | |
smoritaemb 0:580aba13d1a1 193 | uint8 | |
smoritaemb 0:580aba13d1a1 194 | int16 | |
smoritaemb 0:580aba13d1a1 195 | int16 | endianness |
smoritaemb 0:580aba13d1a1 196 | uint16 | |
smoritaemb 0:580aba13d1a1 197 | uint16 | endianness |
smoritaemb 0:580aba13d1a1 198 | int32 | |
smoritaemb 0:580aba13d1a1 199 | int32 | endianness |
smoritaemb 0:580aba13d1a1 200 | uint32 | |
smoritaemb 0:580aba13d1a1 201 | uint32 | endianness |
smoritaemb 0:580aba13d1a1 202 | int64 | |
smoritaemb 0:580aba13d1a1 203 | int64 | endianness |
smoritaemb 0:580aba13d1a1 204 | uint64 | |
smoritaemb 0:580aba13d1a1 205 | uint64 | endianness |
smoritaemb 0:580aba13d1a1 206 | float | |
smoritaemb 0:580aba13d1a1 207 | float | endianness |
smoritaemb 0:580aba13d1a1 208 | double | |
smoritaemb 0:580aba13d1a1 209 | double | endianness |
smoritaemb 0:580aba13d1a1 210 | string | |
smoritaemb 0:580aba13d1a1 211 | string | endianness |
smoritaemb 0:580aba13d1a1 212 | bool array | |
smoritaemb 0:580aba13d1a1 213 | char array | |
smoritaemb 0:580aba13d1a1 214 | int8 array | |
smoritaemb 0:580aba13d1a1 215 | uint8 array | |
smoritaemb 0:580aba13d1a1 216 | int16 array | |
smoritaemb 0:580aba13d1a1 217 | int16 array | endianness |
smoritaemb 0:580aba13d1a1 218 | uint16 array | |
smoritaemb 0:580aba13d1a1 219 | uint16 array | endianness |
smoritaemb 0:580aba13d1a1 220 | int32 array | |
smoritaemb 0:580aba13d1a1 221 | int32 array | endianness |
smoritaemb 0:580aba13d1a1 222 | uint32 array | |
smoritaemb 0:580aba13d1a1 223 | uint32 array | endianness |
smoritaemb 0:580aba13d1a1 224 | int64 array | |
smoritaemb 0:580aba13d1a1 225 | int64 array | endianness |
smoritaemb 0:580aba13d1a1 226 | uint64 array | |
smoritaemb 0:580aba13d1a1 227 | uint64 array | endianness |
smoritaemb 0:580aba13d1a1 228 | float array | |
smoritaemb 0:580aba13d1a1 229 | float array | endianness |
smoritaemb 0:580aba13d1a1 230 | double array | |
smoritaemb 0:580aba13d1a1 231 | double array | endianness |
smoritaemb 0:580aba13d1a1 232 | bool sequence | |
smoritaemb 0:580aba13d1a1 233 | bool sequence | endianness |
smoritaemb 0:580aba13d1a1 234 | char sequence | |
smoritaemb 0:580aba13d1a1 235 | char sequence | endianness |
smoritaemb 0:580aba13d1a1 236 | int8 sequence | |
smoritaemb 0:580aba13d1a1 237 | int8 sequence | endianness |
smoritaemb 0:580aba13d1a1 238 | uint8 sequence | |
smoritaemb 0:580aba13d1a1 239 | uint8 sequence | endianness |
smoritaemb 0:580aba13d1a1 240 | int16 sequence | |
smoritaemb 0:580aba13d1a1 241 | int16 sequence | endianness |
smoritaemb 0:580aba13d1a1 242 | uint16 sequence | |
smoritaemb 0:580aba13d1a1 243 | uint16 sequence | endianness |
smoritaemb 0:580aba13d1a1 244 | int32 sequence | |
smoritaemb 0:580aba13d1a1 245 | int32 sequence | endianness |
smoritaemb 0:580aba13d1a1 246 | uint32 sequence | |
smoritaemb 0:580aba13d1a1 247 | uint32 sequence | endianness |
smoritaemb 0:580aba13d1a1 248 | int64 sequence | |
smoritaemb 0:580aba13d1a1 249 | int64 sequence | endianness |
smoritaemb 0:580aba13d1a1 250 | uint64 sequence | |
smoritaemb 0:580aba13d1a1 251 | uint64 sequence | endianness |
smoritaemb 0:580aba13d1a1 252 | float sequence | |
smoritaemb 0:580aba13d1a1 253 | float sequence | endianness |
smoritaemb 0:580aba13d1a1 254 | double sequence | |
smoritaemb 0:580aba13d1a1 255 | double sequence | endianness |
smoritaemb 0:580aba13d1a1 256