-
Notifications
You must be signed in to change notification settings - Fork 206
/
cfe_sb.h
985 lines (937 loc) · 43.9 KB
/
cfe_sb.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
/************************************************************************
* NASA Docket No. GSC-18,719-1, and identified as “core Flight System: Bootes”
*
* Copyright (c) 2020 United States Government as represented by the
* Administrator of the National Aeronautics and Space Administration.
* All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License. You may obtain
* a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
************************************************************************/
/**
* @file
*
* Purpose:
* This header file contains all definitions for the cFE Software Bus
* Application Programmer's Interface.
*
* Author: R.McGraw/SSI
*
*/
#ifndef CFE_SB_H
#define CFE_SB_H
/*
** Includes
*/
#include "common_types.h"
#include "cfe_error.h"
#include "cfe_sb_api_typedefs.h"
#include "cfe_es_api_typedefs.h"
/*
** Macro Definitions
*/
#define CFE_BIT(x) (1 << (x)) /**< \brief Places a one at bit positions 0 - 31*/
#define CFE_SET(i, x) ((i) |= CFE_BIT(x)) /**< \brief Sets bit x of i */
#define CFE_CLR(i, x) ((i) &= ~CFE_BIT(x)) /**< \brief Clears bit x of i */
#define CFE_TST(i, x) (((i)&CFE_BIT(x)) != 0) /**< \brief true(non zero) if bit x of i is set */
/****************** Function Prototypes **********************/
/** @defgroup CFEAPISBPipe cFE Pipe Management APIs
* @{
*/
/*****************************************************************************/
/**
** \brief Creates a new software bus pipe.
**
** \par Description
** This routine creates and initializes an input pipe that the calling
** application can use to receive software bus messages. By default, no
** messages are routed to the new pipe. So, the application must use
** #CFE_SB_Subscribe to specify which messages it wants to receive on
** this pipe.
**
** \par Assumptions, External Events, and Notes:
** None
**
** \param[out] PipeIdPtr A pointer to a variable of type #CFE_SB_PipeId_t @nonnull,
** which will be filled in with the pipe ID information
** by the #CFE_SB_CreatePipe routine. *PipeIdPtr is the identifier for the created pipe.
**
** \param[in] Depth The maximum number of messages that will be allowed on
** this pipe at one time.
**
** \param[in] PipeName A string @nonnull to be used to identify this pipe in error messages
** and routing information telemetry. The string must be no
** longer than #OS_MAX_API_NAME (including terminator).
** Longer strings will be truncated.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_MAX_PIPES_MET \copybrief CFE_SB_MAX_PIPES_MET
** \retval #CFE_SB_PIPE_CR_ERR \copybrief CFE_SB_PIPE_CR_ERR
**
** \sa #CFE_SB_DeletePipe #CFE_SB_GetPipeOpts #CFE_SB_SetPipeOpts #CFE_SB_GetPipeIdByName
**/
CFE_Status_t CFE_SB_CreatePipe(CFE_SB_PipeId_t *PipeIdPtr, uint16 Depth, const char *PipeName);
/*****************************************************************************/
/**
** \brief Delete a software bus pipe.
**
** \par Description
** This routine deletes an input pipe and cleans up all data structures
** associated with the pipe. All subscriptions made for this pipe by
** calls to #CFE_SB_Subscribe will be automatically removed from the
** SB routing tables. Any messages in the pipe will be discarded.
**
** Applications should not call this routine for all of their
** SB pipes as part of their orderly shutdown process, as the
** pipe will be deleted by the support framework at the
** appropriate time.
**
** \par Assumptions, External Events, and Notes:
** None
**
** \param[in] PipeId The pipe ID (obtained previously from #CFE_SB_CreatePipe)
** of the pipe to be deleted.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
** \sa #CFE_SB_CreatePipe #CFE_SB_GetPipeOpts #CFE_SB_SetPipeOpts #CFE_SB_GetPipeIdByName
**/
CFE_Status_t CFE_SB_DeletePipe(CFE_SB_PipeId_t PipeId);
/**
* @brief Obtain an index value correlating to an SB Pipe ID
*
* This calculates a zero based integer value that may be used for indexing
* into a local resource table/array.
*
* Index values are only guaranteed to be unique for resources of the same
* type. For instance, the indices corresponding to two [valid] application
* IDs will never overlap, but the index of a pipe ID and an app ID
* may be the same. Furthermore, indices may be reused if a resource is
* deleted and re-created.
*
* @note There is no inverse of this function - indices cannot be converted
* back to the original PipeID value. The caller should retain the original ID
* for future use.
*
* @param[in] PipeID Pipe ID to convert
* @param[out] Idx Buffer where the calculated index will be stored @nonnull
*
* @return Execution status, see @ref CFEReturnCodes
* @retval #CFE_SUCCESS @copybrief CFE_SUCCESS
* @retval #CFE_ES_ERR_RESOURCEID_NOT_VALID @copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID
*/
CFE_Status_t CFE_SB_PipeId_ToIndex(CFE_SB_PipeId_t PipeID, uint32 *Idx);
/*****************************************************************************/
/**
** \brief Set options on a pipe.
**
** \par Description
** This routine sets (or clears) options to alter the pipe's behavior.
** Options are (re)set every call to this routine.
**
** \param[in] PipeId The pipe ID of the pipe to set options on.
**
** \param[in] Opts A bit field of options: \ref CFESBPipeOptions
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
** \sa #CFE_SB_CreatePipe #CFE_SB_DeletePipe #CFE_SB_GetPipeOpts #CFE_SB_GetPipeIdByName #CFE_SB_PIPEOPTS_IGNOREMINE
**/
CFE_Status_t CFE_SB_SetPipeOpts(CFE_SB_PipeId_t PipeId, uint8 Opts);
/*****************************************************************************/
/**
** \brief Get options on a pipe.
**
** \par Description
** This routine gets the current options on a pipe.
**
** \param[in] PipeId The pipe ID of the pipe to get options from.
**
** \param[out] OptsPtr A bit field of options: \ref CFESBPipeOptions @nonnull
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
** \sa #CFE_SB_CreatePipe #CFE_SB_DeletePipe #CFE_SB_SetPipeOpts #CFE_SB_GetPipeIdByName #CFE_SB_PIPEOPTS_IGNOREMINE
**/
CFE_Status_t CFE_SB_GetPipeOpts(CFE_SB_PipeId_t PipeId, uint8 *OptsPtr);
/*****************************************************************************/
/**
** \brief Get the pipe name for a given id.
**
** \par Description
** This routine finds the pipe name for a pipe id.
**
** \param[out] PipeNameBuf The buffer to receive the pipe name @nonnull.
**
** \param[in] PipeNameSize The size (in chars) of the PipeName buffer @nonzero.
**
** \param[in] PipeId The PipeId for that name.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
** \sa #CFE_SB_CreatePipe #CFE_SB_DeletePipe #CFE_SB_SetPipeOpts #CFE_SB_GetPipeIdByName
**/
CFE_Status_t CFE_SB_GetPipeName(char *PipeNameBuf, size_t PipeNameSize, CFE_SB_PipeId_t PipeId);
/*****************************************************************************/
/**
** \brief Get pipe id by pipe name.
**
** \par Description
** This routine finds the pipe id for a pipe name.
**
** \param[in] PipeName The name of the pipe @nonnull.
**
** \param[out] PipeIdPtr The PipeId for that name @nonnull.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
** \sa #CFE_SB_CreatePipe #CFE_SB_DeletePipe #CFE_SB_SetPipeOpts #CFE_SB_PIPEOPTS_IGNOREMINE
**/
CFE_Status_t CFE_SB_GetPipeIdByName(CFE_SB_PipeId_t *PipeIdPtr, const char *PipeName);
/**@}*/
/** @defgroup CFEAPISBSubscription cFE Message Subscription Control APIs
* @{
*/
/*****************************************************************************/
/**
** \brief Subscribe to a message on the software bus
**
** \par Description
** This routine adds the specified pipe to the destination list associated
** with the specified message ID.
**
** \par Assumptions, External Events, and Notes:
** Note: As subscriptions are received, the destinations are added to
** the head of a linked list. During the sending of a message, the list
** is traversed beginning at the head of the list. Therefore the
** message will first be sent to the last subscriber. If an application
** has timing constraints and needs to receive a message in the
** shortest possible time, the developer may consider holding off its
** subscription until other applications have subscribed to the message.
**
** \param[in] MsgId The message ID of the message to be subscribed to.
**
** \param[in] PipeId The pipe ID of the pipe the subscribed message
** should be sent to.
**
** \param[in] Quality The requested Quality of Service (QoS) required of
** the messages. Most callers will use #CFE_SB_DEFAULT_QOS
** for this parameter.
**
** \param[in] MsgLim The maximum number of messages with this Message ID to
** allow in this pipe at the same time.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_MAX_MSGS_MET \covtest \copybrief CFE_SB_MAX_MSGS_MET
** \retval #CFE_SB_MAX_DESTS_MET \copybrief CFE_SB_MAX_DESTS_MET
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_BUF_ALOC_ERR \covtest \copybrief CFE_SB_BUF_ALOC_ERR
**
** \sa #CFE_SB_Subscribe, #CFE_SB_SubscribeLocal, #CFE_SB_Unsubscribe, #CFE_SB_UnsubscribeLocal
**/
CFE_Status_t CFE_SB_SubscribeEx(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId, CFE_SB_Qos_t Quality, uint16 MsgLim);
/*****************************************************************************/
/**
** \brief Subscribe to a message on the software bus with default parameters
**
** \par Description
** This routine adds the specified pipe to the destination list for
** the specified message ID. This is the same as #CFE_SB_SubscribeEx
** with the Quality field set to #CFE_SB_DEFAULT_QOS and MsgLim set
** to #CFE_PLATFORM_SB_DEFAULT_MSG_LIMIT (4).
**
** \par Assumptions, External Events, and Notes:
** Note: As subscriptions are received, the destinations are added to
** the head of a linked list. During the sending of a message, the list
** is traversed beginning at the head of the list. Therefore the
** message will first be sent to the last subscriber. If an application
** has timing constraints and needs to receive a message in the
** shortest possible time, the developer may consider holding off its
** subscription until other applications have subscribed to the message.
**
** \param[in] MsgId The message ID of the message to be subscribed to.
**
** \param[in] PipeId The pipe ID of the pipe the subscribed message
** should be sent to.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_MAX_MSGS_MET \covtest \copybrief CFE_SB_MAX_MSGS_MET
** \retval #CFE_SB_MAX_DESTS_MET \copybrief CFE_SB_MAX_DESTS_MET
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_BUF_ALOC_ERR \covtest \copybrief CFE_SB_BUF_ALOC_ERR
**
** \sa #CFE_SB_SubscribeEx, #CFE_SB_SubscribeLocal, #CFE_SB_Unsubscribe, #CFE_SB_UnsubscribeLocal
**/
CFE_Status_t CFE_SB_Subscribe(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId);
/*****************************************************************************/
/**
** \brief Subscribe to a message while keeping the request local to a cpu
**
** \par Description
** This routine adds the specified pipe to the destination list for
** the specified message ID. This is similar to #CFE_SB_SubscribeEx
** with the Quality field set to #CFE_SB_DEFAULT_QOS and MsgLim set
** to #CFE_PLATFORM_SB_DEFAULT_MSG_LIMIT, but will not report the subscription.
**
** Software Bus Network (SBN) application is an example use case,
** where local subscriptions should not be reported to peers.
**
** \par Assumptions, External Events, and Notes:
** - This API is typically only used by Software Bus Network (SBN) Application
**
** \param[in] MsgId The message ID of the message to be subscribed to.
**
** \param[in] PipeId The pipe ID of the pipe the subscribed message
** should be sent to.
**
** \param[in] MsgLim The maximum number of messages with this Message ID to
** allow in this pipe at the same time.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_MAX_MSGS_MET \covtest \copybrief CFE_SB_MAX_MSGS_MET
** \retval #CFE_SB_MAX_DESTS_MET \copybrief CFE_SB_MAX_DESTS_MET
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_BUF_ALOC_ERR \covtest \copybrief CFE_SB_BUF_ALOC_ERR
**
** \sa #CFE_SB_Subscribe, #CFE_SB_SubscribeEx, #CFE_SB_Unsubscribe, #CFE_SB_UnsubscribeLocal
**/
CFE_Status_t CFE_SB_SubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId, uint16 MsgLim);
/*****************************************************************************/
/**
** \brief Remove a subscription to a message on the software bus
**
** \par Description
** This routine removes the specified pipe from the destination
** list for the specified message ID.
**
** \par Assumptions, External Events, and Notes:
** If the Pipe is not subscribed to MsgId, the CFE_SB_UNSUB_NO_SUBS_EID
** event will be generated and #CFE_SUCCESS will be returned
**
** \param[in] MsgId The message ID of the message to be unsubscribed.
**
** \param[in] PipeId The pipe ID of the pipe the subscribed message
** should no longer be sent to.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
** \sa #CFE_SB_Subscribe, #CFE_SB_SubscribeEx, #CFE_SB_SubscribeLocal, #CFE_SB_UnsubscribeLocal
**/
CFE_Status_t CFE_SB_Unsubscribe(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId);
/*****************************************************************************/
/**
** \brief Remove a subscription to a message on the software bus on the current CPU
**
** \par Description
** This routine removes the specified pipe from the destination
** list for the specified message ID on the current CPU.
**
** \par Assumptions, External Events, and Notes:
** This API is typically only used by Software Bus Network (SBN) Application.
** If the Pipe is not subscribed to MsgId, the CFE_SB_UNSUB_NO_SUBS_EID
** event will be generated and #CFE_SUCCESS will be returned
**
** \param[in] MsgId The message ID of the message to be unsubscribed.
**
** \param[in] PipeId The pipe ID of the pipe the subscribed message
** should no longer be sent to.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
** \sa #CFE_SB_Subscribe, #CFE_SB_SubscribeEx, #CFE_SB_SubscribeLocal, #CFE_SB_Unsubscribe
**/
CFE_Status_t CFE_SB_UnsubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId);
/**@}*/
/** @defgroup CFEAPISBMessage cFE Send/Receive Message APIs
* @{
*/
/*****************************************************************************/
/**
** \brief Transmit a message
**
** \par Description
** This routine copies the specified message into a software bus
** buffer which is then transmitted to all subscribers. The
** software bus will read the message ID from the message header to
** determine which pipes should receive the message.
**
** The IsOrigination parameter should be passed as "true" if the message was
** newly constructed by the sender and is being sent for the first time. This
** enables the message origination actions as determined by the CFE MSG module,
** which may include (but not limited to):
** - Updating sequence number
** - Updating timestamp
** - Calcualating a CRC, checksum, or other message error control field
**
** Conversely, when forwarding a message that originated from
** an external entity (e.g. messages passing through CI or SBN), the
** parameter should be passed as "false" to not overwrite existing data.
**
** \par Assumptions, External Events, and Notes:
** - This routine will not normally wait for the receiver tasks to
** process the message before returning control to the caller's task.
** - However, if a higher priority task is pending and subscribed to
** this message, that task may get to run before returning
** control to the caller.
** - In previous versions of CFE, the boolean parameter referred to the
** sequence number header of telemetry messages only. This has been
** extended to apply more generically to any headers, as determined by
** the CFE MSG implementation.
**
** \param[in] MsgPtr A pointer to the message to be sent @nonnull. This must point
** to the first byte of the message header.
** \param[in] IsOrigination Update the headers of the message
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG
** \retval #CFE_SB_BUF_ALOC_ERR \covtest \copybrief CFE_SB_BUF_ALOC_ERR
**/
CFE_Status_t CFE_SB_TransmitMsg(const CFE_MSG_Message_t *MsgPtr, bool IsOrigination);
/*****************************************************************************/
/**
** \brief Receive a message from a software bus pipe
**
** \par Description
** This routine retrieves the next message from the specified pipe.
** If the pipe is empty, this routine will block until either a new
** message comes in or the timeout value is reached.
**
** \par Assumptions, External Events, and Notes:
** Note - If an error occurs in this API, the *BufPtr value may be NULL or
** random. Therefore, it is recommended that the return code be tested
** for CFE_SUCCESS before processing the message.
**
** \param[in, out] BufPtr A pointer to the software bus buffer to receive to @nonnull.
** Typically a caller declares a ptr of type CFE_SB_Buffer_t
** (i.e. CFE_SB_Buffer_t *Ptr) then gives the address of that
** pointer (&Ptr) as this parameter. After a successful
** receipt of a message, *BufPtr will point to the first
** byte of the software bus buffer. This should be
** used as a read-only pointer (in systems with an MMU,
** writes to this pointer may cause a memory protection fault).
** The *BufPtr is valid only until the next call to
** CFE_SB_ReceiveBuffer for the same pipe.
**
** \param[in] PipeId The pipe ID of the pipe containing the message to be obtained.
**
** \param[in] TimeOut The number of milliseconds to wait for a new message if the
** pipe is empty at the time of the call. This can also be set
** to #CFE_SB_POLL for a non-blocking receive or
** #CFE_SB_PEND_FOREVER to wait forever for a message to arrive.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_TIME_OUT \copybrief CFE_SB_TIME_OUT
** \retval #CFE_SB_PIPE_RD_ERR \covtest \copybrief CFE_SB_PIPE_RD_ERR
** \retval #CFE_SB_NO_MESSAGE \copybrief CFE_SB_NO_MESSAGE
**/
CFE_Status_t CFE_SB_ReceiveBuffer(CFE_SB_Buffer_t **BufPtr, CFE_SB_PipeId_t PipeId, int32 TimeOut);
/** @} */
/** @defgroup CFEAPISBZeroCopy cFE Zero Copy APIs
* @{
*/
/*****************************************************************************/
/**
** \brief Get a buffer pointer to use for "zero copy" SB sends.
**
** \par Description
** This routine can be used to get a pointer to one of the software bus'
** internal memory buffers that are used for sending messages. The caller
** can use this memory buffer to build an SB message, then send it using
** the CFE_SB_TransmitBuffer() function. This interface avoids an extra
** copy of the message from the user's memory buffer to the software bus
** internal buffer.
**
** \par Assumptions, External Events, and Notes:
** -# The pointer returned by CFE_SB_AllocateMessageBuffer() is only good for one
** call to CFE_SB_TransmitBuffer().
** -# Once a buffer has been successfully transmitted (as indicated by a successful
** return from CFE_SB_TransmitBuffer()) the buffer becomes owned by the SB application.
** It will automatically be freed by SB once all recipients have finished reading it.
** -# Applications must not de-reference the message pointer (for reading
** or writing) after the call to CFE_SB_TransmitBuffer().
** -# If #CFE_SB_ReleaseMessageBuffer should be used only if a message is not transmitted
**
** \param[in] MsgSize The size of the SB message buffer the caller wants
** (including the SB message header).
**
** \return A pointer to a memory buffer that message data can be written to
** for use with CFE_SB_TransmitBuffer().
**/
CFE_SB_Buffer_t *CFE_SB_AllocateMessageBuffer(size_t MsgSize);
/*****************************************************************************/
/**
** \brief Release an unused "zero copy" buffer pointer.
**
** \par Description
** This routine can be used to release a pointer to one of the software
** bus' internal memory buffers.
**
** \par Assumptions, External Events, and Notes:
** -# This function is not needed for normal "zero copy" transfers. It
** is needed only for cleanup when an application gets a pointer using
** CFE_SB_AllocateMessageBuffer(), but (due to some error condition) never
** uses that pointer in a call to CFE_SB_TransmitBuffer().
**
** \param[in] BufPtr A pointer to the SB internal buffer @nonnull. This must be a
** pointer returned by a call to CFE_SB_AllocateMessageBuffer(),
** but never used in a call to CFE_SB_TransmitBuffer().
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID
**/
CFE_Status_t CFE_SB_ReleaseMessageBuffer(CFE_SB_Buffer_t *BufPtr);
/*****************************************************************************/
/**
** \brief Transmit a buffer
**
** \par Description
** This routine sends a message that has been created directly in an
** internal SB message buffer by an application (after a call to
** #CFE_SB_AllocateMessageBuffer). This interface is more complicated than
** the normal #CFE_SB_TransmitMsg interface, but it avoids an extra copy of
** the message from the user's memory buffer to the software bus
** internal buffer. The "zero copy" interface can be used to improve
** performance in high-rate, high-volume software bus traffic.
**
** The IsOrigination parameter should be passed as "true" if the message was
** newly constructed by the sender and is being sent for the first time. This
** enables the message origination actions as determined by the CFE MSG module,
** which may include (but not limited to):
** - Updating sequence number
** - Updating timestamp
** - Calcualating a CRC, checksum, or other message error control field
**
** Conversely, when forwarding a message that originated from
** an external entity (e.g. messages passing through CI or SBN), the
** parameter should be passed as "false" to not overwrite existing data.
**
** \par Assumptions, External Events, and Notes:
** -# A handle returned by #CFE_SB_AllocateMessageBuffer is "consumed" by
** a _successful_ call to #CFE_SB_TransmitBuffer.
** -# If this function returns CFE_SUCCESS, this indicates the zero copy handle is
** now owned by software bus, and is no longer owned by the calling application,
** and should not be re-used.
** -# However if this function fails (returns any error status) it does not change
** the state of the buffer at all, meaning the calling application still owns it.
** (a failure means the buffer is left in the same state it was before the call).
** -# Applications should be written as if #CFE_SB_AllocateMessageBuffer is
** equivalent to a \c malloc() and a successful call to #CFE_SB_TransmitBuffer
** is equivalent to a \c free().
** -# Applications must not de-reference the message pointer (for reading
** or writing) after a successful call to #CFE_SB_TransmitBuffer.
** -# This function will increment and apply the internally tracked
** sequence counter if set to do so.
**
** \param[in] BufPtr A pointer to the buffer to be sent @nonnull.
** \param[in] IsOrigination Update applicable header field(s) of a newly constructed message
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG
**/
CFE_Status_t CFE_SB_TransmitBuffer(CFE_SB_Buffer_t *BufPtr, bool IsOrigination);
/** @} */
/** @defgroup CFEAPISBMessageCharacteristics cFE Message Characteristics APIs
* @{
*/
/*****************************************************************************/
/**
** \brief Sets the length of user data in a software bus message.
**
** \par Description
** This routine sets the field in the SB message header that determines
** the size of the user data in a software bus message. SB message header
** formats can be different for each deployment of the cFE. So, applications
** should use this function rather than trying to poke a length value directly
** into their SB message buffers.
**
** \par Assumptions, External Events, and Notes:
** - You must set a valid message ID in the SB message header before
** calling this function.
**
** \param[in] MsgPtr A pointer to the buffer that contains the software bus message @nonnull.
** This must point to the first byte of the message header.
**
** \param[in] DataLength The length to set (size of the user data, in bytes).
**/
void CFE_SB_SetUserDataLength(CFE_MSG_Message_t *MsgPtr, size_t DataLength);
/*****************************************************************************/
/**
** \brief Sets the time field in a software bus message with the current spacecraft time.
**
** \par Description
** This routine sets the time of a software bus message with the current
** spacecraft time. This will be the same time that is returned by the
** function #CFE_TIME_GetTime.
**
** \par Assumptions, External Events, and Notes:
** - If the underlying implementation of software bus messages does not
** include a time field, then this routine will do nothing.
**
** \param[in] MsgPtr A pointer to the buffer that contains the software bus message @nonnull.
** This must point to the first byte of the message header.
**/
void CFE_SB_TimeStampMsg(CFE_MSG_Message_t *MsgPtr);
/******************************************************************************/
/**
** \brief Copies a string into a software bus message
**
** \par Description
** Strings within software bus messages have a defined/fixed maximum length, and
** may not necessarily be null terminated within the message. This presents a possible
** issue when using the C library functions to copy strings out of a message.
**
** This performs a very similar function to "strncpy()" except that the sizes
** of _both_ buffers are passed in. Neither buffer is required to be null-terminated,
** but copying will stop after the first termination character is encountered.
**
** If the destination buffer is not completely filled by the source data (such as if
** the supplied string was shorter than the allotted length) the destination buffer
** will be padded with NUL characters up to the size of the buffer, similar to what
** strncpy() does. This ensures that the entire destination buffer is set.
**
** \note
** If the source string buffer is already guaranteed to be null terminated,
** then there is no difference between the C library "strncpy()" function and this
** implementation. It is only necessary to use this when termination of the source
** buffer is not guaranteed.
**
** \param[out] DestStringPtr Pointer to destination buffer (component of SB message definition) @nonnull
** \param[in] SourceStringPtr Pointer to source buffer @nonnull
** \param[in] DestMaxSize Size of destination buffer as defined by the message definition
** \param[in] SourceMaxSize Size of source buffer
**
** \return Number of characters copied or error code, see \ref CFEReturnCodes
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
*/
int32 CFE_SB_MessageStringSet(char *DestStringPtr, const char *SourceStringPtr, size_t DestMaxSize,
size_t SourceMaxSize);
/*****************************************************************************/
/**
** \brief Get a pointer to the user data portion of a software bus message.
**
** \par Description
** This routine returns a pointer to the user data portion of a software
** bus message. SB message header formats can be different for each
** deployment of the cFE. So, applications should use this function and
** avoid hard coding offsets into their SB message buffers.
**
** \par Assumptions, External Events, and Notes:
** None
**
** \param[in] MsgPtr A pointer to the buffer that contains the software bus message @nonnull.
**
** \return A pointer to the first byte of user data within the software bus message.
**/
void *CFE_SB_GetUserData(CFE_MSG_Message_t *MsgPtr);
/*****************************************************************************/
/**
** \brief Gets the length of user data in a software bus message.
**
** \par Description
** This routine returns the size of the user data in a software bus message.
**
** \par Assumptions, External Events, and Notes:
** None
**
** \param[in] MsgPtr A pointer to the buffer that contains the software bus message @nonnull.
** This must point to the first byte of the message header.
**
** \return The size (in bytes) of the user data in the software bus message.
** \retval 0 if an error occurs, such as if the MsgPtr argument is not valid.
**/
size_t CFE_SB_GetUserDataLength(const CFE_MSG_Message_t *MsgPtr);
/******************************************************************************/
/**
** \brief Copies a string out of a software bus message
**
** \par Description
** Strings within software bus messages have a defined/fixed maximum length, and
** may not necessarily be null terminated within the message. This presents a possible
** issue when using the C library functions to copy strings out of a message.
**
** This function should replace use of C library functions such as strcpy/strncpy
** when copying strings out of software bus messages to local storage buffers.
**
** Up to [SourceMaxSize] or [DestMaxSize-1] (whichever is smaller) characters will be
** copied from the source buffer to the destination buffer, and a NUL termination
** character will be written to the destination buffer as the last character.
**
** If the DefaultString pointer is non-NULL, it will be used in place of the source
** string if the source is an empty string. This is typically a string constant that
** comes from the platform configuration, allowing default values to be assumed for
** fields that are unspecified.
**
** IMPORTANT - the default string, if specified, must be null terminated. This will
** be the case if a string literal is passed in (the typical/expected use case).
**
** If the default is NULL, then only the source string will be copied, and the result
** will be an empty string if the source was empty.
**
** If the destination buffer is too small to store the entire string, it will be
** truncated, but it will still be null terminated.
**
** \param[out] DestStringPtr Pointer to destination buffer @nonnull
** \param[in] SourceStringPtr Pointer to source buffer (component of SB message definition)
** \param[in] DefaultString Default string to use if source is empty
** \param[in] DestMaxSize Size of destination storage buffer @nonzero
** \param[in] SourceMaxSize Size of source buffer as defined by the message definition
**
** \return Number of characters copied or error code, see \ref CFEReturnCodes
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
**
*/
int32 CFE_SB_MessageStringGet(char *DestStringPtr, const char *SourceStringPtr, const char *DefaultString,
size_t DestMaxSize, size_t SourceMaxSize);
/** @} */
/** @defgroup CFEAPISBMessageID cFE Message ID APIs
* @{
*/
/*****************************************************************************/
/**
* \brief Identifies whether a given CFE_SB_MsgId_t is valid
*
* \par Description
* Implements a basic sanity check on the value provided
*
* \return Boolean message ID validity indicator
* \retval true Message ID is within the valid range
* \retval false Message ID is not within the valid range
*/
bool CFE_SB_IsValidMsgId(CFE_SB_MsgId_t MsgId);
/*****************************************************************************/
/**
* \brief Identifies whether two #CFE_SB_MsgId_t values are equal
*
* \par Description
* In cases where the #CFE_SB_MsgId_t type is not a simple integer
* type, it may not be possible to do a direct equality check.
* This inline function provides an abstraction for the equality
* check between two #CFE_SB_MsgId_t values.
*
* Applications should transition to using this function to compare
* MsgId values for equality to remain compatible with future versions
* of cFE.
*
* \return Boolean message ID equality indicator
* \retval true Message IDs are Equal
* \retval false Message IDs are not Equal
*/
static inline bool CFE_SB_MsgId_Equal(CFE_SB_MsgId_t MsgId1, CFE_SB_MsgId_t MsgId2)
{
return CFE_SB_MSGID_UNWRAP_VALUE(MsgId1) == CFE_SB_MSGID_UNWRAP_VALUE(MsgId2);
}
/*****************************************************************************/
/**
* \brief Converts a #CFE_SB_MsgId_t to a normal integer
*
* \par Description
* In cases where the #CFE_SB_MsgId_t type is not a simple integer
* type, it is not possible to directly display the value in a
* printf-style statement, use it in a switch() statement, or other
* similar use cases.
*
* This inline function provides the ability to map a #CFE_SB_MsgId_t
* type back into a simple integer value.
*
* Applications should transition to using this function wherever a
* #CFE_SB_MsgId_t type needs to be used as an integer.
*
* \par Assumptions and Notes:
* This negates the type safety that was gained by using a non-
* integer type for the #CFE_SB_MsgId_t value. This should only be used
* in specific cases such as UI display (printf, events, etc) where the
* value is being sent externally. Any internal API calls should be
* updated to use the #CFE_SB_MsgId_t type directly, rather than an
* integer type.
*
* \return Integer representation of the #CFE_SB_MsgId_t
*/
static inline CFE_SB_MsgId_Atom_t CFE_SB_MsgIdToValue(CFE_SB_MsgId_t MsgId)
{
return CFE_SB_MSGID_UNWRAP_VALUE(MsgId);
}
/*****************************************************************************/
/**
* \brief Converts a normal integer into a #CFE_SB_MsgId_t
*
* \par Description
* In cases where the #CFE_SB_MsgId_t type is not a simple integer
* type, it is not possible to directly use an integer value
* supplied via a define or similar method.
*
* This inline function provides the ability to map an integer value
* into a corresponding #CFE_SB_MsgId_t value.
*
* Applications should transition to using this function wherever an
* integer needs to be used for a #CFE_SB_MsgId_t.
*
* \par Assumptions and Notes:
* This negates the type safety that was gained by using a non-
* integer type for the #CFE_SB_MsgId_t value. This should only be
* used in specific cases where the value is coming from an external
* source. Any internal API calls should be updated to return the
* #CFE_SB_MsgId_t type directly, rather than an integer type.
*
* \return #CFE_SB_MsgId_t representation of the integer
*/
static inline CFE_SB_MsgId_t CFE_SB_ValueToMsgId(CFE_SB_MsgId_Atom_t MsgIdValue)
{
CFE_SB_MsgId_t Result = CFE_SB_MSGID_C(MsgIdValue);
return Result;
}
/*****************************************************************************/
/**
* \brief Converts a topic ID and instance number combination into a MsgID value integer
*
* \par Description
* This function accepts a data pair of topic ID + instance number and returns the
* corresponding MsgID Value (integer) for commands.
*
* \par Assumptions and Notes:
* A topic ID identifies a certain data stream from an application, for example
* the CFE Software bus ground commands (CFE_MISSION_SB_CMD_TOPICID). In
* contrast to MsgID, the topic ID is consistent across all CPUs in a system, whereas
* each CPU instance will have a unique MsgID.
*
* CPU instance numbers are 1-based. The instance number of 0 is reserved
* for "global" MsgID values that are the same on all CPUs. The PSP function
* may be used to obtain the current CPU number for the host processor.
*
* \sa CFE_SB_TlmTopicIdToMsgId(), CFE_PSP_GetProcessorId()
*
* \return Integer representation of the #CFE_SB_MsgId_t
*/
CFE_SB_MsgId_Atom_t CFE_SB_CmdTopicIdToMsgId(uint16 TopicId, uint16 InstanceNum);
/*****************************************************************************/
/**
* \brief Converts a topic ID and instance number combination into a MsgID value integer
*
* \par Description
* This function accepts a data pair of topic ID + instance number and returns the
* corresponding MsgID Value (integer) for telemetry.
*
* \par Assumptions and Notes:
* A topic ID identifies a certain data stream from an application, for example
* the CFE Software bus housekeeping telemetry (CFE_MISSION_SB_HK_TLM_TOPICID). In
* contrast to MsgID, the topic ID is consistent across all CPUs in a system, whereas
* each CPU instance will have a unique MsgID.
*
* CPU instance numbers are 1-based. The instance number of 0 is reserved
* for "global" MsgID values that are the same on all CPUs. The PSP function
* may be used to obtain the current CPU number for the host processor.
*
* \sa CFE_SB_CmdTopicIdToMsgId(), CFE_PSP_GetProcessorId()
*
* \return Integer representation of the #CFE_SB_MsgId_t
*/
CFE_SB_MsgId_Atom_t CFE_SB_TlmTopicIdToMsgId(uint16 TopicId, uint16 InstanceNum);
/*****************************************************************************/
/**
* \brief Converts a topic ID to a MsgID value integer for Global commands
*
* \par Description
* This is a wrapper around CFE_SB_CmdTopicIdToMsgId() for topic IDs which
* are the same on all CPUs within a system (i.e. not specific to a certain
* processor)
*
* \par Assumptions and Notes:
* Global MsgIDs may be used when only a single instance of a service exists
* within the system. The CFE framework does not use this feature for commands,
* but is defined for future use.
*
* \sa CFE_SB_CmdTopicIdToMsgId(), CFE_SB_LocalCmdTopicIdToMsgId()
*
* \return Integer representation of the #CFE_SB_MsgId_t
*/
CFE_SB_MsgId_Atom_t CFE_SB_GlobalCmdTopicIdToMsgId(uint16 TopicId);
/*****************************************************************************/
/**
* \brief Converts a topic ID to a MsgID value integer for Global telemetry
*
* \par Description
* This is a wrapper around CFE_SB_TlmTopicIdToMsgId() for topic IDs which
* are the same on all CPUs within a system (i.e. not specific to a certain
* processor)
*
* \par Assumptions and Notes:
* Global MsgIDs may be used when only a single instance of a service exists
* within the system. An example for such telemetry is the time synchronization
* service published by CFE_TIME.
*
* \sa CFE_SB_TlmTopicIdToMsgId(), CFE_SB_LocalTlmTopicIdToMsgId()
*
* \return Integer representation of the #CFE_SB_MsgId_t
*/
CFE_SB_MsgId_Atom_t CFE_SB_GlobalTlmTopicIdToMsgId(uint16 TopicId);
/*****************************************************************************/
/**
* \brief Converts a topic ID to a MsgID value integer for local commands
*
* \par Description
* This is a wrapper around CFE_SB_CmdTopicIdToMsgId() for topic IDs which
* are unique on all CPUs within a system (i.e. specific to a certain
* processor)
*
* \par Assumptions and Notes:
* This assumes the caller is referring to a service running on the same
* processor instance as itself.
*
* \sa CFE_SB_CmdTopicIdToMsgId(), CFE_SB_LocalTlmTopicIdToMsgId()
*
* \return Integer representation of the #CFE_SB_MsgId_t
*/
CFE_SB_MsgId_Atom_t CFE_SB_LocalCmdTopicIdToMsgId(uint16 TopicId);
/*****************************************************************************/
/**
* \brief Converts a topic ID to a MsgID value integer for local telemetry
*
* \par Description
* This is a wrapper around CFE_SB_TlmTopicIdToMsgId() for topic IDs which
* are unique on all CPUs within a system (i.e. specific to a certain
* processor)
*
* \par Assumptions and Notes:
* This assumes the caller is referring to a service running on the same
* processor instance as itself.
*
* \sa CFE_SB_TlmTopicIdToMsgId(), CFE_SB_LocalCmdTopicIdToMsgId()
*
* \return Integer representation of the #CFE_SB_MsgId_t
*/
CFE_SB_MsgId_Atom_t CFE_SB_LocalTlmTopicIdToMsgId(uint16 TopicId);
/** @} */
#endif /* CFE_SB_H */