CORDET Framework - C2 Implementation
CrFwOutStream.c File Reference

Implementation of OutStream State Machine. More...

Go to the source code of this file.

Functions

static void EnqueuePckt (FwSmDesc_t smDesc)
 Function which enqueues a packet on the packet queue. More...
 
static void FlushPcktQueue (FwSmDesc_t smDesc)
 Function which flushes the packet queue. More...
 
static void ResetSeqAndTypeCounters (FwSmDesc_t smDesc)
 Function which resets to 1 all sequence and type counters of the OutStreams. More...
 
static void SendOrEnqueue (FwSmDesc_t smDesc)
 Function which first attempts to hand over a packet to the middleware and, if this fails, it pushes it on the packet queue. More...
 
static int IsPacketQueueEmpty (FwSmDesc_t smDesc)
 Function which checks if the packet queue is empty. More...
 
static CrFwTypeCnt_t GetDestTypeKeyPos (CrFwPckt_t pckt)
 Compute the destination-type key of the argument packet and returns its position (starting from zero) in the array of destination-type keys outStreamDestTypeKey. More...
 
FwSmDesc_t CrFwOutStreamMake (CrFwInstanceId_t i)
 Factory function to retrieve the i-th OutStream State Machine instance. More...
 
CrFwBool_t CrFwOutStreamIsInReady (FwSmDesc_t smDesc)
 Return true if the argument OutStream is in state READY. More...
 
CrFwBool_t CrFwOutStreamIsInBuffering (FwSmDesc_t smDesc)
 Return true if the argument OutStream is in state BUFFERING. More...
 
FwSmDesc_t CrFwOutStreamGet (CrFwDestSrc_t dest)
 Getter function for the OutStream corresponding to the argument destination. More...
 
CrFwDestSrc_t CrFwOutStreamGetDest (FwSmDesc_t outStream, CrFwCounterU1_t i)
 Return the i-th destination associated to the argument outStream. More...
 
CrFwCounterU1_t CrFwOutStreamGetNOfDest (FwSmDesc_t outStream)
 Return the number of destinations associated to the argument outStream. More...
 
void CrFwOutStreamSend (FwSmDesc_t smDesc, CrFwPckt_t pckt)
 Send a packet to the OutStream. More...
 
void CrFwOutStreamConnectionAvail (FwSmDesc_t smDesc)
 Signal that the out-going middleware connection has become available. More...
 
CrFwSeqCnt_t CrFwOutStreamGetSeqCnt (CrFwGroup_t group)
 Return the value of the sequence counter for one of the groups maintained by the OutStreams. More...
 
void CrFwOutStreamSetSeqCnt (CrFwGroup_t group, CrFwSeqCnt_t seqCnt)
 Sets the value of the sequence counter for one of the groups maintained by the OutStreams. More...
 
CrFwCounterU1_t CrFwOutStreamGetNOfPendingPckts (FwSmDesc_t smDesc)
 Return the number of packets currently in the packet queue of an OutStream. More...
 
CrFwGroup_t CrFwOutStreamGetNOfGroups ()
 Return the number of groups associated to the OutStreams. More...
 
CrFwCounterU1_t CrFwOutStreamGetPcktQueueSize (FwSmDesc_t smDesc)
 Return the size of the packet queue of the OutStream. More...
 
void CrFwOutStreamDefConfigAction (FwPrDesc_t prDesc)
 Default configuration action for an OutStream. More...
 
void CrFwOutStreamDefShutdownAction (FwSmDesc_t smDesc)
 Default shutdown action for an OutStream. More...
 
void CrFwOutStreamDefInitAction (FwPrDesc_t prDesc)
 Default initialization action for an OutStream. More...
 
void CrFwOutStreamDefSetDTS (CrFwCounterU2_t *pNofTypeCounter, CrFwDestTypeKey_t **pDestTypeKey)
 Default implementation of Set DST Function for the OutStreams. More...
 
CrFwCounterU2_t CrFwOutStreamGetNOfTypeCounters ()
 Return the number of type counters maintained by the OutStreams. More...
 
