ST AN2618 Application note

AN2618

Application note

eTPU host interface

Introduction

The eTPU is the new generation of Time Processing Unit (TPU). Besides the hardware
enhancement, significant improvements have been made to the accompanying software
development tools; these tools make the enhanced Time Processing Unit (eTPU) easy to
use. A high level language (C) compiler has been developed to allow the user to program
the eTPU by using C language instead of microcode.

To program the eTPU effectively, the programmer still needs to have a clear understanding
of how the eTPU hardware works. Coding in C, the programmer can focus more on the
application logic and leave the mechanics of the eTPU programming to the compiler (i.e.,
register usage and tracking, parameter packing, micro-instruction packing, etc.). With the
help of the eTPU simulator and debugger, eTPU software can be developed much like the
software for the host CPU. Productivity of software development can be significantly
improved.

The introduction of the eTPU C compiler also changes the way the host interfaces to the
eTPU functions. With the help of the compiler, the same symbol can be referenced by the
both eTPU and host software. The host software can interface with eTPU functions via API
functions, instead of accessing physical memory locations and registers. For each eTPU
function, a host interface API function can now be developed as a part of the eTPU C
program. The host application can call these API functions to interface with the eTPU. The
references to these API functions and symbols for parameters are resolved at compile time.
The implementation details of the eTPU functions are hidden from the host application. This
design improves the flexibility of the eTPU functions’ implementation and the portability of
the host application code. This application note discusses how to build the host interface for
eTPU functions.

This application note shows how to build the host interface to access eTPU functions. The
eTPU PWM driver is used as an example to illustrate what the host needs to do to configure
eTPU module, channel and initialize PWM function. The application note also describes the
details of how to export eTPU software information to the host compiler. The working code
example is presented in the Appendix. The user can compile both host and eTPU code,
then download to actual hardware for testing.

September 2007 Rev 1 1/23

www.st.com

Contents AN2618

Contents

1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 eTPU and host interface hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Host interface software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1 Initialization overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.2 eTPU module initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.3 eTPU channel initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.4 eTPU function initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.5 eTPU and host interactive control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4 Software integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Appendix A Code example 1.main.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Appendix B Code example 2.etpu_PWMControl.h . . . . . . . . . . . . . . . . . . . . . . . 12

Appendix C Code example 3.etpuc_pwm.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Appendix D Code example 4.etpuc_image.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Appendix E Code example 5.etpu_pwm_auto.h . . . . . . . . . . . . . . . . . . . . . . . . . 17

Appendix F Code example 6.utility.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Appendix G Code example 7.etpu_pwm.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2/23

AN2618 Overview

1 Overview

Host interface software adds another layer of abstraction between the host CPU and eTPU.
The host interface API functions hide the complexity of the interaction between the host
CPU and eTPU, providing a simple interface for host applications. Ideally, every eTPU
function shall have one or more host interface API functions.

The interface software between host and eTPU facilitates three major tasks:

1. eTPU hardware initialization – configure eTPU peripheral hardware

2. eTPU function initialization – pass initial parameters and initiate function execution

3. eTPU function run time interactive control – update function parameters and handle
handshaking

Once the eTPU peripheral and eTPU functions are initialized, each eTPU function can start
to execute with initial function parameters. The host interface API functions need to be
provided for interactive control (i.e. parameters updating and control mode changing etc.).
To update the parameter or change control mode, the host is responsible for passing
updated parameters to the eTPU functions, and then informing the eTPU that the function
parameters have changed. If a coherent change of function parameters is required, the logic
has to be built in the eTPU functions to ensure the coherency. For some eTPU functions, the
interaction between host and eTPU is an essential part of the operation. In both host and
eTPU software, the logic is needed to handle the handshaking between host and eTPU. The
interaction between the eTPU and host can be encapsulated in the host interface API
functions.

The host code and eTPU code are compiled by different compilers. The host compiler is
normally used to build a single code image for both host and eTPU. In order to build eTPU
code and host code together, the eTPU software building information (i.e. eTPU code
image) has to be exported to the host compiler. The symbol information has to be exported
from the eTPU compiler to the host compiler as well. For the Byte Craft eTPU compiler, the
mechanism is implemented as a set of host interface macros. In the eTPU code, these
macros are inserted to generate proper executable and symbol information for the host
compiler.

The host interface design process is illustrated in the eTPU PWM driver examples in the
Appendices.

3/23

eTPU and host interface hardware AN2618

2 eTPU and host interface hardware

