Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: modem_ref_helper_for_v5_3_217
d7a_1x.h
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__
Generated on Wed Jul 20 2022 12:33:07 by
