File content as of revision 25:14c01b9fc04d:

/// @copyright
/// ========================================================================={{{
/// Copyright (c) 2013-2016 WizziLab                                           /
/// All rights reserved                                                        /
/// =========================================================================}}}
/// @endcopyright

//  =======================================================================
/// @file       modem_ref.h
/// @brief      Wizzilab Modem Reference Driver Implementation
///             Source code should be disclosable and easily portable to
///             any architecture.
//  =======================================================================

#ifndef __MODEM_REF_DRV_H__
#define __MODEM_REF_DRV_H__

#include "hal_types.h"

#include "alp_spec.h"
#include "alp_helpers.h"

// Stuff depending on implementation
#ifdef _ARCH_WIZZILAB_
    // Map debug features on Wizzilab's kernel
    #include "kal.h"
    #define L_API           (1 << 1)
    #define L_URC           (1 << 2)
    #define L_SER           (1 << 3)
    #define ASSERT(c,...)   kal_dbg_assert(c, ##__VA_ARGS__)
    #define DPRINT(l,...)   do {kal_dbg_cprintf(TLEV(7,l), ##__VA_ARGS__);} while(0)
    #define MALLOC(s)       kal_malloc(s)
    #define FREE(s)         kal_free(s)
#else
    // TODO Map on host architecture
#endif

// Maximum number of concurrent 'users'
#define MAX_USER_NB     (8)

// Depending on Host needs/capacities, choose variable-size buffer allocation style
#if 1 // Auto stack alloc
    #define MAX_CMD_BUFFER_SIZE             256
    #define ALLOC_BUFFER(_t,_b,_size)       _t _b[MAX_CMD_BUFFER_SIZE];
    //#define ALLOC_BUFFER(_t,_b,_size)     _t _b[_size]; // If VLA available...
    #define DEALLOC_BUFFER(_b)
#else // Dynamic alloc
    #define ALLOC_BUFFER(_t,_b,_size)       _t* _b = MALLOC(_size);
    #define DEALLOC_BUFFER(_b)              FREE(_b);
#endif

//======================================================================
// Modem Serial Link input/output functions
//==================================================================={{{
// ALP protocol is conveyed on serial link encapsulated in WizziCom (WC)
// packets.
// WC Serial protocol:
// +--------------+--------+--------+--------+---- - - - - - - - - - - --------+
// |     SYNC     |   LEN  |   SEQ  | FLOWID |             PAYLOAD             |
// +--------------+--------+--------+--------+---- - - - - - - - - - - --------+
// |    2 bytes   | 1 byte | 1 byte | 1 byte |            LEN bytes            |
// |<------------>|<------>|<------>|<------>|<--- - - - - - - - - - - ------->|
#define WC_SYNC_BYTE_0          0x01
#define WC_SYNC_BYTE_1          0x1F
#define WC_HEADER_SIZE          5

#define WC_SYNC0_OFFSET         0
#define WC_SYNC1_OFFSET         1
#define WC_LEN_OFFSET           2
#define WC_SEQ_OFFSET           3
#define WC_FLOWID_OFFSET        4

// Input:Serial-traffic coming from Modem must be packetized in WC chuncks
// before being sent to modem-driver through 'modem_input'.
// An example deserializer can be found in "wc_deserialized.c".
//======================================================================
// modem_input
//----------------------------------------------------------------------
/// @brief  Parse packets and handles calls to relevant callbacks.
/// @param  flowid      : WizziCom FlowID.
/// @param  payload     : pointer to payload buffer.
/// @param  size        : payload size in bytes.
//======================================================================
protected void modem_input(u8 flowid,u8* payload,u8 size);

// Output:Modem-driver sends data to Modem through calls to the 'send'
// function passed in 'modem_open'.
// 'send' must be provided by the host application.
//======================================================================
// fx_serial_send_t
//----------------------------------------------------------------------
/// @brief  Send concatenation of 2 buffers of given size over serial link.
/// @param  buffer1     : Pointer to the 1st data buffer to be sent
/// @param  size1       : Size in bytes of the 1st buffer to be sent
/// @param  buffer2     : Pointer to the 2nd data buffer to be sent
/// @param  size2       : Size in bytes of the 2nd buffer to be sent
/// @return               number of bytes sent.
/// @note                 either buffers can be of size zero.
/// @note                 buffer1 is used for WC header
/// @note                 buffer2 is used actual payload
//======================================================================
typedef int  (fx_serial_send_t)     (u8* buffer1, u8 size1,u8* buffer2, u8 size2);

