XMC Peripheral Library for XMC4000 Family
Introducing XMC Peripheral Library
xmc.png

The XMC Peripheral Library (XMC Lib) consists of low-level drivers for the XMC product family peripherals.
Built on top of the Cortex Microcontroller Software Interface Standard (CMSIS), it provides access to all peripheral features.

Supported devices and toolchains

The following 32-Bit Industrial Microcontrollers based on ARM Cortex-M4F are supported:

  • XMC4800 series
  • XMC4700 series
  • XMC4500 series
  • XMC4300 series
  • XMC4400 series
  • XMC4200 series
  • XMC4100 series

The following toolchains are supported:

  • GNU GCC for ARM 11.3.1. (provided with ModusToolbox 3.2).

Overview

XMC Lib consists of routines and data structures which cover all peripheral functions.

It provides a peripheral register abstraction by a set of stateless APIs. It is possible to write a full application without a single peripheral register access.

It is built on top of Cortex Microcontroller Software Interface Standard (CMSIS).

architecture.png

Coding Rules and Conventions

This section describes the set of coding rules and conventions applied to the XMC Peripheral Library:

  • Strict C99 usage, in addition unions and bitfields are used for more compact code and data section.
  • Use only standard data types
  • Use enumerations in favor of defines
  • Naming convention:
    • Variables use only lower case, underscore separated words.
    • Functions use CamelCase convention.
  • Non blocking APIs for better integration in event driven applications. Polling is supported as well by API.
  • Runtime error checking can be enabled by user
  • XMC_ASSERT() used to check input parameters of functions, result of calculations, ... .
    Note
    Only enabled if XMC_ASSERT_ENABLE macro is defined
  • XMC_DEBUG() used to monitor status of application.
    Note
    Only enabled if XMC_DEBUG_ENABLE macro is defined
  • Each driver defines its own namespace: every function and type definition is prefixed by a unique identifier, i.e. XMC_VADC

XMC Peripheral Library follows an object oriented approach, where instances of peripherals are treated as objects = attributes + functions.
Attributes are the peripheral data structures defined in device header file. These gets configured using configuration data structures using initialization functions.
Peripheral functions take a pointer to the peripheral data struct as the first argument.
XMC Peripheral Library uses naming conventions to bind the data struct and the functions that operate on i, i.e. XMC_PERI_DoSomething(XMC_PERI_t const *peri, ...);

Typically a driver contains the following functionality:

  1. Initialization function
    XMC_PERI_STATUS_t XMC_PERI_Init(XMC_PERI_t *const peri, const XMC_PERI_CONFIG_t const *config);
  2. Enable/disable peripheral functions
    void XMC_PERI_Enable(XMC_PERI_t *const peri);
    void XMC_PERI_Disable(XMC_PERI_t *const peri);
  3. Connectivity functions
    void XMC_PERI_SetInputSource(XMC_PERI_t *const peri, ...);
  4. Event handling functions
    void XMC_PERI_Enable(XMC_PERI_t const *peri);
    void XMC_PERI_Disable(XMC_PERI_t const *peri);
    void XMC_PERI_EnableEvent(XMC_PERI_t const *peri);
    void XMC_PERI_DisableEvent(XMC_PERI_t const *peri);
    void XMC_PERI_TriggerEvent(XMC_PERI_t const *peri);
    uint32_t XMC_PERI_GetEventStatus(XMC_PERI_t const *peri);
    void XMC_PERI_SetInterruptNode(XMC_PERI_t const *peri);
  5. Control functions
    void XMC_PERI_Start(XMC_PERI_t const *peri);
    void XMC_PERI_Stop(XMC_PERI_t const *peri);
    void XMC_PERI_Suspend(XMC_PERI_t const *peri);
    void XMC_PERI_Resume(XMC_PERI_t const *peri);
  6. Get/setters functions, run time API to obtain or modify state of peripheral
    void XMC_PERI_SetSomething(XMC_PERI_t const *peri, ...);
    uint32_t XMC_PERI_GetSomething(XMC_PERI_t const *peri);
  7. IRQ Handlers are provided which can be used optionally by the user to make easier the coding
    void XMC_PERI_IRQHandler(uint32_t sr_num);

