WizziLab / modem_ref_v5_3_217

Dependents:   modem_ref_helper_for_v5_3_217

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers d7a_1x.h Source File

d7a_1x.h

Go to the documentation of this file.
00001 /// ======================================================================
00002 ///
00003 /// Copyright (C) 20XX WizziLab
00004 /// All Rights Reserved
00005 ///
00006 /// =======================================================================
00007 ///
00008 /// @file           d7a_1x.h
00009 /// @brief          D7A 1.x API (below ALP and FS)
00010 /// @defgroup D7A   D7A 1.x API
00011 /// @{
00012 /// =======================================================================
00013 
00014 #ifndef __D7A_1X_H__
00015 #define __D7A_1X_H__
00016 
00017 #include "kal_codec.h"
00018 
00019 /// @ingroup D7A_API
00020 /// @defgroup D7A_API_STR       D7A API (all except APL)
00021 /// @{
00022 
00023 // =======================================================================
00024 // d7a_buf_t
00025 // -----------------------------------------------------------------------
00026 /// Generic D7A buffer structure
00027 // =======================================================================
00028 typedef struct
00029 {
00030     /// Buffer payload length
00031     u8  len;
00032     /// Payload start offset (Result length)
00033     u8  pof;
00034     /// Shadow buffer payload length (snap/restore)
00035     u8  shadow_len;
00036     /// Shadow Payload start offset (snap/restore)
00037     u8  shadow_pof;
00038     /// Data
00039     u8  data[1];
00040 
00041 } d7a_buf_t;
00042 
00043 //======================================================================
00044 //  D7A_BUF_R_PTR
00045 //----------------------------------------------------------------------
00046 /// @brief Pointer to the metadata (result)
00047 /// @param  buf         d7a_buf_t buffer
00048 //======================================================================
00049 #define D7A_BUF_R_PTR(buf)              (void*)(((d7a_buf_t*)(buf))->data)
00050 
00051 //======================================================================
00052 //  D7A_BUF_P_PTR
00053 //----------------------------------------------------------------------
00054 /// @brief Pointer to the payload
00055 /// @param  buf         d7a_buf_t buffer
00056 //======================================================================
00057 #define D7A_BUF_P_PTR(buf)              (void*)(((d7a_buf_t*)(buf))->data + ((d7a_buf_t*)(buf))->pof)
00058 
00059 //======================================================================
00060 //  D7A_BUF_P_LEN
00061 //----------------------------------------------------------------------
00062 /// @brief Get the payload length
00063 /// @param  buf         d7a_buf_t buffer
00064 //======================================================================
00065 #define D7A_BUF_P_LEN(buf)              (((d7a_buf_t*)(buf))->len)
00066 
00067 //======================================================================
00068 //  Special session identifiers
00069 //======================================================================
00070 #define D7A_RESP_ID                     (0xff)
00071 
00072 // =======================================================================
00073 // d7a_id_t
00074 // -----------------------------------------------------------------------
00075 /// Identifier types enumerator
00076 // =======================================================================
00077 typedef enum
00078 {
00079     /// skipped Unicast identifier
00080     D7A_ID_VOID = 0,
00081     /// Void identifier (broadcast)
00082     /// with indication of number of reached devices
00083     D7A_ID_NBID = 0,
00084     /// Void identifier (broadcast)
00085     D7A_ID_NOID = 1,
00086     /// Unique Identifier
00087     D7A_ID_UID  = 2,
00088     /// Virtual identifier
00089     D7A_ID_VID  = 3,
00090 
00091 } d7a_id_t;
00092 
00093 // =======================================================================
00094 // d7a_nls_t
00095 // -----------------------------------------------------------------------
00096 /// Enumerator of the NWL security modes
00097 // =======================================================================
00098 typedef enum
00099 {
00100     /// No security enabled
00101     D7A_NLS_NO = 0,
00102     /// Encryption only, Counter Mode
00103     D7A_NLS_AES_CTR,
00104     /// No encryption, Authentication, Cipher-block chaining with 128 bit MAC
00105     D7A_NLS_AES_CBC_MAC_128,
00106     /// No encryption, Authentication, Cipher-block chaining with 64 bit MAC
00107     D7A_NLS_AES_CBC_MAC_64,
00108     /// No encryption, Authentication, Cipher-block chaining with 32 bit MAC
00109     D7A_NLS_AES_CBC_MAC_32,
00110     /// Authentication with CBC-MAC-128 and Encryption with Counter Mode
00111     D7A_NLS_AES_CCM_128,
00112     /// Authentication with CBC-MAC-128 and Encryption with Counter Mode
00113     D7A_NLS_AES_CCM_64,
00114     /// Authentication with CBC-MAC-128 and Encryption with Counter Mode
00115     D7A_NLS_AES_CCM_32,
00116     /// QTY
00117     D7A_NLS_QTY
00118 
00119 } d7a_nls_t;
00120 
00121 //======================================================================
00122 // ID manipulation macros
00123 //======================================================================
00124 
00125 /// Unique ID length
00126 #define D7A_UID_LEN                     (8)
00127 /// Virtual ID length
00128 #define D7A_VID_LEN                     (2)
00129 /// No identifier length
00130 #define D7A_NOID_LEN                    (0)
00131 /// Void (skipped) identifier length
00132 #define D7A_VOID_LEN                    (0)
00133 /// Void ID length with reached
00134 /// devices number indicaiton
00135 #define D7A_NBID_LEN                    (1)
00136 
00137 /// Address is unicast (VID or UID)
00138 #define D7A_ID_IS_UCAST(ctrl)           ((D7A_ID_UID == (ctrl).bf.idf) || (D7A_ID_VID == (ctrl).bf.idf))
00139 
00140 /// Address is broadcast (no identifier)
00141 #define D7A_ID_IS_BCAST(ctrl)           ((D7A_ID_NOID == (ctrl).bf.idf) || (D7A_ID_NBID == (ctrl).bf.idf))
00142 
00143 /// Length of the Addressee identifier
00144 #define D7A_ID_LEN(ctrl)                (((ctrl).bf.idf == D7A_ID_VID) ?    D7A_VID_LEN : \
00145                                         ((ctrl).bf.idf == D7A_ID_UID) ?     D7A_UID_LEN : \
00146                                         ((ctrl).bf.idf == D7A_ID_NBID) ?    D7A_NBID_LEN : \
00147                                                                             D7A_NOID_LEN)
00148 
00149 /// Length of the DLL identifier
00150 #define D7A_DLL_ID_LEN(ctrl)            (((ctrl).bf.idf == D7A_ID_VID) ?    D7A_VID_LEN : \
00151                                         ((ctrl).bf.idf == D7A_ID_UID) ?     D7A_UID_LEN : \
00152                                         ((ctrl).bf.idf == D7A_ID_VOID) ?    D7A_VOID_LEN : \
00153                                                                             D7A_NOID_LEN)
00154 /// length of the Addressee
00155 #define D7A_ADDR_LEN(ctrl)              (D7A_ID_LEN(ctrl) + sizeof(d7a_addressee_t) - D7A_UID_LEN)
00156 
00157 //======================================================================
00158 // Compressed format conversions to use in declarations
00159 //======================================================================
00160 
00161 /// Decode e/m
00162 #define D7A_CTF_D(e,m)                  ((1 << (2*(e))) * (m))
00163 
00164 /// Encode e/m
00165 #define D7A_CTF_E(e,v)                  ((((e) & 0x7) << 5) | (KAL_DIV_INT((v), D7A_CTF_D(e,1)) & 0x1f))
00166 
00167 /// Encode unit to CTF
00168 #define D7A_CTF_ENCODE(v)               (((v) < D7A_CTF_D(0,32)) ? D7A_CTF_E(0,(v)) : \
00169                                         ((v) < D7A_CTF_D(1,32)) ? D7A_CTF_E(1,(v)) : \
00170                                         ((v) < D7A_CTF_D(2,32)) ? D7A_CTF_E(2,(v)) : \
00171                                         ((v) < D7A_CTF_D(3,32)) ? D7A_CTF_E(3,(v)) : \
00172                                         ((v) < D7A_CTF_D(4,32)) ? D7A_CTF_E(4,(v)) : \
00173                                         ((v) < D7A_CTF_D(5,32)) ? D7A_CTF_E(5,(v)) : \
00174                                         ((v) < D7A_CTF_D(6,32)) ? D7A_CTF_E(6,(v)) : \
00175                                         ((v) < D7A_CTF_D(7,32)) ? D7A_CTF_E(7,(v)) : \
00176                                         0xff)
00177 
00178 /// Decode from CTF to unit
00179 #define D7A_CTF_DECODE(ctf)             D7A_CTF_D((ctf).bf.exp,(ctf).bf.mant)
00180 
00181 // =======================================================================
00182 // d7a_addressee_ctrl_t
00183 // -----------------------------------------------------------------------
00184 /// Bitfield structure of the Addressee control byte
00185 // =======================================================================
00186 typedef union
00187 {
00188     // bit access fields
00189     struct {
00190         /// Network security method
00191         u8 nls      : 4;
00192         /// ID type
00193         u8 idf      : 2;
00194         /// RFU
00195         u8 rfu_6    : 1;
00196         u8 rfu_7    : 1;
00197     } bf;
00198 
00199     // byte access
00200     u8 byte;
00201 
00202 } d7a_addressee_ctrl_t;
00203 
00204 // =======================================================================
00205 // d7a_xcl_t
00206 // -----------------------------------------------------------------------
00207 /// Bitfield structure of the Addressee Access Class
00208 // =======================================================================
00209 typedef union
00210 {
00211     // bit access fields
00212     struct {
00213         /// Subclass mask
00214         u8 m    : 4;
00215         /// Specifier
00216         u8 s    : 4;
00217     } bf;
00218 
00219     // byte access
00220     u8 byte;
00221 
00222 } d7a_xcl_t;
00223 
00224 // =======================================================================
00225 // d7a_addressee_t
00226 // -----------------------------------------------------------------------
00227 /// Structure of the D7ATP Addressee byte
00228 // =======================================================================
00229 TYPEDEF_STRUCT_PACKED
00230 {
00231     d7a_addressee_ctrl_t ctrl;
00232     d7a_xcl_t xcl;
00233     u8 id[D7A_UID_LEN];
00234 
00235 } d7a_addressee_t;
00236 
00237 // =======================================================================
00238 // d7a_ctf_t
00239 // -----------------------------------------------------------------------
00240 /// DLL compressed time format
00241 // =======================================================================
00242 typedef kal_ctf_t d7a_ctf_t;
00243 
00244 // =======================================================================
00245 // d7a_ch_header_t
00246 // -----------------------------------------------------------------------
00247 /// Bitfield structure of the channel identifier
00248 // =======================================================================
00249 typedef union
00250 {
00251     // bit access fields
00252     struct {
00253         /// Coding scheme
00254         u8 cs   : 2;
00255         /// Channel Class
00256         u8 cl   : 2;
00257         /// Channel Band
00258         u8 band : 3;
00259         /// Extension
00260         u8 ext  : 1;
00261     } bf;
00262 
00263     // byte access
00264     u8 byte;
00265 
00266 } d7a_ch_header_t;
00267 
00268 // =======================================================================
00269 // d7a_resp_t
00270 // -----------------------------------------------------------------------
00271 /// Enumerator of the D7ASP Response types
00272 // =======================================================================
00273 typedef enum
00274 {
00275     /// No response requested
00276     D7A_RESP_NO = 0,
00277     /// Get all responses in response period.
00278     D7A_RESP_ALL,
00279     /// Get at least one ACK per request during response period
00280     D7A_RESP_ANY,
00281     /// Same as D7A_RESP_ALL, but responders respond only if upper layer payload is available
00282     /// It is suitable for cases when the smart addressing (queries) is used.
00283     D7A_RESP_ALL_ON_DATA,
00284     /// No response requested, repeat the number of times defined in the SEL configuration file
00285     D7A_RESP_NO_RPT,
00286     /// Same as D7A_RESP_ANY, but responders respond only if upper layer payload is available
00287     /// It is suitable for cases when the smart addressing (queries) is used.
00288     D7A_RESP_ANY_ON_DATA,
00289     /// Get at least one acknowledgement per request during response period.
00290     /// Stick to a single responder when possible
00291     D7A_RESP_PREFERRED,
00292     /// Same as D7A_RESP_PREFERRED, but responders respond only if upper layer payload is available
00293     /// It is suitable for cases when the smart addressing (queries) is used.
00294     D7A_RESP_PREFERRED_ON_DATA
00295 
00296 } d7a_resp_t;
00297 
00298 //======================================================================
00299 // d7a_retry_t
00300 // -----------------------------------------------------------------------
00301 // D7A retry policies
00302 //======================================================================
00303 typedef enum
00304 {
00305     /// Single request, try once (context cleaned upon completion)
00306     /// Suitable for low QoS or QoS managed by the application
00307     D7A_RETRY_ONESHOT = 0,
00308     /// Single request, retry 3 times (context cleaned upon completion)
00309     /// Suitable for higher QoS or QoS managed by the application
00310     D7A_RETRY_ONESHOT_RETRY,
00311     /// FIFO mode with fast retry pattern (context kept on completion)
00312     /// Suitable for periodic frequent chart-type ActP notifications (< ~10s between messages)
00313     D7A_RETRY_FIFO_FAST,
00314     /// FIFO mode with slow retry pattern (context kept on completion)
00315     /// Suitable for periodic unfrequent chart-type ActP notifications (> ~10s between messages)
00316     D7A_RETRY_FIFO_SLOW,
00317     /// Single ("last-is-best") mode with fast retry pattern (context kept on completion)
00318     /// Suitable for periodic frequent state-type ActP notifications (< ~10s between messages)
00319     D7A_RETRY_SINGLE_FAST,
00320     /// Single ("last-is-best") mode with slow retry pattern (context kept on completion)
00321     /// Suitable for periodic unfrequent state-type ActP notifications (> ~10s between messages)
00322     D7A_RETRY_SINGLE_SLOW,
00323     /// Single request, retry 8 times or more (context cleaned upon completion)
00324     /// Suitable for rare ActP notifications with higher priority (revision, etc).
00325     /// Suitable for application requests where the QoS is managed by the stack
00326     /// or the completion is not expected synchronously (could be very long)
00327     D7A_RETRY_ONESHOT_STICKY,
00328     /// Reserved for future use
00329     D7A_RETRY_RFU_7
00330 
00331 } d7a_retry_t ;
00332 
00333 // =======================================================================
00334 // d7a_qos_t
00335 // -----------------------------------------------------------------------
00336 /// Bitfield structure of the D7ASP Quality of Service control byte
00337 // =======================================================================
00338 typedef union
00339 {
00340     // bit access fields
00341     struct {
00342         /// Response mode
00343         u8 resp         : 3;
00344         /// Retry mode
00345         u8 retry        : 3;
00346         /// RFU
00347         u8 rfu          : 2;
00348     } bf;
00349 
00350     // byte access
00351     u8 byte;
00352 
00353 } d7a_qos_t;
00354 
00355 // =======================================================================
00356 // d7a_sp_cfg_t
00357 // -----------------------------------------------------------------------
00358 /// Structure of the D7ASP Configuration
00359 // =======================================================================
00360 TYPEDEF_STRUCT_PACKED
00361 {
00362     /// D7ASP QoS
00363     d7a_qos_t qos;
00364     /// Session Start timeout
00365     d7a_ctf_t to;
00366     /// Response execution delay
00367     d7a_ctf_t te;
00368     /// Addressee
00369     d7a_addressee_t addressee;
00370 
00371 } d7a_sp_cfg_t;
00372 
00373 // =======================================================================
00374 // d7a_sp_status_t
00375 // -----------------------------------------------------------------------
00376 /// Bitfield structure of the D7ASP segment status byte
00377 // =======================================================================
00378 typedef union
00379 {
00380     // bit access fields
00381     struct {
00382         /// RFU
00383         u8 rfu          : 4;
00384         /// Identifier type of the received segment
00385         u8 idf          : 2;
00386         /// Current seqnum was already received
00387         u8 retry        : 1;
00388         /// There are not received seqnums anterior to the current seqnum
00389         u8 missed       : 1;
00390     } bf;
00391 
00392     // byte access
00393     u8 byte;
00394 
00395 } d7a_sp_status_t;
00396 
00397 // =======================================================================
00398 // d7a_nwl_security_t
00399 // -----------------------------------------------------------------------
00400 /// NWL Security File structure
00401 // =======================================================================
00402 TYPEDEF_STRUCT_PACKED
00403 {
00404     /// Key counter
00405     u8 key_counter;
00406     /// Frame counter
00407     u32 frame_counter;
00408 
00409 } d7a_nwl_security_t;
00410 
00411 // =======================================================================
00412 // d7a_sp_res_t
00413 // -----------------------------------------------------------------------
00414 /// D7A specific segment metadata
00415 // =======================================================================
00416 TYPEDEF_STRUCT_PACKED
00417 {
00418     /// channel header
00419     d7a_ch_header_t header;
00420     /// channel index
00421     u16 idx;
00422     /// RSSI in -dBm
00423     u8  rxlev;
00424     /// Link budget in dB
00425     u8  lb;
00426     /// Signal-to-noise ratio in dB
00427     s8  snr;
00428     /// D7ASP status
00429     d7a_sp_status_t status;
00430     /// D7ASP Token
00431     u8  token;
00432     /// D7ASP Sequence number
00433     u8  seq;
00434     /// Response timeout
00435     u32 resp_to;
00436     /// Addressee
00437     d7a_addressee_t addressee;
00438     /// NLS security state (optional)
00439     d7a_nwl_security_t nls_state;
00440 
00441 } d7a_sp_res_t;
00442 
00443 // =======================================================================
00444 // d7a_res_t
00445 // -----------------------------------------------------------------------
00446 /// Aggregate packet reception metadata
00447 // =======================================================================
00448 typedef struct
00449 {
00450     /// Handle
00451     u8  id;
00452     /// End reception date
00453     u32 date;
00454     /// frequency offset (frequency error)
00455     s16 fei;
00456     /// Size of the result (depends on origin Addresse ID)
00457     u8  len;
00458     /// Target RXLEV in -dBm
00459     u8  target_rxlev;
00460     /// segment metadata
00461     d7a_sp_res_t sp;
00462 
00463 } d7a_res_t;
00464 
00465 // =======================================================================
00466 // d7a_error_t
00467 // -----------------------------------------------------------------------
00468 /// Error types enumerator for D7A
00469 // =======================================================================
00470 typedef enum
00471 {
00472     /// No error
00473     D7A_ERROR_NO                        =  0,
00474     /// Resource busy
00475     D7A_ERROR_BUSY                      = -1,
00476     /// Bad parameter
00477     D7A_ERROR_BAD_PARAM                 = -2,
00478     /// Duty cycle limit overflow
00479     D7A_ERROR_DUTY_CYCLE                = -3,
00480     /// CCA timeout
00481     D7A_ERROR_CCA_TO                    = -4,
00482     /// Security frame counter overflow
00483     D7A_ERROR_NLS_KEY                   = -5,
00484     /// TX stream underflow
00485     D7A_ERROR_TX_UDF                    = -6,
00486     /// RX stream overflow
00487     D7A_ERROR_RX_OVF                    = -7,
00488     /// RX checksum
00489     D7A_ERROR_RX_CRC                    = -8,
00490     /// Abort
00491     D7A_ERROR_ABORT                     = -9,
00492     /// No ACK received
00493     D7A_ERROR_NO_ACK                    = -10,
00494     /// RX timeout
00495     D7A_ERROR_RX_TO                     = -11,
00496     /// Not supported band
00497     D7A_ERROR_NOT_SUPPORTED_BAND        = -12,
00498     /// Not supported channel
00499     D7A_ERROR_NOT_SUPPORTED_CHANNEL     = -13,
00500     /// Not supported modulation
00501     D7A_ERROR_NOT_SUPPORTED_MODULATION  = -14,
00502     /// No channels in list
00503     D7A_ERROR_VOID_CHANNEL_LIST         = -15,
00504 
00505 } d7a_error_t;
00506 
00507 // =======================================================================
00508 // d7a_req_status_t
00509 // -----------------------------------------------------------------------
00510 /// D7A session request status
00511 // =======================================================================
00512 typedef union
00513 {
00514     struct {
00515         /// Fifo identifier (handle)
00516         u32 id  : 8;
00517         /// Tag of the request
00518         u32 tag : 8;
00519         /// request flush status
00520         u32 ok  : 1;
00521         /// RFU
00522         u32 rfu : 7;
00523         /// D7A error
00524         u32 err : 8;
00525     } bf;
00526 
00527     /// word access
00528     u32 word;
00529 
00530 } d7a_req_status_t;
00531 
00532 // =======================================================================
00533 // d7a_status_t
00534 // -----------------------------------------------------------------------
00535 /// D7A session procedure status upon termination
00536 // =======================================================================
00537 typedef union
00538 {
00539     struct
00540     {
00541         /// Fifo identifier (handle)
00542         u32 id  :  8;
00543         /// Flush status.
00544         u32 ok  :  1;
00545         /// RFU
00546         u32 rfu : 15;
00547         /// D7A error
00548         u32 err :  8;
00549     } bf;
00550 
00551     /// word access
00552     u32 word;
00553 
00554 } d7a_status_t;
00555 
00556 #endif // __D7A_1X_H__