modem_ref.h

00001 /// @copyright
00002 /// ========================================================================={{{
00003 /// Copyright (c) 2013-2016 WizziLab                                           /
00004 /// All rights reserved                                                        /
00005 /// =========================================================================}}}
00006 /// @endcopyright
00007 
00008 //  =======================================================================
00009 /// @file       modem_ref.h
00010 /// @brief      Wizzilab Modem Reference Driver Implementation
00011 ///             Source code should be disclosable and easily portable to
00012 ///             any architecture.
00013 //  =======================================================================
00014 
00015 #ifndef __MODEM_REF_H__
00016 #define __MODEM_REF_H__
00017 
00018 #include "mbed.h"
00019 #include "hal_types.h"
00020 
00021 #include "alp_spec.h"
00022 #include "alp_helpers.h"
00023 #include "alp_payload.h"
00024 
00025 // Stuff depending on implementation
00026 #ifdef _ARCH_WIZZILAB_
00027     // Map debug features on Wizzilab's kernel
00028     #include "kal.h"
00029     #define L_API           (1 << 1)
00030     #define L_URC           (1 << 2)
00031     #define L_SER           (1 << 3)
00032     #define ASSERT(c,...)   kal_dbg_assert(c, ##__VA_ARGS__)
00033     #define DPRINT(l,...)   do {kal_dbg_cprintf(TLEV(7,l), ##__VA_ARGS__);} while(0)
00034     #define MALLOC(s)       kal_malloc(s)
00035     #define FREE(s)         kal_free(s)
00036 #else
00037     // TODO Map on host architecture
00038 #endif
00039 
00040 // Maximum number of concurrent 'users'
00041 #define MAX_USER_NB     (8)
00042 
00043 // Depending on Host needs/capacities, choose variable-size buffer allocation style
00044 #if 1 // Auto stack alloc
00045     #define MAX_CMD_BUFFER_SIZE             256
00046     #define ALLOC_BUFFER(_t,_b,_size)       _t _b[MAX_CMD_BUFFER_SIZE];
00047     //#define ALLOC_BUFFER(_t,_b,_size)     _t _b[_size]; // If VLA available...
00048     #define DEALLOC_BUFFER(_b)
00049 #else // Dynamic alloc
00050     #define ALLOC_BUFFER(_t,_b,_size)       _t* _b = MALLOC(_size);
00051     #define DEALLOC_BUFFER(_b)              FREE(_b);
00052 #endif
00053 
00054 //======================================================================
00055 // Modem Serial Link input/output functions
00056 //==================================================================={{{
00057 // ALP protocol is conveyed on serial link encapsulated in WizziCom (WC)
00058 // packets.
00059 // WC Serial protocol:
00060 // +--------------+--------+--------+--------+---- - - - - - - - - - - --------+
00061 // |     SYNC     |   LEN  |   SEQ  | FLOWID |             PAYLOAD             |
00062 // +--------------+--------+--------+--------+---- - - - - - - - - - - --------+
00063 // |    2 bytes   | 1 byte | 1 byte | 1 byte |            LEN bytes            |
00064 // |<------------>|<------>|<------>|<------>|<--- - - - - - - - - - - ------->|
00065 #define WC_SYNC_BYTE_0          0x01
00066 #define WC_SYNC_BYTE_1          0x1F
00067 #define WC_HEADER_SIZE          5
00068 
00069 #define WC_SYNC0_OFFSET         0
00070 #define WC_SYNC1_OFFSET         1
00071 #define WC_LEN_OFFSET           2
00072 #define WC_SEQ_OFFSET           3
00073 #define WC_FLOWID_OFFSET        4
00074 
00075 // =======================================================================
00076 // wm_cfg_t
00077 // -----------------------------------------------------------------------
00078 /// Modem Configuration
00079 // ===================================================================={{{
00080 TYPEDEF_STRUCT_PACKED
00081 {
00082     /// Automatic openning of D7A stack
00083     u8  autostart_d7a;
00084     /// Automatic 'Join' of LoRaWAN stack
00085     u8  autostart_lwan;
00086     /// Automatic procedure start time (sec)
00087     u16 autostart_delay_s;
00088     /// Debug COM port number (N/A:KAL_COM_NULL)
00089     u8  dbg_com;
00090 } wm_cfg_t;
00091 //}}}
00092 
00093 // Input:Serial-traffic coming from Modem must be packetized in WC chuncks
00094 // before being sent to modem-driver through 'modem_input'.
00095 // An example deserializer can be found in "wc_deserialized.c".
00096 //======================================================================
00097 // modem_ref_input
00098 //----------------------------------------------------------------------
00099 /// @brief  Parse packets and handles calls to relevant callbacks.
00100 /// @param  flowid      : WizziCom FlowID.
00101 /// @param  payload     : pointer to payload buffer.
00102 /// @param  size        : payload size in bytes.
00103 //======================================================================
00104 void modem_ref_input(u8 flowid, u8* payload, u8 size);
00105 
00106 // Output:Modem-driver sends data to Modem through calls to the 'send'
00107 // function passed in 'modem_ref_open'.
00108 // 'send' must be provided by the host application.
00109 //======================================================================
00110 // fx_serial_send_t
00111 //----------------------------------------------------------------------
00112 /// @brief  Send concatenation of 2 buffers of given size over serial link.
00113 /// @param  buffer1     : Pointer to the 1st data buffer to be sent
00114 /// @param  size1       : Size in bytes of the 1st buffer to be sent
00115 /// @param  buffer2     : Pointer to the 2nd data buffer to be sent
00116 /// @param  size2       : Size in bytes of the 2nd buffer to be sent
00117 /// @return               number of bytes sent.
00118 /// @note                 either buffers can be of size zero.
00119 /// @note                 buffer1 is used for WC header
00120 /// @note                 buffer2 is used actual payload
00121 //======================================================================
00122 typedef int  (fx_serial_send_t)     (u8 type, u8* buffer2, u8 size2);
00123 
00124 //======================Low-Level-API================================}}}
00125 
00126 //======================================================================
00127 // High-level API that must be provided by the host application
00128 //==================================================================={{{
00129 
00130 //======================================================================
00131 // fx_read_t
00132 //----------------------------------------------------------------------
00133 /// @brief  Called when ALP-Read is requested by the modem.
00134 ///         Function must perform required actions to fullfil the request
00135 ///         then should call 'respond_read' (or 'respond' in case of error)
00136 /// @param  fid         : File ID
00137 /// @param  offset      : Access Offset in bytes
00138 /// @param  length      : Access Size in bytes
00139 /// @param  id          : ID of the request
00140 //======================================================================
00141 typedef void (fx_read_t)            (u8 action, u8 fid, u32 offset, u32 length, int id);
00142 
00143 //======================================================================
00144 // fx_write_t
00145 //----------------------------------------------------------------------
00146 /// @brief  Called when ALP-Write is requested by the modem.
00147 ///         Function must perform required actions to fullfil the request
00148 ///         then should call 'respond'
00149 /// @param  fid         : File ID
00150 /// @param  data        : Pointer to the destination data buffer
00151 /// @param  offset      : Access Offset in bytes
00152 /// @param  length      : Access Size in bytes
00153 /// @param  id          : ID of the request
00154 //======================================================================
00155 typedef void (fx_write_t)           (u8 action, u8 fid, void* data, u32 offset, u32 length, int id);
00156 
00157 //======================================================================
00158 // fx_read_fprop_t
00159 //----------------------------------------------------------------------
00160 /// @brief  Called when ALP-Read-file-properties is requested by the modem.
00161 ///         Function must perform required actions to fullfil the request
00162 ///         then should call 'respond_fprop' (or 'respond' in case of error)
00163 /// @param  fid         : File ID
00164 /// @param  id          : ID of the request
00165 //======================================================================
00166 typedef void (fx_read_fprop_t)      (u8 action, u8 fid, int id);
00167 
00168 //======================================================================
00169 // fx_flush_t
00170 //----------------------------------------------------------------------
00171 /// @brief  Called when ALP-Flush is requested by the modem.
00172 ///         Function must perform required actions to fullfil the request
00173 ///         then should call 'respond'
00174 /// @param  fid         : File ID
00175 /// @param  id          : ID of the request
00176 //======================================================================
00177 typedef void (fx_flush_t)           (u8 action, u8 fid, int id);
00178 
00179 //======================================================================
00180 // fx_delete_t
00181 //----------------------------------------------------------------------
00182 /// @brief  Called when ALP-Delete is requested by the modem.
00183 ///         Function must perform required actions to fullfil the request
00184 ///         then should call 'respond'
00185 /// @param  fid         : File ID
00186 /// @param  id          : ID of the request
00187 //======================================================================
00188 typedef void (fx_delete_t)          (u8 action, u8 fid, int id);
00189 
00190 //======================================================================
00191 // fx_udata_t
00192 //----------------------------------------------------------------------
00193 /// @brief  Called when Unsollicited Data is received by the Modem (i.e.
00194 ///         peer notifications etc).
00195 /// @param  data        : Pointer to the data buffer
00196 /// @param  length      : Data Size in bytes
00197 //======================================================================
00198 typedef void (fx_udata_t)           (alp_payload_t*);
00199 
00200 //======================================================================
00201 // fx_reset_t
00202 //----------------------------------------------------------------------
00203 /// @brief  Called when RESET URC is generated by the modem.
00204 ///         LDOWN URC is setup by the user through 'modem_ref_enable_urc'
00205 /// @param  ifid        : Interface File ID from which LDOWN is issued
00206 //======================================================================
00207 typedef void (fx_reset_t)           (void);
00208 
00209 //======================================================================
00210 // fx_boot_t
00211 //----------------------------------------------------------------------
00212 /// @brief  Called when BOOT URC is generated by the modem.
00213 /// @param  cause       : Cause of the boot 'H':Pin/Hardware reset
00214 ///                                         'P':POR reset
00215 ///                                         'S':Software reset
00216 ///                                         'L':Low-power reset
00217 ///                                         'W':Watchdog reset
00218 /// @param  nb_boot     : Number of boots since last POR
00219 //======================================================================
00220 typedef void (fx_boot_t)            (u8 cause, u16 nb_boot);
00221 
00222 // Set of functions passed together at modem openning
00223 typedef struct {
00224     // ALP File 'Action' callbacks
00225     fx_read_t*          read;
00226     fx_write_t*         write;
00227     fx_read_fprop_t*    read_fprop;
00228     fx_flush_t*         flush;
00229     fx_delete_t*        remove;
00230     // 'URC' callbacks
00231     fx_udata_t*         udata;
00232     fx_reset_t*         reset;
00233     fx_boot_t*          boot;
00234 } modem_ref_callbacks_t;
00235 
00236 //======================High-Level-API===============================}}}
00237 
00238 //======================================================================
00239 // action_callback_t
00240 //----------------------------------------------------------------------
00241 /// @brief  Type of function called on response(s) generated by an
00242 ///         'action' function. Different functions of this kind can be
00243 ///         associated to different IDs through 'get_id'.
00244 ///         'Action' function are subsequently called with relevant ID.
00245 /// @param  terminal    : '1' at the last call for this ID, '0' otherwise
00246 /// @param  err         : ALP Error code
00247 /// @param  id          : ID of the request
00248 //======================================================================
00249 typedef void (action_callback_t)  (u8 id);
00250 
00251 //======================================================================
00252 // modem_ref_open
00253 //----------------------------------------------------------------------
00254 /// @brief  Open Wizzilab Modem Driver
00255 /// @param  send        : User function implementing serial output.
00256 /// @param  callbacks   : Set of functions called by the driver upon
00257 ///                       reception of commands
00258 /// @return 0
00259 //======================================================================
00260 void modem_ref_open(fx_serial_send_t* send, modem_ref_callbacks_t* callbacks);
00261 void modem_ref_close(void);
00262 void modem_ref_set_boot_cb(fx_boot_t* boot_cb);
00263 
00264 //======================================================================
00265 // modem_ref_get_id
00266 //----------------------------------------------------------------------
00267 /// @brief  Request an ID to perform modem operations
00268 /// @param  cb          : Function called on responses generated for
00269 ///                       this ID.
00270 /// @return Positive ID value, -1 if no more IDs available.
00271 //======================================================================
00272 int modem_ref_get_id(action_callback_t* cb);
00273 
00274 //======================================================================
00275 // modem_ref_free_id
00276 //----------------------------------------------------------------------
00277 /// @brief  Release an ID
00278 /// @param  id          : ID to release.
00279 /// @return ID value, -1 if ID was not in use.
00280 //======================================================================
00281 int modem_ref_free_id(u8 id);
00282 
00283 //======================================================================
00284 // "Action" functions performing requests to the modem
00285 //==================================================================={{{
00286 
00287 void modem_ref_alp(void* itf, alp_payload_t* alp_user, alp_payload_t** alp_rsp, int id);
00288 
00289 //==========================Action===================================}}}
00290 
00291 //======================================================================
00292 // "Response" functions to be called-back on requests from the modem
00293 //==================================================================={{{
00294 void modem_ref_respond(u8 action, s8 status, int id);
00295 void modem_ref_respond_fprop(u8 fid, alp_file_header_t* hdr, int id);
00296 void modem_ref_respond_read(u8 fid, void* data, u32 offset, u32 length, int id);
00297 //==========================Response=================================}}}
00298 
00299 
00300 //=======================================================================
00301 // Modem File IDs are mapped from 64 to 127
00302 // These files are mandatory when building an application that
00303 // uses Wizzilab's D7A Stack, so it will be included in all "Modem"
00304 // applications.
00305 //=======================================================================
00306 // Modem Config/Status
00307 #define FID_WM_REV                      2 // aka D7A_FID_FIRMWARE_VERSION
00308 #define FID_WM_RFU_64                  64
00309 #define FID_HOST_REV                   65
00310 #define FID_WM_SCRATCH                 66
00311 #define FID_WM_STATUS                  67
00312 #define FID_WM_CFG                     68
00313 #define FID_WM_HWCFG                   69
00314 #define FID_WM_CTRL                    70
00315 #define FID_WM_LED_CFG                 71
00316 #define FID_WM_DEBUG                   72
00317 #define FID_WM_POWER_STATUS            73 // For GW power supervisor reporting
00318 #define FID_WM_TLEV                    74 // Trace levels
00319 #define FID_WM_USER_STORAGE            75 // Big generic file for APPs to store data since we can't create permanent files on NRF52.
00320 #define FID_WM_INVT                    76 // Inventory commands
00321 #define FID_WM_RFU_77                  77
00322 #define FID_WM_RFU_78                  78
00323 #define FID_WM_RFU_79                  79
00324 
00325 // LORAWAN Stack
00326 #define FID_LWAN_CFG                   96
00327 #define FID_LWAN_NLS                   97
00328 #define FID_LWAN_ITF                   98 // XXX useless
00329 #define FID_LWAN_STATUS                99
00330 
00331 // Action files
00332 #define FID_ACTP_RPT_FULL             100
00333 #define FID_ACTP_RPT_PART             101
00334 
00335 // Unallocated FIDs
00336 #define FID_UNUSED_102                102
00337 #define FID_UNUSED_103                103
00338 #define FID_UNUSED_104                104
00339 #define FID_UNUSED_105                105
00340 #define FID_UNUSED_106                106
00341 #define FID_UNUSED_107                107
00342 #define FID_UNUSED_108                108
00343 #define FID_UNUSED_109                109
00344 
00345 #define IFID_REPORT                   110
00346 
00347 // Unallocated FIDs
00348 #define FID_UNUSED_111                111
00349 #define FID_UNUSED_112                112
00350 #define FID_UNUSED_113                113
00351 #define FID_UNUSED_114                114
00352 #define FID_UNUSED_115                115
00353 #define FID_UNUSED_116                116
00354 #define FID_UNUSED_117                117
00355 #define FID_UNUSED_118                118
00356 #define FID_UNUSED_119                119
00357 #define FID_UNUSED_120                120
00358 #define FID_UNUSED_121                121
00359 #define FID_UNUSED_122                122
00360 #define FID_UNUSED_123                123
00361 
00362 // Modem Security protocols
00363 #define FID_WM_CHALLENGE              124
00364 
00365 // Modem CUP
00366 #define FID_CUP_CFG_BCAST             125
00367 #define FID_CUP_CFG                   126
00368 #define FID_CUP_CODE                  127
00369 
00370 // HST CUP
00371 #define FID_APP_CUP_CFG_BCAST         252
00372 #define FID_APP_CUP_CFG               253
00373 #define FID_APP_CUP_CODE              254
00374 
00375 // System status
00376 #define FID_SYS_STATUS                255
00377 
00378 #endif
00379 
00380 // vim:fdm=marker:fdc=2