CrFwTypeCnt_t CrFwOutStreamGetTypeCounter (CrFwDestSrc_t dest, CrFwServType_t servType, CrFwServSubType_t servSubType)
 Return the current type counter for a (destination, type, sub-type) triplet or zero if the triplet is not in DTS_SET. More...
 
CrFwBool_t CrFwOutStreamIsInDtsSet (CrFwDestSrc_t dest, CrFwServType_t servType, CrFwServSubType_t servSubType)
 Check whether the (destination, type, sub-type) triplet is in DTS_SET. More...
 

Variables

static FwSmDesc_t baseOutStreamSmDesc = NULL
 Base OutStream from which all other OutStreams are derived.
 
static CrFwCounterU1_t outStreamPcktQueueSize [CR_FW_NOF_OUTSTREAM] = CR_FW_OUTSTREAM_PQSIZE
 The sizes of the packet queues in the OutStream components.
 
static CrFwDestSrc_t outStreamDestPairs [CR_FW_OUTSTREAM_NOF_DEST][2] = CR_FW_OUTSTREAM_DEST_PAIRS
 The (destination, outStream) pairs.
 
static CrFwDestSrc_toutStreamDest [CR_FW_NOF_OUTSTREAM]
 The destinations associated to each outStream.
 
static CrFwDestSrc_t outStreamNofDest [CR_FW_NOF_OUTSTREAM]
 The number of destinations associated to each outStream.
 
static CrFwSeqCnt_t outStreamSeqCounter [CR_FW_OUTSTREAM_NOF_GROUPS]
 The sequence counters managed by the OutStreams.
 
static CrFwCounterU2_t outStreamNofTypeCounter = 0
 The number of type counters maintained by the OutStreams.
 
static CrFwTypeCnt_toutStreamTypeCounter = NULL
 The type counters managed by the OutStreams. More...
 
static CrFwDestTypeKey_toutStreamDestTypeKey = NULL
 Array of destination-type keys. More...
 
static CrFwSetDst_t outStreamSetDts = CR_FW_OUTSTREAM_SET_DTS
 The function implementing the Set DTS Operation.
 
static CrFwPcktHandover_t outStreamHandoverPckt [CR_FW_NOF_OUTSTREAM] = CR_FW_OUTSTREAM_PCKTHANDOVER
 The functions implementing the packet hand-over operations for the OutStream components.
 
static FwPrAction_t outStreamInitCheck [CR_FW_NOF_OUTSTREAM] = CR_FW_OUTSTREAM_INITCHECK
 The functions implementing the initialization checks for the InStream components.
 
static FwPrAction_t outStreamInitAction [CR_FW_NOF_OUTSTREAM] = CR_FW_OUTSTREAM_INITACTION
 The functions implementing the initialization actions for the InStream components.
 
static FwPrAction_t outStreamConfigCheck [CR_FW_NOF_OUTSTREAM] = CR_FW_OUTSTREAM_CONFIGCHECK
 The functions implementing the configuration checks for the InStream components.
 
static FwPrAction_t outStreamConfigAction [CR_FW_NOF_OUTSTREAM] = CR_FW_OUTSTREAM_CONFIGACTION
 The functions implementing the configuration actions for the InStream components.
 
static FwSmAction_t outStreamShutdownAction [CR_FW_NOF_OUTSTREAM] = CR_FW_OUTSTREAM_SHUTDOWNACTION
 The functions implementing the shutdown actions for the InStream components.
 
static FwSmDesc_t outStreamDesc [CR_FW_NOF_OUTSTREAM]
 The descriptors of the OutStream State Machines.
 
static CrFwCmpData_t outStreamData [CR_FW_NOF_OUTSTREAM]
 The base data structures for the OutStream State Machines and their Procedures.
 
static CrFwOutStreamData_t outStreamCmpSpecificData [CR_FW_NOF_OUTSTREAM]
 The component-specific data for the OutStream State Machines and their Procedures.
 

Detailed Description

Implementation of OutStream State Machine.

Author
Vaclav Cechticky vacla.nosp@m.v.ce.nosp@m.chtic.nosp@m.ky@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m
Alessandro Pasetti paset.nosp@m.ti@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m

This file is part of the CORDET Framework.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

For information on alternative licensing, please contact P&P Software GmbH.

Definition in file CrFwOutStream.c.

Function Documentation