The host interface hardware for the eTPU is shown in Figure 1. The host and eTPU can
communicate to each other via event or by data.

The host has access to all eTPU host interface registers. When the host wants the eTPU’s
services, it can issue the host service request (HSR) by writing the eTPU channel control
registers. Once the host service request is acknowledged, a thread of eTPU code
associated with this HSR is activated for execution. The eTPU code in the thread
implements the functions requested by the host. When eTPU needs the host service, it can
issue the interrupt request or DMA data transfer request, or generate a global exception.
The events handling logic is needed in the host software to provide services to the eTPU
corresponding to these requests.

The eTPU code memory (RAM) and data memory (RAM) are accessible by both host and
eTPU. eTPU code memory stores the eTPU executable binary image. At the power up
initialization, following the defined sequences, the host transfers the eTPU code stored in
the flash memory to the eTPU code memory. During the execution, the eTPU micro-engine
fetches the micro-instructions from the code memory.

Figure 1. eTPU host interface hardware

The eTPU data memory is implemented by using tri-port RAM. It provides for data sharing
between the host and eTPU engines. Both host and eTPU can read and write the eTPU
data memory in any data size (8, 16, 24, and 32 bit). Since the eTPU data bus is 24 bits
wide, it is best to pack together a data word with an 8 bit value and a 24 bit value in order to
reduce data memory utilization. To reduce the overhead of packing and unpacking the data,
a virtual mirror memory space of the normal eTPU data memory has been created. The
virtual memory space is called Parameter Sign Extension (PSE) memory space. When the
host reads the 32-bit data from the PSE memory space, it will return the sign extended 24­bit data. The conversion is needed if the 24-bit data is unsigned. Similarly, when the host
writes the 32-bit data to the eTPU PSE memory, only the three least significant bytes will be
written to the eTPU data memory. The most significant byte is untouched.

4/23

AN2618 Host interface software

3 Host interface software

The function partition between the application software and low-level driver is defined during
the software architecture design. To make the software portable, the application software is
normally designed to interface with the low-level driver via abstracted interface APIs. The
host interface of the eTPU functions should be designed such that the implementation of the
low-level driver is hidden from the application software.

Once the application software interface to the low-level driver is defined, the functionality of
the low-level driver can be partitioned between host CPU and eTPU. The eTPU interface
software running on the host CPU is an integral part of the low-level driver. It handles the
details of the interaction between host and eTPU.

The eTPU code and host interface code are compiled by two different compilers. In order to
resolve the eTPU code symbol reference in the host code, it is necessary to export the
symbolic information from the eTPU compiler to the host compiler. Similarly, to build a single
executable image, it is necessary to export eTPU code image to the host compiler. Several
types of information are exported from eTPU_C through host interface files, generated from

#pragma write statements during compilation. For detailed information on #pragma
write, see the eTPU_C documentation.

An example of application software and low-level driver partition is shown in Appendix A on

page 11.

3.1 Initialization overview

The eTPU initialization is an important part of the host interface. At the power up, the host
has to configure the eTPU peripheral properly before the eTPU function can be executed.
The eTPU initialization process is accomplished by both host CPU and eTPU. During the
initialization, the functional partition between host CPU and eTPU is as follows:

Host responsibility:

● eTPU module initialization

● eTPU channel configuration

● Providing initial eTPU function parameters

● Initiating the eTPU function execution

eTPU responsibility:

● Responding to the HSR

● Transitioning into the initialization state

The eTPU initialization can be broken down into three steps: eTPU module initialization,
eTPU channel initialization and eTPU function initialization. The following sections discuss
the interface design and the data exchange between host CPU and eTPU for each step of
initialization.

3.2 eTPU module initialization

At the power up initialization, the eTPU peripheral hardware is configured by the host. The
eTPU module initialization includes the following steps:

5/23

Host interface software AN2618

1. Initialize eTPU global registers

– eTPU MISC Compare Register (ETPU_MISCCMPR)

– eTPU Module Configuration Register (ETPU_MCR)

– eTPU Time Base Configuration Register (ETPU_TBCR)

– eTPU STAC Bus Configuration Register (ETPU_STACR)

– eTPU Engine Configuration Register (ETPU_ECR)

2. Load eTPU code from flash memory to eTPU code RAM

3. Copy initial values of eTPU code global variables to eTPU data memory

