CORDET Framework - C2 Implementation
|
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) | |
Implementation of OutFactory component.
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.
CrFwOutFactoryPoolIndex_t CrFwOutFactoryGetMaxNOfOutCmp | ( | ) |
Return 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
.
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
.
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.
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:
CR_FW_OUTCMP_INIT_KIND_DESC
initializer.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 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.
type | the service type of the OutComponent |
subType | the service sub-type of the OutComponent |
discriminant | the discriminant of the OutComponent |
length | either zero (if the packet length is to be taken from the CR_FW_OUTCMP_INIT_KIND_DESC initializer) or the packet length |
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
.
outCmpInstance | the OutComponent to be released |
Definition at line 244 of file CrFwOutFactory.c.
|
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"
initPr | the Initialization Procedure of the OutFactory |
Definition at line 326 of file CrFwOutFactory.c.
|
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.
initPr | the Initialization Procedure of the OutFactory |
Definition at line 279 of file CrFwOutFactory.c.
|
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.
smDesc | the OutFactory state machine |
Definition at line 346 of file CrFwOutFactory.c.