◆ CrFwOutStreamConnectionAvail()

void CrFwOutStreamConnectionAvail ( FwSmDesc_t  smDesc)

Signal that the out-going middleware connection has become available.

This function sends the ConnectionAvailable command to the OutStream State Machine.

Parameters
smDescthe descriptor of the OutStream State Machine.

Definition at line 329 of file CrFwOutStream.c.

◆ CrFwOutStreamDefConfigAction()

void CrFwOutStreamDefConfigAction ( FwPrDesc_t  prDesc)

Default configuration action for an OutStream.

This function resets the packet queue of the OutStream.

Configuration actions have an outcome (see CrFwResetProc.h). The outcome of this configuration action is always "success".

This function should never be directly called by the end-application. It is declared as a public function so that it may be used in application-specific Configuration Actions.

Parameters
prDescthe descriptor of the Reset Procedure of the OutStream

Definition at line 363 of file CrFwOutStream.c.

◆ CrFwOutStreamDefInitAction()

void CrFwOutStreamDefInitAction ( FwPrDesc_t  prDesc)

Default initialization action for an OutStream.

This function allocates the memory for the packet queue of the OutStream and for the array holding the destinations associated to the outStream, The situation of where the memory allocation fails is not handled and therefore the outcome of this configuration action is always "success".

This function should never be directly called by the end-application. It is declared as a public function so that it may be used in application-specific Initialization Actions.

Parameters
prDescthe descriptor of the Initialization Procedure of the OutStream

Definition at line 384 of file CrFwOutStream.c.

◆ CrFwOutStreamDefSetDTS()

void CrFwOutStreamDefSetDTS ( CrFwCounterU2_t pNofTypeCounter,
CrFwDestTypeKey_t **  destTypeKey 
)

Default implementation of Set DST Function for the OutStreams.

The Set DTS Function is responsible for defining the DTS_SET. The DTS_SET defines the triplets (destination,type,sub-type) for which the OutStream maintain a type counter.

The Set DTS function computes and returns:

  • The number of type counters to be managed by the OutStreams
  • The array of destination-type keys for which type counters must be maintained

This default implementation builds DTS_SET by collecting all the types and sub-types (t,s) of the out-going reports defined in CR_FW_OUTCMP_INIT_KIND_DESC and then building all triplets for the case of the destination ID being equal to 1.

This function allocates the memory for array outStreamDestTypeKey using malloc. It is therefore only suitable for use during the application initialization phase.

Parameters
pNofTypeCounterpointer to variable holding the number of type counters (i.e. the number of triplets (d,t,s) in DTS_SET)
destTypeKeypointer to array of products d*t*s for all triplets (d,t,s) in DTS_SET arranged in increasing order

Definition at line 579 of file CrFwOutStream.c.

◆ CrFwOutStreamDefShutdownAction()

void CrFwOutStreamDefShutdownAction ( FwSmDesc_t  smDesc)

Default shutdown action for an OutStream.

This function resets the packet queue and releases the memory allocated to it and to the array holding the destinations associated to the outStream.

This function should never be directly called by the end-application. It is declared as a public function so that it may be used in application-specific Shutdown Actions.

Parameters
smDescthe descriptor of the OutStream State Machine

Definition at line 373 of file CrFwOutStream.c.

◆ CrFwOutStreamGet()

FwSmDesc_t CrFwOutStreamGet ( CrFwDestSrc_t  dest)

Getter function for the OutStream corresponding to the argument destination.

An OutStream is associated to one or more destinations. The binding between an OutStream and its destinations is done statically in the configuration file CrFwOutStreamUserPar.h.

If the value of the destination argument is illegal (i.e. if no OutStream has been bound to it), this function returns NULL and sets the application error code to: crOutStreamUndefDest.

This function should only be called after all OutStreams have been built through calls to function CrFwOutStreamMake. If this pre-condition is not satisfied, execution of this function could result in an access to a NULL pointer.

Parameters
destthe destination associated to the OutStream
Returns
the descriptor of the OutStream State Machine or NULL if the argument destination was illegal or no OutStream had been bound to it.

Definition at line 293 of file CrFwOutStream.c.

◆ CrFwOutStreamGetDest()

