This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Vector Basic Software Support

1: AN-ISC-2-1081_Interrupt_Control_VStdLib
2: AN-ISC-2-1081_Interrupt_Control_VStdLib_ind
3: AN-ISC-2-1081_Interrupt_Control_VStdLibs
4: TechnicalReference_VStdLib
5: TechnicalReference_VStdLib_GenericAsr
6: TechnicalReference_VStdLib_GenericAsr
7: TechnicalReference_VStdLib_GenericAsr_ind
8: TechnicalReference_VStdLib_GenericAsr_ind
9: TechnicalReference_VStdLib_GenericAsrs
10: TechnicalReference_VStdLib_GenericAsrs
11: TechnicalReference_VStdLib_ind
12: TechnicalReference_VStdLibs
13: VectorBswSuprt Integration Manual
14: VectorBswSuprt Peer Review Checklists

Vector Basic Software Support

Component Documentation

1 - AN-ISC-2-1081_Interrupt_Control_VStdLib

Application Interrupt Control with VStdLib

2 - AN-ISC-2-1081_Interrupt_Control_VStdLib_ind

Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13

3 - AN-ISC-2-1081_Interrupt_Control_VStdLibs

Application Interrupt Control with VStdLib
Version 1.0
2008-08-06
Application Note AN-ISC-2-1081

Author(s) Patrick
Markl
Restrictions Restricted
Membership
Abstract
This application note explains how the application can control interrupt handling via the
VStdLib and which constraints apply.

Table of Contents

1.0
Overview ..........................................................................................................................................................1
1.1
Introduction....................................................................................................................................................1
2.0
Interrupt Control by Application .......................................................................................................................3
2.1
Constraints ....................................................................................................................................................3
2.1.1
Constraint 1: Nested Calls ..........................................................................................................................3
2.1.2
Constraint 2: Recursive Calls when Disabling CAN Interrupts...................................................................3
2.1.3
Constraint 3: No Locking when Disabling CAN Interrupts..........................................................................3
3.0
Solution ............................................................................................................................................................6
3.1.1
Nested Calls................................................................................................................................................6
3.1.2
No Locking of Interrupts..............................................................................................................................7
4.0
Referenced Documents .................................................................................................................................12
5.0
Contacts.........................................................................................................................................................13

1.0 Overview
This application note describes how the user can configure the interrupt control options of the VStdLib. Some
applications provide their own lock/unlock functions, which better fulfill the application’s needs. Because of this the
VStdLib provides a means which allows the application to use it’s own lock/unlock functions, instead of the
implementation provided by the VStdLib.
This application note describes the handling of this use case in more detail.
1.1 Introduction
The VStdLib provides functions to lock/unlock interrupts. There are three options to be set in the configuration tool,
as shown in figure1. The first option (Default) lets the VStdLib lock global interrupts. Depending on the hardware
plattform it is also possible to lock interrupts to a certain level. The lock is implemented by the VStdLib itself.

Figure 1: Possible configuration options for VStdLib interrupt control
1
Copyright © 2008 - Vector Informatik GmbH
Contact Information: www.vector-informatik.com or ++49-711-80 670-0

Application Interrupt Control with VStdLib

The second option (OSEK) is to configure the VStdLib in a way that locking of interrupts is done by means of
OSEK OS functions. The third and last option (User defined) requires the application to perform the
locking/unlocking functionality within callback functions.
This application note focusses mainly on the third option. It describes the way the application has to implement the
callback functions required by the VStdLib.

Figure 2: Configuration of interrupt control by application

Figure 2 shows the VStdLib configuration dialog, if interrupt control by application is configured. The user has to
enter the names of two functions in the dialog, which will be called by the VStdLib in order to lock/unlock interrupts.
If the user has specified the callback function names as shown in figure 2, the application must provide the
implementations of these two two functions. The prototypes are:

void ApplNestedDisable(void);
void ApplNestedRestore(void);

From now on these two function names will be used within this application note.
These two functions are called by the VStdLib, in case any Vector component requests a lock for a critical section.
The user has to make sure that the locking mechanism within these two functions is sufficient to protect data. This
depends heavily on the architecture of the application. The more priority levels exists, which call Vector functions,
the more restrictive the lock must be.

Please check the technical references of the other Vector components for restrictions regarding the call
context of the API functions.

2
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

2.0  Interrupt Control by Application
This configuration option is usually used, if a global lock is not desired by the user or special lock mechanisms are
used. Once this option is configured, there are two functions to be provided by the application. The user can
specify the names of these functions in the configuration dialog of the VStdLib. The VStdLib calls these functions
instead of directly locking/unlocking interrupts. This means, if any Vector component requests an interrupt lock, it is
finally performed by the application provided functions.
The first function is called, in order to perform a lock operation. It is expected, that the application function stores
the current interrupt state(or any other), in order to restore it later. The second function is to restore the previously
saved lock state.
The implementation of these two functions is up to the user. The user may lock just certain interrupt sources or set
a mutex, semaphore or whatever ensures consistent data and fulfills the call context requirements, described in the
Vector component specific technical references.
2.1 Constraints
The usage of Interrupt Control by Application has some constraints, which have to be taken into account. The
following chapters describe them.
2.1.1  Constraint 1: Nested Calls
It is expected that the two callback functions (ApplNestedDisable()/-Restore()) are implemented in a way that
nested calls are possible. This means if the function ApplNestedDisable() was called by some software component
it may happen that this function is called again from somewhere else. This has to be taken into account when
saving and restoring the interrupt state! The implementer of these two function can assume that the number of lock
and unlock calls is identical and nesting is balanced.
2.1.2  Constraint 2: Recursive Calls when Disabling CAN Interrupts
Instead of implementing an own lock mechanism, the user could configure interrupt control by application and call
the CAN driver’s CanCanInterruptDisable()/-Restore() functions. These two function simply disable CAN interrupts
for the given CAN channel. These two CAN driver functions protect the access to their state variables by means of
the VStdLib’s lock mechanism, which would again be implemented by the callbacks provided by the application.
This would cause an indirect recursion.

Please note that CanCanInterruptDisable()/Restore() shall not be called from
ApplNestedDisable()/Restore(). This application note does not provide a solution for this use case!

2.1.3  Constraint 3: No Locking when Disabling CAN Interrupts
One could think of letting the application directly modify the interrupt flags of the CAN controller, to overcome the
recursion, described in the previous chapter. But this would cause the CAN interrupts to be never locked, when
CanCanInterruptDisable() is called, by any component. The reason is that the application’s interrupt lock code
would interfere with the code in the CAN driver’s function CanCanInterruptDisable(). The following pseudo code
shows the way CanCanInterruptDisable() is implemented. It is assumed that ApplNestedDisable()/-Restore() are
implemented to allow nested calls.

3
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

/* CAN Interrupt will be never locked in this example!!! */
void CanCanInterruptDisable(CAN_CHANNEL_CANTYPE_ONLY)
{
ApplNestedDisable();
Lock CAN interrupts
ApplNestedRestore();
}

void ApplNestedDisable(void)
{
Save current CAN interrupt state();
Lock CAN Interrupts();
}

void ApplNestedRestore(void)
{
Restore CAN interrupts to previous state();
}

Figure 3 shows what happens in this case. The function CanCanInterruptDisable() calls ApplNestedDisable() in
order to protect an internal counter. This lock function disables the CAN interrupts, afterwards the CAN driver’s
function locks the CAN interrupts too. The next thing is to call ApplNestedRestore() which again is implemented by
the application and restores the previous CAN interrupt state – in this case enables the CAN interrupts. Now an
inconsistency exists. The code which called CanCanInterruptDisable() assumes locked CAN interrupts, but they
aren’t

4
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

sd FailedLock
Component
CAN Driver
Application
CAN Controller
CanCanInterruptDisable
VStdGlobalInterruptDisable
Lock CAN Interrupt
Lock CAN Interrupt
VStdGlobalInterruptRestore
Unlock CAN Interrupt

Figure 3: Sequence diagram of CanCanInterruptDisable()

5
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

3.0 Solution
This chapter proposes a solution and a code examples, to overcome the constraints 1 and 3 described in the
previous chapters.
3.1.1 Nested
Calls
Solving the first issue – nested calls – is simply done by introducation of a nesting counter. The callbacks
implemented by the application need to manage this counter. The counter is to be incremented, if the function to
lock interrupts is called and decremented if the unlock function is called. The application has to take care to
initialize this counter, before any Vector function is called, in order to ensure a consistent interrupt locking.
The interrupt state is to be modified only if the counter has the value zero. If the value is greater than zero, the
counter is just maintained. The following code example shows, how this nested counter could be implemented.

/* Global variable as nesting counter */
vuint8 gApplNestingCounter;

/* Must be called before the Vector components are initialized! */
void SomeApplicationInitFunction(void)
{
gApplNestingCounter = (vuint8)0;
}

void ApplNestedDisable(void)
{
/* check counter – lock if counter is 0 */
if((vuint8)0 == gApplNestingCounter)
{
/* Save current state and perform lock */
ApplicationSpecificSaveStateAndLock();
}
/* increment counter – do not disable if nested, because already done */
gApplNestingCounter++;
}

void ApplNestedRestore(void)
{
gApplNestingCounter--;
if((vuint8)0 == gApplNestingCounter)
{

6
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

ApplicationSpecificRestoreToPreviousState();
}
}

3.1.2 No Locking of Interrupts
Constraint 3 described a situation, in which the CAN interrupts are not locked at all. This is because the application
implements a lock function, which modifes the CAN interrupt registers with own code. To overcome this issue, a
global flag needs to be implemented. This global flag tells the application, when to lock or unlock CAN interrupts.
The flag is set within two additional callback functions to be implemented by the application. The prototypes of the
additional callbacks are:

void ApplCanAddCanInterruptDisable(CanChannelHandle channel);
void ApplCanAddCanInterruptRestore(CanChannelHandle channel);

The callback functions are called by the CAN driver from within the functions CanCanInterruptDisable() and
CanCanInterruptRestore() and have to be enabled by means of the preprocessor define
C_ENABLE_INTCTRL_ADD_CAN_FCT. This is done, by creating a user config file, which contains this definition.
More information about these two functions can be found in [1].
The sequence diagrams in figure 4 and figure 5 show the lock and unlocking procedure respectively.

7
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

sd InterruptControlByApplication_Lock
Component
CAN Driver
VStdLib
Application
CanCanInterruptDisable
CanNestedGlobalInterruptDisable
ApplDisableFunc
Lock if
Flag
cleared
Lock CAN Interrupts
ApplCanAddCanInterruptDisable
Set
Global
Flag
CanNestedGlobalInterruptRestore
ApplRestoreFunc
Unlock
if Flag
cleared

Figure 4: Sequence diagram for locking just CAN interrupts.

8
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

sd InterruptControlByApplication_UnLock
Component
CAN Driver
VStdLib
Application
CanCanInterruptRestore
VStdGlobalInterruptDisable
ApplDisableFunc
Lock if
Flag
cleared
Restore CAN Interrupts
ApplCanAddCanInterruptRestore
Clear Global Flag
VStdGlobalInterruptRestore
ApplRestoreFunc
Unlock
if Flag
cleared

