param.h

Go to the documentation of this file.

/****************************************************************************
 *
 *   Copyright (c) 2012-2015 PX4 Development Team. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 3. Neither the name PX4 nor the names of its contributors may be
 *    used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 ****************************************************************************/

#ifndef _SYSTEMLIB_PARAM_PARAM_H
#define _SYSTEMLIB_PARAM_PARAM_H

#include <stdint.h>
#include <stdbool.h>
#include <sys/types.h>

#define PARAM_FILE_MAXSIZE      4096

__BEGIN_DECLS

#define PARAM_TYPE_INT32        0
#define PARAM_TYPE_FLOAT        1
#define PARAM_TYPE_STRUCT       100
#define PARAM_TYPE_STRUCT_MAX   (16384 + PARAM_TYPE_STRUCT)
#define PARAM_TYPE_UNKNOWN      (0xffff)

typedef uint16_t param_type_t;


#ifdef __PX4_NUTTX // on NuttX use 16 bits to save RAM

typedef uint16_t    param_t;

#define PARAM_INVALID   ((uint16_t)0xffff)

#define PARAM_HASH      ((uint16_t)INT16_MAX)

#else // on other platforms use 32 bits for better performance

typedef uint32_t    param_t;

#define PARAM_INVALID   ((uint32_t)0xffffffff)

#define PARAM_HASH      ((uint32_t)INT32_MAX)

#endif /* __PX4_NUTTX */


__EXPORT void       param_init(void);

__EXPORT param_t    param_find(const char *name);

__EXPORT param_t    param_find_no_notification(const char *name);

__EXPORT unsigned   param_count(void);

__EXPORT unsigned   param_count_used(void);

__EXPORT bool       param_used(param_t param);

__EXPORT param_t    param_for_index(unsigned index);

__EXPORT param_t    param_for_used_index(unsigned index);

__EXPORT int        param_get_index(param_t param);

__EXPORT int        param_get_used_index(param_t param);

__EXPORT const char *param_name(param_t param);

__EXPORT bool       param_is_volatile(param_t param);

__EXPORT bool       param_value_is_default(param_t param);

__EXPORT bool       param_value_unsaved(param_t param);

__EXPORT param_type_t   param_type(param_t param);

__EXPORT size_t     param_size(param_t param);

__EXPORT int        param_get(param_t param, void *val);

__EXPORT int        param_set(param_t param, const void *val);

__EXPORT void       param_set_used(param_t param);

__EXPORT int        param_set_no_notification(param_t param, const void *val);

__EXPORT void       param_notify_changes(void);

__EXPORT int        param_reset(param_t param);

__EXPORT void       param_reset_all(void);

__EXPORT void       param_reset_excludes(const char *excludes[], int num_excludes);

__EXPORT int        param_export(int fd, bool only_unsaved);

__EXPORT int        param_import(int fd);

__EXPORT int        param_load(int fd);

__EXPORT void       param_foreach(void (*func)(void *arg, param_t param), void *arg, bool only_changed, bool only_used);

__EXPORT int        param_set_default_file(const char *filename);

__EXPORT const char *param_get_default_file(void);

__EXPORT int        param_save_default(void);

__EXPORT int        param_load_default(void);

__EXPORT uint32_t   param_hash_check(void);

__EXPORT void   param_print_status(void);

__EXPORT void   param_control_autosave(bool enable);

/*
 * Macros creating static parameter definitions.
 *
 * Note that these structures are not known by name; they are
 * collected into a section that is iterated by the parameter
 * code.
 *
 * Note that these macros cannot be used in C++ code due to
 * their use of designated initializers.  They should probably
 * be refactored to avoid the use of a union for param_value_u.
 */

#define PARAM_DEFINE_INT32(_name, _default)

#define PARAM_DEFINE_FLOAT(_name, _default)

#define PARAM_DEFINE_STRUCT(_name, _default)

union param_value_u {
    void        *p;
    int32_t     i;
    float       f;
};

struct param_info_s {
    const char  *name

// GCC 4.8 and higher don't implement proper alignment of static data on
// 64-bit. This means that the 24-byte param_info_s variables are
// 16 byte aligned by GCC and that messes up the assumption that
// sequential items in the __param segment can be addressed as an array.
// The assumption is that the address of the second parameter is at
// &param[0]+sizeof(param[0]). When compiled with clang it is
// true, with gcc is is not true.
// See https://llvm.org/bugs/show_bug.cgi?format=multiple&id=18006
// The following hack is for GCC >=4.8 only. Clang works fine without
// this.
#ifdef __PX4_POSIX
    __attribute__((aligned(16)));
#else
    ;
#endif
    param_type_t    type;
    uint16_t        volatile_param: 1;
    union param_value_u val;
};

__END_DECLS



#ifdef  __cplusplus
#if 0 // set to 1 to debug param type mismatches
#include <cstdio>
#define CHECK_PARAM_TYPE(param, type) \
    if (param_type(param) != type) { \
        /* use printf() to avoid having to use more includes */ \
        printf("wrong type passed to param_get() for param %s\n", param_name(param)); \
    }
#else
#define CHECK_PARAM_TYPE(param, type)
#endif

// param is a C-interface. This means there is no overloading, and thus no type-safety for param_get().
// So for C++ code we redefine param_get() to inlined overloaded versions, which gives us type-safety
// w/o having to use a different interface
static inline int param_get(param_t param, float *val)
{
    CHECK_PARAM_TYPE(param, PARAM_TYPE_FLOAT);
    return param_get(param, (void *)val);
}
static inline int param_get(param_t param, int32_t *val)
{
    CHECK_PARAM_TYPE(param, PARAM_TYPE_INT32);
    return param_get(param, (void *)val);
}
#undef CHECK_PARAM_TYPE

#endif /* __cplusplus */

#endif