A peripheral driver is structured as:

  • Common API valid for all the supported devices, i.e. xmc_gpio.h and xmc_gpio.c
  • Family specific extension API, i.e. xmc4_gpio.h and xmc4_gpio.c
  • Maps files to help user to configure connectivity, i.e. xmc4_gpio_map.h already has defined all the pins available depending on the target device selected.

If needed the family extension API implementation file, i.e. xmc4_gpio.c, can also overload common functionality to adapt it to target device. The peripheral driver abstracts the target device, helping the user in code porting to another family or device.

include.png

How to use the XMC Peripheral Library

The following steps are required:

  1. Include header file of required peripheral. No need to include device specific peripheral header files, this is done automatically using the information of the selected target device.
  2. Peripheral configuration and initialization.
  3. Connectivity configuration.
  4. Event/interrupt configuration.
  5. Start operation.
  6. IO configuration.
  7. Manage peripheral.
/* Include files */
#include "xmc_gpio.h"
#include "xmc_i2c.h"
...
int main(void)
{
/* Peripheral configuration and initialization. */
i2c_cfg.baudrate = 400000U;
/* Connectivity configuration. */
/* Event/interrupt configuration. */
NVIC_SetPriority(USIC0_0_IRQn, NVIC_GetPriorityGrouping(), 63, 0);
NVIC_EnableIRQ(USIC0_0_IRQn);
/* Start operation. */
/* IO configuration. */
XMC_GPIO_SetMode(P1_1, XMC_GPIO_MODE_OUTPUT_OPEN_DRAIN | P1_1_AF_U0C0_SCLKOUT);
...
/* Manage peripheral */
{
/* wait for ACK */
}
XMC_I2C_CH_ClearStatusFlag(XMC_I2C1_CH0, XMC_I2C_CH_STATUS_FLAG_ACK_RECEIVED);
...

Device Names

The selection of the target device is done through preprocessor macro, i.e. -DXMC4500_F144x1024 (refer to devices names below)

XMC4800 Series device names:

  • XMC4800_E196x2048
  • XMC4800_F144x2048
  • XMC4800_F100x2048
  • XMC4800_E196x1536
  • XMC4800_F144x1536
  • XMC4800_F100x1536
  • XMC4800_E196x1024
  • XMC4800_F144x1024
  • XMC4800_F100x1024

XMC4700 Series device names:

  • XMC4700_E196x2048
  • XMC4700_F144x2048
  • XMC4700_F100x2048
  • XMC4700_E196x1536
  • XMC4700_F144x1536
  • XMC4700_F100x1536

XMC4500 Series device names:

  • XMC4500_E144x1024
  • XMC4500_F144x1024
  • XMC4500_F100x1024
  • XMC4500_F144x768
  • XMC4500_F100x768
  • XMC4502_F100x768
  • XMC4504_F100x512
  • XMC4504_F144x512

XMC4400 Series device names:

  • XMC4400_F100x512
  • XMC4400_F64x512
  • XMC4400_F100x256
  • XMC4400_F64x256
  • XMC4402_F100x256
  • XMC4402_F64x256

XMC4300 Series device names:

  • XMC4300_F100x256

XMC4200 Series device names:

  • XMC4200_F64x256
  • XMC4200_Q48x256

XMC4100 Series device names:

  • XMC4100_F64x128
  • XMC4100_Q48x128
  • XMC4104_F64x128
  • XMC4104_Q48x128
  • XMC4104_F64x64
  • XMC4104_Q48x64
  • XMC4108_F64x64
  • XMC4108_Q48x64

Directories and Files

The following diagram shows the most important directories and files provided in the distribution.

* mtb-xmclib-cat3                           - XMClib root directory
* +-- CMSIS/Infineon                        - Includes device header files, system and startup files
* +-- Newlib                                - C standard library implementation intended for use on embedded systems
* +-- XMCLib                                - XMC Peripheral Library API root directory
* │   +-- doc                               - Doxygen configuration files to generate documentation
* │   +-- inc                               - XMC Peripheral Library API interface files
* │   +-- src                               - XMC Peripheral Library API implementation files
* +-- device-info                           - Configuration files that defines a resource behavior for ModusToolbox Device Configurator
* +-- docs                                  - XMC Peripheral Library documentation generated with Doxygen
* │   +-- xmc1_api_reference_manual.html    - XMC Peripheral Library documentation with XMC1 specific information
* │   +-- xmc4_api_reference_manual.html    - XMC Peripheral Library documentation with XMC4 specific information
* +-- props.json                            - Device description file for ModusToolbox Device Configurator
* +-- README.md                             - Description of the library
* +-- RELEASE.md                            - Description of the changes in the release 

XMC Lib examples

The XMC Lib examples could be found at https://github.com/Infineon/Code-Examples-for-ModusToolbox-Software

Create the project and open it using one of the following:

In Eclipse IDE for ModusToolbox

  1. Click the New Application link in the Quick Panel (or, use File > New > ModusToolbox Application). This launches the Project Creator tool.
  2. Pick a kit supported by the code example from the list shown in the Project Creator - Choose Board Support Package (BSP) dialog.
  3. In the Project Creator - Select Application dialog, choose the example by enabling the checkbox.
  4. Enter the local path in the Application(s) Root Path field to indicate where the application needs to be created.
  5. Click Create to complete the application creation process.

For more details, see the Eclipse IDE for ModusToolbox User Guide

In Command-line Interface (CLI)

ModusToolbox provides the Project Creator as both a GUI tool and a command line tool to easily create one or more ModusToolbox applications. See the "Project Creator Tools" section of the ModusToolbox User Guide for more details.

Alternatively, you can manually create the application using the following steps:

  1. Download and unzip this repository onto your local machine, or clone the repository.
  2. Open a CLI terminal and navigate to the application folder.
  3. Import the required libraries by executing the make getlibs command.

Various CLI tools include a -h option that prints help information to the terminal screen about that tool. For more details, see the ModusToolbox User Guide.

Test conditions

  • Limited functional test is applied with XMC4700-F144x2048.

Compilers used :

  • GNU GCC for ARM 11.3.1.

XMC Peripheral Library Licensing

License Terms and Copyright Information

Copyright (c) 2015-2024, Infineon Technologies AG All rights reserved.

Boost Software License - Version 1.0 - August 17th, 2003

Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following:

The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

To improve the quality of the software, users are encouraged to share modifications, enhancements or bug fixes with Infineon Technologies AG at XMCSu.nosp@m.ppor.nosp@m.t@inf.nosp@m.ineo.nosp@m.n.com.

Legal Disclaimer The information given in this document shall in no event be regarded as a guarantee of conditions or characteristics. With respect to any examples or hints given herein, any typical values stated herein and/or any information regarding the application of the device, Infineon Technologies hereby disclaims any and all warranties and liabilities of any kind, including without limitation, warranties of non-infringement of intellectual property rights of any third party.

Information For further information on technology, delivery terms and conditions and prices, please contact the nearest Infineon Technologies Office (www.infineon.com).

Warnings Due to technical requirements, components may contain dangerous substances. For information on the types in question, please contact the nearest Infineon Technologies Office. Infineon Technologies components may be used in life-support devices or systems only with the express written approval of Infineon Technologies, if a failure of such components can reasonably be expected to cause the failure of that life-support device or system or to affect the safety or effectiveness of that device or system. Life support devices or systems are intended to be implanted in the human body or to support and/or maintain and sustain and/or protect human life. If they fail, it is reasonable to assume that the health of the user or other persons may be endangered.