//======================Low-Level-API================================}}}

//======================================================================
// High-level API that must be provided by the host application
//==================================================================={{{

//======================================================================
// fx_read_t
//----------------------------------------------------------------------
/// @brief  Called when ALP-Read is requested by the modem.
///         Function must perform required actions to fullfil the request
///         then should call 'respond_read' (or 'respond' in case of error)
/// @param  fid         : File ID
/// @param  offset      : Access Offset in bytes
/// @param  length      : Access Size in bytes
/// @param  id          : ID of the request
//======================================================================
typedef void (fx_read_t)            (u8 fid,u32 offset,u32 length, int id);

//======================================================================
// fx_write_t
//----------------------------------------------------------------------
/// @brief  Called when ALP-Write is requested by the modem.
///         Function must perform required actions to fullfil the request
///         then should call 'respond'
/// @param  fid         : File ID
/// @param  data        : Pointer to the destination data buffer
/// @param  offset      : Access Offset in bytes
/// @param  length      : Access Size in bytes
/// @param  id          : ID of the request
//======================================================================
typedef void (fx_write_t)           (u8 fid,void *data,u32 offset,u32 length, int id);

//======================================================================
// fx_read_fprop_t
//----------------------------------------------------------------------
/// @brief  Called when ALP-Read-file-properties is requested by the modem.
///         Function must perform required actions to fullfil the request
///         then should call 'respond_fprop' (or 'respond' in case of error)
/// @param  fid         : File ID
/// @param  id          : ID of the request
//======================================================================
typedef void (fx_read_fprop_t)      (u8 fid, int id);

//======================================================================
// fx_flush_t
//----------------------------------------------------------------------
/// @brief  Called when ALP-Flush is requested by the modem.
///         Function must perform required actions to fullfil the request
///         then should call 'respond'
/// @param  fid         : File ID
/// @param  id          : ID of the request
//======================================================================
typedef void (fx_flush_t)           (u8 fid, int id);

//======================================================================
// fx_delete_t
//----------------------------------------------------------------------
/// @brief  Called when ALP-Delete is requested by the modem.
///         Function must perform required actions to fullfil the request
///         then should call 'respond'
/// @param  fid         : File ID
/// @param  id          : ID of the request
//======================================================================
typedef void (fx_delete_t)          (u8 fid, int id);

//======================================================================
// fx_udata_t
//----------------------------------------------------------------------
/// @brief  Called when Unsollicited Data is received by the Modem (i.e.
///         peer notifications etc).
///         When available/requested, ISTATUS data corresponding to this
///         reception are given as well.
/// @param  fid         : File ID
/// @param  data        : Pointer to the data buffer
/// @param  offset      : File Offset in bytes
/// @param  length      : Data Size in bytes
/// @param  i_type      : ISTATUS type (0: not available)
/// @param  i_length    : ISTATUS length in bytes
/// @param  i_data      : ISTATUS data pointer
/// @param  id          : ID of the request
//======================================================================
typedef void (fx_udata_t)           (u8 fid,void *data,u32 offset,u32 length, u8 i_type, u8 i_length, u8* i_data);

//======================================================================
// fx_lqual_t
//----------------------------------------------------------------------
/// @brief  Called when LQUAL URC is generated by the modem.
///         LQUAL URC is setup by the user through 'modem_enable_urc'.
///         LQUAL gives percentage of successfully sent packets on a
///         particular interface (IFID).
/// @param  ifid        : Interface File ID from which LQUAL is issued
/// @param  per         : Packet Error Rate in %
//======================================================================
typedef void (fx_lqual_t)           (u8 ifid, int per);

