CORDET Framework - C2 Implementation

Definition of the OutFactory component. More...

Go to the source code of this file.

Functions

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

Detailed Description

Definition of the OutFactory component.

The OutFactory component offers an interface through which OutComponents (see CrFwOutCmp.h) can be allocated and released. Applications need OutComponents to encapsulate out-going commands or reports. This interface provides the factory functions through which an OutComponent can be created and released.

The OutFactory is implemented as an extension of the Base Component of CrFwBaseCmp.h. The OutFactory is a singleton component. This interface provides a function to create the OutFactory and it provides a function to create an OutComponent of a specified kind.

The OutFactory maintains a pool of pre-allocated OutComponents (the size of the pool is defined in CrFwOutFactoryUserPar.h). Memory for the pool is allocated when the OutFactory is initialized and is never released afterwards. Items in the pool are marked as "in use" when they are allocated to an application and are marked as "not in use" when they are released. When the OutFactory is reset, all the items in the pool are marked as "not in use". No memory allocation operations (malloc/free) are therefore performed when OutComponents are allocated or released.

Mode of Use of an OutFactory Component

The configuration of the OutFactory component is defined statically in CrFwOutFactoryUserPar.h.

The OutFactory is created with function CrFwOutFactoryMake. After being created, the OutFactory must be initialized and reset. This is done with functions CrFwCmpInit and CrFwCmpReset. Nominally, after being initialized and reset the OutFactory State Machine should be in state CONFIGURED (this can be checked by verifying that function FwSmGetCurState returns CR_FW_BASE_STATE_CONFIGURED).

After being configured, the OutFactory is ready to manage the creation and release process for OutComponents. An OutComponent is created with function CrFwOutFactoryMakeOutCmp and it is released with function CrFwOutFactoryReleaseOutCmp.

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.h.

Function Documentation

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.

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.

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.

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.

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.

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.

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