-
Notifications
You must be signed in to change notification settings - Fork 209
/
Copy pathcfe_sb.h
1429 lines (1341 loc) · 62.6 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
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
** GSC-18128-1, "Core Flight Executive Version 6.7"
**
** Copyright (c) 2006-2019 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: cfe_sb.h
**
** Purpose:
** This header file contains all definitions for the cFE Software Bus
** Application Programmer's Interface.
**
** Author: R.McGraw/SSI
**
******************************************************************************/
#ifndef _cfe_sb_
#define _cfe_sb_
/*
** Includes
*/
#include "cfe_sb_extern_typedefs.h"
#include "cfe_error.h"
#include "osconfig.h"
#include "cfe_psp.h"
#include "common_types.h"
#include "cfe_mission_cfg.h"
#include "ccsds.h"
#include "cfe_time.h"
/*
** Defines
*/
#define CFE_SB_POLL 0 /**< \brief Option used with #CFE_SB_ReceiveBuffer to request immediate pipe status */
#define CFE_SB_PEND_FOREVER -1 /**< \brief Option used with #CFE_SB_ReceiveBuffer to force a wait for next message */
#define CFE_SB_SUB_ENTRIES_PER_PKT 20 /**< \brief Configuration parameter used by SBN App */
#define CFE_SB_SUBSCRIPTION 0 /**< \brief Subtype specifier used in #CFE_SB_SingleSubscriptionTlm_t by SBN App */
#define CFE_SB_UNSUBSCRIPTION 1 /**< \brief Subtype specified used in #CFE_SB_SingleSubscriptionTlm_t by SBN App */
/* ------------------------------------------------------ */
/* Macro Constants for use with the CFE_SB_MsgId_t type */
/* ------------------------------------------------------ */
/**
* \brief Translation macro to convert from MsgId integer values to opaque/abstract API values
*
* This conversion exists in macro form to allow compile-time evaluation for constants, and
* should not be used directly in application code.
*
* For applications, use the CFE_SB_ValueToMsgId() inline function instead.
*
* \sa CFE_SB_ValueToMsgId()
*/
#define CFE_SB_MSGID_WRAP_VALUE(val) ((CFE_SB_MsgId_t)(val))
/**
* \brief Translation macro to convert to MsgId integer values from opaque/abstract API values
*
* This conversion exists in macro form to allow compile-time evaluation for constants, and
* should not be used directly in application code.
*
* For applications, use the CFE_SB_MsgIdToValue() inline function instead.
*
* \sa CFE_SB_MsgIdToValue()
*/
#define CFE_SB_MSGID_UNWRAP_VALUE(mid) ((CFE_SB_MsgId_Atom_t)(mid))
/**
* \brief Reserved value for CFE_SB_MsgId_t that will not match any valid MsgId
*
* This rvalue macro can be used for static/compile-time data initialization to ensure that
* the initialized value does not alias to a valid MsgId object.
*/
#define CFE_SB_MSGID_RESERVED CFE_SB_MSGID_WRAP_VALUE(-1)
/**
* \brief A literal of the CFE_SB_MsgId_t type representing an invalid ID
*
* This value should be used for runtime initialization of CFE_SB_MsgId_t values.
*
* \note This may be a compound literal in a future revision. Per C99, compound
* literals are lvalues, not rvalues, so this value should not be used in
* static/compile-time data initialization. For static data initialization
* purposes (rvalue), #CFE_SB_MSGID_RESERVED should be used instead.
* However, in the current implementation, they are equivalent.
*/
#define CFE_SB_INVALID_MSG_ID CFE_SB_MSGID_RESERVED
#ifndef CFE_OMIT_DEPRECATED_6_8
/**
* \defgroup CFESBPktTypeDefs cFE SB Packet Type Defines
* \{
*/
#define CFE_SB_PKTTYPE_INVALID CFE_MSG_Type_Invalid /**< \brief #CFE_SB_GetPktType response if message type can not be determined */
#define CFE_SB_PKTTYPE_CMD CFE_MSG_Type_Cmd /**< \brief #CFE_SB_GetPktType response for command packets */
#define CFE_SB_PKTTYPE_TLM CFE_MSG_Type_Tlm /**< \brief #CFE_SB_GetPktType response for telemetry packets */
/** \} */
#endif /* CFE_OMIT_DEPRECATED_6_8 */
/*
** 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 */
/*
** Pipe option bit fields.
*/
#define CFE_SB_PIPEOPTS_IGNOREMINE 0x00000001 /**< \brief Messages sent by the app that owns this pipe will not be sent to this pipe. */
/*
** Type Definitions
*/
/** \brief Software Bus generic message */
typedef union CFE_SB_Msg {
CFE_MSG_Message_t Msg; /**< \brief Base message type without enforced alignment */
long long int LongInt; /**< \brief Align to support Long Integer */
long double LongDouble; /**< \brief Align to support Long Double */
} CFE_SB_Buffer_t;
#ifndef CFE_OMIT_DEPRECATED_6_8
/** \brief Deperecated type to minimize required changes */
typedef CFE_SB_Buffer_t CFE_SB_Msg_t;
/** \brief Deperecated type to minimize required changes */
typedef CFE_MSG_CommandHeader_t CFE_SB_CmdHdr_t;
/** \brief Deperecated type to minimize required changes */
typedef CFE_MSG_TelemetryHeader_t CFE_SB_TlmHdr_t;
#define CFE_SB_CMD_HDR_SIZE (sizeof(CFE_MSG_CommandHeader_t))/**< \brief Size of command header */
#define CFE_SB_TLM_HDR_SIZE (sizeof(CFE_MSG_TelemetryHeader_t))/**< \brief Size of telemetry header */
#endif /* CFE_OMIT_DEPRECATED_6_8 */
/** \brief CFE_SB_TimeOut_t to primitive type definition
**
** Internally used by SB in the #CFE_SB_ReceiveBuffer API. Translated from the
** input parmater named TimeOut which specifies the maximum time in
** milliseconds that the caller wants to wait for a message.
*/
typedef uint32 CFE_SB_TimeOut_t;
/** \brief CFE_SB_PipeId_t to primitive type definition
**
** Software Bus pipe identifier used in many SB APIs
*/
typedef uint8 CFE_SB_PipeId_t;
#ifndef CFE_OMIT_DEPRECATED_6_8
/** \brief Pointer to an SB Message */
typedef CFE_MSG_Message_t *CFE_SB_MsgPtr_t;
/** \brief CFE_SB_MsgPayloadPtr_t defined as an opaque pointer to a message Payload portion */
typedef uint8 *CFE_SB_MsgPayloadPtr_t;
#endif /* CFE_OMIT_DEPRECATED_6_8 */
/** \brief CFE_SB_ZeroCopyHandle_t to primitive type definition
**
** Software Zero Copy handle used in many SB APIs
*/
typedef cpuaddr CFE_SB_ZeroCopyHandle_t;
/** \brief Quality Of Service Type Definition
**
** Currently an unused parameter in #CFE_SB_SubscribeEx
** Intended to be used for interprocessor communication only
**/
typedef struct {
uint8 Priority;/**< \brief Specify high(1) or low(0) message priority for off-board routing, currently unused */
uint8 Reliability;/**< \brief Specify high(1) or low(0) message transfer reliability for off-board routing, currently unused */
}CFE_SB_Qos_t;
extern CFE_SB_Qos_t CFE_SB_Default_Qos;/**< \brief Defines a default priority and reliabilty for off-board routing */
/****************** 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[in, out] PipeIdPtr A pointer to a variable of type #CFE_SB_PipeId_t,
** 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 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 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.
**
** \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] *OptPtr A bit field of options.
**
** \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 *OptPtr);
/*****************************************************************************/
/**
** \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.
**
** \param[in] PipeNameSize The size (in chars) of the PipeName buffer.
**
** \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.
**
** \param[out] PipeIdPtr 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_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 \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 \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 \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 \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.
** Subscription Reporting is enabled for interprocessor communication
** by way of the Software Bus Network (SBN) Application.
**
** \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 \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 \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:
** None
**
** \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_NO_SUBSCRIBERS \copybrief CFE_SB_NO_SUBSCRIBERS
** \retval #CFE_SB_INTERNAL_ERR \copybrief CFE_SB_INTERNAL_ERR
**
** \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
**
** \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_NO_SUBSCRIBERS \copybrief CFE_SB_NO_SUBSCRIBERS
** \retval #CFE_SB_INTERNAL_ERR \copybrief CFE_SB_INTERNAL_ERR
**
** \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.
**
** \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.
**
** \param[in] MsgPtr A pointer to the message to be sent. This must point
** to the first byte of the message header.
** \param[in] IncrementSequenceCount Boolean to increment the internally tracked
** sequence count and update the message if the
** buffer contains a telemetry 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 \copybrief CFE_SB_BUF_ALOC_ERR
**/
CFE_Status_t CFE_SB_TransmitMsg(CFE_MSG_Message_t *MsgPtr, bool IncrementSequenceCount);
#ifndef CFE_OMIT_DEPRECATED_6_8
/*****************************************************************************/
/**
** \brief DEPRECATED: Send a software bus message
** \deprecated Use CFE_SB_TransmitMsg
**
** \par Description
** This routine sends the specified message to all subscribers. The
** software bus will read the message ID from the message header to
** determine which pipes should receive the message.
**
** \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.
** - This function tracks and increments the source sequence counter
** of a telemetry message.
**
** \param[in] MsgPtr A pointer to the message to be sent. This must point
** to the first byte of the message header.
**
** \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 \copybrief CFE_SB_BUF_ALOC_ERR
**/
CFE_Status_t CFE_SB_SendMsg(CFE_MSG_Message_t *MsgPtr);
/*****************************************************************************/
/**
** \brief DEPRECATED: Passes a software bus message
** \deprecated Use CFE_SB_TransmitMsg
**
** \par Description
** This routine sends the specified message to all subscribers. The
** software bus will read the message ID from the message header to
** determine which pipes should receive the message. This routine is
** intended to pass messages not generated by the sending application.
**
** \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 #CFE_SB_PassMsg
** returns control to the caller.
** - This routine will not modify the sequence counter in the message.
**
** \param[in] MsgPtr A pointer to the message to be sent. This must point
** to the first byte of the message header.
**
** \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 \copybrief CFE_SB_BUF_ALOC_ERR
**/
CFE_Status_t CFE_SB_PassMsg(CFE_MSG_Message_t *MsgPtr);
#endif /* CFE_OMIT_DEPRECATED_6_8 */
/*****************************************************************************/
/**
** \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.
** 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 parmeter. 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 \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);
#if CFE_OMIT_DEPRECATED_6_8
/**
* \brief DEPRECATED: receive buffer
* \deprecated use CFE_SB_ReceiveBuffer
*/
CFE_Status_t CFE_SB_RcvMsg(CFE_SB_Buffer_t **BufPtr, CFE_SB_PipeId_t PipeId, int32 TimeOut);
#endif /* CFE_OMIT_DEPRECATED_6_8 */
/**@}*/
/** @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 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.
**
** \par Assumptions, External Events, and Notes:
** -# The pointer returned by #CFE_SB_ZeroCopyGetPtr is only good for one
** call to #CFE_SB_TransmitBuffer.
** -# Applications should be written as if #CFE_SB_ZeroCopyGetPtr is
** equivalent to a \c malloc() and #CFE_SB_TransmitBuffer is equivalent to
** a \c free().
** -# Applications must not de-reference the message pointer (for reading
** or writing) after the call to #CFE_SB_TransmitBuffer.
**
** \param[in] MsgSize The size of the SB message buffer the caller wants
** (including the SB message header).
**
** \param[out] BufferHandle A handle that must be supplied when sending or releasing
** in zero copy mode.
**
** \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_ZeroCopyGetPtr(size_t MsgSize,
CFE_SB_ZeroCopyHandle_t *BufferHandle);
/*****************************************************************************/
/**
** \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_ZeroCopyGetPtr, but (due to some error condition) never uses
** that pointer for a #CFE_SB_TransmitBuffer
**
** \param[in] Ptr2Release A pointer to the SB internal buffer. This must be a
** pointer returned by a call to #CFE_SB_ZeroCopyGetPtr,
** but never used in a call to #CFE_SB_TransmitBuffer.
**
** \param[in] BufferHandle This must be the handle supplied with the pointer
** when #CFE_SB_ZeroCopyGetPtr was called.
**
** \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_ZeroCopyReleasePtr(CFE_SB_Buffer_t *Ptr2Release, CFE_SB_ZeroCopyHandle_t BufferHandle);
/*****************************************************************************/
/**
** \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_ZeroCopyGetPtr). 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.
**
** \par Assumptions, External Events, and Notes:
** -# The pointer returned by #CFE_SB_ZeroCopyGetPtr is only good for
** one call to #CFE_SB_TransmitBuffer.
** -# Callers must not use the same SB message buffer for multiple sends.
** -# Applications should be written as if #CFE_SB_ZeroCopyGetPtr is
** equivalent to a \c malloc() and #CFE_SB_TransmitBuffer is equivalent
** to a \c free().
** -# Applications must not de-reference the message pointer (for reading
** or writing) after the 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.
** \param[in] ZeroCopyHandle The handle supplied by the #CFE_SB_ZeroCopyGetPtr call
** \param[in] IncrementSequenceCount Boolean to increment the internally tracked
** sequence count and update the message if the
** buffer contains a telemetry 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 \copybrief CFE_SB_BUF_ALOC_ERR
**/
CFE_Status_t CFE_SB_TransmitBuffer(CFE_SB_Buffer_t *BufPtr,
CFE_SB_ZeroCopyHandle_t ZeroCopyHandle,
bool IncrementSequenceCount);
#ifndef CFE_OMIT_DEPRECATED_6_8
/*****************************************************************************/
/**
** \brief DEPRECATED: Send an SB message in "zero copy" mode.
** \deprecated use CFE_SB_TransmitBuffer
**
** \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_ZeroCopyGetPtr). 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.
**
** \par Assumptions, External Events, and Notes:
** -# The pointer returned by #CFE_SB_ZeroCopyGetPtr is only good for
** one call to #CFE_SB_TransmitBuffer.
** -# Callers must not use the same SB message buffer for multiple sends.
** -# Applications should be written as if #CFE_SB_ZeroCopyGetPtr is
** equivalent to a \c malloc() and #CFE_SB_TransmitBuffer is equivalent
** to a \c free().
** -# Applications must not de-reference the message pointer (for reading
** or writing) after the call to #CFE_SB_TransmitBuffer.
** -# This function tracks and increments the source sequence counter
** of a telemetry message.
**
** \param[in] BufPtr A pointer to the SB buffer to be sent.
**
** \param[in] BufferHandle The handle supplied with the #CFE_SB_ZeroCopyGetPtr call.
**
** \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 \copybrief CFE_SB_BUF_ALOC_ERR
** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID
**/
CFE_Status_t CFE_SB_ZeroCopySend(CFE_SB_Buffer_t *BufPtr, CFE_SB_ZeroCopyHandle_t BufferHandle);
/*****************************************************************************/
/**
** \brief DEPRECATED: Pass an SB message in "zero copy" mode.
** \deprecated use CFE_SB_TransmitBuffer
**
** \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_ZeroCopyGetPtr). 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. This
** version is intended to pass messages not generated by the caller
** (to preserve the source sequence count).
**
** \par Assumptions, External Events, and Notes:
** -# The pointer returned by #CFE_SB_ZeroCopyGetPtr is only good for
** one call to #CFE_SB_TransmitBuffer or #CFE_SB_ZeroCopyPass.
** -# Callers must not use the same SB message buffer for multiple sends.
** -# Applications should be written as if #CFE_SB_ZeroCopyGetPtr is
** equivalent to a \c malloc() and #CFE_SB_ZeroCopyPass is equivalent
** to a \c free().
** -# Applications must not de-reference the message pointer (for reading
** or writing) after the call to #CFE_SB_ZeroCopyPass.
** -# This routine will not modify the sequence counter in a telemetry
** message
**
** \param[in] BufPtr A pointer to the SB buffer to be sent.
**
** \param[in] BufferHandle The handle supplied with the #CFE_SB_ZeroCopyGetPtr call.
**
** \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 \copybrief CFE_SB_BUF_ALOC_ERR
** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID
**/
CFE_Status_t CFE_SB_ZeroCopyPass(CFE_SB_Buffer_t *BufPtr, CFE_SB_ZeroCopyHandle_t BufferHandle);
/**@}*/
#endif
/** @defgroup CFEAPISBSetMessage cFE Setting Message Characteristics APIs
* @{
*/
#ifndef CFE_OMIT_DEPRECATED_6_8
/*****************************************************************************/
/**
** \brief DEPRECATED - Initialize a buffer for a software bus message.
** \deprecated Use CFE_MSG_Init
**
** \par Description
** This routine fills in the header information needed to create a
** valid software bus message.
**
** \par Assumptions, External Events, and Notes:
** None
**
** \param[in] MsgPtr A pointer to the buffer that will contain the message.
** This will point to the first byte of the message header.
** The \c void* data type allows the calling routine to use
** any data type when declaring its message buffer.
**
** \param[in] MsgId The message ID to put in the message header.
**
** \param[in] Length The total number of bytes of message data, including the SB
** message header .
**
** \param[in] Clear A flag indicating whether to clear the rest of the message:
** \arg true - fill sequence count and packet data with zeroes.
** \arg false - leave sequence count and packet data unchanged.
**/
void CFE_SB_InitMsg(void *MsgPtr,
CFE_SB_MsgId_t MsgId,
size_t Length,
bool Clear );
/*****************************************************************************/
/**
** \brief DEPRECATED - Sets the message ID of a software bus message.
** \deprecated Use CFE_MSG_SetMsgId
**
** \par Description
** This routine sets the Message ID in a software bus message header.
**
** \par Assumptions, External Events, and Notes:
** None
**
** \param[in] MsgPtr A pointer to the buffer that contains the software bus message.
** This must point to the first byte of the message header.
**
** \param[in] MsgId The message ID to put into the message header.
**/
void CFE_SB_SetMsgId(CFE_MSG_Message_t *MsgPtr,
CFE_SB_MsgId_t MsgId);
#endif /* CFE_OMIT_DEPRECATED_6_8 */
/*****************************************************************************/
/**
** \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.
** 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);
#ifndef CFE_OMIT_DEPRECATED_6_8
/*****************************************************************************/
/**
** \brief DEPRECATED: Sets the total length of a software bus message.
** \deprecated Use CFE_MSG_SetSize
**
** \par Description
** This routine sets the field in the SB message header that determines
** the total length of the 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:
** None
**
** \param[in] MsgPtr A pointer to the buffer that contains the software bus message.
** This must point to the first byte of the message header.
**
** \param[in] TotalLength The length to set (total size of the message, in bytes,
** including headers).
**/
void CFE_SB_SetTotalMsgLength(CFE_MSG_Message_t *MsgPtr,size_t TotalLength);
/*****************************************************************************/
/**
** \brief Sets the time field in a software bus message.
** \deprecated Use CFE_MSG_SetMsgTime
**
** \par Description
** This routine sets the time of a software bus message. Most applications
** will want to use #CFE_SB_TimeStampMsg instead of this function. But,
** when needed, this API can be used to send a group of SB messages
** with identical time stamps.
**
** \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 to the message contents
** and will return #CFE_SB_WRONG_MSG_TYPE.
** - Note default implementation of command messages do not have a time field
** and will trigger the #CFE_SB_WRONG_MSG_TYPE error
**
** \param[in] MsgPtr A pointer to the buffer that contains the software bus message.
** This must point to the first byte of the message header.
**
** \param[in] Time The time to include in the message. This will usually be a time
** returned by the function #CFE_TIME_GetTime.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_WRONG_MSG_TYPE \copybrief CFE_SB_WRONG_MSG_TYPE
**/
CFE_Status_t CFE_SB_SetMsgTime(CFE_MSG_Message_t *MsgPtr, CFE_TIME_SysTime_t Time);
#endif /* CFE_OMIT_DEPRECATED_6_8 */
/*****************************************************************************/
/**
** \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.
** This must point to the first byte of the message header.
**/
void CFE_SB_TimeStampMsg(CFE_MSG_Message_t *MsgPtr);