CrFwDestSrc_t CrFwOutStreamGetDest ( FwSmDesc_t  outStream,
CrFwCounterU1_t  i 
)

Return the i-th destination associated to the argument outStream.

The value of i must be in the range 1 to N with N being the number of destinations associated to the outStream as returned by function CrFwOutStreamGetNOfDest. If this constraint is violated, the return value of the function is unpredictable.

The binding between an OutStream and its destinations is done statically in the array CR_FW_OUTSTREAM_DEST_PAIRS. The first destination associated to the outStream is the destination in the first pair of CR_FW_OUTSTREAM_DEST_PAIRS whicih is associated to the outStream; the second destination associated to it is the destination in the second pair; etc.

This function may only be called after the outStream has been initialized.

Parameters
outStreamthe outStream
ithe index of the desired destination (starting from 1)
Returns
the i-th destination of the outStream

Definition at line 306 of file CrFwOutStream.c.

◆ CrFwOutStreamGetNOfDest()

CrFwCounterU1_t CrFwOutStreamGetNOfDest ( FwSmDesc_t  outStream)

Return the number of destinations associated to the argument outStream.

The binding between an OutStream and its destinations is done statically in the array CR_FW_OUTSTREAM_DEST_PAIRS. This function may only be called after the outStream has been initialized.

Parameters
outStreamthe outStream
Returns
the number of destinations associated to the outStream

Definition at line 314 of file CrFwOutStream.c.

◆ CrFwOutStreamGetNOfGroups()

CrFwGroup_t CrFwOutStreamGetNOfGroups ( )

Return the number of groups associated to the OutStreams.

Returns
the number of groups associated to the OutStreams.

Definition at line 351 of file CrFwOutStream.c.

◆ CrFwOutStreamGetNOfPendingPckts()

CrFwCounterU1_t CrFwOutStreamGetNOfPendingPckts ( FwSmDesc_t  smDesc)

Return the number of packets currently in the packet queue of an OutStream.

Parameters
smDescthe descriptor of the OutStream State Machine.
Returns
the number of packets currently in the packet queue of the OutStream.

Definition at line 344 of file CrFwOutStream.c.

◆ CrFwOutStreamGetNOfTypeCounters()

CrFwCounterU2_t CrFwOutStreamGetNOfTypeCounters ( )

Return the number of type counters maintained by the OutStreams.

Returns
the number of type counters maintained by the OutStreams.

Definition at line 618 of file CrFwOutStream.c.

◆ CrFwOutStreamGetPcktQueueSize()

CrFwCounterU1_t CrFwOutStreamGetPcktQueueSize ( FwSmDesc_t  smDesc)

Return the size of the packet queue of the OutStream.

Parameters
smDescthe descriptor of the OutStream State Machine.
Returns
the size of the packet queue of the OutStream.

Definition at line 356 of file CrFwOutStream.c.

◆ CrFwOutStreamGetSeqCnt()

CrFwSeqCnt_t CrFwOutStreamGetSeqCnt ( CrFwGroup_t  group)

Return the value of the sequence counter for one of the groups maintained by the OutStreams.

The group identifier is passed as an argument to the function call. No check is performed on the validity of the group identifier.

Parameters
groupthe identifier of the group
Returns
the OutStream sequence counter

Definition at line 334 of file CrFwOutStream.c.

◆ CrFwOutStreamGetTypeCounter()

CrFwTypeCnt_t CrFwOutStreamGetTypeCounter ( CrFwDestSrc_t  dest,
CrFwServType_t  servType,
CrFwServSubType_t  servSubType 
)

Return the current type counter for a (destination, type, sub-type) triplet or zero if the triplet is not in DTS_SET.

The value returned by this function is the type counter which the OutStream will allocate to the next out-going packet with the argument destination, type and sub-type. If the (destination, type, sub-type) is not in DTS_SET, then zero is returned.

This function may only be called after the DTS_SET has been built. The DTS_SET is built the first time function CrFwOutStreamMake is called.

Parameters
destthe packet destination
servTypethe packet service type
servSubTypethe packet service sub-type
Returns
the type counter for the argument (destination, type, sub-type) triplet.

Definition at line 623 of file CrFwOutStream.c.

