CORDET Framework - C2 Implementation
CrFwOutFactory.c File Reference

Implementation of OutFactory component. More...

Go to the source code of this file.

Functions

static void OutFactoryInitAction (FwPrDesc_t initPr)
 Initialization action for OutFactory. More...
 
static void OutFactoryConfigAction (FwPrDesc_t initPr)
 Configuration action for OutFactory. More...
 
static void OutFactoryShutdownAction (FwSmDesc_t smDesc)
 Shutdown action for OutFactory. More...
 
FwSmDesc_t CrFwOutFactoryMake ()
 Factory function for the singleton instance of the OutFactory. More...
 
FwSmDesc_t CrFwOutFactoryMakeOutCmp (CrFwServType_t type, CrFwServSubType_t subType, CrFwDiscriminant_t discriminant, CrFwPcktLength_t length)
 Make function for an OutComponent. More...
 
void CrFwOutFactoryReleaseOutCmp (FwSmDesc_t outCmpInstance)
 Release function for an OutComponent. More...
 
CrFwOutFactoryPoolIndex_t CrFwOutFactoryGetNOfAllocatedOutCmp ()
 Return the number of OutComponents which are currently allocated. More...
 
CrFwOutFactoryPoolIndex_t CrFwOutFactoryGetMaxNOfOutCmp ()
 Return the maximum number of OutComponents which may be allocated at any one time. More...
 
CrFwInstanceId_t CrFwOutFactoryGetNOfInstanceId ()
 Return the number of distinct instance identifiers supported by the OutFactory. More...
 

Variables

static CrFwCmdRepKindKey_t outCmpKindKey [CR_FW_OUTCMP_NKINDS]
 Array holding the keys of the OutComponents kinds.
 
static CrFwOutCmpKindDesc_t outCmpKindDesc [CR_FW_OUTCMP_NKINDS] = CR_FW_OUTCMP_INIT_KIND_DESC
 Array of service descriptors.
 
static FwSmDesc_t outCmp [CR_FW_OUTFACTORY_MAX_NOF_OUTCMP]
 The pre-allocated OutComponent instances.
 
static CrFwCmpData_t outCmpData [CR_FW_OUTFACTORY_MAX_NOF_OUTCMP]
 The data for the pre-allocated OutComponent instances.
 
static CrFwOutCmpData_t outCmpSpecificData [CR_FW_OUTFACTORY_MAX_NOF_OUTCMP]
 The component-specific data for the pre-allocated OutReport instances.
 
static CrFwBool_t outCmpInUse [CR_FW_OUTFACTORY_MAX_NOF_OUTCMP]
 The in-use status of each pre-allocated OutComponent instance.
 
static CrFwOutFactoryPoolIndex_t nOfAllocatedOutCmp
 The number of currently allocated OutComponents.
 
static CrFwOutFactoryPoolIndex_t nextFreePos
 The index of the next free position in the pool of pre-allocated OutComponent instances (a value of CR_FW_OUTFACTORY_MAX_NOF_OUTCMP indicates that all OutComponent instances have been allocated and there are no free positions left)
 
static CrFwInstanceId_t nOfAllocatedOutCmpSinceReset = 0
 The total number of OutComponents allocated since the OutFactory was reset.
 
static FwSmDesc_t outFactory
 The singleton instance of the OutFactory.
 
static CrFwCmpData_t outFactoryData
 The data for the OutFactory singleton.
 
static CrFwInstanceId_t apidInstanceId = CR_FW_HOST_APP_ID << (sizeof(CrFwInstanceId_t)*8-CR_FW_NBITS_APP_ID)
 The part of the command or report identifier which depends on the application identifier.
 
static CrFwInstanceId_t maxInstanceId = (1 << (sizeof(CrFwInstanceId_t)*8-CR_FW_NBITS_APP_ID))
 The highest value of cmd/rep identifier (before overflowing into the application identifier bits)
 

Detailed Description

Implementation of OutFactory component.

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 CrFwOutFactory.c.

Function Documentation

◆ CrFwOutFactoryGetMaxNOfOutCmp()

CrFwOutFactoryPoolIndex_t CrFwOutFactoryGetMaxNOfOutCmp ( )