//======================================================================
// fx_ldown_t
//----------------------------------------------------------------------
/// @brief  Called when LDOWN URC is generated by the modem.
///         LDOWN URC is setup by the user through 'modem_enable_urc'
///         LDOWN is generated for a particular interface (IFID) after
///         a (configurable) number of consecutive transmission have failed.
/// @param  ifid        : Interface File ID from which LDOWN is issued
//======================================================================
typedef void (fx_ldown_t)           (u8 ifid);

//======================================================================
// fx_reset_t
//----------------------------------------------------------------------
/// @brief  Called when RESET URC is generated by the modem.
///         LDOWN URC is setup by the user through 'modem_enable_urc'
/// @param  ifid        : Interface File ID from which LDOWN is issued
//======================================================================
typedef void (fx_reset_t)           (void);

//======================================================================
// fx_boot_t
//----------------------------------------------------------------------
/// @brief  Called when BOOT URC is generated by the modem.
/// @param  cause       : Cause of the boot 'H':Pin/Hardware reset
///                                         'P':POR reset
///                                         'S':Software reset
///                                         'L':Low-power reset
///                                         'W':Watchdog reset
/// @param  nb_boot     : Number of boots since last POR
//======================================================================
typedef void (fx_boot_t)            (u8 cause, u16 nb_boot);

//======================================================================
// fx_boot_t
//----------------------------------------------------------------------
/// @brief  Called when BUSY URC is generated by the modem.
/// @param  busy       : 0 if not busy, else busy
//======================================================================
typedef void (fx_busy_t)            (u8 busy);

// Set of functions passed together at modem openning
typedef struct {
    // ALP File 'Action' callbacks
    fx_read_t*          read;
    fx_write_t*         write;
    fx_read_fprop_t*    read_fprop;
    fx_flush_t*         flush;
    fx_delete_t*        remove;
    // 'URC' callbacks
    fx_udata_t*         udata;
    fx_lqual_t*         lqual;
    fx_ldown_t*         ldown;
    fx_reset_t*         reset;
    fx_boot_t*          boot;
    fx_busy_t*          busy;
} modem_callbacks_t;
//======================High-Level-API===============================}}}

//======================================================================
// action_callback_t
//----------------------------------------------------------------------
/// @brief  Type of function called on response(s) generated by an
///         'action' function. Different functions of this kind can be
///         associated to different IDs through 'get_id'.
///         'Action' function are subsequently called with relevant ID.
/// @param  terminal    : '1' at the last call for this ID, '0' otherwise
/// @param  err         : ALP Error code
/// @param  id          : ID of the request
//======================================================================
typedef void (action_callback_t)  (u8 terminal, s8 err, u8 id);

//======================================================================
// modem_open
//----------------------------------------------------------------------
/// @brief  Open Wizzilab Modem Driver
/// @param  send        : User function implementing serial output.
/// @param  callbacks   : Set of functions called by the driver upon
///                       reception of commands
/// @return 0
//======================================================================
public void modem_open(fx_serial_send_t* send,modem_callbacks_t* callbacks);
public void modem_close(void);

//======================================================================
// modem_get_id
//----------------------------------------------------------------------
/// @brief  Request an ID to perform modem operations
/// @param  cb          : Function called on responses generated for
///                       this ID.
/// @return Positive ID value, -1 if no more IDs available.
//======================================================================
public int modem_get_id(action_callback_t* cb);

//======================================================================
// modem_free_id
//----------------------------------------------------------------------
/// @brief  Release an ID
/// @param  id          : ID to release.
/// @return ID value, -1 if ID was not in use.
//======================================================================
public int modem_free_id(u8 id);

//======================================================================
// "Action" functions performing requests to the modem
//==================================================================={{{

//======================================================================
// modem_read_file
//----------------------------------------------------------------------
/// @brief  Read a file on Modem
/// @param  fid         : File ID
/// @param  data        : Pointer to the destination data buffer
/// @param  offset      : Access Offset in bytes
/// @param  length      : Access Size in bytes
/// @param  id          : User ID
//======================================================================
public void modem_read_file(u8 fid, void *data, u32 offset, u32 length, u8 id);