Figure 5: Sequence diagram for unlocking just CAN interrupts

The following code example shows how to implement the handling of the global flag. If the function
CanCanInterruptDisable() is called, it calls the ApplNestedDisable(), in order to protect a counter. This function
locks CAN interrupts using own code. When ApplNestedDisable() returns, the CAN driver locks CAN interrupts too.
Afterwards ApplCanAddCanInterruptDisable() is called. This function is implemented by the application and sets
the global flag. Before the function CanCanInterruptDisable() returns, it calls ApplNestedRestore(). The application,
which implements the restore callback function has to check, if the global flag is set. If yes, the CAN interrupts
must not be unlocked!
If the function CanCanInterruptRestore() is called, first ApplNestedDisable() is called again. Then the CAN driver
unlocks the CAN interrupts (if its nesting counter reached the value zero) and calls the function
ApplCanAddCanInterruptRestore(). Within this function the flag is cleared. If ApplNestedRestore() is called now,
the flag is not set anymore and the restore of the CAN interrupts is performed.

9
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

Note that the application needs to implement also a nesting counter, if it uses own code to lock CAN interrupts, in
order to avoid the issue described by constraint 1. The following code example shows, how to implement the
nesting counter and the flag.

vuint8 gCanLockFlag;
vuint8 gApplNestingCounter;

void ApplicationInitFunction(void)
{
/* initialize the flags */
gCanLockFlag = (vuint8)0;
gApplNestingCounter = (vuint8)0;
}

void ApplNestedDisable(void)
{
if((vuint8)0 == gApplNestingCounter)
{
if((vuint8)0 == gCanLockFlag)
{
Save current CAN interrupt state();
Lock CAN Interrupts();
}
}
gApplNestingCounter++;
}

void ApplNestedRestore (void)
{
gApplNestingCounter--;
if((vuint8)0 == gApplNestingCounter)
{
if((vuint8)0 == gCanLockFlag)
{
Restore CAN interrupts to previous state();
}

10
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

}
}

void ApplCanAddCanInterruptDisable(CanChannelHandle channel)
{
gCanLockFlag = (vuint8)1;
}

void ApplCanAddCanInterruptRestore(CanChannelHandle channel)
{
gCanLockFlag = (vuint8)0;
}

11
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

4.0 Referenced Documents
The following table contains the referenced documents.

Referenced Documents
[1] TechnicalReference_CANDriver.pdf

12
Application Note AN-ISC-2-1081

Application Interrupt Control with VStdLib

5.0 Contacts

Vector Informatik GmbH
Vector CANtech, Inc.
VecScan AB
Ingersheimer Straße 24
39500 Orchard Hill Pl., Ste 550
Lindholmspiren 5
70499 Stuttgart
Novi, MI 48375
402 78 Göteborg
Germany
USA
Sweden
Tel.: +49 711-80670-0
Tel: +1-248-449-9290
Tel: +46 (0)31 764 76 00
Fax: +49 711-80670-111
Fax: +1-248-449-9704
Fax: +46 (0)31 764 76 19
Email: info@vector-informatik.de
Email: info@vector-cantech.com
Email: info@vecscan.com

Vector France SAS
Vector Japan Co. Ltd.
Vector Korea IT Inc.
168 Boulevard Camélinat
Seafort Square Center Bld. 18F
Daerung Post Tower III, 508
92240 Malakoff
2-3-12, Higashi-shinagawa,
Guro-gu, Guro-dong, 182-4
France
Shinagawa-ku
Seoul, 152-790
Tel: +33 (0)1 42 31 40 00
J-140-0002 Tokyo
Republic of Korea
Fax: +33 (0)1 42 31 40 09
Tel.: +81 3 5769 6970
Tel.: +82-2-2028-0600
Email: information@vector-france.fr
Fax: +81 3 5769 6975
Fax: +82-2-2028-0604

Email: info@vector-japan.co.jp
Email: info@vector-korea.com

13
Application Note AN-ISC-2-1081

4 - TechnicalReference_VStdLib

VStdLib Technical Reference

5 - TechnicalReference_VStdLib_GenericAsr

MICROSAR VStdLib

6 - TechnicalReference_VStdLib_GenericAsr

MICROSAR VStdLib

7 - TechnicalReference_VStdLib_GenericAsr_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21
Page 22
Page 23
Page 24
Page 25
Page 26

8 - TechnicalReference_VStdLib_GenericAsr_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21
Page 22
Page 23
Page 24
Page 25
Page 26

9 - TechnicalReference_VStdLib_GenericAsrs

MICROSAR VStdLib
Technical Reference

Generic implementation of the Vector Standard Library
Version 1.00.00

Authors
Torsten Kercher
Status
Released

Technical Reference MICROSAR VStdLib
Document Information

History
Author
Date
Version
Remarks
Torsten Kercher
2015-05-04
1.00.00
Creation

Reference Documents
No.
Source
Title
Version
[1]   AUTOSAR
AUTOSAR_TR_BSWModuleList.pdf
1.6.0
[2]   AUTOSAR
AUTOSAR_SWS_DevelopmentErrorTracer.pdf
3.2.0

Caution
We have configured the programs in accordance with your specifications in the
  questionnaire. Whereas the programs do support other configurations than the one
specified in your questionnaire, Vector´s release of the programs delivered to your
company is expressly restricted to the configuration you have specified in the
questionnaire.

2015, Vector Informatik GmbH
Version: 1.00.00
2 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
1  Component History
The  component  history  gives  an  overview  over  the  important  milestones  that  are
supported in the different versions of the component.
Component Version  New Features
1.00
Creation of the component.
2.00
Detach the component from core-based implementations, give optimized
routines and support operations on large data (> 65535 bytes).
Table 1-1   Component history

2015, Vector Informatik GmbH
Version: 1.00.00
5 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
2  Introduction
This  document  describes  the  functionality,  API  and  configuration  of  the  generic  Vector
Standard Library (VStdLib).

Supported AUTOSAR Release*:
4.x
Supported Configuration Variants:
pre-compile
Vendor ID:
VSTDLIB_VENDOR_ID
30 decimal
(= Vector-Informatik,
according to HIS)
Module ID:
VSTDLIB_MODULE_ID
255 decimal
(according to [1])
* For the precise AUTOSAR Release 4.x please see the release specific documentation.

The  VStdLib  provides  a  hardware  independent  implementation  of  memory  manipulation
services used by several MICROSAR BSW components.
2.1
Architecture Overview
The following figure shows where the VStdLib is located in the AUTOSAR architecture.

Figure 2-1  AUTOSAR 4.x Architecture Overview
2015, Vector Informatik GmbH
Version: 1.00.00
6 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
The next figure shows the interfaces to adjacent modules of the VStdLib. These interfaces
are described in chapter 5.
class Module Structure
Module
MICROSAR BSW
module
Module
«use»
Det
«EmbeddedInterface»
VStdLib
«realize»
+  VStdLib_GetVersionInfo()
+  VStdLib_MemClr()
+  VStdLib_MemClrLarge()
«EmbeddedInterface»
+  VStdLib_MemClrMacro()
Det
+  VStdLib_MemCpy()
Module
+  VStdLib_MemCpy_s()
+  Det_ReportError()
«use
+  VStdLib_MemCpy16()
optionally»
+  VStdLib_MemCpy16Large()
«realize»
VStdLib
+  VStdLib_MemCpy32()
«EmbeddedInterface»
«use
+  VStdLib_MemCpy32Large()
(Compiler) Library
optionally»
+  VStdLib_MemCpyLarge()
+  VStdLib_MemCpyLarge_s()
+  VStdLib_MemCpyMacro()
+  VStdLib_MemCpyMacro_s()
+  VStdLib_MemSet()
+  VStdLib_MemSetLarge()
«realize»
+  VStdLib_MemSetMacro()
Module
(Compiler) Library

Figure 2-2  Interfaces to adjacent modules
2015, Vector Informatik GmbH
Version: 1.00.00
7 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
3  Functional Description
This chapter describes the general function of the component.
3.1
Features
The Vector Standard Library gives a standard interface for memory initialization and copy
services as described in  section 5.2. It provides a hardware independent implementation
of  this  interface,  but  also  allows  the  mapping  to  project  specific  implementations  for
optimization reasons.
3.2
Initialization and Main Functions
No initialization is necessary and no main functions are provided.
3.3
Error Handling
3.3.1
Development Error Reporting
By  default,  development  errors  are  reported  to  the  DET  using  the  service
Det_ReportError()  as  specified  in  [2],  if  development  error  reporting  is  enabled  (i.e.
pre-compile parameter VSTDLIB_DEV_ERROR_REPORT == STD_ON).
If  another  module  is  used  for  development  error  reporting,  the  function  prototype  for
reporting the error can be configured by the integrator, but must have the same signature
as the service Det_ReportError().
The reported VStdLib ID is 255. The service IDs identify the services which are described
in section 5.2. The following table presents the service IDs and the related services:
Service ID
Service
VSTDLIB_SID_MEM_SET (0x00)
VStdLib_MemClr(), VStdLib_MemSet()
VSTDLIB_SID_MEM_COPY (0x01)
VStdLib_MemCpy()
VSTDLIB_SID_MEM_COPY_16 (0x02)
VStdLib_MemCpy16()
VSTDLIB_SID_MEM_COPY_32 (0x03)
VStdLib_MemCpy32()
VSTDLIB_SID_MEM_COPY_S (0x04)
VStdLib_MemCpy_s()
VSTDLIB_SID_GET_VERSION_INFO (0x05)
VStdLib_GetVersionInfo()
Table 3-1   Service IDs
The errors reported to DET are described in the following table:
Error Code
Description
VSTDLIB_E_PARAM_POINTER (0x01)
API service used with NULL pointer parameter.
VSTDLIB_E_PARAM_SIZE (0x02)
VStdLib_MemCpy_s() used with invalid
destination size parameter.
Table 3-2   Errors reported to DET
3.3.2
Production Code Error Reporting
No production code error reporting is supported.

2015, Vector Informatik GmbH
Version: 1.00.00
8 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
4  Integration
This  chapter  gives  necessary  information  for  the  integration  of  the  MICROSAR  VStdLib
into an application environment of an ECU.
4.1
Scope of Delivery
The delivery of the VStdLib contains following static files. There are no dynamic files.
File Name
Description
vstdlib.c
This is the source file of the VStdLib.
vstdlib.h
This is the header file that contains the public API.
VStdLib_Cfg.h  This is the configuration header file, see chapter 6 for details.
Table 4-1   Static files
4.2
Include Structure
class IncludeStructure
MemMap.h
Std_Types.h
«include»
«include»
«include»
vstdlib.c
vstdlib.h
VStdLib_Cfg.h
«include»
«include»
«include»
Det.h

Figure 4-1  Include Structure
4.3
Critical Sections
No critical sections are implemented.
2015, Vector Informatik GmbH
Version: 1.00.00
9 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
4.4
Compiler Abstraction and Memory Mapping
The  objects  (e.g.  variables,  functions,  constants)  are  declared  by  compiler  independent
definitions  –  the  compiler  abstraction  definitions.  Each  compiler  abstraction  definition  is
assigned to a memory section.
The  following  table  contains  the  memory  section  names  and  the  compiler  abstraction
definitions of the VStdLib and illustrates their assignment among each other.

