CodeWarrior Development Studio Processor Expert RTOS Adapter User Guide

Transcription

1 CodeWarrior Development Studio Processor Expert RTOS Adapter User Guide Document Number: CWPEXRTUG Rev 10.6, 02/2014

2 2 Freescale Semiconductor, Inc.

3 Contents Section number Title Page Chapter 1 Introduction 1.1 RTOS component files RTOS adapter component properties RTOS component methods and events Relation between RTOS adapter component and RTOS adapter driver...8 Chapter 2 RTOS adapter driver 2.1 RTOS adapter driver properties RTOS adapter driver methods and events RTOS adapter driver subroutines Accessing RTOS adapter Naming convention Optional parameters Hosted properties in RTOS component RTOS adapter driver API Memory allocation RTOSAdap_genDriverMemoryAlloc Constraint Parameters arg_destptrbuffer arg_objtype opt_arg_errcode Optional parameters arg_globdefsthread opt_arg_memoryallocparams...13 Freescale Semiconductor, Inc. 3

4 Section number Title Page RTOSAdap_genDriverMemoryDealloc Parameters arg_ptrbuffer arg_objtype Interrupt Vector Table Handling RTOSAdap_genSetInterruptVector Parameters arg_intvectorproperty arg_isrfunctionname arg_isrparametertype arg_isrparametervalue opt_arg_oldisrsettings Optional parameter arg_globdefsthread RTOSAdap_genRestoreInterruptVector Parameters arg_intvectorproperty arg_oldisrsettings RTOSAdap_genISRSettingsVarDeclaration(arg_varName, opt_arg_comment) Parameters arg_varname opt_arg_comment RTOSAdap_genISRFunctionDefinitionOpen Parameters arg_intvectorproperty arg_isrfunctionname arg_isrparametertype arg_isrparametername RTOSAdap_genISRFunctionDefinitionClose Freescale Semiconductor, Inc.

5 Section number Title Page RTOSAdap_genISRFunctionDeclaration Parameters arg_intvectorproperty arg_isrfunctionname arg_isrparametertype arg_isrparametername Synchronization RTOSAdap_genCriticalSectionBegin Parameters opt_arg_genreentrantmethods Optional parameter RTOSAdap_genCriticalSectionEnd Includes and type definitions RTOSAdap_genRTOSTypeDefinitions() RTOSAdap_genRTOSDriverIncludes()...19 Chapter 3 RTOS development process 3.1 Creating new RTOS adapter component Creating new RTOS adapter driver Running new RTOS adapter...22 Freescale Semiconductor, Inc. 5

6 6 Freescale Semiconductor, Inc.

