toc-app.h

Go to the documentation of this file.

#ifndef TOC_APP_API_H_INCLUDED
#define TOC_APP_API_H_INCLUDED
/**********************************************************************/
/*
 * Copyright (c) 2013-2015, Jetro AS
 * 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. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``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 AUTHOR 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.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * @brief TOC application API
 *
 * @author DT, Jetro AS
 */ /******************************************************************/

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

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup toc
 * @{
 */

/**
 * @brief System TOC segments definition.
 */
#define TOC_SYSTEM_SEGMENT_DESCRIPTORS()  \
  [SEGMENT_RAM] =                         \
  {                                       \
    .Offset = (uint32_t)&TocData,         \
  },                                      \
  [SEGMENT_COMMAND] =                     \
  {                                       \
    .Offset = (uint32_t)&TocCommand,      \
  },                                      \
  [SEGMENT_SERVICES] =                    \
  {                                       \
    .Offset = (uint32_t) &TocServices,    \
  }

/**
 * @brief The utility macro binds a segment structure "type" with tag "tag".
 * See toc-instance.h for defails
 */
#ifdef __cplusplus
  #define BIND_SEGMENT(type, tag)         \
    template <class SegmentLoc>           \
    struct CSegment;                      \
    struct CLoc_ ## tag;                  \
    template <>                           \
    struct CSegment<CLoc_ ## tag>         \
    {                                     \
      typedef type segment_t;             \
      static const uint8_t m_segment = SEGMENT_ ## tag; \
    };
#else
  #define BIND_SEGMENT(type, tag)
#endif


/**
 * @brief The enum defines type of a generic value.
 */
enum toc_val_type_t
{
  TOC_VAL_TYPE_STRING = 0,  /**< The value is a string variable        */
  TOC_VAL_TYPE_INT,         /**< The value is a 32-bit integer         */
  TOC_VAL_TYPE_BOOL,        /**< The value is a Boolean variable       */
  TOC_VAL_TYPE_STRUCT,      /**< The value is a structure              */
  TOC_VAL_TYPE_SERVICE,     /**< BLE service descriptor                */
  TOC_VAL_TYPE_UNKNOWN,     /**< Reserved                              */
};

/**
 * @brief minimal and maximal possible values for the INTEGER parameters.
 */
struct min_max_t
{
  int32_t Min;                                                  /**< Minimal value */
  int32_t Max;                                                  /**< Maximal value */
};

#define TOC_ACL_PUBLIC                    (0)                   /**< The paramater is visible for everyone */
#define TOC_ACL_PROTECTED                 (1)                   /**< The paramater is visible for a super user */
#define TOC_ACL_PRIVATE                   (2)                   /**< The paramater is visible in debug mode only */
#define TOC_ACL_DENIED                    (3)                   /**< The paramater is not visible */

#define TOC_POLICY_PRE_CB                 (1 << 0)              /**< A callback to be called before the paramater access */
#define TOC_POLICY_POST_CB                (1 << 1)              /**< A callback to be called after the paramater access */

#define TOC_FLAG_ACL(x)                   (((x) & 3) << 0)      /**< Access control flags, see TOC_ACL_... */
#define TOC_FLAG_READ_POLICY(x)           (((x) & 3) << 2)      /**< Read policy, see TOC_POLICY_... */
#define TOC_FLAG_WRITE_POLICY(x)          (((x) & 3) << 4)      /**< Write policy, see TOC_POLICY_... */
#define TOC_FLAG_READ                     (1 << 6)              /**< The parameter is readable */
#define TOC_FLAG_WRITE                    (1 << 7)              /**< The parameter is writeable */

#define TOC_FLAG_BINARY                   (1 << 8)              /**< The STRING parameter contains binary data */
#define TOC_FLAG_VIRTUAL                  (1 << 9)              /**< The parameter is a virtual array */
#define TOC_FLAG_EXTERN_LIMITS            (1 << 10)             /**< Min and Max contain offsets to real uint32_t limits in a pool */
#define TOC_FLAG_V_SIZE                   (1 << 11)             /**< The parameter has variable size */

#define TOC_FLAG_BLE_BROADCAST            (1 << 13)             /**< BLE should allow broadcast for the parameter */
#define TOC_FLAG_BLE_NOTIFICATION         (1 << 14)             /**< BLE should allow notification for the parameter */
#define TOC_FLAG_BLE_INDICATION           (1 << 15)             /**< BLE should allow indication for the parameter */

#define TOC_POLICY_MASK                   (3)                   /**< Policy type mask */
#define TOC_FLAG_ACL_MASK                 TOC_FLAG_ACL(3)       /**< ACL flags mask */
#define TOC_FLAG_READ_POLICY_MASK         TOC_FLAG_READ_POLICY(3)   /**< Read policy mask*/
#define TOC_FLAG_WRITE_POLICY_MASK        TOC_FLAG_WRITE_POLICY(3)  /**< Write policy mask */

/**
 * @brief Applikasjon-spesifikk parameter beskrivelse.
 * @param Name navn av parameteren som offset i string pool
 */
struct toc_t
{
  uint16_t Type : 4;                                            /**< Type of the parameter, one of VAL_TYPE_... */
  uint16_t Name : 12;                                           /**< Offset of the name of the parameter in the string pool */
  uint16_t Flags;                                               /**< Binary blags bitmap, see TOC_FLAG_... for details */
  uint16_t Offset : 13;                                         /**< Offset of the parameter in the segment */
  uint16_t Segment : 3;                                         /**< Segment ID where the parameter is located */
  uint8_t Size;                                                 /**< Size of the parameter (a single item for arrays) */
  uint8_t Count;                                                /**< Number of elements in the array */
  uint16_t Min;                                                 /**< Minimal value for the parameter (possibly indirect) */
  uint16_t Max;                                                 /**< Maximal alue for the parameter (possibly indirect) */
  uint16_t Label;                                               /**< Offset of the label of the parameter in the string pool */
  uint16_t Uuid;                                                /**< BLE UUID / HTML class */
};

struct toc_blob_t;

struct toc_segment_descriptor_t
{
  uint32_t Offset;
};

extern const struct toc_segment_descriptor_t TocSegmentTable[];

/**
 * Get minimal and maximal values for the parameter
 */
void TocGetMinMax(const struct toc_blob_t *Ptr, const struct toc_t *Var, struct min_max_t *MinMax);

/**
 * @brief Gir "table of content" (TOC).
 *
 * Tabellen definerer de parameterene applikasjon kan kontrollere.
 * TOC aldri skrives noe i tabellen, så den kan ligge i flash minne.
 *
 * @param Ptr applikasjonen må settes (*TocPtr) pekeren på TOC-tabel
 */
extern void TocAppGetToc(struct toc_blob_t *Ptr);

extern int TocVarPreGet(int Id, int Index);
extern int TocVarPostGet(int Id, int Index);
extern int TocVarPreSet(int Id, int Index);
extern int TocVarPostSet(int Id, int Index);

/** @} */ /* toc */

#ifdef __cplusplus
}
#endif

#endif /* TOC_APP_API_H_INCLUDED */