Return the maximum number of OutComponents which may be allocated at any one time.

Returns
the maximum number of OutComponents which may be allocated at any one time

Definition at line 269 of file CrFwOutFactory.c.

◆ CrFwOutFactoryGetNOfAllocatedOutCmp()

CrFwOutFactoryPoolIndex_t CrFwOutFactoryGetNOfAllocatedOutCmp ( )

Return the number of OutComponents which are currently allocated.

This function returns the number of OutComponents which have been successfully allocated through calls to CrFwOutFactoryMakeOutCmp and have not yet been released through calls to CrFwOutFactoryReleaseOutCmp.

Returns
the number of OutComponents which are currently allocated.

Definition at line 264 of file CrFwOutFactory.c.

◆ CrFwOutFactoryGetNOfInstanceId()

CrFwInstanceId_t CrFwOutFactoryGetNOfInstanceId ( )

Return the number of distinct instance identifiers supported by the OutFactory.

The OutFactory allocates the instance identifier of an OutComponent as explained in the documentation of CrFwOutFactoryMakeOutCmp.

Returns
the maximum number of OutComponents which may be allocated at any one time

Definition at line 274 of file CrFwOutFactory.c.

◆ CrFwOutFactoryMake()

FwSmDesc_t CrFwOutFactoryMake ( )

Factory function for the singleton instance of the OutFactory.

The first time it is called, this function creates the OutFactory singleton instance. Subsequent calls return the same instance. The first time this function is called, it returns the OutFactory in state CREATED.

Returns
the OutFactory singleton instance.

Definition at line 122 of file CrFwOutFactory.c.

◆ CrFwOutFactoryMakeOutCmp()

FwSmDesc_t CrFwOutFactoryMakeOutCmp ( CrFwServType_t  type,
CrFwServSubType_t  subType,
CrFwDiscriminant_t  discriminant,
CrFwPcktLength_t  length 
)

Make function for an OutComponent.

This function returns an OutComponent in state CONFIGURED. The OutComponent is reset before being returned to the caller of this function (its State Execution Counter is guaranteed to be equal to zero).

The caller specifies the kind of OutComponent it wishes by specifying its type, sub-type, discriminant and the packet length. Of these four parameters, the first three (type, sub-type, and discriminant) are mandatory whereas for the last one (length) a dummy value of zero is possible. Given the type, sub-type and discriminant, the function looks for a matching entry in the CR_FW_OUTCMP_INIT_KIND_DESC initializer. If no matching entry is found (i.e. if no entry is found with the same values of type, sub-type and discriminant), then the function sets the application error code to crOutCmpAllocationFail and returns a value of NULL. If instead a matching entry is found, two options are possible:

  • If the length parameter is set to zero, then the function creates and returns an OutComponent with the characteristics given by the matching entry in the CR_FW_OUTCMP_INIT_KIND_DESC initializer.
  • If instead the length parameter has a non-zero value, then the function creates and returns an OutComponent with the characteristics given by the matching entry in the CR_FW_OUTCMP_INIT_KIND_DESC initializer with the exception of the packet length which is set equal to the value specified in the function call.

Thus, the length value specified in the function call may be used to override the length value specified in the CR_FW_OUTCMP_INIT_KIND_DESC initializer). This override mechanism is useful for reports or commands whose length must be determined dynamically (as opposed to being statically determined in the CR_FW_OUTCMP_INIT_KIND_DESC initializer).

When an OutComponent is returned by this function, it has the following attributes set:

  • The OutComponent packet length
  • The OutComponent command/report type flag (which defines whether the OutComponent is a report or a command)
  • The OutComponent source attribute
  • The OutComponent group attribute
  • The OutComponent service type
  • The OutComponent service sub-type
  • The OutComponent discriminant
  • The OutComponent sequence counter
  • The OutComponent instance identifier

The values of type, sub-type, command/report flag and discriminant are derived from the information in the CR_FW_OUTCMP_INIT_KIND_DESC initializer. The type and sub-type cannot be changed after an OutComponent has been created. Applications can instead override the default setting of the discriminant by using function CrFwOutCmpSetDiscriminant.