7 Chapter 1 Introduction RTOS adapter component is a standard operating system Processor Expert component used as a programming interface between Processor Expert logical device drivers and the target operating system. The primary role of RTOS adapter component is to provide appropriate code fragments to logical device drivers during a code generation process. This manual describes RTOS adapter component and RTOS adapter driver in detail. Table 1-1. Manual contents RTOS adapter driver RTOS development process Chapter Description Explains RTOS adapter driver and its properties, methods and events, subroutines, and API. Describes how to create a new RTOS adapter for new RTOS. 1.1 RTOS component files RTOS adapter component is added to the Processor Expert project using Component Selector. You can use Component Inspector view to configure the component. To modify the interface of the existing RTOS component or create a new RTOS component, use standard Component Wizard tool of Processor Expert (in basic version it is available in your installation of CodeWarrior). RTOS component is stored in the following files ($PE stands for the root directory of Processor Expert installation, the default directory structure is: Program Files/Freescale/ CodeWarrior/Processor Expert): $PE/beans/<RTOSComponentName>/*.* Contains the description of the component user interface (properties, methods, events) $PE/drivers/<RTOSComponentName>.src Freescale Semiconductor, Inc. 7

8 RTOS adapter component properties Refers to the branching script. It runs the proper RTOS component script type according to symbol DriverExtension value ( $PE/drivers/sw/<RTOSComponentName>.*) $PE/drivers/sw/<RTOSComponentName>.* Contains DRV, TST, TS2, and CHG scripts of RTOS component NOTE All the files and their structure are standard for Processor Expert technology. 1.2 RTOS adapter component properties The properties of RTOS adapter component are: RTOS version is checked against the supported list of RTOS versions. This property is exported to all components in the project. Other components can use this configuration to adapt to the generated code if it depends on RTOS version. Group of properties configuring RTOS adapter. These properties are propagated to the RTOS adapter. 1.3 RTOS component methods and events RTOS adapter component has no methods and events. 1.4 Relation between RTOS adapter component and RTOS adapter driver RTOS adapter driver is a special driver in Processor Expert, internally used in the code generation process to generate code fragments specific to the selected RTOS. RTOS adapter driver is not visible to the user (it is not listed within the project) except the configuration properties of RTOS adapter driver that are included within the group of properties of RTOS component. There is no difference between RTOS adapter component and RTOS adapter driver from the user perspective, but there is a difference from the Processor Expert perspective. Both RTOS adapter component and RTOS adapter driver act as one RTOS adapter. For details, see RTOS adapter driver topic. 8 Freescale Semiconductor, Inc.

9 Chapter 2 RTOS adapter driver RTOS adapter is a special driver in Processor Expert which is internally used in the code generation process to generate the constructions specific for the selected RTOS. The standard Processor Expert component generates the code based on its properties. Such code defines methods that can be called from the application code. RTOS adapter driver works in a different way. RTOS adapter driver does not define methods that can be called, but it provides methods (subroutines in Processor Expert) that can be called during a code generation process. RTOS adapter driver subroutines generate code fragments that are directly placed into the generated code of LDD components in the project. This chapter explains: RTOS adapter driver properties RTOS adapter driver methods and events RTOS adapter driver subroutines Accessing RTOS adapter 2.1 RTOS adapter driver properties RTOS adapter driver typically needs some configuration properties to implement RTOS functionalities on specific RTOS. Configuration properties of RTOS adapter driver are shown in a group in RTOS Adapter Component (user visible). There are no standard RTOS adapter properties (because it depends on possibilities of specific RTOS), but the following is a typical list of property types used: Overriding standard RTOS functions by user-defined implementations. The standard RTOS functions are used. For example, if there is a standard RTOS function for allocation of system memory, this function can be replaced by user-defined function (with same prototype). Providing design-time configurations to RTOS. Freescale Semiconductor, Inc. 9

10 RTOS adapter driver methods and events For example, some features of RTOS can be configured by C #define-s. RTOS adapter is able to configure such features. Such properties are simply propagated into the generated code that configures RTOS. Optimization choices. If some functionality is implemented in more ways, the configuration property can help to choose which implementation is the best from user perspective. Selecting which RTOS resources should be used for LDD components. You are allowed to choose a resource to be used by LDD layer implementation by selecting a configuration property. 2.2 RTOS adapter driver methods and events RTOS adapter does not generate any user-callable methods or events. It provides only code generation subroutines. 2.3 RTOS adapter driver subroutines Code generation subroutines are methods of RTOS adapter that are executed during code generation process. The result of a subroutine execution is a generation of code that performs the desired functionality during run time. The subroutines are implemented in Processor Expert macro language. The two types of RTOS adapter driver subroutines are: Routines specific for target RTOS - these are implemented in file $PE/drivers/SW/ RTOSAdaptor/<rtosName>_RTOSAdaptor.prg. Routines common to all RTOS adapters (typically providing a support for RTOS specific ones) are implemented in $PE/drivers/SW/RTOSAdaptor/Common_RTOSAdaptor.prg file. The API of both types of suboutines is documented directly in the source code in file $PE/ drivers/sw/rtosadaptor/common_rtosadaptor.prg. In the RTOS specific files, only implementation issues related to the respective RTOSes are documented. 10 Freescale Semiconductor, Inc.

11 2.4 Accessing RTOS adapter Chapter 2 RTOS adapter driver If a common LDD component needs to use RTOS adapter, it includes Common \RTOSAdaptor.prg. This includes common RTOS adapter subroutines and also a specific implementation of RTOS adapter for the selected RTOS in the project Naming convention All RTOS adapter subroutine names start with RTOSAdap_ prefix. Name prefix RTOSAdap_priv_ denotes a private subroutine (should not be used) Optional parameters There is a general concept of optional parameters of RTOS adapter subroutines. For some optional parameters, the default value by RTOSAdap_setDefaultParameter() subroutine can be specified (see documentation of each subroutine for which parameters this feature applies) Hosted properties in RTOS component The values of RTOS adapter properties defined in RTOS component are exported to macro-language global symbols by.ts2 file of RTOS component (file $PE/drivers/SW/ <rtosname>/<rtosname>.ts2). Then the exported values are available in global symbols for other LDD components. In both cases (export and usage,), the global symbols are not accessed directly but through RTOS adapter methods. Simple string-like properties are exported from RTOS component into RTOS adapter by RTOSAdap_publishRTOSProperty(). Reading of property values can be done by RTOSAdap_getRTOSProperty(). Property group for overriding the RTOS service calls is exported by RTOSAdap_defineRTOSFunction(). The configured function can be read by RTOSAdap_getRTOSFunction() RTOS adapter driver API The following is a list of RTOS adapter driver API. Freescale Semiconductor, Inc. 11

12 Accessing RTOS adapter Memory allocation RTOS adapter creates an abstraction of memory allocation system of RTOS. RTOS adapter can also implement static memory allocation if dynamic allocation is not available in the RTOS RTOSAdap_genDriverMemoryAlloc Generates code for dynamic memory allocation of object of type arg_objtype and stores the address of allocated object in arg_destptrbuffer. The allocated memory is suitable for direct usage in LDD driver code (paging, protection). If an allocation is not successful, statement arg_errcode will be executed. If dynamic allocation is not supported, the help static object is generated into thread arg_globdefsthread, and the address of such static object is stored in arg_destbufferptr Constraint The generated code cannot be executed within the run time cycle. The only allowed run time scenario is allocation - usage - deallocation (and possibly repeatedly). It is because of simulation of dynamic allocation Parameters arg_destptrbuffer An l-value expression to which the address of allocated object is assigned arg_objtype Type of the allocated object; NOT pointer to that type opt_arg_errcode Code which will be executed if the allocation fails. If run time detection of memory allocation failure is not enabled or supported by RTOS, the parameter is omitted Optional parameters If not specified (or empty), error handling is not generated. 12 Freescale Semiconductor, Inc.

13 arg_globdefsthread Chapter 2 RTOS adapter driver Name of the thread that has been already created by %THREAD CREATE. Specifies where the definition of help static object is generated if dynamic allocation is not supported opt_arg_memoryallocparams Optional memory allocation parameters. Specifies additional optional parameters in format <param1>=<value> <param2>=<value>.... Optional parameters ZERO - Allocates memory block and fill the memory by zero. UNCACHED - Allocates memory block in uncached area. ALIGN=<boundary> - Allocates memory block whose address is a multiple of <boundary> RTOSAdap_genDriverMemoryDealloc Generates a code fragment for dynamic memory de-allocation (if supported) of memory area at address arg_ptrbuffer. The object should be of type arg_objtype. If dynamic allocation is simulated by static allocation, it does nothing Parameters arg_ptrbuffer Expression which evaluates to the address to object to de-allocate arg_objtype Type of the object to de-allocate (NOT pointer to that type) Interrupt Vector Table Handling RTOS adapter provides an abstraction of settings of interrupt vectors. If RTOS provides dynamic reconfiguration of vector table, maps to this RTOS functionality. If vector table is static, Processor Expert can generate it according to the requests. There are also subroutines for generation of ISR function definition and declaration. Freescale Semiconductor, Inc. 13

14 Accessing RTOS adapter RTOSAdap_genSetInterruptVector Generates the code fragment which routes interrupt vector with name defined by arg_intvectorproperty component property to ISR function with name arg_isrfunctionname. The ISR function obtains an argument of type arg_isrparametertype. The value of such parameter is defined by arg_isrparametervalue. The previous settings of the interrupt vector (handling ISR function and ISR function argument value) are stored into arg_oldisrsettings. If run time allocation of ISR vectors is not available, ISR vector is allocated statically in the interrupt vector table generated by Processor Expert, and the parameter passed into the ISR function is transferred by help global variable; its definition is generated into thread arg_globdefsthread. The code generated by this subroutine and by RTOSAdap_genISRFunctionDefinition() must have access to this possibly generated global symbol. NOTE The generated code requires access to the interrupt vector index constants. See RTOSAdap_getInterruptVectorSymbol topic for details Parameters arg_intvectorproperty Name of the interrupt vector component property arg_isrfunctionname Name of the ISR function which will handle the interrupt vector. ISR function declaration/definition must be generated by proper RTOS adapter subroutines, RTOSAdap_genISRFunctionDefinition* and RTOSAdap_genISRFunctionDeclaration* arg_isrparametertype Type of the ISR function parameter passed into the ISR function arg_isrparametervalue Expression which evaluates to the value of type arg_isrparametertype. The value will be passed into ISR function as an argument opt_arg_oldisrsettings An l-value expression to which the previous settings of interrupt vector are saved. The definition of such object should be generated by RTOSAdap_genISRSettingsVarDeclaration(). 14 Freescale Semiconductor, Inc.

15 Chapter 2 RTOS adapter driver Optional parameter If not specified, old vector settings are not saved arg_globdefsthread Name of the generation thread created by %THREAD CREATE. Specifies where a global variable definition should be generated if run time installation of ISR vectors is not available RTOSAdap_genRestoreInterruptVector Generates the code which restores the settings of the interrupt vector (handling ISR function and ISR function argument value) with name defined by arg_intvectorproperty component property to the state specified by arg_oldisrsettings. NOTE The generated code requires access to the interrupt vector index constants. Refer RTOSAdap_getInterruptVectorSymbol and RTOSAdap_genSetInterruptVector() for details Parameters arg_intvectorproperty Name of the interrupt vector component property arg_oldisrsettings Expression evaluating to the settings to which the interrupt vector. The definition of such object should be generated by RTOSAdap_genISRSettingsVarDeclaration() RTOSAdap_genISRSettingsVarDeclaration(arg_varName, opt_arg_comment) Generates the C declaration of object storing the settings of ISR vector (handling ISR function and ISR function argument value). If generated inside C function body, it results into definition of automatic variable with name arg_varname. If generated inside C structure definition, it results into declaration of structure member with name arg_varname. If generated outside any function definition, it results into definition of global variable with name arg_varname. Freescale Semiconductor, Inc. 15

16 Accessing RTOS adapter Parameters arg_varname Name of the variable/struct member to declare opt_arg_comment Optional comment for the declaration RTOSAdap_genISRFunctionDefinitionOpen Generates the definition of C function named arg_isrfunctionname that can be used as an ISR function for interrupt vector with name defined by arg_intvectorproperty component property. Generates also opening { of the function body and also (if needed) RTOS specific ISR prolog (saving registers, handling stack pointer). The symbol arg_isrparametername of type arg_isrparametertype can be used inside the function body. This symbol contains the value defined during installation of the ISR function. NOTE The code generated by this subroutine must have access to the possibly generated global symbol by RTOSAdap_genSetInterruptVector(). NOTE There can be some RTOS specific limitations to arg_isrparametertype type. See documentation of concrete RTOS adapter for details. NOTE To generate ISR epilog and closing }, use RTOSAdap_genISRFunctionDefinitionClose() Parameters arg_intvectorproperty Name of the interrupt vector defined arg_isrfunctionname component property which can be handled by the ISR function arg_isrfunctionname Name of the C function to define. 16 Freescale Semiconductor, Inc.

17 Chapter 2 RTOS adapter driver arg_isrparametertype Type of the parameter passed into the ISR function arg_isrparametername Name of the parameter passed into the ISR function. This name can be used within the function body to access the value defined during ISR function installation. The parameter evaluates to arg_isrparametertype RTOSAdap_genISRFunctionDefinitionClose Pair subroutine to RTOSAdap_genISRFunctionDefinitionClose() RTOSAdap_genISRFunctionDeclaration Generates the declaration of C function arg_isrfunctionname that can be used as an ISR function for interrupt vector with name defined by arg_intvectorproperty component property. NOTE There can be some RTOS specific limitations to arg_isrparametertype type. See documentation of concrete RTOS adapter for details. NOTE To generate ISR epilog and closing }, use RTOSAdap_genISRFunctionDefinitionClose() Parameters arg_intvectorproperty Name of the interrupt vector defined arg_isrfunctionname component property that can be handled by the ISR function arg_isrfunctionname Name of the C function to declare. Freescale Semiconductor, Inc. 17

18 Accessing RTOS adapter arg_isrparametertype Type of the parameter passed into the ISR function arg_isrparametername Name of the parameter passed into the ISR function; only declaration is generated, so the parameter name is only for information Synchronization There is supported generation of two basic synchronization constructions - methods reentrancy (monitor) and critical sections (interrupts disable/enable) RTOSAdap_genCriticalSectionBegin Generates the code for entering the critical section. All code inside the critical section is protected against interrupting by any interrupt. It is typically implemented as disabling of interrupts. NOTE If reentrancy of methods (see RTOSAdap_genReentrantMethodBegin()) is handled by disabling interrupts, and if methods are required to be reentrant, code may not be generated. The generated code must be in pair with the code generated by RTOSAdap_genCriticalSectionEnd(). The critical section must always be dynamically nested within the code generated by RTOSAdap_genReentrantMethodBegin()/ End() (even if reentrant methods are not required). NOTE It is supported that critical sections can be dynamically nested. For example, a method can be called containing critical section from different critical section Parameters opt_arg_genreentrantmethods Contains 'yes' or 'no' if reentrant methods are or are not required for the current LDD component. It is used only if generation of critical sections can be optimized for this parameter. 18 Freescale Semiconductor, Inc.

19 Chapter 2 RTOS adapter driver Optional parameter If not specified, a default value specified by RTOSAdap_setDefaultParameter() is used RTOSAdap_genCriticalSectionEnd Pair subroutine to RTOSAdap_genCriticalSectionBegin() Includes and type definitions Code generated by RTOS adapter requires some includes and type definitions to be placed into the code, so subroutines are available to generate them RTOSAdap_genRTOSTypeDefinitions() Generates the definitions of RTOS specific types (types with name LDD_RTOS_*). This type should be declared in (or included into) every module where any code generated by the RTOS adapter is used RTOSAdap_genRTOSDriverIncludes() Generates proper #includes to access RTOS driver's API. It is necessary to process these includes before code generated by RTOSAdap_genDriverInstallationsFunctionDefinition() occurs. Freescale Semiconductor, Inc. 19

20 Accessing RTOS adapter 20 Freescale Semiconductor, Inc.

21 Chapter 3 RTOS development process This chapter describes how to create a new RTOS adapter for new RTOS. This chapter explains: Creating new RTOS adapter component Creating new RTOS adapter driver Running new RTOS adapter 3.1 Creating new RTOS adapter component To create a new RTOS component: 1. Use Component Wizard tool to create a new RTOS adapter component. a. Create a new component. b. Fill the short hint, author name, and change the icon (optional). c. Select component category SW Operating System. 2. Add one property of RTOS component (optional) Select the property of type Enumeration for selecting the version of RTOS. This property is optional. 3. Remove the existing RTOS adapter group containing properties to select between RTOS native or user-defined functions to enter/exit into/from a critical section. 4. Add configuration properties of new RTOS adapter. These properties are all RTOS specific. 5. Add calls of export/publish subroutines to the.ts2 file of the RTOS components to export/publish all RTOS adapter properties. For details, see Hosted properties in RTOS component topic. 6. There is a limitation of current Component Wizard distributed with CodeWarrior. As a workaround for this, open bean XML file of RTOS Component located at: $PE/ beans/<rtosname>.bean1 and add <OperatingSystemId>XXX</OperatingSystemId> to the / <Options> new child XML element. Replace XXX with the name of RTOS. Freescale Semiconductor, Inc. 21

22 Creating new RTOS adapter driver NOTE On Windows Vista, the bean file can be created at $SystemDrive/Program Data/Processor Expert/CW/beans/ <rtosname>.bean depending on the permissions on the Program Files directory. 3.2 Creating new RTOS adapter driver The RTOS adapter implementation is stored in a file <OperatingSystemId>_RTOSAdap.prg located at: $PE/drivers/SW/RTOSAdaptor/. To create a new RTOS adapter driver: 1. Create RTOS adapter driver implementation file manually or by copying already existing RTOS adapter driver. For example, Bareboard_RTOSAdaptor.prg. 2. Implement all subroutines required by $PE/drivers/SW/RTOSAdaptor/Common_RTOSAdap.prg file according to the RTOS adapter subroutines documentation (see Accessing RTOS adapter topic for details). To access the RTOS adapter property values, use common RTOS adapter subroutines for getting exported/published parameters (see Hosted properties in RTOS component topic for details). 3.3 Running new RTOS adapter 1. Create a new Processor Expert project or a CodeWarrior project using Processor Expert. 2. Add a new RTOS adapter component. This automatically selects RTOS adapter driver. All LDD components in the project will use new RTOS adapter to generate the code. 22 Freescale Semiconductor, Inc.

23 How to Reach Us: Home Page: freescale.com Web Support: freescale.com/support Information in this document is provided solely to enable system and software implementers to use Freescale products. There are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits based on the information in this document. Freescale reserves the right to make changes without further notice to any products herein. Freescale makes no warranty, representation, or guarantee regarding the suitability of its products for any particular purpose, nor does Freescale assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. Typical parameters that may be provided in Freescale data sheets and/or specifications can and do vary in different applications, and actual performance may vary over time. All operating parameters, including typicals, must be validated for each customer application by customer's technical experts. Freescale does not convey any license under its patent rights nor the rights of others. Freescale sells products pursuant to standard terms and conditions of sale, which can be found at the following address: freescale.com/salestermsandconditions. Freescale, the Freescale logo, CodeWarrior, and Processor Expert are trademarks of Freescale Semiconductor, Inc., Reg. U.S. Pat. & Tm. Off. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. Document Number CWPEXRTUG Revision 10.6, 02/2014