Compiler Abstraction
Definitions

Memory Mapping
Sections
VSTDLIB_CODE
VSTDLIB_APPL_VAR
VSTDLIB_VAR_FAR
VSTDLIB_START_SEC_CODE



VSTDLIB_STOP_SEC_CODE
Table 4-2   Compiler Abstraction and Memory Mapping
The VStdLib declares no global variables or constants thus only a general CODE section
is provided for the memory mapping that is abstracted by VSTDLIB_CODE.
Due to the AUTOSAR compiler and memory abstraction the location of individual data and
the  width  of  pointers  are  not  known  during  development  time.  Hence  the  compiler
abstraction  definition  VSTDLIB_APPL_VAR  refers  to  variables  which  are  defined  by  the
application and not handled by the VStdLib memory mapping.
The function implementation of all memory manipulation services as described in section
5.2  abstracts  all  pointer  arguments  (independently  of  the  target  type)  with
VSTDLIB_VAR_FAR  to  allow  that  all  data  can  be  handled  by  far  accesses.  The  macro
implementation performs an in-place access, thus the unaltered pointer class of the caller
is used.

Note
For most 32bit MCUs it is not necessary to give any qualifiers with VSTDLIB_VAR_FAR
  to  change  the  pointer  class  as  these  platforms  commonly  use  32bit  pointers  that  can
address  the  whole  memory  by  default.  Please  note  that  both  RAM  and  ROM  are
accessed with this qualifier and an external implementation (see section 6.2.1) has to
be used if distinct pointers have to be qualified individually on the used target platform.

2015, Vector Informatik GmbH
Version: 1.00.00
10 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
4.5
Integration Hints
>  Avoid overlapping destination and source memory areas  when using the copy services
as this may lead to unexpected results.
>  Consider  side  effects  if  macros  are  used:  If  either  destination  or  source  pointer  is
retrieved using a call to a function, this function might  be  invoked for nCnt times. It  is
recommended to use temporary pointers to avoid any side effects.
>  The  VStdLib  is  optimized  for  32-bit  MCUs.  When  using  a  controller  with  a  smaller  bit
width it is highly recommended to use an external implementation that is optimized for
this  architecture  (see  VSTDLIB_USE_LIBRARY_FUNCTIONS  in  section  6.2.1).  If  large
data  support  is  not  necessary  define  each  VSTDLIB_RUNTIME_OPTIMIZATION  and
VSTDLIB_SUPPORT_LARGE_DATA to STD_OFF as an alternative.

2015, Vector Informatik GmbH
Version: 1.00.00
11 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5  API Description
See Figure 2-2 for an interfaces overview.
5.1
Type Definitions
The  nCnt  parameter  of  all  memory  manipulation  services  is  of  type  VStdLib_CntType
that  equals  uint32_least  if  VSTDLIB_SUPPORT_LARGE_DATA  is  defined  to  STD_ON
(default setting) or uint16_least if it is explicitly defined to STD_OFF.

5.2
Services provided by VStdLib

5.2.1
VStdLib_GetVersionInfo
Prototype
void VStdLib_GetVersionInfo (Std_VersionInfoType *versioninfo)
Parameter
versioninfo [out]
Pointer to where to store the version information, must not be NULL.
Return code
void
none
Functional Description
Returns the version information of this module.
Returns version information, vendor ID and AUTOSAR module ID of the component.
Particularities and Limitations
The parameter 'versioninfo' has to be valid and reference an object of type Std_VersionInfoType.
Configuration Variant(s): VSTDLIB_VERSION_INFO_API == STD_ON
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-1   VStdLib_GetVersionInfo