◆ CrFwOutStreamIsInBuffering()

CrFwBool_t CrFwOutStreamIsInBuffering ( FwSmDesc_t  smDesc)

Return true if the argument OutStream is in state BUFFERING.

Parameters
smDescthe descriptor of the Base State Machine of the OutStream
Returns
1 if the argument InCommand is in state CONFIGURED, sub-state BUFFERING; 0 otherwise

Definition at line 288 of file CrFwOutStream.c.

◆ CrFwOutStreamIsInDtsSet()

CrFwBool_t CrFwOutStreamIsInDtsSet ( CrFwDestSrc_t  dest,
CrFwServType_t  servType,
CrFwServSubType_t  servSubType 
)

Check whether the (destination, type, sub-type) triplet is in DTS_SET.

This function may only be called after the DTS_SET has been built. The DTS_SET is built the first time function CrFwOutStreamMake is called.

Parameters
destthe packet destination
servTypethe packet service type
servSubTypethe packet service sub-type
Returns
the number of type counters maintained by the OutStreams.

Definition at line 634 of file CrFwOutStream.c.

◆ CrFwOutStreamIsInReady()

CrFwBool_t CrFwOutStreamIsInReady ( FwSmDesc_t  smDesc)

Return true if the argument OutStream is in state READY.

Parameters
smDescthe descriptor of the Base State Machine of the OutStream
Returns
1 if the argument InCommand is in state CONFIGURED, sub-state READY; 0 otherwise

Definition at line 283 of file CrFwOutStream.c.

◆ CrFwOutStreamMake()

FwSmDesc_t CrFwOutStreamMake ( CrFwInstanceId_t  outStreamId)

Factory function to retrieve the i-th OutStream State Machine instance.

The first time this function is called with a certain value of the argument i, it creates the i-th OutStream State Machine instance. Subsequent calls returns the same instance.

The OutStream identifier outStreamId must be in the range: [0, CR_FW_NOF_OUTSTREAM-1]. If the identifier is out of range, the function returns NULL and sets the application error code to: crOutStreamIllId.

The first time this function is called with a certain value of i, it returns an OutStream State Machine which has been started but which still needs to be initialized and configured.

The first time this function is called, it builds the DTS_SET by calling the function CR_FW_OUTSTREAM_SET_DTS. The number of elements in the DTS_SET is then used to allocate the memory for the array holding the type counters (since there is one type counter for each element of DTS_SET).

Parameters
outStreamIdthe identifier of the Base State Machine of the OutStream
Returns
the descriptor of the OutStream State Machine or NULL if the state machine could not be created or if the identifier outStreamId is out of range.

Definition at line 193 of file CrFwOutStream.c.

◆ CrFwOutStreamSend()

void CrFwOutStreamSend ( FwSmDesc_t  smDesc,
CrFwPckt_t  pckt 
)

Send a packet to the OutStream.

This function hands over the argument packet to the OutStream and then it sends command "Send" to its state machine. This causes the OutStream to try to send the packet to the destination associated to the OutStream. If the middleware is not ready to accept the packet, then a copy of the packet is made and is stored in the OutStream's Packet Queue from where it will be sent to the middleware at a later time. If the packet copy cannot be done because no more free packets are available, error crOutStreamNoMorePckt is generated. If the Packet Queue is full, the packet is released and error crOutStreamPQFull is generated.

If packet cannot be sent to the middleware (or to make a copy of the packet and buffer the copy internally if the middleware is currently not available).

The argument pckt is a pointer to the out-going packet. This pointer is "owned" by the caller of function CrFwOutStreamSend who remains responsible for releasing it when it is no longer needed. The function only uses the pointer during its execution.

Parameters
smDescthe descriptor of the OutStream State Machine.
pcktthe packet to be sent by the OutStream

Definition at line 321 of file CrFwOutStream.c.

◆ CrFwOutStreamSetSeqCnt()

void CrFwOutStreamSetSeqCnt ( CrFwGroup_t  group,
CrFwSeqCnt_t  seqCnt 
)

Sets the value of the sequence counter for one of the groups maintained by the OutStreams.

The group identifier is passed as an argument to the function call. No check is performed on the validity of the group identifier.