As explained above, the value of the packet length is either derived from the CR_FW_OUTCMP_INIT_KIND_DESC initializer (if the function is called with the length parameter set to zero) or else it is equal to the length parameter in the function call.

The value of the instance identifier is built as follows. Let n be the number of OutComponents made by the factory since it was last reset; let APP_ID be the application identifier (see CR_FW_HOST_APP_ID); let m be the number of bits reserved for the application identifier (see CR_FW_NBITS_APP_ID); and let s be the number of bits of the instance identifier. The instance identifier is then given by: APP_ID*(2**(s-m))+n. In this formula, the value of n is incremented by 1 every time a new OutComponent is created by the OutFactory and it is reset to 0 when it reaches APP_ID*(2**(s-m)).

The value of the sequence counter is initialized to zero.

The value of the source attribute is set equal to the identifier of the host application (namely CR_FW_HOST_APP_ID).

The value of the group attribute is set to a default value of zero. Applications can override this default setting by using function CrFwOutCmpSetGroup.

This function allocates the memory for the new OutComponent from a pool of pre-allocated memory which is created when the OutFactory is initialized (see OutFactoryInitAction). If no free memory is available in the factory pool, this function returns NULL. Allocation memory failure results in the application error code being set to crOutCmpAllocationFail.

When an OutComponent created by this function is no longer needed, it should be returned to the factory by calling CrFwOutCmpRelease.

If the OutFactory is reset, then all the OutComponents which had been created by the factory are released.

Parameters
typethe service type of the OutComponent
subTypethe service sub-type of the OutComponent
discriminantthe discriminant of the OutComponent
lengtheither zero (if the packet length is to be taken from the CR_FW_OUTCMP_INIT_KIND_DESC initializer) or the packet length
Returns
a new OutComponent or NULL if it was not possible to allocate the memory for the OutComponent.

Definition at line 166 of file CrFwOutFactory.c.

◆ CrFwOutFactoryReleaseOutCmp()

void CrFwOutFactoryReleaseOutCmp ( FwSmDesc_t  outCmpInstance)

Release function for an OutComponent.

The argument of this function must be an OutComponent which was created using function CrFwOutFactoryMakeOutCmp. This function releases the memory which was allocated to the OutComponent. After this function is called, the OutComponent cannot be used any longer. The function does not perform any checks on the existence or status of the OutComponent. An attempt to use an OutComponent which has been released will result in undefined behaviour.

An attempt to release an OutComponent which had already been released, or to release a non-existent OutComponent will result in undefined behaviour and in the application error code being set to: crOutCmpRelErr.

Parameters
outCmpInstancethe OutComponent to be released

Definition at line 244 of file CrFwOutFactory.c.

◆ OutFactoryConfigAction()

static void OutFactoryConfigAction ( FwPrDesc_t  initPr)
static

Configuration action for OutFactory.

This function releases all the OutComponents which are currently allocated. After this function has been called, any OutComponent which is still in use within the application is no longer valid and should be discarded.

This function also resets the counter used to initialize the instance identifier of the OutComponents created by the OutFactory. After reset, the first OutComponent made by the OutFactory will have its instance identifier set to 1.

The outcome of the initialization action is always: "successful"

Parameters
initPrthe Initialization Procedure of the OutFactory

Definition at line 326 of file CrFwOutFactory.c.

◆ OutFactoryInitAction()

static void OutFactoryInitAction ( FwPrDesc_t  initPr)
static

Initialization action for OutFactory.

This function allocates the memory for the OutFactory data structures and initializes the array of descriptors outCmpKindDesc. The outcome of the initialization action is "successful" in all cases except when the memory allocation operation fails.

Parameters
initPrthe Initialization Procedure of the OutFactory

Definition at line 279 of file CrFwOutFactory.c.

◆ OutFactoryShutdownAction()

static void OutFactoryShutdownAction ( FwSmDesc_t  smDesc)
static

Shutdown action for OutFactory.

This function releases the memory which was allocated when the OutFactory was initialized and it sets the number of allocated OutComponents to zero. After this function has been called, any OutComponent which is still in use within the application is no longer valid and should be discarded.

Parameters
smDescthe OutFactory state machine

Definition at line 346 of file CrFwOutFactory.c.

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