//======================================================================
// modem_read_fprop
//----------------------------------------------------------------------
/// @brief  Read a file-properties on Modem
/// @param  fid         : File ID
/// @param  data        : Pointer to the destination data buffer
/// @param  id          : User ID
//======================================================================
public void modem_read_fprop(u8 fid, alp_file_header_t* data, u8 id);

//======================================================================
// modem_read_fprop
//----------------------------------------------------------------------
/// @brief  Read a file-properties on Modem with ROOT privileges
/// @param  fid         : File ID
/// @param  data        : Pointer to the destination data buffer
/// @param  root_key    : Pointer to the ROOT key
/// @param  id          : User ID
//======================================================================
public void modem_read_fprop_root(u8 fid, alp_file_header_t* data, u8* root_key, u8 id);

//======================================================================
// modem_write_fprop
//----------------------------------------------------------------------
/// @brief  Write a file-properties on Modem
/// @param  fid         : File ID
/// @param  data        : Pointer to the header data
/// @param  id          : User ID
//======================================================================
public void modem_read_fprop(u8 fid, alp_file_header_t* data, u8 id);

//======================================================================
// modem_write_fprop_root
//----------------------------------------------------------------------
/// @brief  Write a file-properties on Modem with ROOT privileges
/// @param  fid         : File ID
/// @param  data        : Pointer to the header data
/// @param  root_key    : Pointer to the ROOT key
/// @param  id          : User ID
//======================================================================
public void modem_read_fprop_root(u8 fid, alp_file_header_t* data, u8* root_key, u8 id);

//======================================================================
// modem_write_file
//----------------------------------------------------------------------
/// @brief  Write a file on Modem
/// @note   Writing can trigger a 'notification' depending on file properties.
/// @param  fid         : File ID
/// @param  data        : Pointer to the source data buffer
/// @param  offset      : Access Offset in bytes
/// @param  length      : Access Size in bytes
/// @param  id          : User ID
//======================================================================
public void modem_write_file(u8 fid, void *data, u32 offset, u32 length, u8 id);

//======================================================================
// modem_write_file_root
//----------------------------------------------------------------------
/// @brief  Write a file on Modem with ROOT privileges
/// @note   Writing can trigger a 'notification' depending on file properties.
/// @param  fid         : File ID
/// @param  data        : Pointer to the source data buffer
/// @param  offset      : Access Offset in bytes
/// @param  length      : Access Size in bytes
/// @param  root_key    : Pointer to the ROOT key
/// @param  id          : User ID
//======================================================================
public void modem_write_file_root(u8 fid, void *data, u32 offset, u32 length, u8* root_key, u8 id);

//======================================================================
// modem_flush_file
//----------------------------------------------------------------------
/// @brief  Flush a file on Modem
/// @param  fid         : File ID
/// @param  id          : User ID
//======================================================================
public void modem_flush_file(u8 fid, u8 id);

//======================================================================
// modem_write_file_root
//----------------------------------------------------------------------
/// @brief  Flush a file on Modem with ROOT privileges
/// @param  fid         : File ID
/// @param  root_key    : Pointer to the ROOT key
/// @param  id          : User ID
//======================================================================
public void modem_flush_file_root(u8 fid, u8* root_key, u8 id);

//======================================================================
// modem_declare_file
//----------------------------------------------------------------------
/// @brief  Declare a local file to the Modem. Once declared, the file
///         becomes virtually part of Modem's file-system and can:
///         - be remotely accessed (depending on its permissions)
///         - be "Notified" through notify_file use
/// @note   The file must exist locally.
/// @note   Modem will access the file when needed using ALP commands.
/// @param  fid         : File ID
/// @param  hdr         : ALP File Header.
/// @param  local       : File is local.
/// @param  id          : User ID
//======================================================================
public void modem_declare_file(u8 fid, alp_file_header_t* hdr, u8 local, u8 id);

//======================================================================
// modem_create_file
//----------------------------------------------------------------------
/// @brief  Creates a file on the Modem.
/// @param  fid         : File ID
/// @param  hdr         : ALP File Header.
/// @param  id          : User ID
//======================================================================
public void modem_create_file(u8 fid, alp_file_header_t* hdr, u8 id);