Parameters
groupthe identifier of the group
seqCntthe OutStream sequence counter

Definition at line 339 of file CrFwOutStream.c.

◆ EnqueuePckt()

static void EnqueuePckt ( FwSmDesc_t  smDesc)
static

Function which enqueues a packet on the packet queue.

The packet to be enqueued is taken from the data associated to OutStream State Machine. This function is used as the transition action for the self-transition on the BUFFERING state and as a transition action on the transition out of the READY state. If the packet cannot be enqueued because the packet queue is full, an error is generated and the packet is released.

Parameters
smDescthe state machine descriptor

Definition at line 416 of file CrFwOutStream.c.

◆ FlushPcktQueue()

static void FlushPcktQueue ( FwSmDesc_t  smDesc)
static

Function which flushes the packet queue.

This function is used as the transition action on the transition out of state BUFFERING.

Parameters
smDescthe state machine descriptor

Definition at line 439 of file CrFwOutStream.c.

◆ GetDestTypeKeyPos()

static CrFwTypeCnt_t GetDestTypeKeyPos ( CrFwPckt_t  pckt)
static

Compute the destination-type key of the argument packet and returns its position (starting from zero) in the array of destination-type keys outStreamDestTypeKey.

If the destination-type key of the argument packet is not in the array outStreamDestTypeKey, then the length of the of the array is returned. Packets whose destination-type key is not in array outStreamDestTypeKey are those for which the type counter does not need to be maintained and can be set to zero.

Parameters
pcktthe packet whose destination-type key is computed
Returns
the position of the packet's destination-type key in array outStreamDestTypeKey or the array's length if the packet's destination-type key is not found

Definition at line 557 of file CrFwOutStream.c.

◆ IsPacketQueueEmpty()

static int IsPacketQueueEmpty ( FwSmDesc_t  smDesc)
static

Function which checks if the packet queue is empty.

This function is used as guard for the transition into state READY.

Parameters
smDescthe state machine descriptor
Returns
1 if the packet queue is empty; zero otherwise.

Definition at line 572 of file CrFwOutStream.c.

◆ ResetSeqAndTypeCounters()

static void ResetSeqAndTypeCounters ( FwSmDesc_t  smDesc)
static

Function which resets to 1 all sequence and type counters of the OutStreams.

This function is used as transition action on the transition out of the initial state of an OutStream state machine. Note that this means that, if an application has more than one OutStream, this action will be called multiple times during the application's initialization.

Parameters
smDescthe state machine descriptor

Definition at line 487 of file CrFwOutStream.c.

◆ SendOrEnqueue()

static void SendOrEnqueue ( FwSmDesc_t  smDesc)
static

Function which first attempts to hand over a packet to the middleware and, if this fails, it pushes it on the packet queue.

This function is used as the transition action out of state READY.

Parameters
smDescthe state machine descriptor

Definition at line 501 of file CrFwOutStream.c.

Variable Documentation

◆ outStreamDestTypeKey

CrFwDestTypeKey_t* outStreamDestTypeKey = NULL
static

Array of destination-type keys.

A destination-type key is an unsigned integer obtained as the product of: t*s_max*d_max + s*d_max + d, where d, t, and s are a destination identifier, a service type identifier and a service sub-type identifier for which a type counter is maintained by the OutStreams and d_max and s_max are the maximum value of d and s (as given by constants CR_FW_MAX_DEST and CR_FW_MAX_SERV_SUBTYPE).

The entries in this array are populated by function CR_FW_OUTSTREAM_SET_DTS. They hold all the destination-type triplets for which a type counter is maintained. The entries in the array are arranged in increasing order so that the arrays can be searched through utility function CrFwFindKeyIndex. The size of this array should be equal to the value of outStreamNofTypeCounter.

Definition at line 95 of file CrFwOutStream.c.

◆ outStreamTypeCounter

CrFwTypeCnt_t* outStreamTypeCounter = NULL
static

The type counters managed by the OutStreams.

This array has (outStreamNofTypeCounter+1) entries. The first outStreamNofTypeCounter entries are the type counters. The last entry is always equal to zero.

Definition at line 77 of file CrFwOutStream.c.

P&P Software GmbH, Copyright 2012-2013, All Rights Reserved