Most of the information required to configure the eTPU global registers are not dependent
on the eTPU software implementation (i.e., time base, clock frequency, entry table address,
etc.). The configuration information is determined during the host peripheral configuration
and resource allocation. Only the MISC value depends on the actual eTPU software
implementation; it has to be exported to the host program after the eTPU code is compiled.
The eTPU_C compiler provides a macro (::ETPUmisc) to calculate the MISC value of the
eTPU code image (see Appendix C on page 13).

The eTPU code image is generated when the eTPU C program is compiled. To use this
code in the host program, the eTPU code image can be exported as an array of constant
values. The eTPU_C compiler provides a macro (::ETPUcode) to generate and export the
eTPU code image (see Appendix C on page 13). The eTPU code image constant array is
suitable to be included in the host source code. The host compiler locates the eTPU code
image array in the flash memory at host source code compile time. Since the eTPU micro­engine can only fetch micro-instructions out of eTPU code memory (RAM), at the power up
initialization, the eTPU code image has to be loaded to eTPU code memory.

As it is in the standard C syntax, when the eTPU code is compiled, the global variables are
allocated to the eTPU data memory and the initial values are assigned to the corresponding
memory locations. The standard C syntax requires that all global variables are declared
outside of any function. For eTPU, this means that all global variables have to be declared
outside of any execution thread. Since only the code in a thread can be executed on eTPU,
the global variable initial value assignment statements will not be executed. The global
variables cannot be initialized in the eTPU code; they must be initialized by the host.

The software statements have to be added to the host code to initialize the eTPU global
variables. The initialization values have to be exported from the eTPU compiler to host
compiler. The eTPU_C compiler provides a macro (::ETPUglobalimage) to capture initial
values for all global variables and exports them as a constant array (Appendix D on page

16). At power up initialization, the global variable initial values are loaded to the eTPU data

memory for global variables.

The host interface macros have to be added to the eTPU code in #pragma write
statements to export the eTPU software information to the host compiler (Appendix C on

page 13). These statements will generate header files that contain the MISC value, eTPU

code image and global variable memory image (Appendix D on page 16).

The software for the eTPU module initialization can be encapsulated in an API function. An
example of the eTPU module initialization function implementation is provided in Appendix F

on page 18 (mc_etpu_init()).

6/23

AN2618 Host interface software

3.3 eTPU channel initialization

After the eTPU module is configured, each channel on the eTPU module can be configured.
eTPU channel initialization includes the following tasks:

1. eTPU channel configuration registers initialization

– Assign eTPU function to a channel

– Setup channel priority

– Configure interrupt/DMA/Output enable

– Select eTPU function entry table encoding

– Assign the function frame to a channel

2. eTPU channel status control register initialization

– Set up eTPU function mode

The eTPU channel assignment and the channel priority determination are a part of the host
software architecture design. They are independent of the eTPU functions implementation.
The information for the configuration is provided by the host software design.

During the channel initialization, a section of eTPU data memory is assigned to each
channel. This memory section is called the “function frame”. The function frame contains all
the function parameters and static local variables used by the eTPU function. The starting
address of the function frame is assigned to the channel at initialization. The function frame
assignment can be static or dynamic. Dynamic allocation assigns the function frame to the
channel based on the next available memory space. The availability of the eTPU data
memory depends on the number of functions that have been assigned and the number of
parameters the function is using. Dynamic allocation can reduce the eTPU data memory
consumption by minimizing unused memory ‘holes’. To allocate the function frame
dynamically, the host must know the function frame consumption by a particular eTPU
function. The eTPU_C compiler provides a macro (::ETPUram) to report the number of
parameters and static local variables used by a function at compile time (Appendix C on

page 13).

The eTPU function table entry encoding, interrupt enable, DMA enable, output enable,
output polarity, and function mode are constants specific to the eTPU function software
implementation. It is a good practice to define them only once in the eTPU code and export
the configuration information at compile time.

Once the host interface macros are added to the eTPU code (Appendix C on page 13), the
#pragma write statements will generate a header file that contains all the eTPU function
configuration and software symbol information at compile time (Appendix E on page 17).
The header file can be included in the host interface code to resolve symbol references.

3.4 eTPU function initialization

The eTPU function initialization is the last step of the eTPU initialization process. During the
eTPU function initialization, the host is responsible for passing the parameters to the eTPU
functions and initiating the eTPU function execution by issuing a host service request. Once
the host service request for initialization is recognized, the eTPU will transition to the
initialization state.

Unlike in the host CPU, the eTPU function parameters passed from host are not placed on
the stack. Instead, memory in the function frame is allocated to accommodate every function
parameter. The host passes the eTPU function parameters by writing directly to the eTPU

7/23