2015, Vector Informatik GmbH
Version: 1.00.00
12 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.2
VStdLib_MemClr
Prototype
void VStdLib_MemClr (void *pDst, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to be initialized, must not be NULL.
nCnt [in]
Number of bytes to initialize, pDst must be valid for this amount.
Return code
void
none
Functional Description
Initializes memory to zero.
Sets nCnt bytes starting at pDst to zero.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON, else it is realized by a call to VStdLib_MemSet() with 'nPattern' == 0. The compatible definition
VStdLib_MemClrLarge() exists additionally (and solely) if VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-2   VStdLib_MemClr

2015, Vector Informatik GmbH
Version: 1.00.00
13 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.3
VStdLib_MemClrMacro
Prototype
void VStdLib_MemClrMacro (AnyPtrType *pDst, VStdLib_CntType nCnt)
Parameter
pDst [out]
Any typed pointer to the memory location to be initialized, must be aligned
corresponding to its type and not be NULL.
nCnt [in]
Number of blocks to initialize, pDst must be valid for this amount.
Return code
void
none
Functional Description
Initializes memory to zero (macro implementation).
Sets nCnt blocks starting at pDst to zero (block-size is given by the type of pDst).
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Call context
>  ANY
>  This macro is Synchronous
>  This macro is Reentrant
Table 5-3   VStdLib_MemClrMacro

2015, Vector Informatik GmbH
Version: 1.00.00
14 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.4
VStdLib_MemSet
Prototype
void VStdLib_MemSet (void *pDst, uint8 nPattern, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to be initialized, must not be NULL.
nPattern [in]
The character to be used to initialize the memory.
nCnt [in]
Number of bytes to initialize, pDst must be valid for this amount.
Return code
void
none
Functional Description
Initializes memory to a specified pattern.
Sets nCnt bytes starting at pDst to the character nPattern.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON. The compatible definition VStdLib_MemSetLarge() exists additionally (and solely) if
VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-4   VStdLib_MemSet

2015, Vector Informatik GmbH
Version: 1.00.00
15 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.5
VStdLib_MemSetMacro
Prototype
void VStdLib_MemSetMacro (AnyPtrType *pDst, AnyIntType nPattern,
VStdLib_CntType nCnt)
Parameter
pDst [out]
Any typed pointer to the memory location to be initialized, must be aligned
corresponding to its type and not be NULL.
nPattern [in]
The pattern to be used to initialize the memory (consider the correlation
between its type and the type of pDst).
nCnt [in]
Number of blocks to initialize, pDst must be valid for this amount.
Return code
void
none
Functional Description
Initializes memory to a specified pattern (macro implementation).
Sets nCnt blocks starting at pDst to nPattern (block-size is given by the type of pDst).
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Call context
>  ANY
>  This macro is Synchronous
>  This macro is Reentrant
Table 5-5   VStdLib_MemSetMacro

2015, Vector Informatik GmbH
Version: 1.00.00
16 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.6
VStdLib_MemCpy
Prototype
void VStdLib_MemCpy (void *pDst, const void *pSrc, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to copy to, must not be NULL.
pSrc [in]
Pointer to the memory location to copy from, must not be NULL.
nCnt [in]
Number of bytes to copy, pDst must be valid for this amount.
Return code
void
none
Functional Description
Copies data from one memory location to another.
Copies nCnt bytes starting at pSrc to another memory location starting at pDst.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON. The compatible definition VStdLib_MemCpyLarge() exists additionally (and solely) if
VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-6   VStdLib_MemCpy

2015, Vector Informatik GmbH
Version: 1.00.00
17 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.7
VStdLib_MemCpy16
Prototype
void VStdLib_MemCpy16 (uint16 *pDst, const uint16 *pSrc, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to copy to, 16-bit aligned and not NULL.
pSrc [in]
Pointer to the memory location to copy from, 16-bit aligned and not NULL.
nCnt [in]
Number of 16-bit blocks to copy, pDst must be valid for this amount.
Return code
void
none
Functional Description
Copies data from one memory location to another.
Copies nCnt 16-bit blocks starting at pSrc to another memory location starting at pDst.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON. The compatible definition VStdLib_MemCpy16Large() exists additionally (and solely) if
VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-7   VStdLib_MemCpy16

2015, Vector Informatik GmbH
Version: 1.00.00
18 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.8
VStdLib_MemCpy32
Prototype
void VStdLib_MemCpy32 (uint32 *pDst, const uint32 *pSrc, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to copy to, 32-bit aligned and not NULL.
pSrc [in]
Pointer to the memory location to copy from, 32-bit aligned and not NULL.
nCnt [in]
Number of 32-bit blocks to copy, pDst must be valid for this amount.
Return code
void
none
Functional Description
Copies data from one memory location to another.
Copies nCnt 32-bit blocks starting at pSrc to another memory location starting at pDst.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON. The compatible definition VStdLib_MemCpy32Large() exists additionally (and solely) if
VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-8   VStdLib_MemCpy32

2015, Vector Informatik GmbH
Version: 1.00.00
19 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.9
VStdLib_MemCpy_s
Prototype
void VStdLib_MemCpy_s (void *pDst, VStdLib_CntType nDstSize, const void *pSrc,
VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to copy to, must not be NULL.
nDstSize [in]
Maximum number of bytes to modify in the destination (typically the size of the
destination object).
pSrc [in]
Pointer to the memory location to copy from, must not be NULL.
nCnt [in]
Number of bytes to copy.
Return code
void
none
Functional Description
Verifies the destination size and copies data from one memory location to another.
Uses VStdLib_MemCpy() to copy nCnt bytes starting at pSrc to another memory location starting at pDst, if
nDstSize is greater than or equal to nCnt.
Particularities and Limitations
The parameters 'pDst' and 'nDstSize' have to define a valid memory area.
Configuration Variant(s): The compatible definition VStdLib_MemCpyLarge_s() exists additionally (and
solely) if VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-9   VStdLib_MemCpy_s

2015, Vector Informatik GmbH
Version: 1.00.00
20 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.10  VStdLib_MemCpyMacro
Prototype
void VStdLib_MemCpyMacro (AnyPtrType *pDst, AnyPtrType *pSrc, VStdLib_CntType
nCnt)
Parameter
pDst [out]
Any typed pointer to the memory location to copy to, must be aligned
corresponding to its type and not be NULL.
pSrc [in]
Any typed pointer to the memory location to copy from, must be aligned
corresponding to its type and not be NULL.
nCnt [in]
Number of blocks to copy, pDst must be valid for this amount.
Return code
void
none
Functional Description
Copies data from one memory location to another (macro implementation).
Copies nCnt blocks starting at pSrc to another memory location starting at pDst (block-size is given by the
type of pDst).
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Call context
>  ANY
>  This macro is Synchronous
>  This macro is Reentrant
Table 5-10   VStdLib_MemCpyMacro

2015, Vector Informatik GmbH
Version: 1.00.00
21 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.11  VStdLib_MemCpyMacro_s
Prototype
void VStdLib_MemCpyMacro_s (AnyPtrType *pDst, VStdLib_CntType nDstSize,
AnyPtrType *pSrc, VStdLib_CntType nCnt)
Parameter
pDst [out]
Any typed pointer to the memory location to copy to, must be aligned
corresponding to its type and not be NULL.
nDstSize [in]
Maximum number of blocks to modify in the destination (typically the size of
the destination object).
pSrc [in]
Any typed pointer to the memory location to copy from, must be aligned
corresponding to its type and not be NULL.
nCnt [in]
Number of blocks to copy.
Return code
void
none
Functional Description
Verifies the destination size and copies data from one memory location to another (macro implementation).
Uses VStdLib_MemCpyMacro() to copy nCnt blocks starting at pSrc to another memory location starting at
pDst (block-size is given by the type of pDst), if nDstSize is greater than or equal to nCnt.
Particularities and Limitations
The parameters 'pDst' and 'nDstSize' have to define a valid memory area.
Call context
>  ANY
>  This macro is Synchronous
>  This macro is Reentrant
Table 5-11   VStdLib_MemCpyMacro_s

5.3
Services used by VStdLib
The following table lists used services that are provided by other components. For details
about prototypes and functionality refer to the documentation of the providing component.
Component
API
DET
Det_ReportError()
(Compiler) Library
Refer to section 6.2.2
Table 5-12   Services used by VStdLib
2015, Vector Informatik GmbH
Version: 1.00.00
22 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
6  Configuration
The Vector Standard Library is solely configured manually in a header file.
6.1
Configuration Variants
The VStdLib supports following configuration variants:
>  VARIANT-PRE-COMPILE
6.2
Manual Configuration in Header File
The configuration of the VStdLib is done statically within the file “VStdLib_Cfg.h”.

6.2.1
General configuration
Attribute Name
Values
Description
Default value
is typed bold
VSTDLIB_USE_LIBRARY_FUNCTIONS  STD_ON
If set to STD_ON all memory manipulation routines
STD_OFF
are mapped to external functions (e.g. compiler
libraries or other implementations that are
optimized for the target platform). This requires
additional configuration, refer to section 6.2.2.
If set to STD_OFF generic functions provided by
the VStdLib are used.
VSTDLIB_RUNTIME_OPTIMIZATION
STD_ON
If set to STD_ON optimized routines are used to
STD_OFF
increase the performance of the memory
manipulation functions (increases code size).
If set to STD_OFF code efficient routines are used
that increase runtime.
This setting is only relevant if VSTDLIB_USE_
LIBRARY_FUNCTIONS == STD_OFF.
VSTDLIB_USE_JUMPTABLES
STD_ON
If set to STD_ON jump tables are used to increase
STD_OFF
the performance of the memory manipulation
functions (runtime efficient in general).
If set to STD_OFF the jump tables are replaced by
loops. Use this setting if the compiler generates no
efficient code for the jump tables.
This setting is only relevant if
VSTDLIB_USE_LIBRARY_FUNCTIONS ==
STD_OFF and VSTDLIB_RUNTIME_
OPTIMIZATION == STD_ON.
VSTDLIB_DEV_ERROR_DETECT
STD_ON
If set to STD_ON the development error detection is
STD_OFF
enabled. In this case the pointer arguments of all
global module functions provided by the VStdLib
are checked. If any NULL_PTR is passed, these
functions return without performing any action.

2015, Vector Informatik GmbH
Version: 1.00.00
23 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
VSTDLIB_DEV_ERROR_REPORT
STD_ON
If set to STD_ON the development error reporting is
STD_OFF
enabled (requires VSTDLIB_DEV_ERROR_
DETECT == STD_ON). In this case the function
Det_ReportError() is called if any error is
detected.
VSTDLIB_VERSION_INFO_API
STD_ON
If set to STD_ON the function
STD_OFF
VStdLib_GetVersionInfo() is provided.
VSTDLIB_DUMMY_STATEMENT(v)
e.g. (v) = (v)  Expression that is used for dummy statements to
(void)(v)
avoid compiler warnings about unused identifiers.
Leave this definition empty to disable the usage of
dummy statements.
Table 6-1   General configuration

6.2.2
Additional configuration when using library functions
If  VSTDLIB_USE_LIBRARY_FUNCTIONS  ==  STD_ON  it  is  necessary  to  specify  library
functions  to  be  used  for  the  memory  manipulations.  See  the  corresponding  section  in
“VStdLib_Cfg.h” for details and an example mapping.

Caution
If the external functionality is not able to handle more than 65535 bytes it is necessary
  to define VSTDLIB_SUPPORT_LARGE_DATA to STD_OFF.

It  has  to  be  ensured  that  the  specified  functions  are  able  to  copy  from  and  to  all
memory  locations  independently  of  the  pointer  length.  The  specified  functions  must
behave synchronously.

2015, Vector Informatik GmbH
Version: 1.00.00
24 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
7  Abbreviations
Abbreviation
Description
API
Application Programming Interface
AUTOSAR
Automotive Open System Architecture
BSW
Basis Software
DET
Development Error Tracer
ECU
Electronic Control Unit
HIS
Hersteller Initiative Software
MCU
Microcontroller Unit
MICROSAR
Microcontroller Open System Architecture (the Vector AUTOSAR solution)
SWS
Software Specification
VStdLib
Vector Standard Library
Table 7-1   Abbreviations

2015, Vector Informatik GmbH
Version: 1.00.00
25 / 26
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
8  Contact
Visit our website for more information on

>  News
>  Products
>  Demo software
>  Support
>  Training data
>  Addresses

www.vector.com

2015, Vector Informatik GmbH
Version: 1.00.00
26 / 26
based on template version 5.9.0

Document Outline

10 - TechnicalReference_VStdLib_GenericAsrs

MICROSAR VStdLib
Technical Reference

Generic implementation of the Vector Standard Library
Version 1.00.01

Authors
Torsten Kercher
Status
Released

Technical Reference MICROSAR VStdLib
Document Information

History
Author
Date
Version
Remarks
Torsten Kercher
2015-05-04
1.00.00
Creation
Torsten Kercher
2016-04-12
1.00.01
Update to new CI, no changes in content

Reference Documents
No.
Source
Title
Version
[1]   AUTOSAR
AUTOSAR_TR_BSWModuleList.pdf
1.6.0
[2]   AUTOSAR
AUTOSAR_SWS_DevelopmentErrorTracer.pdf
3.2.0

Caution
We have configured the programs in accordance with your specifications in the
  questionnaire. Whereas the programs do support other configurations than the one
specified in your questionnaire, Vector´s release of the programs delivered to your
company is expressly restricted to the configuration you have specified in the
questionnaire.

© 2016 Vector Informatik GmbH
Version 1.00.01
2
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
1  Component History
The  component  history  gives  an  overview  over  the  important  milestones  that  are
supported in the different versions of the component.
Component Version  New Features
1.00
Creation of the component.
2.00
Detach the component from core-based implementations, give optimized
routines and support operations on large data (> 65535 bytes).
Table 1-1   Component history

© 2016 Vector Informatik GmbH
Version 1.00.01
5
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
2  Introduction
This  document  describes  the  functionality,  API  and  configuration  of  the  generic  Vector
Standard Library (VStdLib).

Supported AUTOSAR Release*:
4.x
Supported Configuration Variants:
pre-compile
Vendor ID:
VSTDLIB_VENDOR_ID
30 decimal
(= Vector-Informatik,
according to HIS)
Module ID:
VSTDLIB_MODULE_ID
255 decimal
(according to [1])
* For the precise AUTOSAR Release 4.x please see the release specific documentation.

The  VStdLib  provides  a  hardware  independent  implementation  of  memory  manipulation
services used by several MICROSAR BSW components.
2.1
Architecture Overview
The following figure shows where the VStdLib is located in the AUTOSAR architecture.

Figure 2-1  AUTOSAR 4.x Architecture Overview
© 2016 Vector Informatik GmbH
Version 1.00.01
6
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
The next figure shows the interfaces to adjacent modules of the VStdLib. These interfaces
are described in chapter 5.
class Module Structure
Module
MICROSAR BSW
module
Module
«use»
Det
«EmbeddedInterface»
VStdLib
«realize»
+  VStdLib_GetVersionInfo()
+  VStdLib_MemClr()
+  VStdLib_MemClrLarge()
«EmbeddedInterface»
+  VStdLib_MemClrMacro()
Det
+  VStdLib_MemCpy()
Module
+  VStdLib_MemCpy_s()
+  Det_ReportError()
«use
+  VStdLib_MemCpy16()
optionally»
+  VStdLib_MemCpy16Large()
«realize»
VStdLib
+  VStdLib_MemCpy32()
«EmbeddedInterface»
«use
+  VStdLib_MemCpy32Large()
(Compiler) Library
optionally»
+  VStdLib_MemCpyLarge()
+  VStdLib_MemCpyLarge_s()
+  VStdLib_MemCpyMacro()
+  VStdLib_MemCpyMacro_s()
+  VStdLib_MemSet()
+  VStdLib_MemSetLarge()
«realize»
+  VStdLib_MemSetMacro()
Module
(Compiler) Library

Figure 2-2  Interfaces to adjacent modules

© 2016 Vector Informatik GmbH
Version 1.00.01
7
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
3  Functional Description
This chapter describes the general function of the component.
3.1
Features
The Vector Standard Library gives a standard interface for memory initialization and copy
services as described in  section 5.2. It provides a hardware independent implementation
of  this  interface,  but  also  allows  the  mapping  to  project  specific  implementations  for
optimization reasons.
3.2
Initialization and Main Functions
No initialization is necessary and no main functions are provided.
3.3
Error Handling
3.3.1
Development Error Reporting
By  default,  development  errors  are  reported  to  the  DET  using  the  service
Det_ReportError()  as  specified  in  [2],  if  development  error  reporting  is  enabled  (i.e.
pre-compile parameter VSTDLIB_DEV_ERROR_REPORT == STD_ON).
If  another  module  is  used  for  development  error  reporting,  the  function  prototype  for
reporting the error can be configured by the integrator, but must have the same signature
as the service Det_ReportError().
The reported VStdLib ID is 255. The service IDs identify the services which are described
in section 5.2. The following table presents the service IDs and the related services:
Service ID
Service
VSTDLIB_SID_MEM_SET (0x00)
VStdLib_MemClr(), VStdLib_MemSet()
VSTDLIB_SID_MEM_COPY (0x01)
VStdLib_MemCpy()
VSTDLIB_SID_MEM_COPY_16 (0x02)
VStdLib_MemCpy16()
VSTDLIB_SID_MEM_COPY_32 (0x03)
VStdLib_MemCpy32()
VSTDLIB_SID_MEM_COPY_S (0x04)
VStdLib_MemCpy_s()
VSTDLIB_SID_GET_VERSION_INFO (0x05)
VStdLib_GetVersionInfo()
Table 3-1   Service IDs
The errors reported to DET are described in the following table:
Error Code
Description
VSTDLIB_E_PARAM_POINTER (0x01)
API service used with NULL pointer parameter.
VSTDLIB_E_PARAM_SIZE (0x02)
VStdLib_MemCpy_s() used with invalid
destination size parameter.
Table 3-2   Errors reported to DET
3.3.2
Production Code Error Reporting
No production code error reporting is supported.
© 2016 Vector Informatik GmbH
Version 1.00.01
8
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
4  Integration
This  chapter  gives  necessary  information  for  the  integration  of  the  MICROSAR  VStdLib
into an application environment of an ECU.
4.1
Scope of Delivery
The delivery of the VStdLib contains following static files. There are no dynamic files.
File Name
Description
vstdlib.c
This is the source file of the VStdLib.
vstdlib.h
This is the header file that contains the public API.
VStdLib_Cfg.h  This is the configuration header file, see chapter 6 for details.
Table 4-1   Static files
4.2
Include Structure
class IncludeStructure
MemMap.h
Std_Types.h
«include»
«include»
«include»
vstdlib.c
vstdlib.h
VStdLib_Cfg.h
«include»
«include»
«include»
Det.h

Figure 4-1  Include Structure
4.3
Critical Sections
No critical sections are implemented.
© 2016 Vector Informatik GmbH
Version 1.00.01
9
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
4.4
Compiler Abstraction and Memory Mapping
The  objects  (e.g.  variables,  functions,  constants)  are  declared  by  compiler  independent
definitions  –  the  compiler  abstraction  definitions.  Each  compiler  abstraction  definition  is
assigned to a memory section.
The  following  table  contains  the  memory  section  names  and  the  compiler  abstraction
definitions of the VStdLib and illustrates their assignment among each other.

Compiler Abstraction
Definitions

Memory Mapping
Sections
VSTDLIB_CODE
VSTDLIB_APPL_VAR
VSTDLIB_VAR_FAR
VSTDLIB_START_SEC_CODE



VSTDLIB_STOP_SEC_CODE
Table 4-2   Compiler Abstraction and Memory Mapping
The VStdLib declares no global variables or constants thus only a general CODE section
is provided for the memory mapping that is abstracted by VSTDLIB_CODE.
Due to the AUTOSAR compiler and memory abstraction the location of individual data and
the  width  of  pointers  are  not  known  during  development  time.  Hence  the  compiler
abstraction  definition  VSTDLIB_APPL_VAR  refers  to  variables  which  are  defined  by  the
application and not handled by the VStdLib memory mapping.
The function implementation of all memory manipulation services as described in section
5.2  abstracts  all  pointer  arguments  (independently  of  the  target  type)  with
VSTDLIB_VAR_FAR  to  allow  that  all  data  can  be  handled  by  far  accesses.  The  macro
implementation performs an in-place access, thus the unaltered pointer class of the caller
is used.

Note
For most 32bit MCUs it is not necessary to give any qualifiers with VSTDLIB_VAR_FAR
  to change the pointer class  as these platforms commonly use 32bit pointers that can
address  the  whole  memory  by  default.  Please  note  that  both  RAM  and  ROM  are
accessed with this qualifier and an external implementation (see section 6.2.1) has to
be used if distinct pointers have to be qualified individually on the used target platform.

© 2016 Vector Informatik GmbH
Version 1.00.01
10
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
4.5
Integration Hints
>  Avoid overlapping destination and source memory areas  when using the copy services
as this may lead to unexpected results.
>  Consider  side  effects  if  macros  are  used:  If  either  destination  or  source  pointer  is
retrieved using a call to a function, this function  might  be  invoked for nCnt times. It  is
recommended to use temporary pointers to avoid any side effects.
>  The  VStdLib  is  optimized  for  32-bit  MCUs.  When  using  a  controller  with  a  smaller  bit
width it is highly recommended to use an external implementation that is optimized for
this  architecture  (see  VSTDLIB_USE_LIBRARY_FUNCTIONS  in  section  6.2.1).  If  large
data  support  is  not  necessary  define  each  VSTDLIB_RUNTIME_OPTIMIZATION  and
VSTDLIB_SUPPORT_LARGE_DATA to STD_OFF as an alternative.

© 2016 Vector Informatik GmbH
Version 1.00.01
11
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5  API Description
See Figure 2-2 for an interfaces overview.
5.1
Type Definitions
The  nCnt  parameter  of  all  memory  manipulation  services  is  of  type  VStdLib_CntType
that  equals  uint32_least  if  VSTDLIB_SUPPORT_LARGE_DATA  is  defined  to  STD_ON
(default setting) or uint16_least if it is explicitly defined to STD_OFF.

5.2
Services provided by VStdLib

5.2.1
VStdLib_GetVersionInfo
Prototype
void VStdLib_GetVersionInfo (Std_VersionInfoType *versioninfo)
Parameter
versioninfo [out]
Pointer to where to store the version information, must not be NULL.
Return code
void
none
Functional Description
Returns the version information of this module.
Returns version information, vendor ID and AUTOSAR module ID of the component.
Particularities and Limitations
The parameter 'versioninfo' has to be valid and reference an object of type Std_VersionInfoType.
Configuration Variant(s): VSTDLIB_VERSION_INFO_API == STD_ON
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-1   VStdLib_GetVersionInfo

© 2016 Vector Informatik GmbH
Version 1.00.01
12
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.2
VStdLib_MemClr
Prototype
void VStdLib_MemClr (void *pDst, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to be initialized, must not be NULL.
nCnt [in]
Number of bytes to initialize, pDst must be valid for this amount.
Return code
void
none
Functional Description
Initializes memory to zero.
Sets nCnt bytes starting at pDst to zero.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON, else it is realized by a call to VStdLib_MemSet() with 'nPattern' == 0. The compatible definition
VStdLib_MemClrLarge() exists additionally (and solely) if VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-2   VStdLib_MemClr

© 2016 Vector Informatik GmbH
Version 1.00.01
13
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.3
VStdLib_MemClrMacro
Prototype
void VStdLib_MemClrMacro (AnyPtrType *pDst, VStdLib_CntType nCnt)
Parameter
pDst [out]
Any typed pointer to the memory location to be initialized, must be aligned
corresponding to its type and not be NULL.
nCnt [in]
Number of blocks to initialize, pDst must be valid for this amount.
Return code
void
none
Functional Description
Initializes memory to zero (macro implementation).
Sets nCnt blocks starting at pDst to zero (block-size is given by the type of pDst).
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Call context
>  ANY
>  This macro is Synchronous
>  This macro is Reentrant
Table 5-3   VStdLib_MemClrMacro

© 2016 Vector Informatik GmbH
Version 1.00.01
14
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.4
VStdLib_MemSet
Prototype
void VStdLib_MemSet (void *pDst, uint8 nPattern, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to be initialized, must not be NULL.
nPattern [in]
The character to be used to initialize the memory.
nCnt [in]
Number of bytes to initialize, pDst must be valid for this amount.
Return code
void
none
Functional Description
Initializes memory to a specified pattern.
Sets nCnt bytes starting at pDst to the character nPattern.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON. The compatible definition VStdLib_MemSetLarge() exists additionally (and solely) if
VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-4   VStdLib_MemSet

© 2016 Vector Informatik GmbH
Version 1.00.01
15
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.5
VStdLib_MemSetMacro
Prototype
void VStdLib_MemSetMacro (AnyPtrType *pDst, AnyIntType nPattern,
VStdLib_CntType nCnt)
Parameter
pDst [out]
Any typed pointer to the memory location to be initialized, must be aligned
corresponding to its type and not be NULL.
nPattern [in]
The pattern to be used to initialize the memory (consider the correlation
between its type and the type of pDst).
nCnt [in]
Number of blocks to initialize, pDst must be valid for this amount.
Return code
void
none
Functional Description
Initializes memory to a specified pattern (macro implementation).
Sets nCnt blocks starting at pDst to nPattern (block-size is given by the type of pDst).
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Call context
>  ANY
>  This macro is Synchronous
>  This macro is Reentrant
Table 5-5   VStdLib_MemSetMacro

© 2016 Vector Informatik GmbH
Version 1.00.01
16
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.6
VStdLib_MemCpy
Prototype
void VStdLib_MemCpy (void *pDst, const void *pSrc, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to copy to, must not be NULL.
pSrc [in]
Pointer to the memory location to copy from, must not be NULL.
nCnt [in]
Number of bytes to copy, pDst must be valid for this amount.
Return code
void
none
Functional Description
Copies data from one memory location to another.
Copies nCnt bytes starting at pSrc to another memory location starting at pDst.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON. The compatible definition VStdLib_MemCpyLarge() exists additionally (and solely) if
VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-6   VStdLib_MemCpy

© 2016 Vector Informatik GmbH
Version 1.00.01
17
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.7
VStdLib_MemCpy16
Prototype
void VStdLib_MemCpy16 (uint16 *pDst, const uint16 *pSrc, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to copy to, 16-bit aligned and not NULL.
pSrc [in]
Pointer to the memory location to copy from, 16-bit aligned and not NULL.
nCnt [in]
Number of 16-bit blocks to copy, pDst must be valid for this amount.
Return code
void
none
Functional Description
Copies data from one memory location to another.
Copies nCnt 16-bit blocks starting at pSrc to another memory location starting at pDst.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON. The compatible definition VStdLib_MemCpy16Large() exists additionally (and solely) if
VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-7   VStdLib_MemCpy16

© 2016 Vector Informatik GmbH
Version 1.00.01
18
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.8
VStdLib_MemCpy32
Prototype
void VStdLib_MemCpy32 (uint32 *pDst, const uint32 *pSrc, VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to copy to, 32-bit aligned and not NULL.
pSrc [in]
Pointer to the memory location to copy from, 32-bit aligned and not NULL.
nCnt [in]
Number of 32-bit blocks to copy, pDst must be valid for this amount.
Return code
void
none
Functional Description
Copies data from one memory location to another.
Copies nCnt 32-bit blocks starting at pSrc to another memory location starting at pDst.
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Configuration Variant(s): This service is implemented externally if VSTDLIB_USE_LIBRARY_FUNCTIONS
== STD_ON. The compatible definition VStdLib_MemCpy32Large() exists additionally (and solely) if
VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-8   VStdLib_MemCpy32

© 2016 Vector Informatik GmbH
Version 1.00.01
19
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.9
VStdLib_MemCpy_s
Prototype
void VStdLib_MemCpy_s (void *pDst, VStdLib_CntType nDstSize, const void *pSrc,
VStdLib_CntType nCnt)
Parameter
pDst [out]
Pointer to the memory location to copy to, must not be NULL.
nDstSize [in]
Maximum number of bytes to modify in the destination (typically the size of the
destination object).
pSrc [in]
Pointer to the memory location to copy from, must not be NULL.
nCnt [in]
Number of bytes to copy.
Return code
void
none
Functional Description
Verifies the destination size and copies data from one memory location to another.
Uses VStdLib_MemCpy() to copy nCnt bytes starting at pSrc to another memory location starting at pDst, if
nDstSize is greater than or equal to nCnt.
Particularities and Limitations
The parameters 'pDst' and 'nDstSize' have to define a valid memory area.
Configuration Variant(s): The compatible definition VStdLib_MemCpyLarge_s() exists additionally (and
solely) if VSTDLIB_SUPPORT_LARGE_DATA == STD_ON.
Call context
>  ANY
>  This function is Synchronous
>  This function is Reentrant
Table 5-9   VStdLib_MemCpy_s

© 2016 Vector Informatik GmbH
Version 1.00.01
20
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.10  VStdLib_MemCpyMacro
Prototype
void VStdLib_MemCpyMacro (AnyPtrType *pDst, AnyPtrType *pSrc, VStdLib_CntType
nCnt)
Parameter
pDst [out]
Any typed pointer to the memory location to copy to, must be aligned
corresponding to its type and not be NULL.
pSrc [in]
Any typed pointer to the memory location to copy from, must be aligned
corresponding to its type and not be NULL.
nCnt [in]
Number of blocks to copy, pDst must be valid for this amount.
Return code
void
none
Functional Description
Copies data from one memory location to another (macro implementation).
Copies nCnt blocks starting at pSrc to another memory location starting at pDst (block-size is given by the
type of pDst).
Particularities and Limitations
The parameters 'pDst' and 'nCnt' have to define a valid memory area.
Call context
>  ANY
>  This macro is Synchronous
>  This macro is Reentrant
Table 5-10   VStdLib_MemCpyMacro

© 2016 Vector Informatik GmbH
Version 1.00.01
21
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
5.2.11  VStdLib_MemCpyMacro_s
Prototype
void VStdLib_MemCpyMacro_s (AnyPtrType *pDst, VStdLib_CntType nDstSize,
AnyPtrType *pSrc, VStdLib_CntType nCnt)
Parameter
pDst [out]
Any typed pointer to the memory location to copy to, must be aligned
corresponding to its type and not be NULL.
nDstSize [in]
Maximum number of blocks to modify in the destination (typically the size of
the destination object).
pSrc [in]
Any typed pointer to the memory location to copy from, must be aligned
corresponding to its type and not be NULL.
nCnt [in]
Number of blocks to copy.
Return code
void
none
Functional Description
Verifies the destination size and copies data from one memory location to another (macro implementation).
Uses VStdLib_MemCpyMacro() to copy nCnt blocks starting at pSrc to another memory location starting at
pDst (block-size is given by the type of pDst), if nDstSize is greater than or equal to nCnt.
Particularities and Limitations
The parameters 'pDst' and 'nDstSize' have to define a valid memory area.
Call context
>  ANY
>  This macro is Synchronous
>  This macro is Reentrant
Table 5-11   VStdLib_MemCpyMacro_s

5.3
Services used by VStdLib
The following table lists used services that are provided by other components. For details
about prototypes and functionality refer to the documentation of the providing component.
Component
API
DET
Det_ReportError()
(Compiler) Library
Refer to section 6.2.2
Table 5-12   Services used by VStdLib

© 2016 Vector Informatik GmbH
Version 1.00.01
22
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
6  Configuration
The Vector Standard Library is solely configured manually in a header file.
6.1
Configuration Variants
The VStdLib supports following configuration variants:
>  VARIANT-PRE-COMPILE
6.2
Manual Configuration in Header File
The configuration of the VStdLib is done statically within the file “VStdLib_Cfg.h”.

6.2.1
General configuration
Attribute Name
Values
Description
Default value
is typed bold
VSTDLIB_USE_LIBRARY_FUNCTIONS  STD_ON
If set to STD_ON all memory manipulation routines
STD_OFF
are mapped to external functions (e.g. compiler
libraries or other implementations that are
optimized for the target platform). This requires
additional configuration, refer to section 6.2.2.
If set to STD_OFF generic functions provided by
the VStdLib are used.
VSTDLIB_RUNTIME_OPTIMIZATION
STD_ON
If set to STD_ON optimized routines are used to
STD_OFF
increase the performance of the memory
manipulation functions (increases code size).
If set to STD_OFF code efficient routines are used
that increase runtime.
This setting is only relevant if VSTDLIB_USE_
LIBRARY_FUNCTIONS == STD_OFF.
VSTDLIB_USE_JUMPTABLES
STD_ON
If set to STD_ON jump tables are used to increase
STD_OFF
the performance of the memory manipulation
functions (runtime efficient in general).
If set to STD_OFF the jump tables are replaced by
loops. Use this setting if the compiler generates no
efficient code for the jump tables.
This setting is only relevant if
VSTDLIB_USE_LIBRARY_FUNCTIONS ==
STD_OFF and VSTDLIB_RUNTIME_
OPTIMIZATION == STD_ON.
VSTDLIB_DEV_ERROR_DETECT
STD_ON
If set to STD_ON the development error detection is
STD_OFF
enabled. In this case the pointer arguments of all
global module functions provided by the VStdLib
are checked. If any NULL_PTR is passed, these
functions return without performing any action.

© 2016 Vector Informatik GmbH
Version 1.00.01
23
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
VSTDLIB_DEV_ERROR_REPORT
STD_ON
If set to STD_ON the development error reporting is
STD_OFF
enabled (requires VSTDLIB_DEV_ERROR_
DETECT == STD_ON). In this case the function
Det_ReportError() is called if any error is
detected.
VSTDLIB_VERSION_INFO_API
STD_ON
If set to STD_ON the function
STD_OFF
VStdLib_GetVersionInfo() is provided.
VSTDLIB_DUMMY_STATEMENT(v)
e.g. (v) = (v)  Expression that is used for dummy statements to
(void)(v)
avoid compiler warnings about unused identifiers.
Leave this definition empty to disable the usage of
dummy statements.
Table 6-1   General configuration

6.2.2
Additional configuration when using library functions
If  VSTDLIB_USE_LIBRARY_FUNCTIONS  ==  STD_ON  it  is  necessary  to  specify  library
functions  to  be  used  for  the  memory  manipulations.  See  the  corresponding  section  in
“VStdLib_Cfg.h” for details and an example mapping.

Caution
If the external functionality is not able to handle more than 65535 bytes it is necessary
  to define VSTDLIB_SUPPORT_LARGE_DATA to STD_OFF.

It  has  to  be  ensured  that  the  specified  functions  are  able  to  copy  from  and  to  all
memory  locations  independently  of  the  pointer  length.  The  specified  functions  must
behave synchronously.

© 2016 Vector Informatik GmbH
Version 1.00.01
24
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
7  Abbreviations
Abbreviation
Description
API
Application Programming Interface
AUTOSAR
Automotive Open System Architecture
BSW
Basis Software
DET
Development Error Tracer
ECU
Electronic Control Unit
HIS
Hersteller Initiative Software
MCU
Microcontroller Unit
MICROSAR
Microcontroller Open System Architecture (the Vector AUTOSAR solution)
SWS
Software Specification
VStdLib
Vector Standard Library
Table 7-1   Abbreviations

© 2016 Vector Informatik GmbH
Version 1.00.01
25
based on template version 5.9.0

Technical Reference MICROSAR VStdLib
8  Contact
Visit our website for more information on

>  News
>  Products
>  Demo software
>  Support
>  Training data
>  Addresses

www.vector.com

© 2016 Vector Informatik GmbH
Version 1.00.01
26
based on template version 5.9.0

Document Outline

11 - TechnicalReference_VStdLib_ind

Outline
Page 1
Page 2
Page 3
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21

12 - TechnicalReference_VStdLibs

VStdLib
Technical Reference

Vector Standard Library
Version 1.6.2

Authors
Patrick Markl, Timo Vanoni
Status
Released

Technical Reference VStdLib

1  Document Information
1.1
History
Author
Date
Version
Remarks
Patrick Markl
2008-02-06
1.0
Creation, merge from Application Note
Patrick Markl
2008-10-31
1.3
Fixed document version
Patrick Markl
2008-11-07
1.4
Added information about mixed VStdLib versions
Patrick Markl
2009-07-02
1.5
Updated assertion codes
Added chapter about QNX OS
Patrick Markl
2009-10-16
1.6
Described inclusion of OSEK OS header file
Timo Vanoni
2013-05-10
1.6.2
ESCAN00067020: The interrupt lock functions
do not work correctly for the user mode at
specific controller
Table 1-1   History of the Document

Please note
We have configured the programs in accordance with your specifications in the
  questionnaire. Whereas the programs do support other configurations than the one
specified in your questionnaire, Vector’s release of the programs delivered to your
company is expressly restricted to the configuration you have specified in the
questionnaire.
2013, Vector Informatik GmbH
Version: 1.6.2
2 / 21
based on template version 3.7

Technical Reference VStdLib

2  Introduction
The  basic  idea  of  the  VStdLib  is  to  provide  standard  functionality  to  different  Vector
components. This  includes  memory  copy  and  interrupt  locking  functions. The  VStdLib  is
also  a  means  to  provide  special  memory  copy  functions,  which  are  not  available  by
compiler libraries to the communication components.
The  VStdLib  is  designed  to  be  used  by  Vector  communication  components  only.  So  the
customer integrating the communication stack will probably not notice the VStdLib at all.
The VStdLib is highly hardware specific. This means some functions are only available on
certain  platforms.  This  includes  special  copy  functions  for  far,  near  or  huge  memory.  A
hardware  specific  VStdLib  does  not  necessarily  implement  all  possible  copy  function  for
the  corresponding  hardware  platform,  but  only  the  functions  required  by  the  Vector
software components.
The  VStdLib  also  provides  interrupt  lock  functions.  This  feature  depends  on  the
CANbedded CAN driver’s Reference Implementation (RI). The RI defines a certain feature
set to be supported by the CAN driver. CAN drivers which implement RI1.5 and higher do
not  provide  an  interrupt  locking  mechanism  as  previously  implementations  did
(CanGlobalInterruptDisable/CanGlobalInterruptRestore). These driver require a VStdLib to
provide  this  functionality,  although  the  API  CanGlobalInterruptDisable  and
CanGlobalInterruptRestore remains for compatibility. Please refer to the CANbedded CAN
driver technical reference for more information about your specific CAN driver.

2013, Vector Informatik GmbH
Version: 1.6.2
5 / 21
based on template version 3.7

Technical Reference VStdLib

3  Functional Description
The  VStdLib  provides  basically  two  main  functionalities  to  Vector  communication  stack
components.
>  Functions to copy memory
>  Functions to lock/unlock interrupts
Interrupt locking functionality is required for CAN drivers with a reference  implementation
1.5 or higher or MICROSAR stacks. Functions to copy memory are always provided. The
following table describes the API of the VStdLib which is used internally.

API Function
Description
VStdMemSet
Initializes default RAM memory to a certain
character.
VStdMemNearSet
Initializes near RAM memory to a certain character.
VStdMemFarSet
Initializes far RAM memory to a certain character.
VStdMemClr
Clears default RAM to zero.
VStdMemNearClr
Clears near RAM to zero.
VStdMemFarClr
Clears far RAM to zero.
VStdMemCpyRamToRam
Copies default RAM to default RAM.
VStdMemCpyRomToRam
Copies default ROM to default RAM.
VStdMemCpyRamToNearRam
Copies default RAM to near RAM.
VStdMemCpyRomToNearRam
Copies default ROM to near RAM.
VStdMemCpyRamToFarRam
Copies default RAM to far RAM.
VStdMemCpyRomToFarRam
Copies default ROM to far RAM.
VStdMemCpy16RamToRam
Copies default RAM to default RAM. The copying is
performed 16 bit wise.
VStdMemCpy16RamToFarRam
Copies default RAM to far RAM. The copying is
performed 16 bit wise.
VStdMemCpy16FarRamToRam
Copies far RAM to default RAM. The copying is
performed 16 bit wise.
VStdMemCpy32RamToRam
Copies default RAM to default RAM. The copying is
performed 32 bit wise.
VStdMemCpy32RamToFarRam
Copies default RAM to far RAM. The copying is
performed 32 bit wise.
VStdMemCpy32FarRamToRam
Copies far RAM to default RAM. The copying is
performed 32 bit wise.

2013, Vector Informatik GmbH
Version: 1.6.2
6 / 21
based on template version 3.7

Technical Reference VStdLib

Info
The API functions described in the following table contain “near” and “far” as parts of
  the API names. The meaning of near and far depends on the platform and the functions
are not necessarily implemented to work on near or far memory.
The wording “default RAM” or “default ROM” means RAM or ROM data which is not
explicitly declared to be near or far. These data inherit the current compiler memory
model settings.

Caution
One cannot be sure that a far to near copy routine (for instance) implements really a
  copying from far to near. This depends on the platform and the supported memory
models of the communication stack!
2013, Vector Informatik GmbH
Version: 1.6.2
7 / 21
based on template version 3.7

Technical Reference VStdLib

4  Integration
The  integration  of  the  VStdLib  is  straightforward.  As  the  other  Vector  components  the
VStdLib  is  to  be  configured  by  means  of  the  configuration  tool.  The  configuration  is
described in the next chapter. Chapter 6 describes some callback function which have to
be implemented by the application depending on the configuration.
In order to integrate the VStdLib simply add the file vstdlib.c as the other Vector software
components to the compile and link list.
4.1
CANbedded Particularities
If the VStdLib is integrated as part of a CANbedded stack the initialization of the VStdLib is
performed by the CAN or LIN driver automatically.
4.2
MICROSAR Particularities
If  a  MICROSAR  stack  is  integrated  the  VStdLib  is  not  initialized  by  any  of  the  software
components.  The  application  has  to  take  care  that  the  VStdLib’s  initialization  function  is
called  before  any  other  MICROSAR API  function  is  called.  The  following  code  example
shows how to initialize the VStdLib.

void InitRoutine(void)
{
  ...

  /* Initialize the VstLib */
  VStdInitPowerOn();

  /* Perform initialization of the other software components */
  ...

}

4.3
Mixing VStdLib Versions
If you receive different software component packages from Vector, it is possible that these
packages  contain  different  VStdLib  versions. A  general  rule  is  to  use  the  VStdLib  which
was received with the CAN driver package. In case you encounter any incompatibilities or
have questions, please contact the Vector support.

2013, Vector Informatik GmbH
Version: 1.6.2
8 / 21
based on template version 3.7

Technical Reference VStdLib

5  Configuration
It depends on the used communication software  if  the VStdLib has configurable options.
The  configuration  tool  provides  options  for  the  VStdLib  if  (as  previously  described)  the
used CAN driver has RI1.5 or higher or a MICROSAR stack is used.
The VStdLib is configured by means of the configuration tool. CANGen provides an own
dialog named VStdLib to configure  this component. In GENy these configuration options
are  found  in  the  hardware  options  dialog.  The  following  two  pictures  show  the
configuration dialogs in both tools. The first picture shows the dialog in GENy.

Figure 5-1  VStdLib configuration dialog in GENy

The next picture shows the configuration dialog of the VStdLib in the CANGen tool.

Figure 5-2  VStdLib configuration dialog in CANGen
2013, Vector Informatik GmbH
Version: 1.6.2
9 / 21
based on template version 3.7

Technical Reference VStdLib

The following table describes the different configuration items of the VStdLib dialogs.

Configuration Item
Description
Lock Mechanism
One can select the interrupt lock mechanism
used by the VStdLib. The VStdLib provides
four different types: Default, LockLevel, OSEK
and User.
The setting “OSEK” covers OSEK OS and
AUTOSAR OS.
Lock Level
If LockLevel was selected as Lock Mechanism
one can select the interrupt lock level used for
CANbedded components. The VStdLib will
lock interrupts up to the specified level. Higher
level interrupts remain unlocked.
Nested Disable
If “User” was selected as Lock Mechanism the
user can type in the name of the user defined
function which lock the interrupts.
Nested Restore
If “User” was selected as Lock Mechanism the
user can type in the name of the user defined
function which restores the interrupts to their
previous state.
Assertions
If this checkbox is enabled the VStdLib will call
an assertion function in case of a fatal error.

If one configures the option Lock Mechanism as “User” two function have to be provided.
The prototype of both functions is:

void UserFunction(void)

The  first  function  entered  under  the  option  “Nested  Disable”  is  expected  to  disable
interrupts  and  store  the  current  context  of  the  interrupt  state  (Current  I-Flag,  Current
Interrupt Lock Level, etc.) to a global variable.
The second function entered under “Nested Restore” is expected to restore the interrupts
to the previous state using the value which was saved in the context of “Nested Disable”.

Caution
The two functions must not implement a disable/enable mechanism but a
  disable/restore mechanism! Otherwise it may happen that interrupts remain locked until
the next Power On reset.

2013, Vector Informatik GmbH
Version: 1.6.2
10 / 21
based on template version 3.7

Technical Reference VStdLib

The configuration option  “User” can be used instead of the previously known CAN driver
option “Interrupt Control by Application”.

5.1
Usage with OSEK OS
If OSEK OS is configured as lock mechanism the VStdLib needs to include the header of
the OSEK OS. Since the header of the OSEK OS may have different names depending on
the OS supplier the VStdLib includes always the same header file. This header file has to
be provided by the user. The file’s name must be os.h. If the OSEK OS already provides a
file named like this nothing needs to be done (as long it provides the required prototypes).
Otherwise the user has to create a header file named os.h and include the corresponding
OSEK OS file.
If the VStdLib is configured to lock/unlock interrupts by means of OSEK OS the following
OSEK functions are called to implement the lock:
>  SuspendAllInterrupts
>  ResumeAllInterrupts

5.2
Usage with QNX OS
In case the VStdLib is used in a QNX OS environment two options for interrupt locking are
available.  Depending  on  the  way  CAN  interrupts  are  handled  (ISR,  Interrupt  Thread)
different locking mechanisms are needed.

In  case  the  CAN  interrupts  are  handled  by  an  interrupt  thread  the  locking  is  done  by
means of mutexes. These are not implemented by the VStdLib but the QWrap component.
Please refer to Figure 5-3 which shows the locking configuration in this case.

Figure 5-3  Locking configuration in case CAN events are handled in an interrupt thread
User defined locking is also required if the VStdLib is configured to run in the context of the
QNX startup code (minidriver). The MdWrap component  provides the same callbacks as
shown in Figure 5-3 also in that case. QWrap and MdWrap implement the same callback
names in case the same tool configuration is used to generate for the minidriver and the
fulldriver.

2013, Vector Informatik GmbH
Version: 1.6.2
11 / 21
based on template version 3.7

Technical Reference VStdLib

In  case  CAN  interrupts  are  handled  by  a  CAN  interrupt  routine  the  VStdLib  locking
functions disable/restore  the global interrupt flag.  Mutexes are not used. In this case the
configuration of the VStdLib must be set to Default as shown in Figure 5-4.

Figure 5-4  Configuration of the VStdLib in case of handling CAN events on interrupt level

2013, Vector Informatik GmbH
Version: 1.6.2
12 / 21
based on template version 3.7

Technical Reference VStdLib

6  API Description
This chapter describes the API of the VStdLib.

6.1
Initialization

VStdInitPowerOn
Prototype
void VStdInitPowerOn(void)
Parameter
None
-
Return code
None
-
Functional Description
Initializes the VStdLib component.
Particularities and Limitations
>  This function must be called once after PowerOn reset. This function must not be re-called
later.
>  The application must not call any other Vector communication stack function before this
function. This includes also the other VStdLib functions. In other words: The function
VStdInitPowerOn must be the very first Vector function being called after startup. Depending
on the architecture the caller must take care about interruptions of the init function which may
violate this requirement (OS task which calls another Vector function).
>  If the CANbedded stack is used this function is automatically called by the CAN or LIN driver.
>  In a MICROSAR communication stack is integrated this function has to be called by the
application before any other MICROSAR API function is called.

Call context
>  Task context

2013, Vector Informatik GmbH
Version: 1.6.2
13 / 21
based on template version 3.7

Technical Reference VStdLib

6.2
Interrupt Control

VStdSuspendAllInterrupts
Prototype
void VStdSuspendAllInterrupts(void)
Parameter
None
-
Return code
None
-
Functional Description
Disables all interrupts or locks interrupts to a certain lock level. This depends on the hardware platform.
The way interrupts are locked is to be configured in the configuration tool.
Particularities and Limitations
>  This function is designed to be called in a nested way (except User Interrupt Control is
configured).
>  Every call to VStdSuspendAllInterrupts must have a corresponding call to
VStdResumeAllInterrupts.
>  If User Interrupt Control is configured this function is redirected to the functions specified by
the user in the configuration tool. No nesting counter is implemented. The user may have to
take special care to handle this behavior.
>  Depending on the used OS this function may use either a global lock or a mutex.
>  Default implementation only works if corresponding flags can be modified (e.g. in privileged
mode).
Call context
>  No limitation

VStdResumeAllInterrupts
Prototype
void VStdResumeAllInterrupts(void)
Parameter
None
-
Return code
None
-
Functional Description
Resumes the interrupts which were locked using the API function VStdSuspendAllInterrupts.
2013, Vector Informatik GmbH
Version: 1.6.2
14 / 21
based on template version 3.7

Technical Reference VStdLib

Particularities and Limitations
>  This function must not be called without a corresponding call to VStdSuspendAllInterrupts.
>  If User Interrupt Control is configured this function is redirected to the functions specified by
the user in the configuration tool. No nesting counter is implemented. The user may have to
take special care to handle this behavior.
>  Depending on the used OS this function may use either a global lock or a mutex.
>  Default implementation only works if corresponding flags can be modified (e.g. in privileged
mode).
Call context
>  No limitation

6.3
Memory Functions
This  chapter  describes  not  all functions,  as they  do  all  the  same except  for  the memory
qualifiers of the source and destination locations.

VStdMemSet
Prototype
void VStdMemSet (void *pDest, vuint8 nPattern, vuint16 nCnt)
Parameter
pDest
The start address in memory which is to be initialized using the given
character.
nPattern
The character to be used to fill nCnt Bytes starting at address pDest.
nCnt
The number of Bytes to be filled using the given character.
Return code
None
-
Functional Description
This function fills nCnt Bytes starting at address pDest in memory using the character nPattern.
Particularities and Limitations
>  This function exists in three variants (default, near and far memory). Depending on the
platform these function may be implemented differently
Call context
>  No restriction

VStdMemSet
2013, Vector Informatik GmbH
Version: 1.6.2
15 / 21
based on template version 3.7

Technical Reference VStdLib

Prototype
void VStdMemClr (void *pDest, vuint16 nCnt)
Parameter
pDest
The start address in memory which is to be initialized to zero.
nCnt
The number of Bytes to be set to zero.
Return code
None
-
Functional Description
This function initializes nCnt Bytes starting at address pDest in memory to zero.
Particularities and Limitations
>  This function exists in three variants (default, near and far memory). Depending on the
platform these function may be implemented differently
Call context
>  No restriction

VStdMemSet
Prototype
void VStdMemCpy (void *pDest, void *pSrc, vuint16 nCnt)
Parameter
pDest
The destination address to which the data is copied.
pSrc
The source address from where the data is copied.
nCnt
The number of Bytes to be copied from start address pSrc to destination
address pDest.
Return code
None
-
Functional Description
This function copies a block of nCnt Bytes starting at memory location pSrc to another memory location
starting at address pDest.
Particularities and Limitations
>  This function exists in many variants. These variants implement different memory source and
destination locations.
>  The implementation of these functions is highly platform dependent
>  The memory blocks starting at pSrc and pDest must no overlap.
Call context
>  No restriction

2013, Vector Informatik GmbH
Version: 1.6.2
16 / 21
based on template version 3.7

Technical Reference VStdLib

6.4
Callback Functions

ApplVStdFatalError
Prototype
void ApplVStdFatalError (vuint8 nErrorNumber)
Parameter
nErrorNumber
This parameter describes the reason which caused the assertion.
Return code
None
-
Functional Description
This function is called by the VStdLib in case an assertion fails.
Particularities and Limitations
>  This function is to be implemented by the application.
>  If this function returns to the caller, it is not ensured that the calling functions finished
successfully. It has to be considered as a severe error if this function is called.
Call context
>  No restriction

2013, Vector Informatik GmbH
Version: 1.6.2
17 / 21
based on template version 3.7

Technical Reference VStdLib

7  Assertions
If  the  user  enables  the  option  “Assertions”  the  VStdLib  component  performs  additional
checks.  If  a  checked  condition  fails  the  assertion  function  ApplVStdFatalError  is  called.
The implementation of this function is to be provided by the application. This function has
an  errorcode  parameter  which  describes  the  reason  which  caused  the  assertion.  The
following table describes these reasons.

Errorcode
Description
kVStdErrorIntDisableTooOften
The called VStdLib interrupt locking function
exceeded a nesting call depth of 127.
kVStdErrorIntRestoreTooOften
The number of calls of the VStdLib interrupt
unlocking function was higher than the number of
nested interrupt lock calls.
kVStdErrorMemClrInvalidParameter
A memclr function of the VStdLib was called with an
invalid pointer parameter
kVStdErrorMemCpyInvalidParameter
A memcpy function of the VStdLib was called with an
invalid pointer parameter
kVStdErrorMemSetInvalidParameter
A memset function of the VStdLib was called with an
invalid pointer parameter
kVStdErrorUnexpectedLockState
A interrupt restore function of the VStdLib is called
but the interrupts are already unlocked. This state is
not expected and must never occur.

Caution
Note that some of the assertions exist solely in case the VStdLib is configured to use
  no library functions. In that case the missing library functionality is implemented directly
in the VStdLib source file.

Note
Not every assertion code is implemented on each hardware.

2013, Vector Informatik GmbH
Version: 1.6.2
18 / 21
based on template version 3.7

Technical Reference VStdLib

8  Limitations
8.1
Interrupt control does not work correctly in user mode
For  proper  functionality  it  is  required  that  the  interrupt  lock  functions  can  modify  the
relevant  bits  (e.g.  Interrupt  Level,  Interrupt  Enable)  in  the  corresponding  registers  (e.g.
processor status word).
If the specific controller supports any non-privileged mode (e.g. user mode) that does not
allow  access  to  the  relevant  registers  and  the  interrupt  lock  APIs  are  called  within  this
context the interrupt lock may not work as expected.
2013, Vector Informatik GmbH
Version: 1.6.2
19 / 21
based on template version 3.7

Technical Reference VStdLib

9  Glossary and Abbreviations
9.1
Glossary
Term
Description
User configuration file  A text file which is appended by the configuration tool to the generated
source files. If a user configuration file is required the technical reference
describes it and the contents.

9.2
Abbreviations
Abbreviation
Description
RI
Reference implementation of the CANbedded CAN driver. The reference
implementation defines the features a CAN driver must provide. From
Reference Implementation 1.5 (RI1.5) the interrupt locking functionality of
each CAN driver is moved to the VStdLib for the specific platform.
VStdLib
Vector Standard Library

2013, Vector Informatik GmbH
Version: 1.6.2
20 / 21
based on template version 3.7

Technical Reference VStdLib

10 Contact
Visit our website for more information on

> News
> Products
> Demo software
> Support
> Training data
> Addresses

www.vector-informatik.com
2013, Vector Informatik GmbH
Version: 1.6.2
21 / 21
based on template version 3.7

Document Outline

13 - VectorBswSuprt Integration Manual

Integration Manual

For

VectorBswSuprt

VERSION: 1

DATE: 02/01/17

Prepared By:

Software Group,

Nexteer Automotive,

Saginaw, MI, USA

Location: The official version of this document is stored in the Nexteer Configuration Management System.

Revision History

Sl. No.	Description	Author	Version	Date
1	Initial version	Lucas Wendling	1.0	02/01/17

Table of Contents

1 Abbrevations And Acronyms 4

2 References 5

3 Dependencies 6

3.1 SWCs 6

3.2 Global Functions(Non RTE) to be provided to Integration Project 6

4 Configuration REQUIREMeNTS 7

4.1 Build Time Config 7

4.2 Configuration Files to be provided by Integration Project 7

4.3 Da Vinci Parameter Configuration Changes 7

4.4 DaVinci Interrupt Configuration Changes 7

4.5 Manual Configuration Changes 7

5 Integration DATAFLOW REQUIREMENTS 8

5.1 Required Global Data Inputs 8

5.2 Required Global Data Outputs 8

5.3 Specific Include Path present 8

6 Runnable Scheduling 9

7 Memory Map REQUIREMENTS 10

7.1 Mapping 10

7.2 Usage 10

7.3 Non RTE NvM Blocks 10

7.4 RTE NvM Blocks 10

8 Compiler Settings 11

8.1 Preprocessor MACRO 11

8.2 Optimization Settings 11

9 Appendix 12

Abbrevations And Acronyms

Abbreviation	Description

References

This section lists the title & version of all the documents that are referred for development of this document

Sr. No.	Title	Version

Dependencies

SWCs

Module	Required Feature

Note : Referencing the external components should be avoided in most cases. Only in unavoidable circumstance external components should be referred. Developer should track the references.

Global Functions(Non RTE) to be provided to Integration Project

Configuration REQUIREMeNTS

Note this component contains a superset of the different versions of the Vector VStdLib. The CANbedded SIP versions of these are in folders following a two-part version structure XX.XX.XX_YY.YY.YY. The AUTOSAR SIP versions of these are in folders following a standard version structure XX.XX.XX. Please note that projects that use both AUTOSAR and CANbedded pieces typically should use the CANbedded versions vs the AUTOSAR versions. The integrator is responsible for selecting the correct version for their particual project (usually driven by what was delivered for that particular program’s Vector SIP delivery) by using the appropriate Green Hills .gpj subproject as will as pointing the include search path to the appropriate subdirectory of this component.

Additionally, some versions of VStdLib are provided with a template file for configuration of the module. If these versions are applicable to the project integrating VStdLib, this template file should be copied into the project for inclusion in the build after adapting the template for the needs of the project. Additionally, the leading underscore should be removed from this file. This file can be found in the “tools/template/” folder of this component. For details on how to adapt, third party documentation found in this component can be referenced as needed.

Build Time Config

Modules	Notes

Configuration Files to be provided by Integration Project

N/A

Da Vinci Parameter Configuration Changes

Parameter	Notes	SWC

DaVinci Interrupt Configuration Changes

ISR Name	Notes

Manual Configuration Changes

Constant	Notes	SWC

Integration DATAFLOW REQUIREMENTS

Required Global Data Inputs

Required Global Data Outputs

Specific Include Path present

Yes

Runnable Scheduling

Third party documentation can be referenced as needed.

Init	Scheduling Requirements	Trigger

Runnable	Scheduling Requirements	Trigger

.

Memory Map REQUIREMENTS

Mapping

Memory Section	Contents	Notes

* Each …START_SEC… constant is terminated by a …STOP_SEC… constant as specified in the AUTOSAR Memory Mapping requirements.

Usage

Feature	RAM	ROM

NvM Blocks

Compiler Settings

Preprocessor MACRO

Optimization Settings

Appendix

14 - VectorBswSuprt Peer Review Checklists

Overview

Summary Sheet
Synergy Project

Sheet 1: Summary Sheet

Rev 1.2

8-Jun-15

Peer Review Summary Sheet

Synergy Project Name:

kzshz2: Intended Use: Identify which component is being reviewed. This should be the Module Short Name from Synergy Rationale: Required for traceability. It will help to ensure this form is not attaced to the the wrong change request. VectorBswSuprt

Revision / Baseline:

kzshz2: Intended Use: Identify which Synergy revision of this component is being reviewed Rationale: Required for traceability. It will help to ensure this form is not attaced to the the wrong change request. Suprt_Vector_Bsw_02.02.00

Change Owner:

kzshz2: Intended Use: Identify the developer who made the change(s) Rationale: A change request may have more than one resolver, this will help identify who made what change. Change owner identification may be required by indusrty standards. Lucas Wendling

Work CR ID:

EA4#9536

kzshz2: Intended Use: Intended to identify at a high level to the reviewers which areas of the component have been changed. Rationale: This will be good information to know when ensuring appropriate reviews have been completed. Modified File Types:

kzshz2: Intended Use: Identify who where the reviewers, what they reviewed, and if the reviewed changes have been approved to release the code for testing. Comments here should be at a highlevel, the specific comments should be present on the specific review form sheet. Rationale: Since this Form will be attached to the Change Request it will confirm the approval and provides feedback in case of audits. ADD DR Level Move reviewer and approval to individual checklist form Review Checklist Summary:

Reviewed:

N/A

MDD

N/A

Source Code

N/A

PolySpace

N/A

Integration Manual

N/A

Davinci Files

Comments:

3rd Party BSW component. Only reviewed 3rd party files for correctness to delivery and any Nexteer created

source files and documentation

General Guidelines:
- The reviews shall be performed over the portions of the component that were modified as a result of the Change Request.
- New components should include FDD Owner and Integrator as apart of the Group Review Board (Source Code, Integration Manual, and Davinci Files)
- Enter any rework required into the comment field and select No. When the rework is complete, review again using this same review sheet and select Yes. Add date and additional comment stating that the rework is completed.
- To review a component with multiple source code files use the "Add Source" button to create a Source code tab for each source file.
- .h file should be reviewed with the source file as part of the source file.

Sheet 2: Synergy Project

Peer Review Meeting Log (Component Synergy Project Review)

Quality Check Items:

Rationale is required for all answers of No

New baseline version name from Summary Sheet follows

Yes

Comments:

Follows convention created for

naming convention

BSW components

Project contains necessary subprojects

N/A

Comments:

Project contains the correct version of subprojects

N/A

Comments:

Design subproject is correct version

N/A

Comments:

General Notes / Comments:

LN: Intended Use: Identify who were the reviewers and if the reviewed changes have been approved. Rationale: Since this Form will be attached to the Change Request it will confirm the approval and provides feedback in case of audits. KMC: Group Review Level removed in Rev 4.0 since the design review is not checked in until approved, so it would always be DR4. Review Board:

Change Owner:

Lucas Wendling

Review Date :

02/03/17

Lead Peer Reviewer:

Rijvi

Approved by Reviewer(s):

Yes

Other Reviewer(s):