PX4 Firmware
PX4 Autopilot Software http://px4.io
param.h
Go to the documentation of this file.
1 /****************************************************************************
2  *
3  * Copyright (c) 2012-2015 PX4 Development Team. All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in
13  * the documentation and/or other materials provided with the
14  * distribution.
15  * 3. Neither the name PX4 nor the names of its contributors may be
16  * used to endorse or promote products derived from this software
17  * without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
25  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
26  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
29  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30  * POSSIBILITY OF SUCH DAMAGE.
31  *
32  ****************************************************************************/
33 
34 /**
35  * @file param.h
36  *
37  * Global parameter store.
38  *
39  * Note that a number of API members are marked const or pure; these
40  * assume that the set of parameters cannot change, or that a parameter
41  * cannot change type or size over its lifetime. If any of these assumptions
42  * are invalidated, the attributes should be re-evaluated.
43  */
44 
45 #ifndef _SYSTEMLIB_PARAM_PARAM_H
46 #define _SYSTEMLIB_PARAM_PARAM_H
47 
48 #include <stdint.h>
49 #include <stdbool.h>
50 #include <sys/types.h>
51 
52 /** Maximum size of the parameter backing file */
53 #define PARAM_FILE_MAXSIZE 4096
54 
56 
57 /**
58  * Parameter types.
59  */
60 #define PARAM_TYPE_INT32 0
61 #define PARAM_TYPE_FLOAT 1
62 #define PARAM_TYPE_STRUCT 100
63 #define PARAM_TYPE_STRUCT_MAX (16384 + PARAM_TYPE_STRUCT)
64 #define PARAM_TYPE_UNKNOWN (0xffff)
65 
66 typedef uint16_t param_type_t;
67 
68 
69 #ifdef __PX4_NUTTX // on NuttX use 16 bits to save RAM
70 /**
71  * Parameter handle.
72  *
73  * Parameters are represented by parameter handles, which can
74  * be obtained by looking up parameters. They are an offset into a global
75  * constant parameter array.
76  */
77 typedef uint16_t param_t;
78 
79 /**
80  * Handle returned when a parameter cannot be found.
81  */
82 #define PARAM_INVALID ((uint16_t)0xffff)
83 
84 /**
85  * Magic handle for hash check param
86  */
87 #define PARAM_HASH ((uint16_t)INT16_MAX)
88 
89 #else // on other platforms use 32 bits for better performance
90 
91 /**
92  * Parameter handle.
93  *
94  * Parameters are represented by parameter handles, which can
95  * be obtained by looking up parameters. They are an offset into a global
96  * constant parameter array.
97  */
98 typedef uint32_t param_t;
99 
100 /**
101  * Handle returned when a parameter cannot be found.
102  */
103 #define PARAM_INVALID ((uint32_t)0xffffffff)
104 
105 /**
106  * Magic handle for hash check param
107  */
108 #define PARAM_HASH ((uint32_t)INT32_MAX)
109 
110 #endif /* __PX4_NUTTX */
111 
112 
113 /**
114  * Initialize the param backend. Call this on startup before calling any other methods.
115  */
116 __EXPORT void param_init(void);
117 
118 /**
119  * Look up a parameter by name.
120  *
121  * @param name The canonical name of the parameter being looked up.
122  * @return A handle to the parameter, or PARAM_INVALID if the parameter does not exist.
123  * This call will also set the parameter as "used" in the system, which is used
124  * to e.g. show the parameter via the RC interface
125  */
126 __EXPORT param_t param_find(const char *name);
127 
128 /**
129  * Look up a parameter by name.
130  *
131  * @param name The canonical name of the parameter being looked up.
132  * @return A handle to the parameter, or PARAM_INVALID if the parameter does not exist.
133  */
135 
136 /**
137  * Return the total number of parameters.
138  *
139  * @return The number of parameters.
140  */
141 __EXPORT unsigned param_count(void);
142 
143 /**
144  * Return the actually used number of parameters.
145  *
146  * @return The number of parameters.
147  */
148 __EXPORT unsigned param_count_used(void);
149 
150 /**
151  * Wether a parameter is in use in the system.
152  *
153  * @return True if it has been written or read
154  */
155 __EXPORT bool param_used(param_t param);
156 
157 /**
158  * Look up a parameter by index.
159  *
160  * @param index An index from 0 to n, where n is param_count()-1.
161  * @return A handle to the parameter, or PARAM_INVALID if the index is out of range.
162  */
163 __EXPORT param_t param_for_index(unsigned index);
164 
165 /**
166  * Look up an used parameter by index.
167  *
168  * @param index The parameter to obtain the index for.
169  * @return The index of the parameter in use, or -1 if the parameter does not exist.
170  */
171 __EXPORT param_t param_for_used_index(unsigned index);
172 
173 /**
174  * Look up the index of a parameter.
175  *
176  * @param param The parameter to obtain the index for.
177  * @return The index, or -1 if the parameter does not exist.
178  */
179 __EXPORT int param_get_index(param_t param);
180 
181 /**
182  * Look up the index of an used parameter.
183  *
184  * @param param The parameter to obtain the index for.
185  * @return The index of the parameter in use, or -1 if the parameter does not exist.
186  */
188 
189 /**
190  * Obtain the name of a parameter.
191  *
192  * @param param A handle returned by param_find or passed by param_foreach.
193  * @return The name assigned to the parameter, or NULL if the handle is invalid.
194  */
195 __EXPORT const char *param_name(param_t param);
196 
197 /**
198  * Obtain the volatile state of a parameter.
199  *
200  * @param param A handle returned by param_find or passed by param_foreach.
201  * @return true if the parameter is volatile
202  */
204 
205 /**
206  * Test whether a parameter's value has changed from the default.
207  *
208  * @return If true, the parameter's value has not been changed from the default.
209  */
211 
212 /**
213  * Test whether a parameter's value has been changed but not saved.
214  *
215  * @return If true, the parameter's value has not been saved.
216  */
218 
219 /**
220  * Obtain the type of a parameter.
221  *
222  * @param param A handle returned by param_find or passed by param_foreach.
223  * @return The type assigned to the parameter.
224  */
226 
227 /**
228  * Determine the size of a parameter.
229  *
230  * @param param A handle returned by param_find or passed by param_foreach.
231  * @return The size of the parameter's value.
232  */
233 __EXPORT size_t param_size(param_t param);
234 
235 /**
236  * Copy the value of a parameter.
237  *
238  * @param param A handle returned by param_find or passed by param_foreach.
239  * @param val Where to return the value, assumed to point to suitable storage for the parameter type.
240  * For structures, a bitwise copy of the structure is performed to this address.
241  * @return Zero if the parameter's value could be returned, nonzero otherwise.
242  */
243 __EXPORT int param_get(param_t param, void *val);
244 
245 /**
246  * Set the value of a parameter.
247  *
248  * @param param A handle returned by param_find or passed by param_foreach.
249  * @param val The value to set; assumed to point to a variable of the parameter type.
250  * For structures, the pointer is assumed to point to a structure to be copied.
251  * @return Zero if the parameter's value could be set from a scalar, nonzero otherwise.
252  */
253 __EXPORT int param_set(param_t param, const void *val);
254 
255 /**
256  * Mark a parameter as used. Only marked parameters will be sent to a GCS.
257  * A call to param_find() will mark a param as used as well.
258  *
259  * @param param A handle returned by param_find or passed by param_foreach.
260  */
261 __EXPORT void param_set_used(param_t param);
262 
263 /**
264  * Set the value of a parameter, but do not notify the system about the change.
265  *
266  * @param param A handle returned by param_find or passed by param_foreach.
267  * @param val The value to set; assumed to point to a variable of the parameter type.
268  * For structures, the pointer is assumed to point to a structure to be copied.
269  * @return Zero if the parameter's value could be set from a scalar, nonzero otherwise.
270  */
271 __EXPORT int param_set_no_notification(param_t param, const void *val);
272 
273 /**
274  * Notify the system about parameter changes. Can be used for example after several calls to
275  * param_set_no_notification() to avoid unnecessary system notifications.
276  */
277 __EXPORT void param_notify_changes(void);
278 
279 /**
280  * Reset a parameter to its default value.
281  *
282  * This function frees any storage used by struct parameters, and returns the parameter
283  * to its default value.
284  *
285  * @param param A handle returned by param_find or passed by param_foreach.
286  * @return Zero on success, nonzero on failure
287  */
288 __EXPORT int param_reset(param_t param);
289 
290 /**
291  * Reset all parameters to their default values.
292  *
293  * This function also releases the storage used by struct parameters.
294  */
295 __EXPORT void param_reset_all(void);
296 
297 /**
298  * Reset all parameters to their default values except for excluded parameters.
299  *
300  * This function also releases the storage used by struct parameters.
301  *
302  * @param excludes Array of param names to exclude from resetting. Use a wildcard
303  * at the end to exclude parameters with a certain prefix.
304  * @param num_excludes The number of excludes provided.
305  */
306 __EXPORT void param_reset_excludes(const char *excludes[], int num_excludes);
307 
308 /**
309  * Export changed parameters to a file.
310  * Note: this method requires a large amount of stack size!
311  *
312  * @param fd File descriptor to export to (-1 selects the FLASH storage).
313  * @param only_unsaved Only export changed parameters that have not yet been exported.
314  * @return Zero on success, nonzero on failure.
315  */
316 __EXPORT int param_export(int fd, bool only_unsaved);
317 
318 /**
319  * Import parameters from a file, discarding any unrecognized parameters.
320  *
321  * This function merges the imported parameters with the current parameter set.
322  *
323  * @param fd File descriptor to import from (-1 selects the FLASH storage).
324  * @return Zero on success, nonzero if an error occurred during import.
325  * Note that in the failure case, parameters may be inconsistent.
326  */
327 __EXPORT int param_import(int fd);
328 
329 /**
330  * Load parameters from a file.
331  *
332  * This function resets all parameters to their default values, then loads new
333  * values from a file.
334  *
335  * @param fd File descriptor to import from (-1 selects the FLASH storage).
336  * @return Zero on success, nonzero if an error occurred during import.
337  * Note that in the failure case, parameters may be inconsistent.
338  */
339 __EXPORT int param_load(int fd);
340 
341 /**
342  * Apply a function to each parameter.
343  *
344  * Note that the parameter set is not locked during the traversal. It also does
345  * not hold an internal state, so the callback function can block or sleep between
346  * parameter callbacks.
347  *
348  * @param func The function to invoke for each parameter.
349  * @param arg Argument passed to the function.
350  * @param only_changed If true, the function is only called for parameters whose values have
351  * been changed from the default.
352  * @param only_used If true, the function is only called for parameters which have been
353  * used in one of the running applications.
354  */
355 __EXPORT void param_foreach(void (*func)(void *arg, param_t param), void *arg, bool only_changed, bool only_used);
356 
357 /**
358  * Set the default parameter file name.
359  * This has no effect if the FLASH-based storage is enabled.
360  *
361  * @param filename Path to the default parameter file. The file is not required to
362  * exist.
363  * @return Zero on success.
364  */
365 __EXPORT int param_set_default_file(const char *filename);
366 
367 /**
368  * Get the default parameter file name.
369  *
370  * @return The path to the current default parameter file; either as
371  * a result of a call to param_set_default_file, or the
372  * built-in default.
373  */
374 __EXPORT const char *param_get_default_file(void);
375 
376 /**
377  * Save parameters to the default file.
378  * Note: this method requires a large amount of stack size!
379  *
380  * This function saves all parameters with non-default values.
381  *
382  * @return Zero on success.
383  */
384 __EXPORT int param_save_default(void);
385 
386 /**
387  * Load parameters from the default parameter file.
388  *
389  * @return Zero on success.
390  */
391 __EXPORT int param_load_default(void);
392 
393 /**
394  * Generate the hash of all parameters and their values
395  *
396  * @return CRC32 hash of all param_ids and values
397  */
398 __EXPORT uint32_t param_hash_check(void);
399 
400 /**
401  * Print the status of the param system
402  *
403  */
404 __EXPORT void param_print_status(void);
405 
406 /**
407  * Enable/disable the param autosaving.
408  * Re-enabling with changed params will not cause an autosave.
409  * @param enable true: enable autosaving, false: disable autosaving
410  */
411 __EXPORT void param_control_autosave(bool enable);
412 
413 /**
414  * Parameter value union.
415  */
417  void *p;
418  int32_t i;
419  float f;
420 };
421 
422 /**
423  * Static parameter definition structure.
424  *
425  * This is normally not used by user code; see the PARAM_DEFINE macros
426  * instead.
427  */
428 struct param_info_s {
429  const char *name
430 
431 // GCC 4.8 and higher don't implement proper alignment of static data on
432 // 64-bit. This means that the 24-byte param_info_s variables are
433 // 16 byte aligned by GCC and that messes up the assumption that
434 // sequential items in the __param segment can be addressed as an array.
435 // The assumption is that the address of the second parameter is at
436 // &param[0]+sizeof(param[0]). When compiled with clang it is
437 // true, with gcc is is not true.
438 // See https://llvm.org/bugs/show_bug.cgi?format=multiple&id=18006
439 // The following hack is for GCC >=4.8 only. Clang works fine without
440 // this.
441 #ifdef __PX4_POSIX
442  __attribute__((aligned(16)));
443 #else
444  ;
445 #endif
447  uint16_t volatile_param: 1;
448  union param_value_u val;
449 };
450 
452 
453 
454 
455 #ifdef __cplusplus
456 #if 0 // set to 1 to debug param type mismatches
457 #include <cstdio>
458 #define CHECK_PARAM_TYPE(param, type) \
459  if (param_type(param) != type) { \
460  /* use printf() to avoid having to use more includes */ \
461  printf("wrong type passed to param_get() for param %s\n", param_name(param)); \
462  }
463 #else
464 #define CHECK_PARAM_TYPE(param, type)
465 #endif
466 
467 // param is a C-interface. This means there is no overloading, and thus no type-safety for param_get().
468 // So for C++ code we redefine param_get() to inlined overloaded versions, which gives us type-safety
469 // w/o having to use a different interface
470 static inline int param_get(param_t param, float *val)
471 {
472  CHECK_PARAM_TYPE(param, PARAM_TYPE_FLOAT);
473  return param_get(param, (void *)val);
474 }
475 static inline int param_get(param_t param, int32_t *val)
476 {
477  CHECK_PARAM_TYPE(param, PARAM_TYPE_INT32);
478  return param_get(param, (void *)val);
479 }
480 #undef CHECK_PARAM_TYPE
481 
482 #endif /* __cplusplus */
483 
484 #endif
__EXPORT param_t param_find_no_notification(const char *name)
Look up a parameter by name.
Definition: parameters.cpp:376
__EXPORT void param_init(void)
Initialize the param backend.
Definition: parameters.cpp:230
__EXPORT size_t param_size(param_t param)
Determine the size of a parameter.
Definition: parameters.cpp:525
param_type_t type
Definition: param.h:446
__EXPORT bool param_value_unsaved(param_t param)
Test whether a parameter&#39;s value has been changed but not saved.
Definition: parameters.cpp:508
__EXPORT int param_import(int fd)
Import parameters from a file, discarding any unrecognized parameters.
__EXPORT void param_foreach(void(*func)(void *arg, param_t param), void *arg, bool only_changed, bool only_used)
Apply a function to each parameter.
uint16_t volatile_param
Definition: param.h:447
#define __END_DECLS
Definition: visibility.h:59
#define PARAM_TYPE_INT32
Parameter types.
Definition: param.h:60
__EXPORT void param_print_status(void)
Print the status of the param system.
__EXPORT int param_get(param_t param, void *val)
Copy the value of a parameter.
Definition: parameters.cpp:589
__EXPORT int param_set_no_notification(param_t param, const void *val)
Set the value of a parameter, but do not notify the system about the change.
Definition: parameters.cpp:820
uint16_t param_type_t
Definition: param.h:66
__EXPORT int param_get_index(param_t param)
Look up the index of a parameter.
Definition: parameters.cpp:449
__EXPORT const char * param_get_default_file(void)
Get the default parameter file name.
Definition: parameters.cpp:968
__EXPORT int param_set(param_t param, const void *val)
Set the value of a parameter.
Definition: parameters.cpp:814
Definition: I2C.hpp:51
__EXPORT param_t param_for_index(unsigned index)
Look up a parameter by index.
Definition: parameters.cpp:408
__EXPORT void param_set_used(param_t param)
Mark a parameter as used.
Definition: parameters.cpp:838
__EXPORT bool param_value_is_default(param_t param)
Test whether a parameter&#39;s value has changed from the default.
Definition: parameters.cpp:498
__EXPORT int param_get_used_index(param_t param)
Look up the index of an used parameter.
Definition: parameters.cpp:459
__EXPORT unsigned param_count(void)
Return the total number of parameters.
Definition: parameters.cpp:382
int32_t i
Definition: param.h:418
void * p
Definition: param.h:417
Static parameter definition structure.
Definition: param.h:428
__EXPORT const char * param_name(param_t param)
Obtain the name of a parameter.
Definition: parameters.cpp:486
__EXPORT void param_reset_excludes(const char *excludes[], int num_excludes)
Reset all parameters to their default values except for excluded parameters.
Definition: parameters.cpp:916
Parameter value union.
Definition: param.h:416
__EXPORT int param_export(int fd, bool only_unsaved)
Export changed parameters to a file.
__EXPORT unsigned param_count_used(void)
Return the actually used number of parameters.
Definition: parameters.cpp:388
#define __BEGIN_DECLS
Definition: visibility.h:58
__EXPORT int param_set_default_file(const char *filename)
Set the default parameter file name.
Definition: parameters.cpp:945
__EXPORT param_type_t param_type(param_t param)
Obtain the type of a parameter.
Definition: parameters.cpp:519
__EXPORT int param_save_default(void)
Save parameters to the default file.
Definition: parameters.cpp:974
struct __attribute__((__packed__)) reading_msg
Definition: leddar_one.cpp:80
int fd
Definition: dataman.cpp:146
__EXPORT uint32_t param_hash_check(void)
Generate the hash of all parameters and their values.
__EXPORT param_t param_find(const char *name)
Look up a parameter by name.
Definition: parameters.cpp:370
const char * name
Definition: tests_main.c:58
#define PARAM_TYPE_FLOAT
Definition: param.h:61
__EXPORT bool param_is_volatile(param_t param)
Obtain the volatile state of a parameter.
Definition: parameters.cpp:492
__EXPORT void param_notify_changes(void)
Notify the system about parameter changes.
Definition: parameters.cpp:323
__EXPORT void param_control_autosave(bool enable)
Enable/disable the param autosaving.
Definition: parameters.cpp:687
__EXPORT void param_reset_all(void)
Reset all parameters to their default values.
Definition: parameters.cpp:910
float f
Definition: param.h:419
__EXPORT int param_reset(param_t param)
Reset a parameter to its default value.
Definition: parameters.cpp:857
__EXPORT param_t param_for_used_index(unsigned index)
Look up an used parameter by index.
Definition: parameters.cpp:420
__EXPORT int param_load_default(void)
Load parameters from the default parameter file.
__EXPORT int param_load(int fd)
Load parameters from a file.
uint32_t param_t
Parameter handle.
Definition: param.h:98
__EXPORT bool param_used(param_t param)
Wether a parameter is in use in the system.
Definition: parameters.cpp:826