diff --git a/doc/Requirements.md b/doc/Requirements.md new file mode 100644 index 0000000..3d7b469 --- /dev/null +++ b/doc/Requirements.md @@ -0,0 +1,200 @@ +--- +title: Core Flight Software - Software Bus Networking Requirements +tags: cFE SBN +abstract: Software Requirements for the Core Flight System Software Bus + Networking (SBN) application +--- + +# Software Bus Networking Requirements (cFE SBN) {#SBN} + +## SBN: Application Requirements {#SBN10} + +### SBN1000 + +SBN shall be a Core Flight Software application and comply with cFS +application interface requirements. + +### SBN1001 + +SBN shall provide one or more network modules, each of which shall interface +with a network technology over which SBN shall transmit and receive messages +from configured SBN peers. + +### SBN1001.1 + +SBN shall support zero or more networks, up to a configured maximum number of +networks. Each network may use any one of the network modules and SBN +shall allow multiple networks, each utilizing a different network module. + +### SBN1001.2 + +For each configured network, SBN shall communicate with zero or more peers, +up to a configured maximum number of peers per network, per the compile-time +limit. + +### SBN1002 + +SBN shall automatically establish and maintain connections to peers. + +*Rationale: Networks may be unreliable or otherwise experience radiation- +induced errors that may interrupt the connection.* + +### SBN1003 + +SBN shall continue to relay messages to connected peers even when some +peers in the network are not connected. + +*Rationale: Networks may be unreliable, or peers may be brought online or +offline separately from this cFS instance.* + +### SBN1004 + +SBN shall use a minimum of network and processor resources. + +*Rationale: Resources are limited and valuable.* + +### SBN1004.1 + +SBN shall interface with cFS to track all subscriptions made by local +applications and shall communicate those subscriptions to all peers. + +*Rationale: Communicating the subscription information ensures that only +messages relevant to local applications are received and only messages +relevant to remote applications are sent.* + +### SBN1004.2 + +SBN shall only send messages for peer connection awareness when required +for the network technology. + +*Rationale: Some network technologies lack an infrastructure to track +whether a connection is currently/still established. In order to communicate +subscription state information, SBN needs to be aware of the state of +connections so that if a peer connection is lost and re-established, +all local subscriptions must be retransmitted. However, network resources +are limited, so only the minimum amount of traffic shall be sent to +maintain awareness.* + +### SBN1004.3 + +When configured to do so, SBN shall filter out messages with particular +identifiers that would normally be sent to a peer. + +*Rationale: By default, SBN will send all subscribed-to messages to a peer. +There may be some configurations where this would result in a great deal of +unwanted traffic.* + +### SBN1005 + +When configured to do so, SBN shall translate local message identifiers +prior to sending to a peer. This translation shall be configurable per peer. + +*Rationale: Complex spacecraft configurations may involve multiple subsystems +managed by different organizations and may have complex configuration +management. Translations will reduce the impact of subsystem changes.* + +### SBN1006 + +All SBN headers shall be in network-byte (big-endian) order. + +*Rationale: SBN may be used in an environment where some peers are of a +different byte order.* + +### SBN1007 + +All SBN-generated protocol messages shall be in network-byte (big-endian) order. + +*Rationale: SBN may be used in an environment where some peers are of a +different byte order.* + +### SBN1008 + +SBN shall not modify messages it receives from peers and shall inject those +messages onto the local Software Bus. + +*Rationale: Until EDS is implemented in cFS, understanding the complexity +of the message structures for every message would be burdensome and, once +EDS is implemented, would become redundant.* + +### SBN1009 + +SBN shall not modify Software Bus messages it sends to peers. + +*Rationale: Until EDS is implemented in cFS, understanding the complexity +of the message structures for every message would be burdensome and, once +EDS is implemented, would become redundant.* + +### SBN1010 + +SBN shall track housekeeping information and, when commanded to do so, +transmit that information as housekeeping messages on the local Software +Bus (to be downlinked by other cFS components.) + +Housekeeping statistics to be tracked: + +- Valid commands received by this application. +- Invalid commands received by this application. +- Per-peer, the number of messages sent to a particular peer. +- Per-peer, the number of messages received from a particular peer. + +## SBN: Operational Interface {#SBN20} + +### SBN2000 + +SBN shall be configured by a cFS-standard compile-time configuration +header file, defining relevant upper and lower limits and other sizing +parameters. + +### SBN2001 + +SBN network configuration shall be described in standard cFS Tables. + +### SBN2002 + +SBN remapping/filtering configuration shall be described in standard cFS Tables. + +### SBN2003 + +SBN shall comply with Core Flight Software application interface requirements. + +### SBN2004 + +Upon receipt of a Command, SBN application shall generate a NO-OP event message. + +*Rationale: This command is useful as a general sub-system aliveness test.* + +### SBN2005 + +Upon receipt of a valid Command, SBN shall increment a valid Command +counter. + +*Rationale: The ground needs the capability to verify that the command was +received and accepted by SBN.* + +### SBN2006 + +Upon receipt of an invalid Command, SBN shall increment the invalid Command +counter and generate an event message. + +*Rationale: The ground needs an indicator if a command is rejected by SBN.* + +### SBN2007 + +Upon receipt of a Command, SBN shall send housekeeping telemetry indicating +the operating status of the application. + +*Rationale: The ground needs an indicator of the current running state of SBN.* + +### SBN2008 + +Upon receipt of a Command, SBN shall send housekeeping telemetry indicating +the current operating status regarding a particular peer. + +*Rationale: The ground needs an indicator of the current running state of SBN.* + +### SBN2009 + +Upon receipt of a Command, SBN shall set to zero the housekeeping statistics. + +*Rationale: This command is a common feature in heritage sub-system software +design.* diff --git a/fsw/platform_inc/sbn_interfaces.h b/fsw/platform_inc/sbn_interfaces.h index 1fc44b8..0e080df 100644 --- a/fsw/platform_inc/sbn_interfaces.h +++ b/fsw/platform_inc/sbn_interfaces.h @@ -281,20 +281,6 @@ struct SBN_IfOps_s { */ int (*ReportModuleStatus)(SBN_ModuleStatusPacket_t *Buffer); - /** - * Resets a specific peer. - * This function must be present, but can simply return SBN_NOT_IMPLEMENTED - * if it is not used by or not applicable to a module. - * - * @param Peer[in] Peer to reset - * - * @return SBN_SUCCESS when the peer is reset correctly. - * SBN_ERROR if the peer cannot be reset. - * SBN_NOT_IMPLEMENTED if the module does not implement this - * function. - */ - int (*ResetPeer)(SBN_PeerInterface_t *Peer); - /** * Unload a network. This will unload all associated peers as well. * diff --git a/fsw/platform_inc/sbn_msgdefs.h b/fsw/platform_inc/sbn_msgdefs.h index e3a2071..8464adc 100644 --- a/fsw/platform_inc/sbn_msgdefs.h +++ b/fsw/platform_inc/sbn_msgdefs.h @@ -2,18 +2,14 @@ #define _sbn_msgdefs_h_ #define SBN_NOOP_CC 0 -#define SBN_RESET_CC 1 -#define SBN_RESET_PEER_CC 2 - -#define SBN_REMAPCFG_CC 5 -#define SBN_REMAPADD_CC 6 -#define SBN_REMAPDEL_CC 7 #define SBN_HK_CC 10 #define SBN_HK_NET_CC 11 #define SBN_HK_PEER_CC 12 #define SBN_HK_PEERSUBS_CC 13 #define SBN_HK_MYSUBS_CC 14 +#define SBN_HK_RESET_CC 15 +#define SBN_HK_RESET_PEER_CC 16 #define SBN_SCH_WAKEUP_CC 100 #define SBN_TBL_CC 110 diff --git a/fsw/src/sbn_cmds.c b/fsw/src/sbn_cmds.c index 3cac8e7..45a93f7 100644 --- a/fsw/src/sbn_cmds.c +++ b/fsw/src/sbn_cmds.c @@ -6,11 +6,25 @@ #include "sbn_remap.h" #include "sbn_pack.h" -/*******************************************************************/ -/* */ -/* Reset telemetry counters */ -/* */ -/*******************************************************************/ +/** + * @brief Initializes the housekeeping counters for a peer. + * + * @param[in] Peer The peer interface for which to reset housekeeping. + */ +static void InitializePeerCounters(SBN_PeerInterface_t *Peer) +{ + Peer->LastSend = (OS_time_t){0, 0}; + Peer->LastRecv = (OS_time_t){0, 0}; + Peer->SendCnt = 0; + Peer->RecvCnt = 0; + Peer->SendErrCnt = 0; + Peer->RecvErrCnt = 0; +}/* end InitializePeerCounters() */ + +/** + * @brief Initializes the housekeeping counters both at the app level + * and for each peer. + */ void SBN_InitializeCounters(void) { SBN.CmdCnt = 0; @@ -24,16 +38,13 @@ void SBN_InitializeCounters(void) for(PeerIdx = 0; PeerIdx < Net->PeerCnt; PeerIdx++) { SBN_PeerInterface_t *Peer = &Net->Peers[PeerIdx]; - Peer->SendCnt = 0; - Peer->RecvCnt = 0; - Peer->SendErrCnt = 0; - Peer->RecvErrCnt = 0; + InitializePeerCounters(Peer); }/* end for */ }/* end for */ }/* end SBN_InitializeCounters */ /************************************************************************/ -/** \brief Verify message length +/** \brief Verify message length. ** ** \par Description ** Checks if the actual length of a software bus message matches @@ -153,7 +164,7 @@ static void NoopCmd(CFE_SB_MsgPtr_t MsgPtr) ** \sa #SBN_RESET_CC ** *************************************************************************/ -static void ResetCountersCmd(CFE_SB_MsgPtr_t MsgPtr) +static void HKResetCmd(CFE_SB_MsgPtr_t MsgPtr) { if(!VerifyMsgLen(MsgPtr, CFE_SB_CMD_HDR_SIZE, "reset counters")) { @@ -166,13 +177,13 @@ static void ResetCountersCmd(CFE_SB_MsgPtr_t MsgPtr) ** Don't increment counter because we're resetting anyway */ SBN_InitializeCounters(); -}/* end ResetCountersCmd */ +}/* end HKResetCmd */ /************************************************************************/ -/** \brief Reset Peer +/** \brief Reset Peer counters command ** ** \par Description -** Reset a specified peer. +** Reset the counters for a specified peer. ** ** \par Assumptions, External Events, and Notes: ** None @@ -183,7 +194,7 @@ static void ResetCountersCmd(CFE_SB_MsgPtr_t MsgPtr) ** \sa #SBN_RESET_PEER_CC ** *************************************************************************/ -static void ResetPeerCmd(CFE_SB_MsgPtr_t MsgPtr) +static void HKResetPeerCmd(CFE_SB_MsgPtr_t MsgPtr) { if(!VerifyMsgLen(MsgPtr, SBN_CMD_PEER_LEN, "reset peer")) { @@ -213,115 +224,12 @@ static void ResetPeerCmd(CFE_SB_MsgPtr_t MsgPtr) SBN_PeerInterface_t *Peer = &Net->Peers[PeerIdx]; CFE_EVS_SendEvent(SBN_CMD_EID, CFE_EVS_INFORMATION, - "reset peer command (NetIdx=%d, PeerIdx=%d)", + "hk reset peer command (NetIdx=%d, PeerIdx=%d)", NetIdx, PeerIdx); SBN.CmdCnt++; - - if(Net->IfOps->ResetPeer(Peer) == SBN_NOT_IMPLEMENTED) - { - CFE_EVS_SendEvent(SBN_CMD_EID, CFE_EVS_INFORMATION, - "reset peer not implemented for net"); - }/* end if */ -}/* end ResetPeerCmd */ - -/************************************************************************/ -/** \brief Configure Remapping behavior. -** -** \par Description -** Configure the remapping behavior (enabling/disabling, defining -** default behavior for when a MID is not in the remap table.) -** -** \par Assumptions, External Events, and Notes: -** None -** -** \param [in] MsgPtr A #CFE_SB_MsgPtr_t pointer that -** references the software bus message -** -** \sa #SBN_REMAPCFG_CC -** -*************************************************************************/ -static void RemapCfgCmd(CFE_SB_MsgPtr_t MsgPtr) -{ - if(!VerifyMsgLen(MsgPtr, SBN_CMD_REMAPCFG_LEN, "remap cfg")) - { - return; - }/* end if */ - - uint8 *Ptr = (uint8 *)MsgPtr + CFE_SB_CMD_HDR_SIZE; - SBN.RemapEnabled = *Ptr++; - SBN.RemapTbl->RemapDefaultFlag = *Ptr; - - CFE_EVS_SendEvent(SBN_CMD_EID, CFE_EVS_INFORMATION, - "remap cfg (RemapEnabled=%d, RemapDefaultFlag=%d)", - SBN.RemapEnabled, SBN.RemapTbl->RemapDefaultFlag); -}/* end RemapCfgCmd */ - -/************************************************************************/ -/** \brief Add remapping behavior. -** -** \par Description -** Adds a remapping to the remapping table. -** -** \par Assumptions, External Events, and Notes: -** Will fail if there is insufficient space in the table. -** -** \param [in] MsgPtr A #CFE_SB_MsgPtr_t pointer that -** references the software bus message -** -** \sa #SBN_REMAPADD_CC -** -*************************************************************************/ -static void RemapAddCmd(CFE_SB_MsgPtr_t MsgPtr) -{ - if(!VerifyMsgLen(MsgPtr, SBN_CMD_REMAPADD_LEN, "remap add")) - { - return; - }/* end if */ - - uint8 *Ptr = (uint8 *)MsgPtr + CFE_SB_CMD_HDR_SIZE; - uint32 ProcessorID = *((uint32 *)Ptr); Ptr += sizeof(ProcessorID); - CFE_SB_MsgId_t FromMID = *((CFE_SB_MsgId_t *)Ptr); Ptr += sizeof(FromMID); - CFE_SB_MsgId_t ToMID = *((CFE_SB_MsgId_t *)Ptr); - - CFE_EVS_SendEvent(SBN_CMD_EID, CFE_EVS_INFORMATION, - "remap add (ProcessorID=%d, FromMID=0x%04x, ToMID=0x%04x)", - ProcessorID, FromMID, ToMID); - SBN_RemapAdd(ProcessorID, FromMID, ToMID); -}/* end RemapAddCmd */ - -/************************************************************************/ -/** \brief Delete remapping behavior. -** -** \par Description -** Deletes a remapping from the remapping table. -** -** \par Assumptions, External Events, and Notes: -** Will do nothing if the entry does not exist in the table. -** -** \param [in] MsgPtr A #CFE_SB_MsgPtr_t pointer that -** references the software bus message -** -** \sa #SBN_REMAPDEL_CC -** -*************************************************************************/ -static void RemapDelCmd(CFE_SB_MsgPtr_t MsgPtr) -{ - if(!VerifyMsgLen(MsgPtr, SBN_CMD_REMAPDEL_LEN, "remap del")) - { - return; - }/* end if */ - - uint8 *Ptr = (uint8 *)MsgPtr + CFE_SB_CMD_HDR_SIZE; - uint32 ProcessorID = *((uint32 *)Ptr); Ptr += sizeof(ProcessorID); - CFE_SB_MsgId_t FromMID = *((CFE_SB_MsgId_t *)Ptr); - - CFE_EVS_SendEvent(SBN_CMD_EID, CFE_EVS_INFORMATION, - "remap del (ProcessorID=%d, FromMID=0x%04x)", - ProcessorID, FromMID); - - SBN_RemapDel(ProcessorID, FromMID); -}/* end RemapDelCmd */ + InitializePeerCounters(Peer); +}/* end HKResetPeerCmd */ /** \brief Housekeeping request command * @@ -649,22 +557,6 @@ void SBN_HandleCommand(CFE_SB_MsgPtr_t MsgPtr) case SBN_NOOP_CC: NoopCmd(MsgPtr); break; - case SBN_RESET_CC: - ResetCountersCmd(MsgPtr); - break; - case SBN_RESET_PEER_CC: - ResetPeerCmd(MsgPtr); - break; - - case SBN_REMAPCFG_CC: - RemapCfgCmd(MsgPtr); - break; - case SBN_REMAPADD_CC: - RemapAddCmd(MsgPtr); - break; - case SBN_REMAPDEL_CC: - RemapDelCmd(MsgPtr); - break; case SBN_HK_CC: HKCmd(MsgPtr); @@ -681,6 +573,13 @@ void SBN_HandleCommand(CFE_SB_MsgPtr_t MsgPtr) case SBN_HK_MYSUBS_CC: MySubsCmd(MsgPtr); break; + case SBN_HK_RESET_CC: + HKResetCmd(MsgPtr); + break; + case SBN_HK_RESET_PEER_CC: + HKResetPeerCmd(MsgPtr); + break; + case SBN_SCH_WAKEUP_CC: CFE_EVS_SendEvent(SBN_CMD_EID, CFE_EVS_DEBUG, "wakeup");