//======================================================================
// modem_delete_file
//----------------------------------------------------------------------
/// @brief  Deletes a file on the Modem.
/// @param  fid         : File ID
/// @param  id          : User ID
//======================================================================
public void modem_delete_file(u8 fid, u8 id);

//======================================================================
// modem_notify_file
//----------------------------------------------------------------------
/// @brief  "Notify" a local file using its D7AActP properties.
/// @note   The file must exist locally and must have been 'declared'.
/// @param  fid         : File ID
/// @param  offset      : Access Offset in bytes
/// @param  length      : Access Size in bytes
/// @param  id          : User ID
//======================================================================
public void modem_notify_file(u8 fid, u32 offset, u32 length, u8 id);

//======================================================================
// modem_alp_raw
//----------------------------------------------------------------------
/// @brief  Execute specific ALP payload on Modem.
/// @param  payload     : pointer to ALP Payload to be executed on Modem
/// @param  length      : ALP Payload size
/// @param  id          : User ID
//======================================================================
public void modem_send_raw_alp(u8* payload, u32 length, u8 id);

public void modem_send_file_content(u8* itf, u8 itf_length, void *istatus, u8 fid, void *data,u32 offset,u32 length, u8 id);

public void modem_remote_read_file(u8* itf, u8 itf_length, void *istatus , u8 fid, void *data, u32 offset, u32 length, u8 id);

public void modem_remote_write_file(u8* itf, u8 itf_length, void *istatus , u8 fid, void *data, u32 offset, u32 length, u8 id);

public void modem_enable_urc(u8 type, u8 ifid, u8 val, u8 enable, u8 id);

public void modem_activate_itf(u8 type, u8 nb_dev, u8 ifid, u8 flags, u8 enable, u8 id);

//==========================Action===================================}}}

//======================================================================
// "Response" functions to be called-back on requests from the modem
//==================================================================={{{
public void modem_respond(u8 action, s8 status, int id);
public void modem_respond_fprop(u8 fid, u8* hdr, int id);
public void modem_respond_read(u8 fid,void *data,u32 offset,u32 length, int id);
//==========================Response=================================}}}


//=======================================================================
// Modem File IDs are mapped from 64 to 127
// These files are mandatory when building an application that
// uses Wizzilab's D7A Stack, so it will be included in all "Modem"
// applications.
//=======================================================================
// IDs
#define FID_MODEM_REV                      2 // XXX Match D7A one.
#define FID_HOST_REV                      65
#define FID_WM_SCRATCH                    66
#define FID_WM_CFG                        68
#define FID_WM_HWCFG                      69
#define FID_HST_RMTCTRL                   70
#define FID_MODEM_LED_CFG                 71
#define FID_CUP_CFG_BCAST                125
#define FID_CUP_CFG                      126
#define FID_CUP_CODE                     127
#define FID_APP_CUP_CFG_BCAST            252 // XXX Normalized APP CUP Files
#define FID_APP_CUP_CFG                  253 // XXX Normalized APP CUP Files
#define FID_APP_CUP_CODE                 254 //

// TODO: TBD
// Action files
#define FID_ACTP_RPT_FULL                100
#define FID_ACTP_RPT_PART                101
// Interface files
#define FID_D7A_ITF0                     108
#define FID_D7A_ITF1                     109
#define FID_D7A_ITF2                     110
#define FID_D7A_ITF3                     111
#define FID_D7A_ITF4                     112
#define FID_D7A_ITF5                     113
// Create "User" readable IFIDs
// XXX Keep sync'ed to ITF definitions...
#define IFID_RARE_SINGLE_CHECK  FID_D7A_ITF0
#define IFID_SINGLE_CHECK       FID_D7A_ITF1
#define IFID_REPORT             FID_D7A_ITF2
#define IFID_REPORT_CHECKED     FID_D7A_ITF3
#define IFID_PING               FID_D7A_ITF4
#define IFID_BLINK              FID_D7A_ITF5
// TODO LORAWAN "ITFs"
#define FID_LWAN_ITF0                     98
#define FID_LWAN_ITF1                     99

#endif