StdDotH

From Texas Instruments Embedded Processors Wiki

Jump to: navigation, search

Translate this page to

Introduction

This topic addresses frequently asked questions about data types introduced by the <xdc/std.h> file provided by the XDCtools, and describes "Best Known Methods" used in, and promoted by, TI.

The approaches recommended are strongly aligned with recommended practices for consuming RTSC content.

Which std.h should I use?

Source code should always use #include <xdc/std.h>; i.e., the std.h that is in the xdc package. Then, if you are not using the xdc build engine to build your code (i.e., package.bld-based builds), you must also specify the target that you are building for.

How do you specify the target? You must define 2 symbols (typically via the -D option to the compiler):

xdc_target_types__
xdc_target_name__

The table below shows the setting for a variety of targets:

If you are using a TI compiler: -Dxdc_target_types__=ti/targets/std.h
- For a C64P device, add: -Dxdc_target_name__=C64P
If you are using a gcc ARM compiler add the following: -Dxdc_target_types__=gnu/targets/arm/std.h
- For an v5T runtime environment, add: -Dxdc_target_name__=GCArmv5T
If you are using a Microsoft compiler add the following: : -Dxdc_target_types__=microsoft/targets/arm/std.h
- For a WinCE runtime environment, add: -Dxdc_target_name__=WinCE

There are more details on the Integrating RTSC Modules article.

Why is this necessary? The definitions of base types are (unfortunately) compiler specific, so we need to identify the compiler. We must also allow customers to use any compiler to build source packages, so it is not possible for a single std.h header (even with ifdef's) to satisfy the needs of all customers. So, we provide a single header, <xdc/std.h>, which #include's a set of compiler-specific definitions of a small set of "base types". This allows the customer (or us) to add support for a new compiler without ever having to modify <xdc/std.h>.

What about `<ti/bios/include/std.h>`?

ti/bios/include/std.h defines BIOS-specific data types (e.g. SmUns, LgUns, etc). Inclusion of this header is okay if you need these data types, but it's intentionally, explicitly a BIOS header. This reinforces a dependency of your code base on DSP/BIOS.

Are there #include order dependencies?

Key points:

<xdc/std.h> is the only header that has a order dependency; the Target Content conventions (which are the same for DSP/BIOS, XDAIS, Codec Engine, etc.) require that <xdc/std.h> must be included by the client before any module header.
xdc/std.h defines a small set of "base types" which do not have a module prefix; all other identifiers are declared in a module header.
All module headers must prefix all declared identifiers and include headers for any referenced identifiers (except std.h)
All headers (including std.h) can be included multiple times

Since all content is delivered in the form of "modules" that follow the conventions above, there is never a module header file order dependency. In addition, every source file that uses a module must include <xdc/std.h>.

Why not always include std.h in every module header? Mostly for historical reasons: since all modules use the base types in std.h, it was considered (at one time) too inefficient for this header to be included by all headers. As time went on the efficiency argument held less weight but we now have a number of legacy headers that do not include std.h. Thus, clients can not assume that it will be included by a module header and we must continue to make this one and only exception.

Notes

The previously recommended definition (xdc_target__) has been deprecated as it was problematic to specify on the command line (the angle brackets and quoting was tough to get right in many shells). The two new definitions (xdc_target_types__ and xdc_target_name__ replace that.